QSGRendererInterface Class
提供访问场景图的某些图形 API 特定内部功能的接口。更多
| 头文件： | #include <QSGRendererInterface> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Quick)target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake： | QT += quick |
公共类型
| 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 } |
公共函数
| 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 |
静态公共成员
| bool | isApiRhiBased(QSGRendererInterface::GraphicsApi api) |
详细说明
渲染器接口允许访问场景图中图形 API 的特定功能。此类内部结构通常不会公开。但是，在通过QSGRenderNode 等方式集成自定义渲染时，可能需要查询某些值，例如场景图使用的图形设备（如 Direct3D 或 Vulkan 设备）。
QSGRendererInterface 的功能具有不同的可用性。API 和语言查询，如graphicsApi() 或shaderType() 总是可用的，这意味着只需构建一个QQuickWindow 或QQuickView ，就可以通过QQuickWindow::rendererInterface() 直接查询正在使用的图形 API 或着色语言。这就保证了GraphicsInfo QML 类型等实用程序能够尽早报告正确的值，而不会出现条件属性值（例如取决于shaderType() ）评估为意外值的情况。
然而，特定于引擎的访问器（如getResource() ）只有在场景图初始化后才可用。此外，在调用这些函数时，可能会受到后端特定的限制。唯一能保证成功的方法是在渲染节点（即为下一帧准备命令列表）时调用它们。在实践中，这通常意味着QSGRenderNode::render().
成员类型文档
enum QSGRendererInterface::GraphicsApi
| 常数 | 值 | 说明 |
|---|---|---|
QSGRendererInterface::Unknown | 0 | 正在使用未知图形 API |
QSGRendererInterface::Software | 1 | 正在使用Qt Quick 2D 渲染器 |
QSGRendererInterface::OpenVG | 2 | 通过 EGL 使用 OpenVG |
QSGRendererInterface::OpenGL (since Qt 5.14) | 3 | 通过图形抽象层使用 OpenGL ES 2.0 或更高版本。 |
QSGRendererInterface::Direct3D11 (since Qt 5.14) | 4 | 通过图形抽象层使用 Direct3D 11。 |
QSGRendererInterface::Direct3D12 (since Qt 6.6) | 8 | 通过图形抽象层使用 Direct3D 12。 |
QSGRendererInterface::Vulkan (since Qt 5.14) | 5 | 通过图形抽象层使用 Vulkan 1.0。 |
QSGRendererInterface::Metal (since Qt 5.14) | 6 | 通过图形抽象层的 Metal |
QSGRendererInterface::Null (since Qt 5.14) | 7 | 通过图形抽象层的 Null（无输出）。 |
enum QSGRendererInterface::RenderMode
| 常数 | 值 | 描述 |
|---|---|---|
QSGRendererInterface::RenderMode2D | 0 | 正常 2D 渲染 |
QSGRendererInterface::RenderMode2DNoDepthBuffer | 1 | 禁用深度缓冲区的正常 2D 渲染 |
QSGRendererInterface::RenderMode3D | 2 | 场景作为 3D 图形的一部分进行渲染 |
enum QSGRendererInterface::Resource
| 常数 | 值 | 说明 |
|---|---|---|
QSGRendererInterface::DeviceResource | 0 | 资源是指向图形设备的指针（如适用）。例如，VkDevice * 、MTLDevice * 或ID3D11Device * 。请注意，对于 Vulkan，返回值是指向 VkDevice 的指针，而不是句柄本身。这是因为 Vulkan 句柄可能不是指针，而且使用的大小可能与架构的指针大小不同，因此仅仅将void * 转换成/转换成 Vulkan 句柄是错误的。 |
QSGRendererInterface::CommandQueueResource | 1 | 资源是指向场景图使用的图形命令队列的指针（如适用）。例如，VkQueue * 或MTLCommandQueue * 。请注意，对于 Vulkan，返回值是指向 VkQueue 的指针，而不是句柄本身。 |
QSGRendererInterface::CommandListResource | 2 | 资源是指向场景图使用的命令列表或缓冲区的指针（如适用）。例如，VkCommandBuffer * 或MTLCommandBuffer * 。该对象的有效期有限，仅在场景图准备下一帧时有效。请注意，对于 Vulkan，返回值是指向 VkCommandBuffer 的指针，而不是句柄本身。 |
QSGRendererInterface::PainterResource | 3 | 当使用软件后端运行时，该资源是指向场景图使用的活动QPainter 的指针。 |
QSGRendererInterface::RhiResource (since Qt 5.14) | 4 | 该资源是指向场景图使用的QRhi 实例的指针（如适用）。 |
QSGRendererInterface::RhiSwapchainResource (since Qt 6.0) | 5 | 该资源是指向与窗口相关联的 QRhiSwapchain 实例的指针。当窗口与QQuickRenderControl 结合使用时，该值为空。 |
QSGRendererInterface::RhiRedirectCommandBuffer (since Qt 6.0) | 6 | 该资源是指向QRhiCommandBuffer 实例的指针，该实例与窗口及其QQuickRenderControl 关联。当窗口未与QQuickRenderControl 关联时，该值为空。 |
QSGRendererInterface::RhiRedirectRenderTarget (since Qt 6.0) | 7 | 该资源是指向与窗口及其QQuickRenderControl 相关联的QRhiTextureRenderTarget 实例的指针。当窗口未与QQuickRenderControl 关联时，该值为空。请注意，该值始终反映主纹理渲染目标，且不依赖于Qt Quick 场景，这意味着它不会考虑ShaderEffect 或QQuickItem 图层生成的任何附加纹理目标渲染传递。 |
QSGRendererInterface::PhysicalDeviceResource (since Qt 5.14) | 8 | 资源是指向场景图使用的物理设备对象的指针（如适用）。VkPhysicalDevice *请注意，对于 Vulkan，返回值是指向 VkPhysicalDevice 的指针，而不是句柄本身。 |
QSGRendererInterface::OpenGLContextResource (since Qt 5.14) | 9 | 资源是指向场景图（在渲染线程上）使用的QOpenGLContext 的指针（如适用）。 |
QSGRendererInterface::DeviceContextResource (since Qt 5.14) | 10 | 该资源是指向场景图使用的设备上下文的指针（如适用）。例如，ID3D11DeviceContext * 。 |
QSGRendererInterface::CommandEncoderResource (since Qt 5.14) | 11 | 该资源是指向场景图使用的当前活动渲染命令编码器对象的指针（如适用）。例如，MTLRenderCommandEncoder * 。该对象的有效期有限，仅在场景图记录下一帧的渲染时有效。 |
QSGRendererInterface::VulkanInstanceResource (since Qt 5.14) | 12 | 资源是指向场景图使用的QVulkanInstance 的指针（如适用）。 |
QSGRendererInterface::RenderPassResource (since Qt 5.14) | 13 | 该资源是指向场景图使用的主渲染传递的指针，描述了颜色和深度/眩晕附件及其使用方式。例如，VkRenderPass * 。请注意，该值始终反映的是主渲染目标（屏幕窗口或纹理QQuickRenderControl 重定向到的纹理），它不依赖于Qt Quick 场景，也就是说，它不考虑ShaderEffect 或QQuickItem 图层生成的任何附加纹理目标渲染传递。 |
QSGRendererInterface::RedirectPaintDevice (since Qt 6.4) | 14 | 资源是指向QPaintDevice 实例的指针，该实例与窗口及其QQuickRenderControl 相关联。当窗口未与QQuickRenderControl 关联时，该值为空。 |
QSGRendererInterface::GraphicsQueueFamilyIndexResource (since Qt 6.6) | 15 | 资源是指向场景图使用的图形队列族索引的指针（如适用）。对于 Vulkan，这是指向uint32_t 索引值的指针。 |
QSGRendererInterface::GraphicsQueueIndexResource (since Qt 6.6) | 16 | 该资源是指向场景图使用的图形队列索引（uint32_t）的指针（如适用）。在使用 Vulkan 时，这是一个指向uint32_t 索引值的指针，实际上就是为CommandQueueResource 报告的 VkQueue 的索引。 |
枚举 QSGRendererInterface::ShaderCompilationType
标志 QSGRendererInterface::ShaderCompilationTypes
| 常量 | 值 | 描述 |
|---|---|---|
QSGRendererInterface::RuntimeCompilation | 0x01 | 支持着色器源代码的运行时编译 |
QSGRendererInterface::OfflineCompilation | 0x02 | 支持预编译字节码 |
ShaderCompilationTypes 类型是QFlags<ShaderCompilationType> 的类型定义。它存储 ShaderCompilationType 值的 OR 组合。
枚举 QSGRendererInterface::ShaderSourceType
flags QSGRendererInterface::ShaderSourceTypes
| 常量 | 值 | 描述 |
|---|---|---|
QSGRendererInterface::ShaderSourceString | 0x01 | 着色器源可以在包含着色器源的本地或资源文件的相应属性中以字符串形式提供。ShaderEffect |
QSGRendererInterface::ShaderSourceFile | 0x02 | 支持包含着色器源代码的本地文件或资源文件 |
QSGRendererInterface::ShaderByteCode | 0x04 | 支持包含着色器字节码的本地文件或资源文件 |
ShaderSourceTypes 类型是QFlags<ShaderSourceType> 的类型定义。它存储 ShaderSourceType 值的 OR 组合。
enum QSGRendererInterface::ShaderType
| 常数 | 值 | 说明 |
|---|---|---|
QSGRendererInterface::UnknownShadingLanguage | 0 | 由于未关联窗口和场景图，因此尚不清楚 |
QSGRendererInterface::GLSL | 1 | GLSL 或 GLSL ES |
QSGRendererInterface::HLSL | 2 | HLSL |
QSGRendererInterface::RhiShader (since Qt 5.14) | 3 | 消耗QShader 实例，该实例包含多种目标语言和中间格式的着色器变体。 |
成员函数文档
[virtual] void *QSGRendererInterface::getResource(QQuickWindow *window, QSGRendererInterface::Resource resource) const
查询window 中的图形resource 。如果相关资源不支持或不可用，则返回空值。
查询成功后，返回的指针要么是指向接口的直接指针，要么是指向需要先取消引用的不透明句柄的指针（例如VkDevice dev = *static_cast<VkDevice *>(result) ）。后者是必要的，因为此类句柄的大小可能与指针不同。
注意： 返回指针的所有权不会转移给调用者。
注意： 此函数只能在呈现线程上调用。
[virtual] void *QSGRendererInterface::getResource(QQuickWindow *window, const char *resource) const
查询图形资源。resource 是特定于后台的密钥。这样就可以支持资源枚举中未列出的任何未来资源。
注意： 返回指针的所有权不会转移给调用者。
注意： 此函数只能在呈现线程上调用。
[pure virtual] QSGRendererInterface::GraphicsApi QSGRendererInterface::graphicsApi() const
返回Qt Quick 场景图正在使用的图形 API。
注意： 此函数可在任何线程上调用。
[static] bool QSGRendererInterface::isApiRhiBased(QSGRendererInterface::GraphicsApi api)
如果api 基于图形抽象层 (QRhi) 而不是直接调用本地图形 API，则返回 true。
注意： 此函数可在任何线程上调用。
[pure virtual] QSGRendererInterface::ShaderCompilationTypes QSGRendererInterface::shaderCompilationType() const
返回应用程序正在使用的Qt Quick 后端所支持的着色器编译方法的位掩码。
注意： 此函数可在任何线程上调用。
另请参见 QtQuick::GraphicsInfo 。
[pure virtual] QSGRendererInterface::ShaderSourceTypes QSGRendererInterface::shaderSourceType() const
返回在ShaderEffect 项目中提供着色器源的受支持方式的位掩码。
注意： 此函数可在任何线程上调用。
另请参见 QtQuick::GraphicsInfo 。
[pure virtual] QSGRendererInterface::ShaderType QSGRendererInterface::shaderType() const
返回应用程序正在使用的Qt Quick 后端所支持的着色语言。
注： 此函数可在任何线程上调用。
另请参阅 QtQuick::GraphicsInfo 。
© 2025 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.
