Editing Darkplaces material system/Stages

{{navigation title|Darkplaces material system|Stages}}
== Base Stage ==
=== Texture Map ===
Specifies the base texture map (a 24 or 32-bit TGA or JPEG file) used for this material. 

'''map &lt;textureName&gt;'''
:The texture may or may not contain alpha channel information. Texture name can have no extension as engine will automatically add it. For texture/blah, darkplaces will search for this textures:
:* dds/texture/blah.dds
:* texture/blah.tga
:* texture/blah.png
:* texture/blah.jpeg

'''clampMap &lt;textureName&gt;'''
:Specifies the source texture map (see map). Clamping keeps texture from tiling (texture coordinates is clamped to 0-1).
'''Design note''': level editor doesnt show clampMap properly, moreover [[brush | brushes]] use texture projection which is converted to real texture coordinates when map is compiled. To bypass that limitation use "Fit" instrument in surface/patch inspector as it always make 0-1-compliant texture projection.

'''animMap &lt;frequency&gt; &lt;texture1&gt; ... &lt;texture64&gt;'''
:The surfaces in the game can be animated by displaying a sequence of 1 to 64 frames (separate texture maps). These animations are affected by other keyword effects in the same and later shader stages.
:* '''frequency''' : The number of times that the animation cycle will repeat within a one second time period. The larger the value, the more repeats within a second. Animations that should last for more than a second need to be expressed as decimal values.
:* '''texture1...texture64''': the texture path/texture name for each animation frame must be explicitly listed. Up to 64 frames (64 separate texture files) can be used to make an animated sequence. Each frame is displayed for an equal subdivision of the frequency value.
:If you want to clamp texture coordinates such as in '''clampMap''', put '''animClampMap''' instead of '''animMap'''.
:'''Example''':
 <font color=green>// A 4 frame animated sequence, calling each frame in sequence over a cycle length of 4 seconds.</font>
 <font color=green>// Each frame would be displayed for 1 second before the next one is displayed.</font>
 <font color=green>// The cycle repeats after the last frame in sequence shown.</font>
 <font color=blue>animMap</font> 0.25 '''models/fx/flame1 models/fx/flame2 models/fx/flame3 models/fx/flame4'''
:'''Design Notes''': To make a texture image appear for an unequal (longer) amount of time (compared to other frames), repeat that frame more than once in the sequence.

=== Blend Function ===
Blend functions are the keyword commands that tell engine's renderer how material will be mixed with objects that is behind it.

The most common blend functions are set up here as simple commands, and should be used unless you really know what you are doing.

'''blendFunc blend'''
:Traditional alpha blending (shorthand command for ''blendFunc GL_SRC_ALPHA GL_ONE_MINUS_SRC_ALPHA'').

'''blendFunc add'''
:Additive blending  (shorthand command for ''blendFunc GL_ONE GL_ONE'').

'''blendFunc addalpha'''
:Additive blending with alpha (shorthand command for ''blendFunc GL_ONE GL_ONE_MINUS_SRC_ALPHA'').

'''blendFunc filter'''
:A filter will always result in darker pixels than what is behind it, but it can also remove color selectively. Lightmaps are filters. Shorthand command that can be substituted for either ''blendFunc GL_DST_COLOR GL_ZERO'' or ''blendFunc GL_ZERO GL_SRC_COLOR'').

'''blendFunc &lt;source&gt; &lt;destination&gt;'''
:Alternative, GL-friendly blending mode definition. Source is pixel of texture. Destination is pixel in framebuffer. Possible codes for source and destination:
:* GL_ONE
:* GL_ZERO
:* GL_SRC_COLOR
:* GL_SRC_ALPHA
:* GL_DST_COLOR
:* GL_DST_ALPHA
:* GL_ONE_MINUS_SRC_COLOR
:* GL_ONE_MINUS_SRC_ALPHA
:* GL_ONE_MINUS_DST_COLOR
:* GL_ONE_MINUS_DST_ALPHA

=== alphaGen vertex ===

Enables vertex-controlled transparency. Reguires per-vertex rgba attributes which is supported on [[bmodel | submodels]].

[[ASE]] format used by [[misc_model]] (and converted to map geometry during compile) supports per-vertex transparency. 

Other model formats such as [[MD3]], [[DPM]], [[IQM]] does not support per-vertex rgba attributes, hence cannot have per-vertex transparency.

=== tcGen environment ===
Generate spherical environment-mapped texture coordinates. Used for fake gloss effect.

=== tcMod &lt;function&gt; ===
Specifies how texture coordinates are modified after they are generated. The valid functions for tcMod are ''rotate'', ''scale'', ''scroll'', ''stretch'', ''transform'', ''turb'' and ''page''. Up to 4 tcMod's are allowed.

When using multiple tcMod functions during a stage, place the scroll command last in order, because it performs a mod operation to save precision, and that can disturb other operations. Texture coordinates are modified in the order in which tcMods are specified.

'''Example''':
 <font color=green>// texture coordinates will be scaled then scrolled.</font>
 <font color=blue>tcMod scale</font> 0.5 0.5
 <font color=blue>tcMod scroll</font> 1 1

'''tcMod rotate &lt;degrees/sec&gt;'''
:This keyword causes the texture coordinates to rotate. The value is expressed in degrees rotated each second. A positive value means clockwise rotation. A negative value means counterclockwise rotation. For example ''tcMod rotate 5'' would rotate texture coordinates 5 degrees each second in a clockwise direction. The texture rotates around the center point of the texture map, so you are rotating a texture with a single repetition, be careful to center it on the brush (unless off-center rotation is desired).

