Home

For more precise control of your graphics, you will need shaders.

Introduction

This document describes the shader engine that is used in Racer starting from v0.5.2. Note that much of the ideas of the shader definition is heavily inspired on Quake3's shader scripts (if only to reduce the learning curve). Although different in form (Racer uses .ini files), the syntax and options have much in common. Reading a document on Quake3 Arena's shader engine will probably help with understanding Racer's engine, if you have trouble understanding certain parts. However, do note that Racer's shader engine does not have the same amount of features that Q3 has. Some features are less suited to a racing simulation, or may just have not been implemented yet because of the amount of work or complexity.

For some example shaders, see the Shader tutorial.

What does the shader engine do?

The engine attempts to use the graphics card optimally, by minimizing state changes (such as texture switching, but also other states). Rendering order is also sorted based on the shaders. When possible, this is done only once after loading all the graphics. All in an attempt to speed up throughput to the graphics card.

General shader structure

Shaders are defined in .shd files, which take the form of .ini files (as most other Racer files). Each shader must begin with 'shader_'; an example for a shader name is 'shader_f3top'.
A shader consists of 2 parts:

• Global parameters
  Examples of these are 'cull' and 'sort'. They indicate parameters that are layer-independent. With Cg shaders being used, most parameters are global, and only textures are defined per-layer.
• Layers
  Each shader consists of 1 or more layers. These are the passes that are done on each polygon. The more passes, the longer rendering may take, although if possible and enabled, multitexturing is used to speed up multiple passes. Since multiple layers may be combined into 1 rendering pass (if multitextured), the term 'layer' is used instead of 'pass'.

Typical usage

Although usage might turn out slightly different from what I expect, something can be said about general uses of shaders. Shaders are normally named to reflect the main texture image they refer to. Since DOF files simply reference texture names (not shader names), the shader engine searches for a shader with the texture name to see if this is actually a more complex material than just a texture. So in essence the texture name IS the material/shader name and is as such referred to.

To distinguish shaders for models (DOF files) in different directories, they are prefixed with the directory which they target. For example, when loading a car 'x', first the file 'data/cars/x/car.shd' is loaded. A shader in car.shd indicated by the path 'shader_f3top' will be named 'data/cars/x/f3top' in the shader engine. After loading the .shd file, the models themselves are loaded (from the same data/cars/x directory). If the model loader encounters a material with the texture name 'f3top.bmp', it searches for shader 'data/cars/x/f3top' and so finds the correct (local) shader definition. Most of this happens in the background, so you only have to make sure that the shader file is in the same directory as the referred DOF and image files.

In the above, note that the extension of the file (.bmp, .tga etc) is ignored. As a result, do note use image filenames that differ only in their extensions! If you have a file named 'f3top.bmp' and 'f3top.tga', both will refer to the same shader. This obviously may lead to subtle problems (hard to track).

Debugging

To check whether your shader files are ok, it is often a good idea to check the QLOG file regularly for errors concerning the shader files. The QLOG file is either in the installation directory (Windows) or the user's home directory (Unix).

Parameter reference

See below for a complete reference on all the available parameters.

Cull

The 'cull' keyword indicates how polygons drawn with this shader need to be culled (if at all). The argument is:

Fog

Each shader can have fog turned on or off. This isn't possible to do per layer (I don't think that's needed).
Setting the shader 'fog' line to 1 will turn on fog (default). It is often useful to turn off fog (fog=0) for sky elements, that otherwise get too foggy. It's better in those cases to turn off fog (faster) and use a foggy texture map instead.

Sort

Although the graphics engine sorts while rendering based on shader properties and object distances, sometimes you'll experience render order 'fighting'; objects flicker as some of their parts are rendered in different order. To counter this, you can add an explicit sort_offset into the global section of a shader definition.

The render engine uses an internal sort ordering system to roughly sort different types of shaders. These sorting orders are spaced 100 apart:

The sort offset ranges from -99 to +99, where positive means render later than a shader with sort_offset=0. For example, the Lamborghini Murcielago has lights just below a transparent glass mesh. To make sure the glass renders on top of the lights, set shader_glass.sort_offset to 1. Also, if a track has a fence that is divided into big chunks, you can use sort_offset to avoid errors that can happen due to Z distance estimations (the fence being rendered too soon and overdrawn by other objects).

As you can see from the sort table above, using a sort_offset greater than 100 or less than -100 will move through a serious sorting boundary, and can mess up rendering order more than you can oversee.

