Editing Darkplaces material system/Key Concepts

{{navigation title|Darkplaces material system|Key Concepts|General Keywords}}
Ideally, a designer or artist who is manipulating textures with material files has a basic understanding of wave forms and knows about mixing colored light (high school physics sort of stuff). If not, there are some concepts you need to have a grasp on to make materials work for you.

Materials not only modify the visible aspect of textures on a geometry [[Brush | brush]], [[Patch mesh | curve]] or mesh model, but they can also have an effect on both the content, "shape" and apparent movement of those things. A surface effect does nothing to modify the shape or content of the brush. Surface effects include glows, transparencies and rgb (red, green, blue) value changes. Content materials affect the way the brush operates in the game world. Examples include water, nonsolid, and detail. Deformation effects change the actual shape of the affected brush or curve, and may make it appear to move.

== Power has a Price ==
The material script gives the designer, artist and programmer a great deal of easily accessible power over the appearance of and potential special effects that may be applied to surfaces in the game world. But it is power that comes with a price tag attached, and the cost is measured in performance speed. Many OpenGL 2.0 effects attached with material keywords (such as [[water shader]], [[refraction]] cubemap, [[offset mapping]]) makes renderer to do more calculations, which take more CPU/GPU time and make game slower. Water shader surface will draw a world 2 times to get reflective and refractive image, refraction cubemap will add one more texture sampler, parallax mapping will make more texture lookups (from 3 for traditional offset mapping to 14-15 for relief mapping). Blended surfaces will be drawn twice if lit by one or more realtime lights (this means their triangle count will have double effect on r_speeds).

== RGB Color ==
RGB means "Red, Green, Blue". Mixing red, green and blue light in differing intensities creates the colors in computers and television monitors. This is called additive color (as opposed to the mixing of pigments in paint or colored ink in the printing process, which is subtractive color). In Darkplaces engine and most higher-end computer art programs (and the color selector in Windows), the intensities of the individual Red, Green and Blue components are expressed as number values. When mixed together on a screen, number values of equal intensity in each component color create a completely neutral (gray) color. The lower the number value (towards 0), the darker the shade. The higher the value, the lighter the shade or the more saturated the color until it reaches a maximum value of 255 (in the art programs). All colors possible on the computer can be expressed as a formula of three numbblack is 0 0 0. The value for ers. The value for complete complete white is 255 255 255. However, the Darkplaces graphics engine requires that the color range be "normalized" into a range between 0.0 and 1.0. 

{{tip:often you can see RGBA abbreviation which stands for 'RGB + alpha', this is RGB with one more channel - transparency channel. 32-bit images is RGBA, while 24-bit is RGB.}}

== Normalization: a scale of 0 to 1 ==
The mathematics in Darkplaces engine use a scale of 0.0 to 1.0 instead of 0 to 255. Most computer art programs that can express RGB values as numbers use the 0 to 255 scale. To convert numbers, divide each of the art program's values for the component colors by 255. The resulting three values are your Darkplaces formula for that color component. The same holds true for [[texture coordinates]].

== Texture Sizes ==
Texture files are measured in pixels (picture elements). Textures are measured in powers of 2, with 16 x16 pixels being the smallest (typically) texture in use. Most will be larger. Textures need not be square, so long as both dimensions are powers of 2. Examples include: 32x256, 16x32, 128x16.

== Measurements ==
The measurements used in the materials are in either game units, color units, or texture coordinates.

=== Game unit ===
:A game unit is used by deformations to specify sizes relative to the world. In Blood Omnicide 16 units equals one foot, 48 units equals to one meter. The default texture scale used by the NetRadiant map editor results in two texels for each game unit, but that can be freely changed and perturbated with material scripts.

=== Color units ===
:Colors scale the values generated by the texture units to produce lighting effects. A value of 0.0 will be completely black, and a value of 1.0 will leave the texture unchanged. Colors are sometimes specified with a single value to be used across all red, green, and blue channels, or sometimes as separate values for each channel.

=== [[Texture coordinates]] ===
:This is the normalized (see above) dimensions of the original texture image. A full texture, regardless of its original size in texels, has a normalized measurement of 1.0 x 1.0. For normal repeating textures, it is possible to have value greater than 1.0 or less than 0.0, resulting in repeating of the texture. The coordinates are usually assigned by the level editor or modeling tools, but you still need to be aware of this for scrolling or turbulent movement of the texture at runtime.

== Waveform Functions ==

Some of the material rendering functions use waveforms to modulate measurements over time. Where appropriate, additional information is provided with wave modulated keyword functions to describe the effect of a particular waveform on that process. Currently there are five waveforms in use in material scripts:

* '''sin''': sine wave, a regular smoothly flowing wave ranging from -1 to 1.
* '''triangle''': triangle is a wave with a sharp ascent and a sharp decay, ranging from 0 to 1. It will make a choppy looking wave forms.
* '''square''': a square wave simply switches from -1 to 1 with no in-between.
* '''sawtooth''': in the sawtooth wave, the ascent is like a triangle wave from 0 to 1, but the decay cuts off sharply back to 0.
* '''inversesawtooth''': this is the reverse of the sawtooth... instant ascent to the peak value (1), then a triangle wave descent to the valley value (0). The phase on this goes from 1.0 to 0.0 instead of 0.0 to 1.0. This wave is particularly useful for additive cross-fades.

Waveforms all have the following properties:

'''base'''
:Where the wave form begins. Amplitude is measured from this base value.

'''amplitude''' 
:This is the height of the wave created, measured from the base. You will probably need to test and tweak this value to get it correct for each new shader stage. The greater the amplitude, the higher the wave peaks and the deeper the valleys.

'''phase'''
:This is a normalized value between 0.0 and 1.0. Changing phase to a non-zero value affects the point on the wave at which the wave form initially begins to be plotted. Example: In Sin or Triangle wave, a phase of 0.25 means it begins one fourth (25%) of the way along the curve, or more simply put, it begins at the peak of the wave. A phase of 0.5 would begin at the point the wave re-crosses the base line. A phase of 0.75 would be at the lowest point of the valley. If only one wave form is being used in material, a phase shift will probably not be noticed and phase should have a value of zero (0). However, including two or more stages of the same process in a single material, but with the phases shifted can be used to create interesting visual effects. Phase changes can also be used when you have two uses of the same effect near each other, and you don't want them to be synchronized. You would write a separate material for each, changing only the phase value.

'''freq'''
:Frequency. This value is expressed as repetitions or cycles of the wave per second. A value of 1 would cycle once per second. A value of 10 would cycle 10 times per second. A value of 0.1 would cycle once every 10 seconds.