QRhiTextureRenderTargetDescription Class
描述渲染目标的颜色和深度或深度/模板附件。更多
| 头文件： | #include <rhi/qrhi.h> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate) |
| qmake： | QT += gui-private |
| 自 | Qt 6.6 |
公共函数
| QRhiTextureRenderTargetDescription() | |
| QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment) | |
| QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiRenderBuffer *depthStencilBuffer) | |
| QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiTexture *depthTexture) | |
| const QRhiColorAttachment * | cbeginColorAttachments() const |
| const QRhiColorAttachment * | cendColorAttachments() const |
| const QRhiColorAttachment * | colorAttachmentAt(qsizetype index) const |
| qsizetype | colorAttachmentCount() const |
(since 6.8) QRhiTexture * | depthResolveTexture() const |
| QRhiRenderBuffer * | depthStencilBuffer() const |
| QRhiTexture * | depthTexture() const |
| void | setColorAttachments(std::initializer_list<QRhiColorAttachment> list) |
| void | setColorAttachments(InputIterator first, InputIterator last) |
(since 6.8) void | setDepthResolveTexture(QRhiTexture *tex) |
| void | setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer) |
| void | setDepthTexture(QRhiTexture *texture) |
(since 6.9) void | setShadingRateMap(QRhiShadingRateMap *map) |
(since 6.9) QRhiShadingRateMap * | shadingRateMap() const |
详细说明
纹理渲染目标有零个或多个纹理作为颜色附件，零个或一个渲染缓冲器作为深度/模板组合缓冲器，或者零个或一个纹理作为深度缓冲器。
注意： depthStencilBuffer() 和depthTexture() 不能同时设置（不能同时为非空）。
让我们看看结合QRhiTextureRenderTarget 使用的一些示例。
由于使用了构造函数，因此纹理（没有深度/模版缓冲区）的目标设置非常简单：
QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(256, 256), 1, QRhiTexture::RenderTarget); texture->create(); QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ texture }));
下面将创建一个纹理渲染目标，并将其设置为纹理的 mip 层 #2：
QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget | QRhiTexture::MipMapped); texture->create(); QRhiColorAttachment colorAtt(texture); colorAtt.setLevel(2); QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt });
另一个例子，这次是渲染深度纹理：
QRhiTexture *shadowMap = rhi->newTexture(QRhiTexture::D32F, QSize(1024, 1024), 1, QRhiTexture::RenderTarget); shadowMap->create(); QRhiTextureRenderTargetDescription rtDesc; rtDesc.setDepthTexture(shadowMap); QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);
这是一种非常常见的情况，将纹理作为色彩附件，将渲染缓冲区作为深度/模版，以实现深度测试：
QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget); texture->create(); QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512)); depthStencil->create(); QRhiTextureRenderTargetDescription rtDesc({ texture }, depthStencil); QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);
最后，为了以可移植的方式实现多采样渲染（因此也支持 OpenGL ES 3.0），使用QRhiRenderBuffer 作为（多采样）色彩缓冲区，然后解析为常规（非多采样）二维纹理。为了进行深度测试，还使用了深度模版缓冲区，该缓冲区也必须使用相同的采样计数：
QRhiRenderBuffer *colorBuffer = rhi->newRenderBuffer(QRhiRenderBuffer::Color, QSize(512, 512), 4); // 4x MSAA colorBuffer->create(); QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512), 4); depthStencil->create(); QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget); texture->create(); QRhiColorAttachment colorAtt(colorBuffer); colorAtt.setResolveTexture(texture); QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt, depthStencil });
注意： 启用多采样解析时，可能根本不会写出多采样数据。这意味着只要设置了解析纹理，之后就不能将色彩附件中的多采样纹理用于着色器采样（或其他用途），因为多采样色彩缓冲区只是一个中间存储，在某些 GPU 架构上根本不会写回数据。详情请参见PreserveColorContents 。
注： 当使用setDepthTexture() 而非setDepthStencilBuffer() 时，如果深度（模版）数据之后不再需要，可在QRhiTextureRenderTarget 上设置 DoNotStoreDepthStencilContents 标志。这样就可以向底层 3D API 表明深度/模版数据可以丢弃，从而有可能在使用平铺 GPU 架构时获得更好的性能。当深度/模版缓冲区为QRhiRenderBuffer （以及多采样颜色纹理，参见前注）时，这一点是隐式的，但对于深度（模版）QRhiTexture ，则需要明确声明这一意图。默认情况下，QRhi 假定数据是相关的（例如，深度纹理会在之后的着色器中采样）。
注： 这是一个兼容性保障有限的 RHI API，详情请参见QRhi 。
另请参阅 QRhiColorAttachment 和QRhiTextureRenderTarget 。
成员函数文档
[constexpr noexcept] QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription()
构建一个空的纹理渲染目标描述。
QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment)
构建一个纹理渲染目标描述，其中包含一个由colorAttachment 描述的附件。
QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiRenderBuffer *depthStencilBuffer)
构建包含两个附件的纹理渲染目标描述，其中一个是由colorAttachment 描述的颜色附件，另一个是由depthStencilBuffer 描述的深度/模版附件。
QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiTexture *depthTexture)
构建带有两个附件的纹理渲染目标描述，其中一个是由colorAttachment 描述的颜色附件，另一个是由depthTexture 描述的深度附件。
注意： depthTexture 必须有合适的格式，如QRhiTexture::D16 或QRhiTexture::D32F 。
const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cbeginColorAttachments() const
返回指向附件列表中第一个项目的常量迭代器。
const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cendColorAttachments() const
返回一个常量迭代器，指向附件列表中的最后一个项目。
const QRhiColorAttachment *QRhiTextureRenderTargetDescription::colorAttachmentAt(qsizetype index) const
返回指定index 的颜色附件。
qsizetype QRhiTextureRenderTargetDescription::colorAttachmentCount() const
返回当前设置的颜色附件数量。
[since 6.8] QRhiTexture *QRhiTextureRenderTargetDescription::depthResolveTexture() const
返回多采样深度（或深度模版）纹理（或纹理数组）解析到的纹理。如果没有（这是最常见的情况），则返回nullptr 。
此函数在 Qt 6.8 中引入。
另请参阅 setDepthResolveTexture()、QRhiColorAttachment::resolveTexture() 和depthTexture()。
QRhiRenderBuffer *QRhiTextureRenderTargetDescription::depthStencilBuffer() const
返回用作深度模版缓冲区的 renderbuffer，如果没有设置，则返回nullptr 。
另请参见 setDepthStencilBuffer().
QRhiTexture *QRhiTextureRenderTargetDescription::depthTexture() const
返回当前引用的深度纹理，如果没有设置深度纹理，则返回nullptr 。
另请参阅 setDepthTexture()。
void QRhiTextureRenderTargetDescription::setColorAttachments(std::initializer_list<QRhiColorAttachment> list)
设置list 颜色附件。
template <typename InputIterator> void QRhiTextureRenderTargetDescription::setColorAttachments(InputIterator first, InputIterator last)
通过迭代器first 和last 设置颜色附件列表。
[since 6.8] void QRhiTextureRenderTargetDescription::setDepthResolveTexture(QRhiTexture *tex)
设置深度（或深度模版）解析纹理tex 。
tex 预计为二维纹理或二维纹理数组，其格式与通过 () 设置的纹理相匹配。setDepthTexture
注： 解析深度（或深度模版）数据只有在运行时报告支持QRhi::ResolveDepthStencil 功能时才有效。图形 API 并不普遍支持深度模版解析。因此，假设深度钢网解析无条件可用的设计是不可移植的，应避免使用。
注意： 作为对 OpenGL ES 的额外限制，设置深度解析纹理可能只能与setDepthTexture() 结合使用，而不能与setDepthStencilBuffer() 结合使用。
此函数在 Qt 6.8 中引入。
另请参阅 depthResolveTexture()、QRhiColorAttachment::setResolveTexture() 和setDepthTexture()。
void QRhiTextureRenderTargetDescription::setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)
设置深度模版的renderBuffer 。并非必须设置，例如，当该渲染目标的任何渲染通道中的任何图形流水线都没有使用深度测试/写入或模版相关功能时，可将其设置为nullptr 。
注意： depthStencilBuffer() 和depthTexture() 不能同时设置（不能同时为非空）。
在二维QRhiTexture 上使用QRhiRenderBuffer 作为深度或深度/模版缓冲区是非常常见的，也是推荐的应用方法。如果深度数据需要事后访问（如在着色器中采样），或涉及multiview rendering 时（因为此时深度纹理必须是纹理数组），使用QRhiTexture 和setDepthTexture() 将变得非常重要。
另请参见 depthStencilBuffer() 和setDepthTexture()。
void QRhiTextureRenderTargetDescription::setDepthTexture(QRhiTexture *texture)
设置深度模版的texture 。这是setDepthStencilBuffer() 的一种替代方法，在这种方法中，提供的不是QRhiRenderBuffer ，而是具有合适类型（如QRhiTexture::D32F ）的QRhiTexture 。
注意： depthStencilBuffer() 和depthTexture() 不能同时设置（不能同时为非空）。
texture 可以是二维纹理，也可以是二维纹理数组（支持纹理数组时）。指定纹理数组尤其与 相关。multiview rendering
注意： 如果texture 是带有模版组件的格式，如QRhiTexture::D24S8 ，它也将作为模版缓冲区。
另请参阅 depthTexture() 和setDepthStencilBuffer()。
[since 6.9] void QRhiTextureRenderTargetDescription::setShadingRateMap(QRhiShadingRateMap *map)
与指定的QRhiShadingRateMap map 关联。只有在报告支持QRhi::VariableRateShadingMap 功能时，该功能才起作用。
当同时调用QRhiCommandBuffer::setShadingRate() 时，每个磁贴将使用两个着色率中较高的一个。目前还无法控制组合器的行为。
注意： 如果渲染目标已经创建（成功调用 create()），设置着色率贴图意味着需要一个不同的、新的QRhiRenderPassDescriptor ，因此需要重建。请再次调用 setRenderPassDescriptor()（在渲染传递之外），然后通过调用 create() 进行重建。这还会带来其他滚动后果，例如图形管道：这些管道也需要与新的QRhiRenderPassDescriptor 关联，然后重建。有关如何处理这一问题的建议，请参见QRhiRenderPassDescriptor::serializedFormat() 。记住也要设置QRhiGraphicsPipeline::UsesShadingRate 标志。
此功能在 Qt 6.9 中引入。
另请参见 shadingRateMap()。
[since 6.9] QRhiShadingRateMap *QRhiTextureRenderTargetDescription::shadingRateMap() const
返回当前设置的QRhiShadingRateMap 。默认情况下为nullptr 。
此函数在 Qt 6.9 中引入。
另请参阅 setShadingRateMap()。
© 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.
