Persistent Caching of Shaders with Qt Quick 3D

Shaders and 3D Materials

Rendering a 3D object with a material involves a vertex and fragment shader.

The following happens at run time when a material is encountered for the first time during the lifetime of a 3D scene:

• The shader source texts are generated.
• The shaders are sent through the standard Qt shader pipeline. The result is an intermediate bytecode version of the shader (SPIR-V), a number of source code variants for other 3D APIs (GLSL for OpenGL, HLSL for Direct3D, etc.), and additional metadata.
• When the 3D engine creates a graphics pipeline, a bytecode or source variant suitable for the 3D API used is chosen, and then the underlying 3D API will likely perform a second-phase compilation targeting the actual GPU instruction set.

All this together can be a costly operation. To avoid this in subsequent runs of the application, two persistent, disk-based caches are employed.

Low-level Cache

Qt Quick 3D builds on Qt Quick and the scenegraph. When it comes to persistent, disk-based caching of OpenGL program binaries, Vulkan pipelines, etc., the same infrastructure is used.

See QQuickGraphicsConfiguration#Pipeline Cache Save and Load for a detailed discussion of this.

By default the shader disk cache is enabled. This means that even when the platform or 3D API implementation does not perform its own persistent caching of compiled shaders, Qt may still store the OpenGL program binaries or similar assets that get collected during the lifetime of a QQuickWindow. Writing the data to disk happens when the window is closed, and it is reloaded on the next run of the application. This way the creation of graphics pipelines may be significantly faster when the shaders were encountered during previous runs of the application.

The shaders to 3D materials and post-processing effects participate in this too.

Material Shader Cache

Unlike Qt Quick, Qt Quick 3D currently relies on run time generation of the shader source texts for 3D materials and effects. The exception for this is when the Shadergen Tool is used, however that feature is experimental and is not recommended for production use at the moment.

Generating the shader source texts and then performing the first-phase compilation and transpilation (see Qt Shader Tools for details) can be an expensive operation. For 2D materials and effects this typically happens at build time, whereas for 3D that is not an option currently.

Therefore, Qt Quick 3D employs another disk-based cache. This stores the assets for the generated 3D materials and effects.

This means that, in combination with the low-level cache, a 3D scene with a material that has been encountered during the previous runs of the application will not lead to an expensive, blocking operation when encountered again in subsequent runs.

The application attribute Qt::AA_DisableShaderDiskCache and the corresponding environment variable apply to the material shader cache as well. When set, both Qt's low-level and Qt Quick 3D's material cache will get disabled.