qt/qtdeclarative/src/quick/items/qquickgraphicsconfiguration.cpp

Revision control

Copy as Markdown

// Copyright (C) 2020 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
#include "qquickgraphicsconfiguration_p.h"
#include <QCoreApplication>
#include <rhi/qrhi.h>
QT_BEGIN_NAMESPACE
/*!
\class QQuickGraphicsConfiguration
\since 6.0
\inmodule QtQuick
\brief QQuickGraphicsConfiguration controls lower level graphics settings
for the QQuickWindow.
The QQuickGraphicsConfiguration class is a container for low-level graphics
settings that can affect how the underlying graphics API, such as Vulkan,
is initialized by the Qt Quick scene graph. It can also control certain
aspects of the scene graph renderer.
\note Setting a QQuickGraphicsConfiguration on a QQuickWindow must happen
early enough, before the scene graph is initialized for the first time for
that window. With on-screen windows this means the call must be done before
invoking show() on the QQuickWindow or QQuickView. With QQuickRenderControl
the configuration must be finalized before calling
\l{QQuickRenderControl::initialize()}{initialize()}.
\section1 Configuration for External Rendering Engines or XR APIs
When constructing and showing a QQuickWindow that uses Vulkan to render, a
Vulkan instance (\c VkInstance), a physical device (\c VkPhysicalDevice), a
device (\c VkDevice) and associated objects (queues, pools) are initialized
through the Vulkan API. The same is mostly true when using
QQuickRenderControl to redirect the rendering into a custom render target,
such as a texture. While QVulkanInstance construction is under the
application's control then, the initialization of other graphics objects
happen the same way in QQuickRenderControl::initialize() as with an
on-screen QQuickWindow.
For the majority of applications no additional configuration is needed
because Qt Quick provides reasonable defaults for many low-level graphics
settings, for example which device extensions to enable.
This will not alway be sufficient, however. In advanced use cases, when
integrating direct Vulkan or other graphics API content, or when
integrating with an external 3D or VR engine, such as, OpenXR, the
application will want to specify its own set of settings when it comes to
details, such as which device extensions to enable.
That is what this class enables. It allows specifying, for example, a list
of device extensions that is then picked up by the scene graph when using
Vulkan, or graphics APIs where the concept is applicable. Where some
concepts are not applicable, the related settings are simply ignored.
Examples of functions in this category are setDeviceExtensions() and
preferredInstanceExtensions(). The latter is useful when the application
manages its own \l QVulkanInstance which is then associated with the
QQuickWindow via \l QWindow::setVulkanInstance().
\section1 Qt Quick Scene Graph Renderer Configuration
Another class of settings are related to the scene graph's renderer. In
some cases applications may want to control certain behavior,such as using
the depth buffer when rendering 2D content. In Qt 5 such settings were
either not controllable at all, or were managed through environment
variables. In Qt 6, QQuickGraphicsConfiguration provides a new home for
these settings, while keeping support for the legacy environment variables,
where applicable.
An example in this category is setDepthBufferFor2D().
\section1 Graphics Device Configuration
When the graphics instance and device objects (for example, the VkInstance
and VkDevice with Vulkan, the ID3D11Device with Direct 3D, etc.) are
created by Qt when initializing a QQuickWindow, there are settings which
applications or libraries will want to control under certain circumstances.
Before Qt 6.5, some of such settings were available to control via
environment variables. For example, \c QSG_RHI_DEBUG_LAYER or \c
QSG_RHI_PREFER_SOFTWARE_RENDERER. These are still available and continue to
function as before. QQuickGraphicsConfiguration provides C++ setters in
addition.
For example, the following main() function opens a QQuickView while
specifying that the Vulkan validation or Direct3D debug layer should be
enabled:
\code
int main(int argc, char *argv[])
{
QGuiApplication app(argc, argv);
QQuickGraphicsConfiguration config;
config.setDebugLayer(true);
QQuickView *view = new QQuickView;
view->setGraphicsConfiguration(config);
view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
view->show();
return app.exec();
}
\endcode
\section1 Pipeline Cache Save and Load
Qt Quick supports storing the graphics/compute pipeline cache to disk, and
reloading it in subsequent runs of an application. What exactly the
pipeline cache contains, how lookups work, and what exactly gets
accelerated all depend on the Qt RHI backend and the underlying native
graphics API that is used at run time. Different 3D APIs have different
concepts when it comes to shaders, programs, and pipeline state objects,
and corresponding cache mechanisms. The high level pipeline cache concept
here abstracts all this to storing and retrieving a single binary blob to
and from a file.
\note Storing the cache on disk can lead to improvements, sometimes
significant, in subsequent runs of the application.
When the same shader program and/or pipeline state is encountered as in a
previous run, a number of operations are likely skipped, leading to faster
shader and material initialization times, which means startup may become
faster and lags and "janks" during rendering may be reduced or avoided.
When running with a graphics API where retrieving and reloading the
pipeline cache (or shader/program binaries) is not applicable or not
supported, attempting to use a file to save and load the cache has no
effect.
\note In many cases the retrieved data is dependent on and tied to the
graphics driver (and possibly the exact version of it). Qt performs the
necessary checks automatically, by storing additional metadata in the
pipeline cache file. If the data in the file does not match the graphics
device and driver version at run time, the contents will be ignored
transparently to the application. It is therefore safe to reference a cache
that was generated on another device or driver.
There are exceptions to the driver dependency problem, most notably Direct
3D 11, where the "pipeline cache" is used only to store the results of
runtime HLSL->DXBC compilation and is therefore device and vendor
independent.
In some cases it may be desirable to improve the very first run of the
application, by "pre-seeding" the cache. This is possible by shipping the
cache file saved from a previous run, and referencing it on another machine
or device. This way, the application or device has the shader
programs/pipelines that have been encountered before in the run that saved
the cache file available already during its first run. Shipping and
deploying the cache file only makes sense if the device and graphics
drivers are the same on the target system, otherwise the cache file is
ignored if the device or driver version does not match (with the exception
of D3D11), as described above.
Once the cache contents is loaded, there is still a chance that the
application builds graphics and compute pipelines that have not been
encountered in previous runs. In this cases the cache is grown, with the
pipelines / shader programs added to it. If the application also chooses to
save the contents (perhaps to the same file even), then both the old and
new pipelines will get stored. Loading from and saving to the same file in
every run allows an ever growing cache that stores all encountered
pipelines and shader programs.
In practice the Qt pipeline cache can be expected to map to the following
native graphics API features:
\list
\li Vulkan -
- Saving the pipeline cache effectively stores the blob retrieved from
with additional metadata to safely identify the device and the driver
since the pipeline cache blob is dependent on the exact driver.
\li Metal -
- With pipeline cache saving enabled, Qt stores all render and compute
pipelines encountered into an MTLBinaryArchive. Saving the pipeline cache
stores the blob retrieved from the archive, with additional metadata to
identify the device. \b{Note:} currently MTLBinaryArchive usage is disabled
on macOS and iOS due to various issues on some hardware and OS versions.
\li OpenGL - There is no native concept of pipelines, the "pipeline cache"
stores a collection of program binaries retrieved via
The program binaries are packaged into a single blob, with additional
metadata to identify the device, driver, and its version that the binaries
were retrieved from. Persistent caching of program binaries is not new in
Qt: Qt 5 already had similar functionality in QOpenGLShaderProgram, see
\l{QOpenGLShaderProgram::}{addCacheableShaderFromSourceCode()}
for example. In fact that mechanism is always active in Qt 6 as well when
using Qt Quick with OpenGL. However, when using the new, graphics API
independent pipeline cache abstraction provided here, the Qt 5 era program
binary cache gets automatically disabled, since the same content is
packaged in the "pipeline cache" now.
\li Direct 3D 11 - There is no native concept of pipelines or retrieving
binaries for the second phase compilation (where the vendor independent,
intermediate bytecode is compiled into the device specific instruction
set). Drivers will typically employ their own caching system on that level.
Instead, the Qt Quick "pipeline cache" is used to speed up cases where the
shaders contain HLSL source code that needs to be compiled into the
intermediate bytecode format first. This can present significant
performance improvements in application and libraries that compose shader
code at run time, because in subsequent runs the potentially expensive,
uncached calls to
can be avoided if the bytecode is already available for the encountered
HLSL shader. A good example is Qt Quick 3D, where the runtime-generated
shaders for materials imply having to deal with HLSL source code. Saving
and reloading the Qt Quick pipeline cache can therefore bring considerable
improvements in scenes with one or more \l{View3D} items in
them. A counterexample may be Qt Quick itself: as most built-in shaders for
2D content ship with DirectX bytecode generated at build time, the cache is
not going to present any significant improvements.
\endlist
All this is independent from the shader processing performed by the
\l [QtShaderTools]{Qt Shader Tools} module and its command-line tools such
as \c qsb. As an example, take Vulkan. Having the Vulkan-compatible GLSL
source code compiled to SPIR-V either at offline or build time (directly
via qsb or CMake) is good, because the expensive compilation from source
form is avoided at run time. SPIR-V is however a vendor-independent
intermediate format. At runtime, when constructing graphics or compute
pipelines, there is likely another round of compilation happening, this
time from the intermediate format to the vendor-specific instruction set of
the GPU (and this may be dependent on certain state in the graphics
pipeline and the render targets as well). The pipeline cache helps with
this latter phase.
\note Many graphics API implementation employ their own persistent disk
cache transparently to the applications. Using the pipeline cache feature
of Qt Quick will likely provide improvements in this case, but the gains
might be smaller.
Call setPipelineCacheSaveFile() and setPipelineCacheLoadFile() to control
which files a QQuickWindow or QQuickView saves and loads the pipeline cache
to/from.
To get an idea of the effects of enabling disk storage of the pipeline
cache, enable the most important scenegraph and graphics logs either via
the environment variable \c{QSG_INFO=1}, or both the
\c{qt.scenegraph.general} and \c{qt.rhi.general} logging categories. When
closing the QQuickWindow, there is log message like the following:
\badcode
Total time spent on pipeline creation during the lifetime of the QRhi was 123 ms
\endcode
This gives an approximate idea of how much time was spent in graphics and
compute pipeline creation (which may include various stages of shader
compilation) during the lifetime of the window.
When loading from a pipeline cache file is enabled, this is confirmed with
a message:
\badcode
Attempting to seed pipeline cache from 'filename'
\endcode
Similarly, to check if saving of the cache is successfully enabled, look
for a message such as this:
\badcode
Writing pipeline cache contents to 'filename'
\endcode
\section1 The Automatic Pipeline Cache
When no filename is provided for save and load, the automatic pipeline
caching strategy is used. This involves storing data to the
application-specific cache location of the system (\l
QStandardPaths::CacheLocation).
This can be disabled by one of the following means:
\list
\li Set the application attribute Qt::AA_DisableShaderDiskCache.
(completely disables the automatic storage)
\li Set the environment variable QT_DISABLE_SHADER_DISK_CACHE to a non-zero
value. (completely disables the automatic storage)
\li Set the environment variable QSG_RHI_DISABLE_SHADER_DISK_CACHE to a
non-zero value. (completely disables the automatic storage)
\li Call setAutomaticPiplineCache() with the enable argument set to false.
(completely disables the automatic storage)
\li Set a filename by calling setPipelineCacheLoadFile(). (only disables
loading from the automatic storage, prefering the specified file instead)
\li Set a filename by calling setPipelineCacheSaveFile(). (only disables
writing to the automatic storage, prefering the specified file instead)
\endlist
The first two are existing mechanisms that are used since Qt 5.9 to control
the OpenGL program binary cache. For compatibility and familiarity the same
attribute and environment variable are supported for Qt 6's enhanced
pipeline cache.
The automatic pipeline cache uses a single file per application, but a
different one for each RHI backend (graphics API). This means that changing
to another graphics API in the next run of the application will not lead to
losing the pipeline cache generated in the previous run. Applications with
multiple QQuickWindow instances shown simultaneously may however not
benefit 100% since the automatic cache can only store the data collected
from one RHI object at a time. (and with the default \c threaded render
loop each window has its own RHI as rendering operates independently on
dedicated threads). To fully benefit from the disk cache in application
with multiple windows, prefer setting the filename explicitly, per-window
via setPipelineCacheSaveFile().
\sa QQuickWindow::setGraphicsConfiguration(), QQuickWindow, QQuickRenderControl
*/
/*!
Constructs a default QQuickGraphicsConfiguration that does not specify any
additional settings for the scene graph to take into account.
*/
QQuickGraphicsConfiguration::QQuickGraphicsConfiguration()
: d(new QQuickGraphicsConfigurationPrivate)
{
}
/*!
\internal
*/
void QQuickGraphicsConfiguration::detach()
{
qAtomicDetach(d);
}
/*!
\internal
*/
QQuickGraphicsConfiguration::QQuickGraphicsConfiguration(const QQuickGraphicsConfiguration &other)
: d(other.d)
{
d->ref.ref();
}
/*!
\internal
*/
QQuickGraphicsConfiguration &QQuickGraphicsConfiguration::operator=(const QQuickGraphicsConfiguration &other)
{
qAtomicAssign(d, other.d);
return *this;
}
/*!
Destructor.
*/
QQuickGraphicsConfiguration::~QQuickGraphicsConfiguration()
{
if (!d->ref.deref())
delete d;
}
/*!
\return the list of Vulkan instance extensions Qt Quick prefers to
have enabled on the VkInstance.
In most cases Qt Quick is responsible for creating a QVulkanInstance. This
function is not relevant then. On the other hand, when using
QQuickRenderControl in combination with Vulkan-based rendering, it is the
application's responsibility to create a QVulkanInstance and associate it
with the (offscreen) QQuickWindow. In this case, it is expected that the
application queries the list of instance extensions to enable, and passes
them to QVulkanInstance::setExtensions() before calling
QVulkanInstance::create().
\since 6.1
*/
QByteArrayList QQuickGraphicsConfiguration::preferredInstanceExtensions()
{
#if QT_CONFIG(vulkan)
return QRhiVulkanInitParams::preferredInstanceExtensions();
#else
return {};
#endif
}
/*!
Sets the list of additional \a extensions to enable on the graphics device
(such as, the \c VkDevice).
When rendering with a graphics API where the concept is not applicable, \a
extensions will be ignored.
\note The list specifies additional, extra extensions. Qt Quick always
enables extensions that are required by the scene graph.
*/
void QQuickGraphicsConfiguration::setDeviceExtensions(const QByteArrayList &extensions)
{
if (d->deviceExtensions != extensions) {
detach();
d->deviceExtensions = extensions;
}
}
/*!
\return the list of the requested additional device extensions.
*/
QByteArrayList QQuickGraphicsConfiguration::deviceExtensions() const
{
return d->deviceExtensions;
}
/*!
Sets the usage of depth buffer for 2D content to \a enable. When disabled,
the Qt Quick scene graph never writes into the depth buffer.
By default the value is true, unless the \c{QSG_NO_DEPTH_BUFFER}
environment variable is set.
The default value of true is the most optimal setting for the vast majority
of scenes. Disabling depth buffer usage reduces the efficiency of the scene
graph's batching.
There are cases however, when allowing the 2D content write to the depth
buffer is not ideal. Consider a 3D scene as an "overlay" on top the 2D
scene, rendered via Qt Quick 3D using a \l View3D with
\l{View3D::renderMode}{renderMode} set to \c Overlay. In this case, having
the depth buffer filled by 2D content can cause unexpected results. This is
because the way the 2D scene graph renderer generates and handles depth
values is not necessarily compatible with how a 3D scene works. This may end
up in depth value clashes, collisions, and unexpected depth test
failures. Therefore, the robust approach here is to call this function with
\a enable set to false, and disable depth buffer writes for the 2D content
in the QQuickWindow.
\note This flag is not fully identical to setting the
\c{QSG_NO_DEPTH_BUFFER} environment variable. This flag does not control the
depth-stencil buffers' presence. It is rather relevant for the rendering
pipeline. To force not having depth/stencil attachments at all, set
\c{QSG_NO_DEPTH_BUFFER} and \c{QSG_NO_STENCIL_BUFFER}. Be aware however
that such a QQuickWindow, and any Item layers in it, may then become
incompatible with items, such as View3D with certain operating modes,
because 3D content requires a depth buffer. Calling this function is always
safe, but can mean that resources, such as depth buffers, are created even
though they are not actively used.
*/
void QQuickGraphicsConfiguration::setDepthBufferFor2D(bool enable)
{
if (d->flags.testFlag(QQuickGraphicsConfigurationPrivate::UseDepthBufferFor2D) != enable) {
detach();
d->flags.setFlag(QQuickGraphicsConfigurationPrivate::UseDepthBufferFor2D, enable);
}
}
/*!
\return true if depth buffer usage is enabled for 2D content.
By default the value is true, unless the \c{QSG_NO_DEPTH_BUFFER}
environment variable is set.
*/
bool QQuickGraphicsConfiguration::isDepthBufferEnabledFor2D() const
{
return d->flags.testFlag(QQuickGraphicsConfigurationPrivate::UseDepthBufferFor2D);
}
/*!
Enables the graphics API implementation's debug or validation layers, if
available.
In practice this is supported with Vulkan and Direct 3D 11, assuming the
necessary support (validation layers, Windows SDK) is installed and
available at runtime. When \a enable is true, Qt will attempt to enable the
standard validation layer on the VkInstance, or set
\c{D3D11_CREATE_DEVICE_DEBUG} on the graphics device.
For Metal on \macos, set the environment variable
\c{METAL_DEVICE_WRAPPER_TYPE=1} instead before launching the application.
Calling this function with \a enable set to true is equivalent to setting
the environment variable \c{QSG_RHI_DEBUG_LAYER} to a non-zero value.
The default value is false.
\note Enabling debug or validation layers may have a non-insignificant
performance impact. Shipping applications to production with the flag
enabled is strongly discouraged.
\note Be aware that due to differences in the design of the underlying
graphics APIs, this setting cannot always be a per-QQuickWindow setting,
even though each QQuickWindow has their own QQuickGraphicsConfiguration.
With Vulkan in particular, the instance object (VkInstance) is only created
once and then used by all windows in the application. Therefore, enabling
the validation layer is something that affects all windows. This also means
that attempting to enable validation via a window that only gets shown after
some other windows have already started rendering has no effect with Vulkan.
Other APIs, such as D3D11, expose the debug layer concept as a per-device
(ID3D11Device) setting, and so it is controlled on a true per-window basis
(assuming the scenegraph render loop uses a dedicated graphics
device/context for each QQuickWindow).
\since 6.5
\sa isDebugLayerEnabled()
*/
void QQuickGraphicsConfiguration::setDebugLayer(bool enable)
{
if (d->flags.testFlag(QQuickGraphicsConfigurationPrivate::EnableDebugLayer) != enable) {
detach();
d->flags.setFlag(QQuickGraphicsConfigurationPrivate::EnableDebugLayer, enable);
}
}
/*!
\return true if the debug/validation layers are to be enabled.
By default the value is false.
\sa setDebugLayer()
*/
bool QQuickGraphicsConfiguration::isDebugLayerEnabled() const
{
return d->flags.testFlag(QQuickGraphicsConfigurationPrivate::EnableDebugLayer);
}
/*!
Where applicable, \a enable controls inserting debug markers and object
names into the graphics command stream.
Some frameworks, such as Qt Quick 3D, have the ability to annotate the
graphics objects they create (buffers, textures) with names and also
indicate the beginning and end of render passes in the command buffer. These
are then visible in frame captures made with tools like
\l{https://renderdoc.org/}{RenderDoc} or XCode.
Graphics APIs where this can be expected to be supported are Vulkan (if
VK_EXT_debug_utils is available), Direct 3D 11, and Metal.
Calling this function with \a enable set to true is equivalent to setting
the environment variable \c{QSG_RHI_PROFILE} to a non-zero
value.
The default value is false.
\note Enabling debug markers may have a performance impact. Shipping
applications to production with the flag enabled is not recommended.
\since 6.5
\sa isDebugMarkersEnabled()
*/
void QQuickGraphicsConfiguration::setDebugMarkers(bool enable)
{
if (d->flags.testFlag(QQuickGraphicsConfigurationPrivate::EnableDebugMarkers) != enable) {
detach();
d->flags.setFlag(QQuickGraphicsConfigurationPrivate::EnableDebugMarkers, enable);
}
}
/*!
\return true if debug markers are enabled.
By default the value is false.
\sa setDebugMarkers()
*/
bool QQuickGraphicsConfiguration::isDebugMarkersEnabled() const
{
return d->flags.testFlag(QQuickGraphicsConfigurationPrivate::EnableDebugMarkers);
}
/*!
When enabled, GPU timing data is collected from command buffers on
platforms and 3D APIs where this is supported. This data is then printed in
the renderer logs that can be enabled via \c{QSG_RENDER_TIMING} environment
variable or logging categories such as \c{qt.scenegraph.time.renderloop},
and may also be made visible to other modules, such as Qt Quick 3D's
\l DebugView item.
By default this is disabled, because collecting the data may involve
additional work, such as inserting timestamp queries in the command stream,
depending on the underlying graphics API. To enable, either call this
function with \a enable set to true, or set the \c{QSG_RHI_PROFILE}
environment variable to a non-zero value.
Graphics APIs where this can be expected to be supported are Direct 3D 11,
Direct 3D 12, Vulkan (as long as the underlying Vulkan implementation
supports timestamp queries), Metal, and OpenGL with a core or compatibility
profile context for version 3.3 or newer. Timestamps are not supported with
OpenGL ES.
\since 6.6
\sa timestampsEnabled(), setDebugMarkers()
*/
void QQuickGraphicsConfiguration::setTimestamps(bool enable)
{
if (d->flags.testFlag(QQuickGraphicsConfigurationPrivate::EnableTimestamps) != enable) {
detach();
d->flags.setFlag(QQuickGraphicsConfigurationPrivate::EnableTimestamps, enable);
}
}
/*!
\return true if GPU timing collection is enabled.
By default the value is false.
\since 6.6
\sa setTimestamps()
*/
bool QQuickGraphicsConfiguration::timestampsEnabled() const
{
return d->flags.testFlag(QQuickGraphicsConfigurationPrivate::EnableTimestamps);
}
/*!
Requests choosing an adapter or physical device that uses software-based
rasterization. Applicable only when the underlying API has support for
enumerating adapters (for example, Direct 3D or Vulkan), and is ignored
otherwise.
If the graphics API implementation has no such graphics adapter or physical
device available, the request is ignored. With Direct 3D it can be expected
that a
rasterizer is always available. With Vulkan, the flag only has an effect if
Mesa's \c lavapipe, or some other physical device reporting
\c{VK_PHYSICAL_DEVICE_TYPE_CPU} is available.
Calling this function with \a enable set to true is equivalent to setting
the environment variable \c{QSG_RHI_PREFER_SOFTWARE_RENDERER} to a non-zero
value.
The default value is false.
\since 6.5
\sa prefersSoftwareDevice()
*/
void QQuickGraphicsConfiguration::setPreferSoftwareDevice(bool enable)
{
if (d->flags.testFlag(QQuickGraphicsConfigurationPrivate::PreferSoftwareDevice) != enable) {
detach();
d->flags.setFlag(QQuickGraphicsConfigurationPrivate::PreferSoftwareDevice, enable);
}
}
/*!
\return true if a software rasterizer-based graphics device is prioritized.
By default the value is false.
\sa setPreferSoftwareDevice()
*/
bool QQuickGraphicsConfiguration::prefersSoftwareDevice() const
{
return d->flags.testFlag(QQuickGraphicsConfigurationPrivate::PreferSoftwareDevice);
}
/*!
Changes the usage of the automatic pipeline cache based on \a enable.
The default value is true, unless certain application attributes or
environment variables are set. See \l{The Automatic Pipeline Cache} for
more information.
\since 6.5
\sa isAutomaticPipelineCacheEnabled()
*/
void QQuickGraphicsConfiguration::setAutomaticPipelineCache(bool enable)
{
if (d->flags.testFlag(QQuickGraphicsConfigurationPrivate::AutoPipelineCache) != enable) {
detach();
d->flags.setFlag(QQuickGraphicsConfigurationPrivate::AutoPipelineCache, enable);
}
}
/*!
\return true if the automatic pipeline cache is enabled.
By default this is true, unless certain application attributes or
environment variables are set. See \l{The Automatic Pipeline Cache} for
more information.
\since 6.5
\sa setAutomaticPipelineCache()
*/
bool QQuickGraphicsConfiguration::isAutomaticPipelineCacheEnabled() const
{
return d->flags.testFlag(QQuickGraphicsConfigurationPrivate::AutoPipelineCache);
}
/*!
Sets the \a filename where the QQuickWindow is expected to store its
graphics/compute pipeline cache contents. The default value is empty, which
means pipeline cache loading is disabled.
See \l{Pipeline Cache Save and Load} for a discussion on pipeline caches.
Persistently storing the pipeline cache can lead to performance
improvements in future runs of the application since expensive shader
compilation and pipeline construction steps may be avoided.
If and when the writing of the file happens is not defined. It will likely
happen at some point when tearing down the scenegraph due to closing the
window. Therefore, applications should not assume availability of the file
until the QQuickWindow is fully destructed. QQuickGraphicsConfiguration
only stores the filename, it does not perform any actual I/O and graphics
operations on its own.
When running with a graphics API where retrieving the pipeline cache (or
shader/program binaries) is not applicable or not supported, calling this
function has no effect.
Calling this function is mostly equivalent to setting the environment
variable \c{QSG_RHI_PIPELINE_CACHE_SAVE} to \a filename, with one important
difference: this function controls the pipeline cache storage for the
associated QQuickWindow only. Applications with multiple QQuickWindow or
QQuickView instances can therefore store and later reload the cache contents
via files dedicated to each window. The environment variable does not allow
this.
\since 6.5
\sa pipelineCacheLoadFile(), pipelineCacheSaveFile()
*/
void QQuickGraphicsConfiguration::setPipelineCacheSaveFile(const QString &filename)
{
if (d->pipelineCacheSaveFile != filename) {
detach();
d->pipelineCacheSaveFile = filename;
}
}
/*!
\return the currently set filename for storing the pipeline cache.
By default the value is an empty string.
*/
QString QQuickGraphicsConfiguration::pipelineCacheSaveFile() const
{
return d->pipelineCacheSaveFile;
}
/*!
Sets the \a filename where the QQuickWindow is expected to load the initial
contents of its graphics/compute pipeline cache from. The default value is
empty, which means pipeline cache loading is disabled.
See \l{Pipeline Cache Save and Load} for a discussion on pipeline caches.
Persistently storing the pipeline cache can lead to performance
improvements in future runs of the application since expensive shader
compilation and pipeline construction steps may be avoided.
If and when the loading of the file's contents happens is not defined, apart
from that it will happen at some point during the initialization of the
scenegraph of the QQuickWindow. Therefore, the file must continue to exist
after calling this function. QQuickGraphicsConfiguration only stores the
filename, it cannot perform any actual I/O and graphics operations on its
own. The real work is going to happen later on, possibly on another thread.
When running with a graphics API where retrieving and reloading the
pipeline cache (or shader/program binaries) is not applicable or not
supported, calling this function has no effect.
Calling this function is mostly equivalent to setting the environment
variable \c{QSG_RHI_PIPELINE_CACHE_LOAD} to \a filename, with one important
difference: this function controls the pipeline cache storage for the
associated QQuickWindow only. Applications with multiple QQuickWindow or
QQuickView instances can therefore store and later reload the cache contents
via files dedicated to each window. The environment variable does not allow
this.
\note If the data in the file does not match the graphics device and driver
version at run time, the contents will be ignored, transparently to the
application. This applies to a number of graphics APIs, and the necessary
checks are taken care of by Qt. There are exceptions, most notably Direct
3D 11, where the "pipeline cache" is used only to store the results of
runtime HLSL->DXBC compilation and is therefore device and vendor
independent.
\warning The serialized pipeline cache data is assumed to be trusted
content. Application developers are advised to never pass in data from
untrusted sources.
\since 6.5
\sa pipelineCacheLoadFile(), setPipelineCacheSaveFile()
*/
void QQuickGraphicsConfiguration::setPipelineCacheLoadFile(const QString &filename)
{
if (d->pipelineCacheLoadFile != filename) {
detach();
d->pipelineCacheLoadFile = filename;
}
}
/*!
\return the currently set filename for loading the pipeline cache.
By default the value is an empty string.
*/
QString QQuickGraphicsConfiguration::pipelineCacheLoadFile() const
{
return d->pipelineCacheLoadFile;
}
QQuickGraphicsConfigurationPrivate::QQuickGraphicsConfigurationPrivate()
: ref(1)
{
// Defaults based on env.vars. NB! many of these variables are documented
// and should be considered (semi-)public API. Changing the env.var. names
// is therefore not allowed.
flags = {};
static const bool useDepthBufferFor2D = qEnvironmentVariableIsEmpty("QSG_NO_DEPTH_BUFFER");
if (useDepthBufferFor2D)
flags |= UseDepthBufferFor2D;
static const bool enableDebugLayer = qEnvironmentVariableIntValue("QSG_RHI_DEBUG_LAYER");
if (enableDebugLayer)
flags |= EnableDebugLayer;
static const bool enableProfilingRelated = qEnvironmentVariableIntValue("QSG_RHI_PROFILE");
if (enableProfilingRelated)
flags |= EnableDebugMarkers | EnableTimestamps;
static const bool preferSoftwareDevice = qEnvironmentVariableIntValue("QSG_RHI_PREFER_SOFTWARE_RENDERER");
if (preferSoftwareDevice)
flags |= PreferSoftwareDevice;
// here take the existing QOpenGL disk cache attribute and env.var. into account as well
static const bool autoPipelineCache = !QCoreApplication::instance()->testAttribute(Qt::AA_DisableShaderDiskCache)
&& !qEnvironmentVariableIntValue("QT_DISABLE_SHADER_DISK_CACHE")
&& !qEnvironmentVariableIntValue("QSG_RHI_DISABLE_DISK_CACHE");
if (autoPipelineCache)
flags |= AutoPipelineCache;
static const QString pipelineCacheSaveFileEnv = qEnvironmentVariable("QSG_RHI_PIPELINE_CACHE_SAVE");
pipelineCacheSaveFile = pipelineCacheSaveFileEnv;
static const QString pipelineCacheLoadFileEnv = qEnvironmentVariable("QSG_RHI_PIPELINE_CACHE_LOAD");
pipelineCacheLoadFile = pipelineCacheLoadFileEnv;
}
QQuickGraphicsConfigurationPrivate::QQuickGraphicsConfigurationPrivate(const QQuickGraphicsConfigurationPrivate &other)
: ref(1),
deviceExtensions(other.deviceExtensions),
flags(other.flags),
pipelineCacheSaveFile(other.pipelineCacheSaveFile),
pipelineCacheLoadFile(other.pipelineCacheLoadFile)
{
}
#ifndef QT_NO_DEBUG_STREAM
QDebug operator<<(QDebug dbg, const QQuickGraphicsConfiguration &config)
{
QDebugStateSaver saver(dbg);
const QQuickGraphicsConfigurationPrivate *cd = QQuickGraphicsConfigurationPrivate::get(&config);
dbg.nospace() << "QQuickGraphicsConfiguration("
<< "flags=0x" << Qt::hex << cd->flags << Qt::dec
<< " flag-isDepthBufferEnabledFor2D=" << config.isDepthBufferEnabledFor2D()
<< " flag-isDebugLayerEnabled=" << config.isDebugLayerEnabled()
<< " flag-isDebugMarkersEnabled=" << config.isDebugMarkersEnabled()
<< " flag-prefersSoftwareDevice=" << config.prefersSoftwareDevice()
<< " flag-isAutomaticPipelineCacheEnabled=" << config.isAutomaticPipelineCacheEnabled()
<< " pipelineCacheSaveFile=" << cd->pipelineCacheSaveFile
<< " piplineCacheLoadFile=" << cd->pipelineCacheLoadFile
<< " extra-device-extension-requests=" << cd->deviceExtensions
<< ')';
return dbg;
}
#endif // QT_NO_DEBUG_STREAM
QT_END_NAMESPACE