Stages

Darkplaces material system | previous chapter: Darkplaces material system

Base Stage

Texture Map

Specifies the base texture map (a 24 or 32-bit TGA or JPEG file) used for this material.

map <textureName>

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 <textureName>

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 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 <frequency> <texture1> ... <texture64>

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:

// A 4 frame animated sequence, calling each frame in sequence over a cycle length of 4 seconds.
// Each frame would be displayed for 1 second before the next one is displayed.
// The cycle repeats after the last frame in sequence shown.
animMap 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 <source> <destination>

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 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 <function>

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:

// texture coordinates will be scaled then scrolled.
tcMod scale 0.5 0.5
tcMod scroll 1 1

tcMod rotate <degrees/sec>

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 <sScale> <tScale>

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:

// 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)
tcMod scale 0.5 2

tcMod scroll <sSpeed> <tSpeed>

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:

Moves the texture down and right (relative to the TGA files original coordinates) at the rate of a half texture each second of travel.
tcMod scroll 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 <func> <base> <amplitude> <phase> <frequency>

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 <m00> <m01> <m10> <m11> <t0> <t1>

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 <base> <amplitude> <phase> <freq>

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 <width> <height> <delay>

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:

// To use that animation, make a texture with the frames aligned in a grid like this:
//    1   2   3   4
//    5   6   7   8
// Then align it in on the model/brush/curve so only one of the animation frames can be seen on the surface.
// Engine will then display the frames in order and the cycle will repeat every 0.8 seconds.
tcMod page 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
{
    dpglossintensitymod 0.5
    dpglossexponentmod 0.2
    dpmeshcollisions
    dpreflectcube textures/envmaps/crystal01_
    dpnoshadow
    {
        map models/mapobjects/cave/crystal01
    }
    // lightmap stage
    {
        map $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
{ 
    qer_editorimage radiant/textures/terraintest

    surfaceparm stone
    surfaceparm detail 
    surfaceparm trans 
    // base stage - background texture
    { 
        map textures/terrain/grass
    } 
    // terrain blending stage - foreground texture
    { 
        map textures/terrain/rock
        blendFunc blend
        alphaFunc GE128 // optional parm and enables additional alpha-splatting effect to be used in blending algorithm
        alphaGen vertex
    } 
    // lightmap stage
    { 
        map $lightmap
    }
}