qtquick3d-shadercache.qdoc

Go to the documentation of this file.

// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\title Persistent Caching of Shaders with Qt Quick 3D
\page quick3d-shadercache
 
\section1 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:
 
\list
 
\li The shader source texts are generated.
 
\li The shaders are sent through \l{Qt Shader Tools}{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.
 
\li When the 3D engine creates a \l{QRhiGraphicsPipeline}{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.
 
\endlist
 
All this together can be a costly operation. To avoid this in subsequent runs of
the application, two persistent, disk-based caches are employed.
 
\section1 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 \l{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 \l 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.
 
\section1 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 \l{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 \l{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.
 
\note Just as with the low-level shader and pipeline cache, this requires a
writable filesystem and that the platform provides a writable cache location via
QStandardPaths.
 
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.
 
\note The \c qml tool sets this attribute by default. Pass the
\c{--enable-shader-cache} command-line argument to get a behavior identical to
standalone Qt applications.
 
*/