QSGRendererInterface Class

An interface providing access to some of the graphics API specific internals of the scenegraph. More...

Header: #include <QSGRendererInterface>
CMake: find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick

Public Types

enum GraphicsApi { Unknown, Software, OpenVG, OpenGL, Direct3D11, …, Null }
enum RenderMode { RenderMode2D, RenderMode2DNoDepthBuffer, RenderMode3D }
enum Resource { DeviceResource, CommandQueueResource, CommandListResource, PainterResource, RhiResource, …, GraphicsQueueIndexResource }
enum ShaderCompilationType { RuntimeCompilation, OfflineCompilation }
flags ShaderCompilationTypes
enum ShaderSourceType { ShaderSourceString, ShaderSourceFile, ShaderByteCode }
flags ShaderSourceTypes
enum ShaderType { UnknownShadingLanguage, GLSL, HLSL, RhiShader }

Public Functions

virtual void *getResource(QQuickWindow *window, QSGRendererInterface::Resource resource) const
virtual void *getResource(QQuickWindow *window, const char *resource) const
virtual QSGRendererInterface::GraphicsApi graphicsApi() const = 0
virtual QSGRendererInterface::ShaderCompilationTypes shaderCompilationType() const = 0
virtual QSGRendererInterface::ShaderSourceTypes shaderSourceType() const = 0
virtual QSGRendererInterface::ShaderType shaderType() const = 0

Static Public Members

bool isApiRhiBased(QSGRendererInterface::GraphicsApi api)

Detailed Description

Renderer interfaces allow accessing graphics API specific functionality in the scenegraph. Such internals are not typically exposed. However, when integrating custom rendering via QSGRenderNode for example, it may become necessary to query certain values, for instance the graphics device (e.g. the Direct3D or Vulkan device) that is used by the scenegraph.

QSGRendererInterface's functions have varying availability. API and language queries, such as, graphicsApi() or shaderType() are always available, meaning it is sufficient to construct a QQuickWindow or QQuickView, and the graphics API or shading language in use can be queried right after via QQuickWindow::rendererInterface(). This guarantees that utilities like the GraphicsInfo QML type are able to report the correct values as early as possible, without having conditional property values - depending on for instance shaderType() - evaluate to unexpected values.

Engine-specific accessors, like getResource(), are however available only after the scenegraph is initialized. Additionally, there may be backend-specific limitations on when such functions can be called. The only way that is guaranteed to succeed is calling them when the rendering of a node (i.e. the preparation of the command list for the next frame) is active. In practice this typically means QSGRenderNode::render().

Member Type Documentation

enum QSGRendererInterface::GraphicsApi

ConstantValueDescription
QSGRendererInterface::Unknown0An unknown graphics API is in use
QSGRendererInterface::Software1The Qt Quick 2D Renderer is in use
QSGRendererInterface::OpenVG2OpenVG via EGL
QSGRendererInterface::OpenGL (since Qt 5.14)3OpenGL ES 2.0 or higher via a graphics abstraction layer.
QSGRendererInterface::Direct3D11 (since Qt 5.14)4Direct3D 11 via a graphics abstraction layer.
QSGRendererInterface::Direct3D12 (since Qt 6.6)8Direct3D 12 via a graphics abstraction layer.
QSGRendererInterface::Vulkan (since Qt 5.14)5Vulkan 1.0 via a graphics abstraction layer.
QSGRendererInterface::Metal (since Qt 5.14)6Metal via a graphics abstraction layer.
QSGRendererInterface::Null (since Qt 5.14)7Null (no output) via a graphics abstraction layer.

enum QSGRendererInterface::RenderMode

ConstantValueDescription
QSGRendererInterface::RenderMode2D0Normal 2D rendering
QSGRendererInterface::RenderMode2DNoDepthBuffer1Normal 2D rendering with depth buffer disabled
QSGRendererInterface::RenderMode3D2Scene is rendered as part of a 3D graph

enum QSGRendererInterface::Resource

