Material decls are similar to shader files from Quake3, but they are a lot more powerful. Materials have a lot of power, especially when combined with scripts and GL programs.

The format of a table definiton is:

table <tablename> { [snap] [clamp] { <data>, <data>, ... } }

Now, armed with this knowledge, we can easily construct a square wave lookup table:

table squarewave { snap { 0, 1 } }

Let's look at a simple material (some random wall in the alpha labs):

textures/alphalabs/a_lfwall21b
{
    qer_editorimage textures/alphalabs/a_lfwall21b
    bumpmap         textures/base_wall/lfwall21_local
    diffusemap      textures/alphalabs/a_lfwall21b
    specularmap     textures/alphalabs/a_lfwall21b_s
}

The first line is the name of the material (which in this case also happens to be the name of the diffuse map). Notice the absence of a 'material' keyword. This is because it is in a .mtr file, where the 'material' keyword is assumed. If you chose to put this in another type of file, you would need the 'material' keyword.

The global section begins right after the open curly brace. The first key word we see is qer_editorimage, which tells Radiant which image to use in the editor. This is the image used in the texture window, as well as in the 3D view. Next we define the bump map (normal map), the diffuse map (colors), and the specular map (gloss). This is about as basic of a material file you can get, while still using the advanced lighting features. Technically all you need is 'diffusemap', in which case the specular map is black, the bump map is blue, and the editorimage is the diffusemap. Creating an entire map with those types of materials will look roughly like Quake 3.

This material looks like it doesn't have any stages, but in fact it has 3 stages. The 'bumpmap' 'diffusemap' and 'specularmap' keywords are simply shortcuts for stages as we will see later.

This is the material file for outdoor glass, which is one of the more complex materials in the game:

textures/glass/outdoor_glass1
{
    noSelfShadow
    noshadows
    twosided
    translucent
    glass
    forceoverlays
    sort decal

    qer_editorimage textures/glass/glass1
    {
        vertexProgram heatHaze.vfp
        vertexParm  0  0 , 0  // texture scrolling
        vertexParm  1  .5  // magnitude of the distortion

        fragmentProgram heatHaze.vfp
        fragmentMap 0  _currentRender
        fragmentMap 1  textures/sfx/vp1 // the normal map for distortion
    }
    {
        maskcolor				
        map makealpha(textures/glass/glass1)
    }	
    {
        blend gl_dst_alpha, gl_one
        maskalpha
        cubeMap env/gen2
        red     Parm0
        green   Parm1
        blue    Parm2
        texgen  reflect
    }
    {
        blend filter
        map textures/glass/outdoor_glass1fx
    }
}

First the global section sets up some properties for the material. Two keywords to take note of: 'glass' specifies the sound that is made when things hit it (NOT the way it looks). The 'forceoverlays' keyword forces decals like blood to draw on it. Normally blood and weapon decals are disabled on transparent surfaces because it tends to look wrong.

The first stage in this material is what sets up the vertex and pixel program. The programs are defined in "glprogs/heatHaze.vfp". This stage is completely skipped on older (non ARB2) hardware, and is actually drawn last on modern hardware because of the reference to _currentRender. As the comments explain, for this particular vertex program, parm 0 defines the texture scrolling, and parm 1 defines how much the image is distorted. The meaning of these parms depends completely on how the vertex program is written, so consult your programmer.

The second stage sets up an alpha channel stage. It doesn't actually write anything to the screen, but rather it sets some values in the alpha channel which are used in the next stage.

The third stage is the main color stage. Because 'blend' references gl_dst_alpha, the color value depends on the alpha value set in stage 2. Normally we would just put the alpha value directly in the image map, but this stage uses a 6 sided cube map texture, which moves with the viewer (because of texgen reflect). We don't want the alpha channel to move, however, so we have to set it in a different stage. 'red', 'green', and 'blue' being set to 'param0', 'param1', and 'param2' allow the level designer to change the color of the glass by changing the 'shaderParm' values in the editor. As you will see later, this could be shortened to just 'colored'

The fourth stage just blends a static image map on top.

Let's take a look at a material to see these features in use:

models/weapons/soulcube/soulcube3fx
{
    noSelfShadow
    translucent
    noShadows
    {
        if ( parm7 > 3 )
        blend add
        map models/weapons/soulcube/soulcube3fx
        rgb scTable[ time * .5 ] 
    }
}

In Doom 3, certain stages of the material can be selectively turned on and off. The 'if' command in this example means "only draw this material if parm7 is greater than 3." There are a few places where parm7 can get set, one of them is in the editor with the 'shaderParm0' to 'shaderParm11' keys. Another place is in the script file (such as with weapons). Of course, it can also get set in the code.

Notice the use of a lookup table in this material. Here we are using 'time' (which is a floating point number that increases forever) to look up a value in 'scTable' (which was defined using a 'table' decl earlier).

The mathematical operators you can use in a material are %, /, *, -, and +. You can also use the boolean operators <, >, <=, >=, ==, !=, &&, and ||. The meaning of the symbols is the same as in C/C++, Java, PHP, etc. Mathematical expressions should be enclosed in parenthesis (there are cases where they don't have to be, such as when they are used as an index to a lookup table, but it never hurts to have too many. For the operands, you can use a lookup table, any numerical constant, and any of the following variables:

• time: Forever increasing floating point value that returns the current time in seconds
• parm0-parm11: Parameters that can be set a number of ways (discussed above)
• global0-global7: Not used right now
• fragmentPrograms: Constant that is 1 if ARB fragment programs are available. This is mostly used for disabling a stage by specifying "if ( fragmentPrograms == 1 )"
• sound: The current sound amplitude of the entity using this material. This is used to create light materials that pulse with the sound.

Global Keywords for regular materials

{
  blend diffusemap
  map <map>
}

{
  blend specularmap
  map <map>
}

{
  blend bumpmap
  map <map>
}

polygonOffset 1
discrete
sort decal
noShadows

Deforms

Global Keywords for light materials

Global Surface Parameters

Stage Keywords

maskRed
maskGreen
maskBlue

red <exp>
green <exp>
blue <exp>

red <exp>
green <exp>
blue <exp>
alpha <exp>

red exp0
green exp1
blue exp2
alpha exp3

color parm0, parm1, parm2, parm3

fragmentProgram <prog>
vertexProgram <prog>

Parameters Key

Image Program Functions
These can be used anywhere that accepts <map> and can be nested