QQuickGraphicsConfiguration controls lower level graphics settings for the QQuickWindow. More...

#include <qquickgraphicsconfiguration.h>

Collaboration diagram for QQuickGraphicsConfiguration:

Public Member Functions
	QQuickGraphicsConfiguration ()
	Constructs a default QQuickGraphicsConfiguration that does not specify any additional settings for the scene graph to take into account.

	~QQuickGraphicsConfiguration ()
	Destructor.

	QQuickGraphicsConfiguration (const QQuickGraphicsConfiguration &other)

QQuickGraphicsConfiguration &	operator= (const QQuickGraphicsConfiguration &other)

void	setDeviceExtensions (const QByteArrayList &extensions)
	Sets the list of additional extensions to enable on the graphics device (such as, the `VkDevice`).

QByteArrayList	deviceExtensions () const

void	setDepthBufferFor2D (bool enable)
	Sets the usage of depth buffer for 2D content to enable.

bool	isDepthBufferEnabledFor2D () const

void	setDebugLayer (bool enable)
	Enables the graphics API implementation's debug or validation layers, if available.

bool	isDebugLayerEnabled () const

void	setDebugMarkers (bool enable)
	Where applicable, enable controls inserting debug markers and object names into the graphics command stream.

bool	isDebugMarkersEnabled () const

void	setTimestamps (bool enable)
	When enabled, GPU timing data is collected from command buffers on platforms and 3D APIs where this is supported.

bool	timestampsEnabled () const

void	setPreferSoftwareDevice (bool enable)
	Requests choosing an adapter or physical device that uses software-based rasterization.

bool	prefersSoftwareDevice () const

void	setAutomaticPipelineCache (bool enable)
	Changes the usage of the automatic pipeline cache based on enable.

bool	isAutomaticPipelineCacheEnabled () const

void	setPipelineCacheSaveFile (const QString &filename)
	Sets the filename where the QQuickWindow is expected to store its graphics/compute pipeline cache contents.

QString	pipelineCacheSaveFile () const

void	setPipelineCacheLoadFile (const QString &filename)
	Sets the filename where the QQuickWindow is expected to load the initial contents of its graphics/compute pipeline cache from.

QString	pipelineCacheLoadFile () const

Static Public Member Functions
static QByteArrayList	preferredInstanceExtensions ()

Friends
class	QQuickGraphicsConfigurationPrivate

Q_QUICK_EXPORT QDebug	operator<< (QDebug dbg, const QQuickGraphicsConfiguration &config)

Detailed Description

QQuickGraphicsConfiguration controls lower level graphics settings for the QQuickWindow.

Since: 6.0 \inmodule QtQuick

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()}.

Definition at line 15 of file qquickgraphicsconfiguration.h.

Constructor & Destructor Documentation

◆ QQuickGraphicsConfiguration() [1/2]

QQuickGraphicsConfiguration::QQuickGraphicsConfiguration ( )

Constructs a default QQuickGraphicsConfiguration that does not specify any additional settings for the scene graph to take into account.

Definition at line 327 of file qquickgraphicsconfiguration.cpp.

◆ ~QQuickGraphicsConfiguration()

QQuickGraphicsConfiguration::~QQuickGraphicsConfiguration ( )

Destructor.

Definition at line 361 of file qquickgraphicsconfiguration.cpp.

References QBasicAtomicInteger< T >::deref(), and QQuickGraphicsConfigurationPrivate::ref.

Here is the call graph for this function:

◆ QQuickGraphicsConfiguration() [2/2]

QQuickGraphicsConfiguration::QQuickGraphicsConfiguration ( const QQuickGraphicsConfiguration & other )

Definition at line 343 of file qquickgraphicsconfiguration.cpp.

References QBasicAtomicInteger< T >::ref(), and QQuickGraphicsConfigurationPrivate::ref.

Here is the call graph for this function:

Member Function Documentation

