Pre-Compiling Shaders

A shader is a small program executed on the GPU, and of course it takes some time to get compiled and loaded. Usually, compiling and loading a single GPU program does not take much time, but shaders often have a lot of "variants". Complex shaders have multiple preprocessor directives (defines) for various cases, each combination of these directives defines a shader variant. So we end up having to compile many thousands of slightly different GPU programs. Compiling shaders on demand at runtime causes freezes and requires extra memory. In order to reduce overhead, all required shader combinations are parsed, compiled, and stored in the shader cache. Loading precompiled shaders from cache is much faster.

Shader cache for OpenGL represents a pre-translation of shaders from UUSL to GLSL, not a compilation. It is generated 5-10 times faster than for DirectX but uses 5-6 times more disk space.

There are no special requirements for shaders caching such as installing or setting up any additional software.

Every time when the Engine fails to retrieve a shader from the cache, the required shader is compiled and added to cache automatically. However, this may cause your application to "hiccup" (freeze for a while). Which is totally unacceptable for many applications (e.g. real-time simulators). So, the point is that you should have the most complete shader cache containing all variants that are used in your application.

Precompilation of all shaders is an important feature guaranteeing, that at the time your project is completed and final builds are ready to be handed over to customers, you will have a complete shader cache. This significantly reduces the number of freezes in the final release build and smooths your application's framerate. Shaders are precompiled for all materials in the project.

This feature is available via the Precompile All Shaders button on the toolbar near the Play button or via the Editor section of the Settings window when a world is loaded.

You can use it in one of the following ways:

• Constant background precompilation

  When this button is enabled, each time you create a new material, you'll see the following message on shader compilation in the viewport:

  

  Notice

  You can stop the process of shaders cache generation in case the UnigineEditor's UI response has become too slow via the corresponding button right on the compilation message.

  Materials, for which the shaders were not yet compiled, will be temporarily replaced with base ones colored in grey and having no textures. This may take a couple of seconds depending on your computer's performance. This option guarantees, that you always have a complete shader cache for the selected graphics API.

• Precompilation on demand

  Sometimes constant background compilation of shaders may disturb and slow down your work, this is typical for some engines. UNIGINE lets you disable shaders precompilation. You can enable it just before measuring performance of your final build. In this case shader cache generation will take much more time (up to half an hour) depending on your project's complexity and selected graphics API. But it will be performed only once instead of slowing down your work each time you make changes to your materials.

  Notice

  This mode is recommended for graphics programmers to save time on recompilation when changing states of materials.

Forced shader precompilation ensures, that you have the most complete world-independent shaders cache for all materials in your project. However, changing some local settings, such as the ones for geodetic pivot, terrain, water, or clouds (e.g. changing some material state via the Tracker or your application logic) still leads to recompilation of shaders, but just a local one performed only for the corresponding type of objects.

The following actions should be performed to generate the most complete shader cache for your project:

1. Open all worlds, that contain geodetic pivot, terrain, water, or clouds.
2. For each of these worlds perform the following:
   • water - put a scene camera over water, under water and at the waterline between the two media.
   • terrain - put a scene camera high above the terrain and move it to the terrain surface.
   • clouds - put a scene camera over above the clouds, under the clouds and inside the clouds.
3. Create and launch tracks for all material states, that you plan to switch via your application's logic.

Output shader cache for DirectX / OpenGL / Vulkan is generated inside the data folder:

• DirectX 11 — shader_d3d11.cache
• DirectX 12 — shader_d3d12_dxc.cache, pso_log_d3d12_dxc.cache
• OpenGL — shader_gl.cache
• Vulkan — shader_vk.cache, pso_log_vk.cache

As your project is completed and final builds are ready to be handed over to customers, you should copy all shader cache files to the data directory of the final build.

If you pass a project name via the command line or on engine initialization:

-project_name "YourProject"

• Windows — C:/Users/<username>/YourProject/
• Linux — /home/<username>/.YourProject/