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 或着色语言。 这保证了诸如 QML 类型 `GraphicsInfo ` 之类的实用工具能够尽早报告正确的值，而不会因依赖于 `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 * 类型是错误的。 |
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 结合使用时，该值为 null。 |
QSGRendererInterface::RhiRedirectCommandBuffer (since Qt 6.0) | 6 | 该资源是与窗口及其QQuickRenderControl 关联的QRhiCommandBuffer 实例的指针。当窗口未与QQuickRenderControl 关联时，该值为null。 |
QSGRendererInterface::RhiRedirectRenderTarget (since Qt 6.0) | 7 | 该资源是与窗口及其QQuickRenderControl 关联的QRhiTextureRenderTarget 实例的指针。当窗口未关联QQuickRenderControl 时，该值为null。请注意，该值始终反映主纹理渲染目标，且不依赖于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 相关联时，该值为 null。 |
QSGRendererInterface::GraphicsQueueFamilyIndexResource (since Qt 6.6) | 15 | 该资源是场景图所用图形队列家族索引的指针（如适用）。在 Vulkan 中，这是指向uint32_t 索引值的指针。 |
QSGRendererInterface::GraphicsQueueIndexResource (since Qt 6.6) | 16 | 该资源是一个指向场景图所用图形队列索引（uint32_t）的指针（如适用）。在 Vulkan 中，这是一个指向uint32_t 索引值的指针，实际上即为CommandQueueResource 报告的 VkQueue 索引。 |
enum QSGRendererInterface::ShaderCompilationType
flags QSGRendererInterface::ShaderCompilationTypes
| 常数 | 值 | 描述 |
|---|---|---|
QSGRendererInterface::RuntimeCompilation | 0x01 | 支持着色器源代码的运行时编译 |
QSGRendererInterface::OfflineCompilation | 0x02 | 支持预编译字节码 |
ShaderCompilationTypes 类型是QFlags<ShaderCompilationType> 的 typedef 定义。它存储 ShaderCompilationType 值的按“或”运算组合。
enum QSGRendererInterface::ShaderSourceType
flags QSGRendererInterface::ShaderSourceTypes
| 常数 | 值 | 描述 |
|---|---|---|
QSGRendererInterface::ShaderSourceString | 0x01 | 着色器源代码可以作为字符串提供在ShaderEffect |
QSGRendererInterface::ShaderSourceFile | 0x02 | 支持包含着色器源代码的本地文件或资源文件 |
QSGRendererInterface::ShaderByteCode | 0x04 | 支持包含着色器字节码的本地文件或资源文件 |
ShaderSourceTypes 类型是QFlags<ShaderSourceType> 的 typedef。它存储 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 。如果所查询的资源不受支持或不可用，则返回null。
成功时，返回的指针要么是直接指向某个接口的指针，要么是指向一个需要先进行解引用（例如VkDevice dev = *static_cast<VkDevice *>(result) ）的不透明句柄的指针。后者是必要的，因为此类句柄的大小可能与普通指针不同。
注意： 返回指针的所有权 绝不会转移给调用方。
注意：此 函数必须仅在渲染线程上调用。
[virtual] void *QSGRendererInterface::getResource(QQuickWindow *window, const char *resource) const
查询图形资源。resource 是后端特有的键。这使得系统能够支持 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 。
© 2026 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.
