QSGRendererInterface 类
提供对场景图一些图形 API 特定内部访问的接口。更多...
| 头文件 | #include <QSGRendererInterface> |
| CMake | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake | QT += quick |
公共类型
| 枚举 | GraphicsApi { Unknown, Software, OpenVG, OpenGL, Direct3D11, …, Null } |
| 枚举 | RenderMode { RenderMode2D, RenderMode2DNoDepthBuffer, RenderMode3D } |
| 枚举 | Resource { DeviceResource, CommandQueueResource, CommandListResource, PainterResource, RhiResource, …, GraphicsQueueIndexResource } |
| 枚举 | ShaderCompilationType { RuntimeCompilation, OfflineCompilation } |
| 标志 | ShaderCompilationTypes |
| 枚举 | ShaderSourceType { ShaderSourceString, ShaderSourceFile, ShaderByteCode } |
| 标志 | ShaderSourceTypes |
| 枚举 | 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。
成员类型文档
枚举 QSGRendererInterface::GraphicsApi
| 常量 | 值 | 描述 |
|---|---|---|
QSGRendererInterface::Unknown | 0 | 正在使用未知的图形 API |
QSGRendererInterface::Software | 1 | 正在使用 Qt Quick 2D 渲染器 |
QSGRendererInterface::OpenVG | 2 | 通过 EGL 的 OpenVG |
QSGRendererInterface::OpenGL (自 Qt 5.14) | 3 | OpenGL ES 2.0 或更高版本通过图形抽象层 |
QSGRendererInterface::Direct3D11 (自 Qt 5.14) | 4 | 通过图形抽象层使用 Direct3D 11 |
QSGRendererInterface::Direct3D12 (自 Qt 6.6) | 8 | 通过图形抽象层使用 Direct3D 12 |
QSGRendererInterface::Vulkan (自 Qt 5.14) | 5 | 通过图形抽象层使用 Vulkan 1.0 |
QSGRendererInterface::Metal (自 Qt 5.14) | 6 | 通过图形抽象层使用 Metal |
QSGRendererInterface::Null (自 Qt 5.14) | 7 | 通过图形抽象层使用 Null（无输出） |
枚举 QSGRendererInterface::RenderMode
| 常量 | 值 | 描述 |
|---|---|---|
QSGRendererInterface::RenderMode2D | 0 | 普通 2D 渲染 |
QSGRendererInterface::RenderMode2DNoDepthBuffer | 1 | 普通 2D 渲染（禁用深度缓冲区） |
QSGRendererInterface::RenderMode3D | 2 | 场景以 3D 图的形式渲染 |
枚举 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（自 Qt 5.14 开始） | 4 | 该资源是指向在适用的情况下场景图使用的 QRhi 实例的指针。 |
QSGRendererInterface::RhiSwapchainResource（自 Qt 6.0 开始） | 5 | 该资源是指向与窗口关联的 QRhiSwapchain 实例的指针。当窗口与 QQuickRenderControl 结合使用时，值为空。 |
QSGRendererInterface::RhiRedirectCommandBuffer（自 Qt 6.0 开始） | 6 | 该资源是指向与窗口及其 QQuickRenderControl 关联的 QRhiCommandBuffer 实例的指针。当窗口未与 QQuickRenderControl 关联时，值为空。 |
QSGRendererInterface::RhiRedirectRenderTarget（自 Qt 6.0 开始） | 7 | 该资源是指向与窗口及其 QQuickRenderControl 关联的 QRhiTextureRenderTarget 实例的指针。当窗口未与 QQuickRenderControl 关联时，值为空。注意，该值始终反映了主纹理渲染目标，它与 Qt Quick 场景无关，这意味着它不会考虑到由 ShaderEffect 或 QQuickItem 层生成的任何额外的纹理目标渲染过程。 |
QSGRendererInterface::PhysicalDeviceResource（自 Qt 5.14 开始） | 8 | 当适用时，该资源是指向场景图使用的物理设备对象（例如，VkPhysicalDevice *）的指针。注意，在 Vulkan 中，返回值是指向 VkPhysicalDevice 的指针，而不是句柄本身。 |
QSGRendererInterface::OpenGLContextResource（自 Qt 5.14 开始） | 9 | 当适用时，该资源是指向场景图使用的（在渲染线程上）QOpenGLContext 的指针。 |
QSGRendererInterface::DeviceContextResource（自 Qt 5.14 开始） | 10 | 当适用时，该资源是指向场景图使用的设备上下文的指针（例如，ID3D11DeviceContext *）。 |
QSGRendererInterface::CommandEncoderResource（自 Qt 5.14 开始） | 11 | 当适用时，该资源是指向当前活动的渲染命令编码器对象（例如，MTLRenderCommandEncoder *）的指针。该对象的有效性有限，仅在场景图记录下一帧的渲染过程时有效。 |
QSGRendererInterface::VulkanInstanceResource（自 Qt 5.14 开始） | 12 | 当适用时，该资源是指向场景图使用的 QVulkanInstance 的指针。 |
QSGRendererInterface::RenderPassResource（自 Qt 5.14 开始） | 13 | 该资源是指向场景图使用的主要渲染过程的指针，描述了颜色和深度/暗度附加物以及它们的使用方式。例如，VkRenderPass *。注意，该值始终反映了主渲染目标（无论是屏幕窗口还是 QQuickRenderControl 重定向到的纹理）且它与 Qt Quick 场景无关，这意味着它不会考虑到由 ShaderEffect 或 QQuickItem 层生成的任何额外的纹理目标渲染过程。 |
QSGRendererInterface::RedirectPaintDevice（自 Qt 6.4 开始） | 14 | 该资源是指向与窗口及其 QQuickRenderControl 关联的 QPaintDevice 实例的指针。当窗口未与 QQuickRenderControl 关联时，值为空。 |
QSGRendererInterface::GraphicsQueueFamilyIndexResource（自 Qt 6.6 开始） | 15 | 当适用时，该资源是指向场景图使用的图形队列族索引的指针。在 Vulkan 中，这是一个指向 uint32_t 索引值的指针。 |
QSGRendererInterface::GraphicsQueueIndexResource（自 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 值的按位或组合。
enum QSGRendererInterface::ShaderType
| 常量 | 值 | 描述 |
|---|---|---|
QSGRendererInterface::UnknownShadingLanguage | 0 | 由于没有窗口和场景图而尚不清楚 |
QSGRendererInterface::GLSL | 1 | GLSL 或 GLSL ES |
QSGRendererInterface::HLSL | 2 | HLSL |
QSGRendererInterface::RhiShader (自 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。
注意：此函数可以在任何线程上调用。
[纯虚函数] QSGRendererInterface::ShaderCompilationTypes QSGRendererInterface::shaderCompilationType() const
返回一个位掩码，表示应用程序使用的Qt Quick后端所支持的着色器编译方法。
注意：此函数可以在任何线程上调用。
[纯虚函数] QSGRendererInterface::ShaderSourceTypes QSGRendererInterface::shaderSourceType() const
返回一个位掩码，表示在ShaderEffect项目中提供着色器源的方式。
注意：此函数可以在任何线程上调用。
[纯虚函数] QSGRendererInterface::ShaderType QSGRendererInterface::shaderType() const
返回应用程序使用的Qt Quick后端所支持的着色语言。
注意：此函数可以在任何线程上调用。
© 2024 Qt公司有限公司。此处包含的文档贡献归各自所有者所有。此处提供的文档受GNU自由文档许可证版本1.3的条款约束，由自由软件基金会发布。Qt及其相关标志是芬兰的Qt公司及其在世界各地的分公司和关联公司的商标。所有其他商标均为其各自所有者的财产。
