Shader Cache and Generation

This section discusses the shader cache and how to generate shader cache .pak files.

Shader Cache

The shader cache stores a collection of parsed and precompiled shaders. Since the
shader code is written with multiple definitions, Lumberyard can generate an enormous
number
of different shaders. Compiling shaders on demand at run time is only possible on
the
PC. On-demand shader compiling can cause freezes during the game play and uses extra
memory. To reduce this overhead, all required shader combinations for a game are parsed,
compiled, and stored in the shader cache.

ShaderCache.pak – Contains compiled shaders for all possible combinations that have been submitted
to the remote shader compiler.

ShaderCacheStartup.pak – Contains a small subset
of the shader cache that is used during game start. This file is loaded into
memory for quicker start times, but is not required. This cache is often used to
hold the minimum required set of shaders to show a loading screen so that the
rest of the loading can occur.

ShaderCache.pak File
Generation

Creating a ShaderCache.pak file consists of running the BuildShaderPak_DX11.bat batch script, which in turn runs
ShaderCacheGen.exe to ensure the local cache directory contains all the shaders that are listed in the
ShaderList.txt file. The
BuildShaderPak_DX11.bat script packs the contents of the cache directory, creates a ShaderCache.zip file, and then renames the file to
ShaderCache.pak.

You can find the ShaderList_platform.txt file either from the remote shader compiler server or from the Lumberyard Editor
directory. This file
contains the list of all shaders which ShaderCacheGen.exe uses to produce the shader combinations for your game.

When running Lumberyard Editor, individual shaders are created as you view them. As
such,
you do not strictly need a remote shader compiler server to test game release mode
or
test shader pack generation. You just need access to the
ShaderList_platform.txt file
that is created in the
lumberyard_version\dev\cache\game_name\platform\user\cache\shaders
directory when running Lumberyard Editor.

However, only the shaders you have viewed on your local computer while running Lumberyard
Editor will be listed in the ShaderList_platform.txt
file. For this reason, it is recommended that you use a remote shader compiler server
if possible.

Note

During development time, when you run the game or Lumberyard Editor, and before the
shaders are packed into shader cache .pak files, loose shader
files are created in the following directory:
lumberyard_version\Dev\Cache\your_game\platform\user\cache

The following sections detail the steps used to generate ShaderCache.pak files:

ShaderCacheGen.exe

Lumberyard ships with ShaderCacheGen.exe, which is located in the
lumberyard_version\dev\Bin64
directory. ShaderCacheGen.exe is a stripped-down version of the
Lumberyard game launcher without the render viewport, and is used to populate the
local
shader cache directory with all the shaders contained in the
ShaderList.txt file.

When running ShaderCacheGen.exe, it first loads the
ShaderCacheGen.cfg file, which you can customize to suit
your needs.

If you customized Lumberyard in any way, you must build Lumberyard and your game using
the
all profile. This argument builds both
ShaderCacheGen.exe (and ensures that it is up-to-date) and
the game .dll files that are required.

Packing the Shader Cache Using a Batch File

The BuildShaderPak_DX11.bat file generates the ShaderCache.pak files, which are saved to the
lumberyard_version\dev\build\platform\your_game directory. The batch file first calls the
ShaderCacheGen.exe and then calls Tools\pakShaders.bat.

From a command line, navigate to the lumberyard_version\dev directory, and run the BuildShaderPak_DX11.bat, and
specify the location to the ShaderList_platform.txt file.

Once the shader .pak files are created, you can move them as needed. For example, if you already built
a release version of your game, you can place them with
the rest of the .pak files.

When compiling shaders for your project, you can customize the BuildShaderPak_DX11.bat file as needed. The following is an excerpt from a sample
.bat file:

set SOURCESHADERLIST=%1
set GAMENAME=your_game_project
set DESTSHADERFOLDER=Cache\%GAMENAME%\PC\user\Cache\Shaders
set SHADERPLATFORM=PC
rem other available platforms are GL4 GLES3 METAL
rem if changing the above platform, also change the below directory name (D3D11, METAL, GL4, GLES3)
set SHADERFLAVOR=D3D11

Packing the Shader Cache Manually

If you want to use more complex build pipelines, you can pack the shader cache manually.

To pack the shader cache manually

Run ShaderCacheGen.exe to generate the shader cache so you can pack it later.

Zip all the shaders into a ShaderCache.zip file, then rename the file to ShaderCache.pak.

Each platform has different .pak files. See the following
directory mapping for the PC platforms: