Darkplaces material system

Introduction

Darkplaces material system is created to put more direct control over the surfaces qualities of textures into the hands of designers and artists.

This article will contain a parts of Quake 3 Shader Manual by By Paul Jaquays and Brian Hook adapted for Darkplaces engine.

What is a Material?

Materials are short text scripts that define the properties of a surface as it appears and functions in a game world (or compatible editing tool). By convention, the documents that contain these scripts usually has the same name as the texture set which contains the textures being modified (e.g; textures_inn, models_mapobjects_crypt, etc,). Several specific script documents have also been created to handle special cases, like liquids, environments and special effects.

For Darkplaces, material scripts are located in 'Path_To_The_Game/gamedir/scripts'.

A Darkplaces material file consists of a series of surface attribute and rendering instructions formatted within braces ("{" and "}"). Below you can see a simple example of syntax and format for a single process, including the Q3MAP keywords or "Surface Parameters", which follow the first bracket and a single bracketed "stage":

// material definition
textures/mymaterial
{
   // parameters
   qer_editorImage radiant/textures/mymaterial
   q3map_textureImage radiant/textures/mymaterial
   dpglossexponentmod 0.5
   surfaceparm stone
   // base stage
   {
       map textures/mymaterial // engine will search fo textures/mymaterial.tga, textures/mymaterial.jpeg
   }
   // lighting stage
   {
       map $lightmap
   }
}

Material names & Conventions

The first line is the material name. Material names can be up to 63 characters long. The names are often a mirror of a pathname to a .tga file without the extension or basedir (/Blood Omnicide/kain in our case), but they do not need to be. Materials that are only going to be referenced by the game code, not modeling tools, often are just a single world, like "collision" or "dpbihclip". Materials that are used on characters or other polygon models need to mirror a .tga file, which allows the modelers to build with normal textures, then have the special effects show up when the model is loaded into the game. Materials that are placed on surfaces in the map editor commonly mirror a .tga file, but the "qer_editorimage" material parameter can force the editor to use an arbitrary image for display.

Material pathnames have a case sensitivity issue - on windows, they aren't case sensitive, but on unix they are. Try to always use lowercase for filenames, and always use forward slashes "/" for directory separators.

Inspired by Quake 3

Quake 3 shader scripts was an inspiration for darkplaces material system and visual look of material scripts is very very close to quake 3. So if you are familiar with Id Tech 3 shaders system, you will be right home with materials. Therefore there is some serious differences because Darkplaces material system was written independently and aimed to realtime lightning rendering and OpenGL 2.0.

Since Darkplaces uses tools with Id Tech 3 roots, materials is often spelled as 'shaders' there. To not be confused, this terms are nearly identical in q3 tools:

• Shader = Material
• Shader name = Surface shader = Material name = Surface material
• Shader script = Material script
• Shader keywords = Material keyworkds
• etc

Material Types

The keywords that affect materials are divided into three classes. The first class of keywords are global parameters. Some global parameters ( "surfaceparms" And all "q3map_" keywords) are processed by Q3MAP2 and change physical attributes of the surface that uses the material. These attributes can affect the player. To see changes in these parameters one must recompile the map.

Second class are keywords parsed by engine server part (surfaceparms, some other keywords). They are changes physical properties of surface and can affact gameplay.

The remaining global keywords, and all Stage Specific Keywords are processed by the renderer. They are appearance changes only and have no effect on game play or game mechanics. Changes to any of these attributes will take effect as soon as the game goes to another level or vid_restarts (type command vid_restart in the game console).

Material keywords are not case sensitive.

IMPORTANT NOTE: some of the material commands may be order dependent, so it's good practice to place all global material commands (keywords defined in this section) at the very beginning of the material and to place material stages at the end (see various examples).

Key Concepts

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.

Surface Effects vs. Content Effects vs. Deformation Effects

Materials not only modify the visible aspect of textures on a geometry brush, 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.

NOTE: 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 units.

'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.