ConstantValueDescription
QSGRendererInterface::DeviceResource0The resource is a pointer to the graphics device, when applicable. For example, a VkDevice *, MTLDevice * or ID3D11Device *. Note that with Vulkan the returned value is a pointer to the VkDevice, not the handle itself. This is because Vulkan handles may not be pointers, and may use a different size from the architecture's pointer size so merely casting to/from void * is wrong.
QSGRendererInterface::CommandQueueResource1The resource is a pointer to the graphics command queue used by the scenegraph, when applicable. For example, a VkQueue * or MTLCommandQueue *. Note that with Vulkan the returned value is a pointer to the VkQueue, not the handle itself.
QSGRendererInterface::CommandListResource2The resource is a pointer to the command list or buffer used by the scenegraph, when applicable. For example, a VkCommandBuffer * or MTLCommandBuffer *. This object has limited validity, and is only valid while the scene graph is preparing the next frame. Note that with Vulkan the returned value is a pointer to the VkCommandBuffer, not the handle itself.
QSGRendererInterface::PainterResource3The resource is a pointer to the active QPainter used by the scenegraph, when running with the software backend.
QSGRendererInterface::RhiResource (since Qt 5.14)4The resource is a pointer to the QRhi instance used by the scenegraph, when applicable.
QSGRendererInterface::RhiSwapchainResource (since Qt 6.0)5The resource is a pointer to a QRhiSwapchain instance that is associated with the window. The value is null when the window is used in combination with QQuickRenderControl.
QSGRendererInterface::RhiRedirectCommandBuffer (since Qt 6.0)6The resource is a pointer to a QRhiCommandBuffer instance that is associated with the window and its QQuickRenderControl. The value is null when the window is not associated with a QQuickRenderControl.
QSGRendererInterface::RhiRedirectRenderTarget (since Qt 6.0)7The resource is a pointer to a QRhiTextureRenderTarget instance that is associated with the window and its QQuickRenderControl. The value is null when the window is not associated with a QQuickRenderControl. Note that the value always reflects the main texture render target and it does not depend on the Qt Quick scene, meaning it does not take any additional texture-targeting render passes generated by ShaderEffect or QQuickItem layers into account.
QSGRendererInterface::PhysicalDeviceResource (since Qt 5.14)8The resource is a pointer to the pysical device object used by the scenegraph, when applicable. For example, a VkPhysicalDevice *. Note that with Vulkan the returned value is a pointer to the VkPhysicalDevice, not the handle itself.
QSGRendererInterface::OpenGLContextResource (since Qt 5.14)9The resource is a pointer to the QOpenGLContext used by the scenegraph (on the render thread), when applicable.
QSGRendererInterface::DeviceContextResource (since Qt 5.14)10The resource is a pointer to the device context used by the scenegraph, when applicable. For example, a ID3D11DeviceContext *.
QSGRendererInterface::CommandEncoderResource (since Qt 5.14)11The resource is a pointer to the currently active render command encoder object used by the scenegraph, when applicable. For example, a MTLRenderCommandEncoder *. This object has limited validity, and is only valid while the scene graph is recording a render pass for the next frame.
QSGRendererInterface::VulkanInstanceResource (since Qt 5.14)12The resource is a pointer to the QVulkanInstance used by the scenegraph, when applicable.
QSGRendererInterface::RenderPassResource (since Qt 5.14)13The resource is a pointer to the main render pass used by the scenegraph, describing the color and depth/stecil attachments and how they are used. For example, a VkRenderPass *. Note that the value always reflects the main render target (either the on-screen window or the texture QQuickRenderControl redirects to) and it does not depend on the Qt Quick scene, meaning it does not take any additional texture-targeting render passes generated by ShaderEffect or QQuickItem layers into account.
QSGRendererInterface::RedirectPaintDevice (since Qt 6.4)14The resource is a pointer to QPaintDevice instance that is associated with the window and its QQuickRenderControl. The value is null when the window is not associated with a QQuickRenderControl.
QSGRendererInterface::GraphicsQueueFamilyIndexResource (since Qt 6.6)15The resource is a pointer to the graphics queue family index used by the scenegraph, when applicable. With Vulkan, this is a pointer to a uint32_t index value.
QSGRendererInterface::GraphicsQueueIndexResource (since Qt 6.6)16The resource is a pointer to the graphics queue index (uint32_t) used by the scenegraph, when applicable. With Vulkan, this is a pointer to a uint32_t index value, which in practice is the index of the VkQueue reported for CommandQueueResource.