◆ deviceExtensions()

QByteArrayList QQuickGraphicsConfiguration::deviceExtensions ( ) const

Returns: the list of the requested additional device extensions.

Definition at line 412 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::deviceExtensions.

Referenced by QSGRhiSupport::createRhi().

Here is the caller graph for this function:

◆ isAutomaticPipelineCacheEnabled()

bool QQuickGraphicsConfiguration::isAutomaticPipelineCacheEnabled ( ) const

Returns: 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

See also: setAutomaticPipelineCache()

Definition at line 694 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::AutoPipelineCache, and QQuickGraphicsConfigurationPrivate::flags.

Referenced by QSGRhiSupport::createRhi().

Here is the caller graph for this function:

◆ isDebugLayerEnabled()

bool QQuickGraphicsConfiguration::isDebugLayerEnabled ( ) const

Returns: true if the debug/validation layers are to be enabled.

By default the value is false.

See also: setDebugLayer()

Definition at line 524 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::EnableDebugLayer, and QQuickGraphicsConfigurationPrivate::flags.

Referenced by QSGRhiSupport::createRhi(), and QQuickWidgetPrivate::rhiConfig().

Here is the caller graph for this function:

◆ isDebugMarkersEnabled()

bool QQuickGraphicsConfiguration::isDebugMarkersEnabled ( ) const

Returns: true if debug markers are enabled.

By default the value is false.

See also: setDebugMarkers()

Definition at line 570 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::EnableDebugMarkers, and QQuickGraphicsConfigurationPrivate::flags.

Referenced by QSGRhiSupport::createRhi().

Here is the caller graph for this function:

◆ isDepthBufferEnabledFor2D()

bool QQuickGraphicsConfiguration::isDepthBufferEnabledFor2D ( ) const

Returns: true if depth buffer usage is enabled for 2D content.

By default the value is true, unless the {QSG_NO_DEPTH_BUFFER} environment variable is set.

Definition at line 465 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::flags, and QQuickGraphicsConfigurationPrivate::UseDepthBufferFor2D.

◆ operator=()

QQuickGraphicsConfiguration & QQuickGraphicsConfiguration::operator= ( const QQuickGraphicsConfiguration & other )

Definition at line 352 of file qquickgraphicsconfiguration.cpp.

References other(), and qAtomicAssign().

Here is the call graph for this function:

◆ pipelineCacheLoadFile()

QString QQuickGraphicsConfiguration::pipelineCacheLoadFile ( ) const

Returns: the currently set filename for loading the pipeline cache.

By default the value is an empty string.

Definition at line 806 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::pipelineCacheLoadFile.

◆ pipelineCacheSaveFile()

QString QQuickGraphicsConfiguration::pipelineCacheSaveFile ( ) const

Returns: the currently set filename for storing the pipeline cache.

By default the value is an empty string.

Definition at line 746 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::pipelineCacheSaveFile.

Referenced by QSGRhiSupport::createRhi().

Here is the caller graph for this function:

◆ preferredInstanceExtensions()

QByteArrayList QQuickGraphicsConfiguration::preferredInstanceExtensions ( )

static

Returns: 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

Definition at line 382 of file qquickgraphicsconfiguration.cpp.

◆ prefersSoftwareDevice()

bool QQuickGraphicsConfiguration::prefersSoftwareDevice ( ) const

Returns: true if a software rasterizer-based graphics device is prioritized.

By default the value is false.

See also: setPreferSoftwareDevice()

Definition at line 659 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::flags, and QQuickGraphicsConfigurationPrivate::PreferSoftwareDevice.

Referenced by QSGRhiSupport::createRhi().

Here is the caller graph for this function:

◆ setAutomaticPipelineCache()

void QQuickGraphicsConfiguration::setAutomaticPipelineCache ( bool enable )

Changes the usage of the automatic pipeline cache based on 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

See also: isAutomaticPipelineCacheEnabled()

