Generating Shader Combinations - Lumberyard User Guide

Generating Shader Combinations

Make sure that the Remote Shader Compiler has been set up successfully first. The remote shader compiler should be accessible by everyone playing the game, especially QA. Try to have everyone who is working on a certain game project share the same remote shader compiler.

Normal game builds should contain shader cache .pak files generated by the shader cache generation phase. At the beginning of a project this could be either completely missing (because no shaders requests have been submitted yet) or the .pak files could still be missing a lot of shaders.

When Lumberyard tries to render an object it will check if the compiled shader is available. When the shader is not available, it will try to load it from the global cache. This can either be loaded directly or through the streaming engine. The direct loading will cause direct disc access from the render thread and this could cause severe stalls due to the streaming thread trying to access the disc at the same time.

By default, when shader compiling is disabled, Lumberyard will stream the shaders from the global cache. The object won't be rendered when shader data is being streamed in. This default behavior can be modified with the following console variable. Note that streaming of shaders is not allowed when shader compiling is enabled, and Lumberyard will automatically disable the following console variable:

r_shadersAsyncActivation = 0

When the shader is missing from the global cache, a "request line" to store this missing shader is directly sent to the remote shader compiler to be sure that this shader will be available in the next shader cache generation. This happens even when shader compiling is disabled, but the remote shader compiler needs to be active.

When no shader compiler is defined or if the shader compiler is disabled then the request line will be ignored. It is recommended to test the remote shader compiler as much as possible to collect as many shader combinations as possible. The remote shader compiling can be disabled with the following console variable, which is disabled by default in release builds, otherwise is always enabled:

r_shadersRemoteCompiler = 0

The submission of the shader request lines can be disabled as well:

r_shadersSubmitRequestLine = 0

When shader compiling is disabled and the shader is missing in the global cache, the object won't be rendered at all. When shader compiling is enabled, and the remote shader compiler is active, an asynchronous request to compile the shader will be sent to the remote shader compiler. If the remote shader compiler is disabled, then the shader will be compiled locally on the PC platform. Other game platforms do not support local compilation.

To keep track of the current shader cache state in game, extra debug information can be enabled using the following console variable:

r_displayinfo = 2

A shader cache information line can be found on the top right of the screen, which reports the amount of Global Cache Misses (GCM) that have been found so far. It also reports if shader compiling is currently enabled or not.

All the shader cache misses also get written to a text file at the following location: \Shaders\ShaderCacheMisses.txt. This information is only used for debugging the current state of the shader cache, and should ideally be empty.