enum QSGRendererInterface::ShaderCompilationType
flags QSGRendererInterface::ShaderCompilationTypes

ConstantValueDescription
QSGRendererInterface::RuntimeCompilation0x01Runtime compilation of shader source code is supported
QSGRendererInterface::OfflineCompilation0x02Pre-compiled bytecode supported

The ShaderCompilationTypes type is a typedef for QFlags<ShaderCompilationType>. It stores an OR combination of ShaderCompilationType values.

enum QSGRendererInterface::ShaderSourceType
flags QSGRendererInterface::ShaderSourceTypes

ConstantValueDescription
QSGRendererInterface::ShaderSourceString0x01Shader source can be provided as a string in the corresponding properties of ShaderEffect
QSGRendererInterface::ShaderSourceFile0x02Local or resource files containing shader source code are supported
QSGRendererInterface::ShaderByteCode0x04Local or resource files containing shader bytecode are supported

The ShaderSourceTypes type is a typedef for QFlags<ShaderSourceType>. It stores an OR combination of ShaderSourceType values.

enum QSGRendererInterface::ShaderType

ConstantValueDescription
QSGRendererInterface::UnknownShadingLanguage0Not yet known due to no window and scenegraph associated
QSGRendererInterface::GLSL1GLSL or GLSL ES
QSGRendererInterface::HLSL2HLSL
QSGRendererInterface::RhiShader (since Qt 5.14)3Consumes QShader instances containing shader variants for multiple target languages and intermediate formats.

Member Function Documentation

[virtual] void *QSGRendererInterface::getResource(QQuickWindow *window, QSGRendererInterface::Resource resource) const

Queries a graphics resource in window. Returns null when the resource in question is not supported or not available.

When successful, the returned pointer is either a direct pointer to an interface, or a pointer to an opaque handle that needs to be dereferenced first (for example, VkDevice dev = *static_cast<VkDevice *>(result)). The latter is necessary since such handles may have sizes different from a pointer.

Note: The ownership of the returned pointer is never transferred to the caller.

Note: This function must only be called on the render thread.

[virtual] void *QSGRendererInterface::getResource(QQuickWindow *window, const char *resource) const

Queries a graphics resource. resource is a backend-specific key. This allows supporting any future resources that are not listed in the Resource enum.

Note: The ownership of the returned pointer is never transferred to the caller.

Note: This function must only be called on the render thread.

[pure virtual] QSGRendererInterface::GraphicsApi QSGRendererInterface::graphicsApi() const

Returns the graphics API that is in use by the Qt Quick scenegraph.

Note: This function can be called on any thread.

[static] bool QSGRendererInterface::isApiRhiBased(QSGRendererInterface::GraphicsApi api)

Returns true if api is based on a graphics abstraction layer (QRhi) instead of directly calling the native graphics API.

Note: This function can be called on any thread.

[pure virtual] QSGRendererInterface::ShaderCompilationTypes QSGRendererInterface::shaderCompilationType() const

Returns a bitmask of the shader compilation approaches supported by the Qt Quick backend the application is using.

Note: This function can be called on any thread.

See also QtQuick::GraphicsInfo.

[pure virtual] QSGRendererInterface::ShaderSourceTypes QSGRendererInterface::shaderSourceType() const

Returns a bitmask of the supported ways of providing shader sources in ShaderEffect items.

Note: This function can be called on any thread.

See also QtQuick::GraphicsInfo.

[pure virtual] QSGRendererInterface::ShaderType QSGRendererInterface::shaderType() const

Returns the shading language supported by the Qt Quick backend the application is using.

Note: This function can be called on any thread.

See also QtQuick::GraphicsInfo.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.