Physical properties

Next to the visual properties of a shader (which are by far the most important aspect of shaders), you can also specify some physical properties.

Graphics properties

The shader also contains a variable to modify some purely graphical properties.

Vertex and fragment shaders

(Available since v0.5.3 beta 8) Use the vertex_shader and fragment_shader options to define Cg shader programs for a world of added graphics power (so take note; Racer 'shaders' are material definitions which can have vertex & fragment shaders as part of them; unfortunately the term 'shader' is used in 2 different contexts here). The property shader_*.vertex_shader.file indicates the file to use for vertex shaders, similar to fragment shaders which use shader_*.fragment_shader.file.

More information on parameters available in Cg shaders can be found at the Racer GPU Shaders page.

Cg was created by nVidia as a general purpose GPU shader language. It looks quite a bit like C++ although it has severe limitations due to the fact that you use these little programs to modify vertex & fragments. See http://developer.nvidia.com/object/cg_tutorial_teaching.html as a start, or try Google.

Currently the options for specifying GPU shaders are:

Fog

Coming up.

Global - material (lighting)

Note that global material properties have been defined since v0.7.2. This version introduces passing of material properties to Cg shaders. As most Cg shaders will only use 1 pass, the need for a global material definition became apparent. Note though that the global material properties are actually stored in the 1st layer! This means that if you define global material properties, the first layer's properties will be overruled.

These properties are passed to Cg shaders (see GPU shaders) as Ka (ambient), Kd (diffuse), Ke (emission), Ks (specular) and 'shininess'.

You can specify shininess, specular color and emission; all material properties. Note that if these do not stay constant in the entire shader, multiple separate rendering passes will be used (less efficient).

An starting point for a shiny road is roughly to set shininess at 10, and specular at 0.2 0.2 0.2 1.

Layer - depth function

Each layer can have its own depth function. It is selected by a 'depthfunc=...' line. This works as follow: fragment_z value FUNC framebuffer_z. So the default depth function of 'lequal' means that the depth function only passes (meaning the fragment will be written) if the fragment's Z position is less than or equal to the value currently in the Z-buffer. Possible values are:

Performance note: changing depth functions between layers means no single-pass multi-texturing can take place to combine the 2 layers with different depth functions.

Layer - depth write

For each layer you can define whether the depthbuffer (Z-buffer) is written or not. Default is 1 (depthbuffer is written to). With 'depthwrite=0' you can turn off depth writes for the layer. Normally, transparent shaders will have depthwrite=0 and opaque ones have depthwrite=1 (the default).

Layer - alpha function

Each layer can have its own alpha function. It is selected by a 'alphafunc=...' line. Fragments (pixels) not passing the alpha test won't be drawn. This is useful to make transparent objects that do write to the Z-buffer but are still see-through. You can use it for trees for example; if many trees overlap, you want to use Z-buffering, but still make the trees seethrough; use 'alphafunc=gequal 128' for example. This will not render any pixels that are more than half transparent (and not update the Z-buffer for those pixels).

The reference value (which is needed for most functions) is a value from 0..255. Also note that different layers that have different layer functions can NOT be multitextured (rendered in combination), so be careful about the performance if you use multiple layers with different alpha functions. Possible values are:

Performance note: changing depth functions between layers means no single-pass multi-texturing can take place to combine the 2 layers with different depth functions.

Layer - alpha to coverage

Blending (mixing with the destination image) is relatively expensive, and quickly causes ordering issues (what to draw first). An alternative that works when anti-aliasing your screen is alpha-to-coverage. This technique uses the amount of 'alpha' to define a 'coverage' grid of pixels; a sort of on/off grid. The nice thing about this grid is that is works as a mask, and can be used in combination with Z-buffering, making the ordering issues disappear, as well as the need to blend.

To change a blending shader into an alpha-to-coverage layer, turn off the blendfunc, and set the layer's alpha_to_coverage property to 1. You probably need to tune the alphafunc value to make the masking thinner or thicker. An example shader that uses alpha to coverage goes like this:

vf_standard_transparent
{
  vertex_shader 
  {
    file=standard_v.cg
  }
  fragment_shader
  {
    file=standard_transparent_f.cg
  }
  diffuse=1 1 1
  ambient=1 1 1
}

shader_bush~vf_standard_transparent
{
  cull=none
  layer0
  {
    map=bush.tga
    alphafunc=gequal 50
    alpha_to_coverage=1
  }
}

