This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Rendering
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Materials and Shaders
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Animations-Related Classes
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
VR-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials

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.

Notice
DirectX shaders cache generated for debug builds should not be used for release builds, as shader compilation is performed without optimizations. Re-generate DirectX shaders cache for your release build for maximum performance (ensured by optimized compilation).

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.

Notice
The shaders cache should be generated for float- and double-precision builds separately, as each of them uses its own shader cache (i.e. cache generated for float precision is not suitable for a double-precision build). In case your application is released with both builds float and double, you'll have to generate shaders cache twice.

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.

Precompile All Shaders option on the toolbar and in the Editor section of the Settings window

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.
Notice
To minimize run-time recompilation of shaders for materials, whose states are to be changed via the application logic, you can also create separate materials having the required state values and switch between these materials instead of changing states.

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
Warning
Do not put shader cache files to UNG archives! You will not have a substantial file size reduction, as cache files already use LZ4 compression. Moreover, in this case new shaders, that can be generated on your end user's side, won't be added to 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:

Shell commands
-project_name "YourProject"
you should copy shader cache files to the following directory:
  • Windows — C:/Users/<username>/YourProject/
  • Linux — /home/<username>/.YourProject/
Last update: 2023-10-05
Build: ()