Basics: ShaderPrecompiler

Material precompiler to avoid stuttering during on-the-fly generation

Table of Contents

When and Why

Usually, the engine is generating shaders (either vertex or pixel/fragment) on the fly, depending on the materials your are using, the dynamic lights count, and many other factors. Each time a shader is generated, a small lag can occur, depending on the driver and the shader complexity.

When your game seems to stutter and you can see something like

[o Message ] {Rendering }Created generic fragment program : 0x0000000200000100 (ALUIns:17, TEXIns:0, TEXInd:1, Par:5, Att:2, Tmp:5)
[o Message ] {Rendering }Created generic vertex program 7 : 0x0000000000000100 (Ins:20, Par:8, Tmp:4, Mat:0)
in the console window, only then should you think about precompiling your shaders.

Precompiling Shaders

When targeting some platforms with fixed hardware (eg. consoles), this will be done offline by ShiVa. But when you are targeting any other platforms (eg. mobiles/desktops), you have to do that at loading time.

- There are 2 types of shaders: vertex shaders, and fragment/pixel shaders. (.vps or .fps)
- There are 2 categories of shaders: "generic" shaders, and "special" shaders. (starts with G or S)
- Each vertex or fragment/pixel shader the engine creates has a unique 64bits ID. (hexadecimal number, starts with 0x)
- Each shader is separated by a space (delimiter)


We want to avoid the runtime stalls resulting from the generation of
- a generic fragment program with the ID 0x0000000200000100
- a generic vertex program with the ID 0x0000000000000100

We can fix that by putting the following line in some onInit handler at game start:
debug.compileShaderList ( "G0000000200000100.fps G0000000000000100.vps" )

Recommended Procedure

- Play the game on the target device, try to launch every effect/model/power/option to fire off every shader.
- Call debug.getCompiledShaderList in the same session.
- Store the resulting string in an XML file, or just log it.
- Finally, re-inject this list in your game sources to precompile the shaders as shown above.