'''tcMod scale &lt;sScale&gt; &lt;tScale&gt;'''
:Resizes (enlarges or shrinks) the texture coordinates by multiplying them against the given factors of sScale and tScale. The values "s" and "t" conform to the "x" and "y" values (respectively) as they are found in the original texture. The values for sScale and tScale are NOT normalized. This means that a value greater than 1.0 will increase the size of the texture. A positive value less than one will reduce the texture to a fraction of its size and cause it to repeat within the same area as the original texture.
:'''Example''': 
 <font color=green>// repeat twice along texture width, but expand to twice its height (in which case half of the texture would be seen in the same area as the original)</font>
 <font color=blue>tcMod scale</font> 0.5 2

'''tcMod scroll &lt;sSpeed&gt; &lt;tSpeed&gt;'''
:Scrolls the texture coordinates with the given speeds. The values "s" and "t" conform to the "x" and "y" values (respectively) as they are found in the original texture file. The scroll speed is measured in "textures" per second. A "texture" is the dimension of the texture being modified and includes any previous material modifications to the original texture file). A negative s value would scroll the texture to the left. A negative t value would scroll the texture down.
:'''Example''': 
 <font color=green>Moves the texture down and right (relative to the TGA files original coordinates) at the rate of a half texture each second of travel.</font>
 <font color=blue>tcMod scroll</font> 0.5 -0.5
:'''IMPORTANT NOTE''': This should be the last tcMod in a stage. Otherwise there may be a popping or snapping visual effect in some materials.

'''tcMod stretch &lt;func&gt; &lt;base&gt; &lt;amplitude&gt; &lt;phase&gt; &lt;frequency&gt;'''
:Stretches the texture coordinates with the given function. Stretching is defined as stretching the texture coordinate away from the center of the polygon and then compressing it towards the center of the polygon. (see Key Concepts for waveform parameter definitions).

'''tcMod transform &lt;m00&gt; &lt;m01&gt; &lt;m10&gt; &lt;m11&gt; &lt;t0&gt; &lt;t1&gt;'''
:Transforms each texture coordinate as follows:
:S = s * m00 + t * m10 + t0
:T = s * m01 + t * m11 + t1
:This is for use by programmers.

'''tcMod turb &lt;base&gt; &lt;amplitude&gt; &lt;phase&gt; &lt;freq&gt;'''
:Applies turbulence to the texture coordinate. Turbulence is a back and forth churning and swirling effect on the texture.
:'''IMPORTANT NOTE''': This should be first tcMod in a stage because it is only software tcMod (all other ones transform texture matrix).
:* '''base''' : Undefined.
:* '''amplitude''' : This is essentially the intensity of the disturbance or twisting and squiggling of the texture.
:* '''phase''' : See the explanation for phase under the deformVertexes keyword.
:* '''freq''' : Frequency. This value is expressed as repetitions or cycles of the wave per second. A value of one 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.

'''tcMod page &lt;width&gt; &lt;height&gt; &lt;delay&gt;'''
:Texture animation using texture coordinates shifting. Require all animations to be stored in single texture in the form of tiles.
:The texture is shifted by 1/<width> every <delay> seconds, and by 1/<height> every <delay>*<width> seconds.
:'''Example''':
 <font color=green>// To use that animation, make a texture with the frames aligned in a grid like this:</font>
 <font color=green>//    1   2   3   4</font>
 <font color=green>//    5   6   7   8</font>
 <font color=green>// Then align it in on the model/brush/curve so only one of the animation frames can be seen on the surface.</font>
 <font color=green>// Engine will then display the frames in order and the cycle will repeat every 0.8 seconds.</font>
 <font color=blue>tcMod page</font > 4 2 0.1

== Lightmap Stage ==

This stage tells renderer to show material with static lighting ([[lightmap]], [[vertex lighting]] or [[lightgrid]]) applied. It have no parameters and must always be the last stage.

'''Example''':

 '''models/mapobjects/cave/crystal01'''
 {
     <font color=blue>dpglossintensitymod</font> 0.5
     <font color=blue>dpglossexponentmod</font> 0.2
     <font color=blue>dpmeshcollisions</font>
     <font color=blue>dpreflectcube</font> '''textures/envmaps/crystal01_'''
     <font color=blue>dpnoshadow</font>
     {
         <font color=blue>map</font> '''models/mapobjects/cave/crystal01'''
     }
     <font color=green>// lightmap stage</font>
     {
         <font color=blue>map</font> '''$lightmap'''
     }
 }

== Terrain Blending Stage ==

For terrain blending to be used on material, additional stage that represents second texture (foreground layer) for terrain blending should be added.

Example:

 '''textures/terraintest'''
 { 
     <font color=blue>qer_editorimage</font> '''radiant/textures/terraintest'''
 
     <font color=blue>surfaceparm</font> stone
     <font color=blue>surfaceparm</font> detail 
     <font color=blue>surfaceparm</font> trans 
     <font color=green>// base stage - background texture</font>
     { 
         <font color=blue>map</font> '''textures/terrain/grass'''
     } 
     <font color=green>// terrain blending stage - foreground texture</font>
     { 
         <font color=blue>map</font> '''textures/terrain/rock'''
         <font color=blue>blendFunc blend</font>
         <font color=blue>alphaFunc GE128</font> <font color=green>// optional parm and enables additional alpha-splatting effect to be used in blending algorithm</font>
         <font color=blue>alphaGen vertex</font>
     } 
     <font color=green>// lightmap stage</font>
     { 
         <font color=blue>map</font> '''$lightmap'''
     }
 }