This will use depthwrite=1, but because of the alpha to coverage masking, it will appear transparent. The quality of the look is dependent on the amount of anti-aliasing, but for things like trees and bushes this is quite ok. Things like see-through glass may be better off using actual blending.

Alpha to coverage looks a bit like this:

Layer - maps

This is the basic necessity of a layer; a texture map (an image). Note that (for crossplatform's sake) every map will be converted to lowercase. This enables Windows track creations to work on Linux with little effort. A map is specified in layer<x>.map and can take the following values:

In v0.8.20, you can also specify the image type in layer<n>.mode. Use 'srgb' for images obtained from regular cameras, and 'linear' for generated images like bumpmaps. Notice that alpha remains unchanged. Any srgb image (the default) will have a gamma of 0.45 applied.

Layer - material (lighting)

You can specify shininess, specular color and emission; all material properties. Note that if these do not stay constant in the entire shader, multiple separate rendering passes will be used (less efficient).

Unclear is whether the colors (specular/emission) can actually have negative R, G, B and A values (upto -1)?!

An starting point for a shiny road is roughly to set shininess at 10, and specular at 0.2 0.2 0.2 1.

Layer blending functions

To mix layers, you need to use a blending functions for every layer beyond layer0. So layer1, layer2 etc. all need a 'blendfunc=...' line. Otherwise the previous layers wouldn't be visible. Each blendfunction contains two factors; the first for the source (texture pixels) and the 2nd for the destination (previous layer or framebuffer). Note that not all blend factor mixes may be supported by the hardware.

The possible blend factors are:

In addition, some often-used abbreviations can be used as the blend function:

Layer - mipmap_bias

Often you'll use the global shader mipmap_bias setting (see above) to define a mipmap bias (level) for each layer. You can overrule the mipmap_bias per layer though. This can be useful perhaps for metallic shaders for example, where you have a more diffuse layer and a lacquer layer, where each layer has its own amount of blurring.

See also Texture Filtering below.

Layer - texture environment

The texture environment can be set with 'texenv=...'. This defines how lighting affects the textured pixels.

Layer - texture filtering

With 'mipmap=...' you can define whether the texture uses mipmapping (1) or not (0). Uses mipmap_min_lod (default: 0) and mipmap_max_lod (default: 1000) to define the LOD range from which to choose. For example, use mipmap_max_lod=2 on a road texture to avoid too much blur (at the cost of rendering speed). Note that min_lod/max_lod may NOT be listened to in Racer, since ATI/AMD drivers seem to crash when it's being used (setting OpenGL's GL_TEXTURE_MIN_LOD crashes the card, even when setting it to its default value). Use mipmap_lod_bias to set LOD biasing; defaulting to 0, a value above 0 makes mipmapped textures kick in sooner, a value <0 'delays' the use of mipmaps until pixels are further away. This feature is not supported for ATI graphics cards.

If you want to check how your texture level-of-detail usage looks (for example how the resolution of your texture matches with which mipmaps are actually used in rendering, check out the 'Testing mipmapping with stub textures' page. That page explains how to visualize the mipmaps used onscreen (which is really resolution-dependent, so be a bit careful).

Layer - texture wrapping

Some textures need to be repeated over an object (this is the default), but sometimes you want the texture to end after having been applied once, for example for treelines. For example (in treelines), due to rounding in texture coordinates you would see the bottom part of the trees just shimmering through at the top of the texture (which is mostly empty). In that case, using clamp_to_edge on the layer with the tree texture. An example is given in the image to the right; the woods01 object in CarlswoodNT has wrap_t=clamp_to_edge applied since v0.5.2. 4 wrapping parameters are loaded: wrap_s, wrap_t, wrap_r and wrap_q. They determine the wrapping in each texture direction (often only s & t are used). Wrap_q is probably never used.

Layer - texture coordinate modification

For some layers, you may want to modify the texture coordinates. For example, a detail texture generally requires a more dense view, say 4 to 8x that of the underlying (less detailed) texture. This is done by passing every texture coordinate through a texture matrix (hardware accelerated by the way).

Layer - texture coordinate generation

Instead of explicit texture coordinates, there are a couple of modes to automatically generate texture coordinates. Use 'texgen_s' and 'texgen_t' to set the S and T texture coordinate generation functions. S and T are like UV coordinates that most modeling packages tend to use.

(last updated February 27, 2013 )