Definition at line 675 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::AutoPipelineCache, and QQuickGraphicsConfigurationPrivate::flags.

◆ setDebugLayer()

void QQuickGraphicsConfiguration::setDebugLayer ( bool enable )

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 enable is true, Qt will attempt to enable the standard validation layer on the VkInstance, or set {D3D11_CREATE_DEVICE_DEBUG} on the graphics device.

For Metal on \macos, set the environment variable {METAL_DEVICE_WRAPPER_TYPE=1} instead before launching the application.

Calling this function with enable set to true is equivalent to setting the environment variable {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.; 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

See also: isDebugLayerEnabled()

Definition at line 509 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::EnableDebugLayer, and QQuickGraphicsConfigurationPrivate::flags.

◆ setDebugMarkers()

void QQuickGraphicsConfiguration::setDebugMarkers ( bool enable )

Where applicable, 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 enable set to true is equivalent to setting the environment variable {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

See also: isDebugMarkersEnabled()

Definition at line 555 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::EnableDebugMarkers, and QQuickGraphicsConfigurationPrivate::flags.

◆ setDepthBufferFor2D()

void QQuickGraphicsConfiguration::setDepthBufferFor2D ( bool enable )

Sets the usage of depth buffer for 2D content to enable.

When disabled, the Qt Quick scene graph never writes into the depth buffer.

By default the value is true, unless the {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 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 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 {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 {QSG_NO_DEPTH_BUFFER} and {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.

Definition at line 451 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::flags, and QQuickGraphicsConfigurationPrivate::UseDepthBufferFor2D.

◆ setDeviceExtensions()

void QQuickGraphicsConfiguration::setDeviceExtensions ( const QByteArrayList & extensions )

Sets the list of additional extensions to enable on the graphics device (such as, the VkDevice).

When rendering with a graphics API where the concept is not applicable, extensions will be ignored.

Note: The list specifies additional, extra extensions. Qt Quick always enables extensions that are required by the scene graph.

Definition at line 401 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::deviceExtensions.

◆ setPipelineCacheLoadFile()

void QQuickGraphicsConfiguration::setPipelineCacheLoadFile ( const QString & filename )

Sets the 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 {QSG_RHI_PIPELINE_CACHE_LOAD} to 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.

Since: 6.5

See also: pipelineCacheLoadFile(), setPipelineCacheSaveFile()

Definition at line 793 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::pipelineCacheLoadFile.

◆ setPipelineCacheSaveFile()

void QQuickGraphicsConfiguration::setPipelineCacheSaveFile ( const QString & filename )

Sets the 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 {QSG_RHI_PIPELINE_CACHE_SAVE} to 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

See also: pipelineCacheLoadFile(), setPipelineCacheSaveFile()

Definition at line 733 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::pipelineCacheSaveFile.

◆ setPreferSoftwareDevice()

void QQuickGraphicsConfiguration::setPreferSoftwareDevice ( bool enable )

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 \l{https://docs.microsoft.com/en-us/windows/win32/direct3darticles/directx-warp}{WARP}-based rasterizer is always available. With Vulkan, the flag only has an effect if Mesa's lavapipe, or some other physical device reporting {VK_PHYSICAL_DEVICE_TYPE_CPU} is available.

Calling this function with enable set to true is equivalent to setting the environment variable {QSG_RHI_PREFER_SOFTWARE_RENDERER} to a non-zero value.

The default value is false.

Since: 6.5

See also: prefersSoftwareDevice()

Definition at line 644 of file qquickgraphicsconfiguration.cpp.

References QQuickGraphicsConfigurationPrivate::flags, and QQuickGraphicsConfigurationPrivate::PreferSoftwareDevice.

◆ setTimestamps()

void QQuickGraphicsConfiguration::setTimestamps ( bool enable )

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 {QSG_RENDER_TIMING} environment variable or logging categories such as {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 enable set to true, or set the {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.