Introduction

Shader support is handled two different ways in the TGEA. The first way is for the engine itself to procedurally generate shaders from base Material properties. The second way is for programmers to specify their own shaders by using CustomMaterials and ShaderData structures.

Contents


Procedural Shader Generation

Procedural shaders or Materials (as they are known in Torque) are output into human readable HLSL form in the example/shaders directory. The vertex and pixel shaders have the respective shaderVxxx.hlsl and shaderPxxx.hlsl filenames where xxx is an incremental number. Each number is the same for matching vertex and pixel shaders, so shaderV010.hlsl and shaderP010.hlsl are the complete shader pair.

The procedurally generated shaders are created and compiled at run time every time the engine starts. This will likely change in the future such that they are cached. The shaders are generated specifically for whatever hardware they are running on. As a result, the number and length of the shader files will vary depending on the video card being used.

The engine can be set so new shaders are not generated. This is useful for debugging and modifying procedural shaders.

Specifying Hand Written Shaders

To use hand written shaders, a ShaderData datablock must be used. This datablock refers only to the vertex and pixel shader filenames and a hardware target level. Shaders are API specific, so DirectX and OpenGL shaders must be explicitly identified. At the time of this writing, only Direct3D is implemented so only the following data is relevant:

DXVertexShaderFile

Indicates a filename that contains a DirectX vertex shader program. It must contain only one program and no pixel shader, just the vertex shader. It can be either an HLSL or assembly level shader. The former must have a filename extension of .hlsl, otherwise it assumes it is an assembly file.

DXPixelShaderFile

Indicates a filename that contains a DirectX pixel shader program. It must contain only one program and no vertex shader, just the pixel shader. It can be either an HLSL or assembly level shader. The former must have a filename extension of .hlsl, otherwise it assumes it is an assembly file.

pixVersion

This indicates what target level of shader should be compiled. Valid numbers at the time of this writing are 1.1, 1.4, 2.0, and 3.0. The shader will not run properly if your hardware does not support the level of shader you have compiled.

Sample ShaderData

Here is a sample ShaderData datablock. This is used in conjuction with CustomMaterials. Multiple CustomMaterials can reference the same ShaderData structure. See shaders.cs for more examples.

   datablock ShaderData( BumpCubemap )
   {
   DXVertexShaderFile 	= "shaders/bumpCubeV.hlsl";
   DXPixelShaderFile 	= "shaders/bumpCubeP.hlsl";
   pixVersion = 1.1;
   };

Custom Materials

CustomMaterials are what allow the user to map their ShaderData to a specific texture on an art asset in the game (much like Materials).


CustomMaterial Properties


CustomMaterials are derived from Materials, so they can hold a lot of the same properties, but it is up to the user to code how these properties are used.

texture[x]

Specifies either a texture filename, or a texture coming from the scenegraph. The "x" is a number from 0 to the max number of texture units supported on the hardware the CustomMaterial shader is targeting (see the version property description, below).

There are several textures that can be grabbed from the scenegraph and used in shaders. Here is a list:

$lightmap

Interior lightmap

$normmap

Interior light-normal map (not a bumpmap, but used for bumpmapping)

$fog

The fog texture generated by the scenegraph

$cubemap

The cubemap specified with the cubemap parameter of the CustomMaterial $dynamicCubemap

Cubemap passed in from scenegraph

$backbuff

A copy of the screenbuffer - useful for refraction effects

shader

The shader parameter indicates the pixel and/or vertex shader to be used with the CustomMaterial. This parameter expects a ShaderData datablock. See Shaders.

version

Each CustomMaterial datablock targets a specific level of pixel shader hardware. The version parameter indicates this level. Ie. nVIDIA's Geforce 2 would be 0.0, Geforce 3 and 4ti's would be 1.1, the Geforce FX cards would be 2.0, and the Geforce 6xxx cards would be 3.0.

fallback

High level CustomMaterials (ones targeting 3.0 or 2.0 pixel shader hardware) can specify fallbacks for lower levels of hardware. This allows complete control over how a material looks on each possible platform. The fallback parameter is simply another CustomMaterial that is targeting a lower level hardware.

When mapping a CustomMaterial to a texture, the highest level CustomMaterial in the fallback chain should be specified. That way the TGEA can follow the fallback chain down until it reaches a material that can be rendered.

pass

In addition to targeting a specific level of hardware, each CustomMaterial also targets just a single rendering pass. If more passes are desired they can be specified using the pass parameter. It just takes another CustomMaterial definition.

Sample CustomMaterial

Example

    new CustomMaterial( ShinyMetal2_0 )
    {
       texture[0] = "test/metalBump";   // bumpmap texture in texture unit 0
       texture[3] = "$cubemap";         // cubemap texture in texture unit 3
    
       cubemap    = Lobby;
       shader     = BumpCubemap;
       version    = 2.0;
       fallback   = ShinyMetal1;          // specify fallback for 1.1 hardware
       pass[0]    = ShinyMetal2_1;        // specify second pass
    
       specular = "1.0 1.0 1.0 0.0";    // can use the specular parameter from Material
       specularPower = 8.0;
    };