QRhiTextureRenderTargetDescription Class
描述渲染目标的颜色和深度，或深度/模板附件。更多...
| 标题： | #include <rhi/qrhi.h> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS GuiPrivate) 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.12) int | depthLayer() 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.12) void | setDepthLayer(int depthLayer) |
(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 }));以下代码创建了一个纹理渲染目标，该目标配置为指向纹理的第 2 级 MIP：
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 作为（多采样）颜色缓冲区，然后解析为常规的（非多采样）2D 纹理。 为了启用深度测试，还需使用一个深度-模板缓冲区，该缓冲区必须使用相同的采样数：
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 default] 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.12] int QRhiTextureRenderTargetDescription::depthLayer() const
返回用于深度/模板附加的数组切片索引，默认为 -1。
该函数于 Qt 6.12 中引入。
另请参阅 setDepthLayer() 和setDepthTexture()。
[since 6.8] QRhiTexture *QRhiTextureRenderTargetDescription::depthResolveTexture() const
返回多采样深度（或深度-模板）纹理（或纹理数组）解析到的目标纹理。若不存在该纹理（这是最常见的情况），则返回nullptr 。
该函数在 Qt 6.8 中引入。
另请参阅 setDepthResolveTexture()、QRhiColorAttachment::resolveTexture() 和depthTexture()。
QRhiRenderBuffer *QRhiTextureRenderTargetDescription::depthStencilBuffer() const
返回用作深度-模板缓冲区的渲染缓冲区，若未设置则返回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.12] void QRhiTextureRenderTargetDescription::setDepthLayer(int depthLayer)
设置用于深度/模板附加的数组切片索引。
传递 -1（默认值）表示不针对特定层。当设置为非负值时，渲染目标将附加一个视图，该视图精确针对深度纹理的该层（切片）。此设置仅在通过 `setDepthTexture()` 提供二维数组深度纹理时有效；否则该值将被忽略。
该值必须在深度纹理的数组大小范围内；传递超出范围的索引将导致未定义行为。该索引相对于底层纹理是绝对的，无论创建纹理时是否指定了数组范围。
指定depthLayer 将禁用深度附件的分层/多视图渲染。
该函数在 Qt 6.12 中引入。
另请参阅 depthLayer() 和setDepthTexture()。
[since 6.8] void QRhiTextureRenderTargetDescription::setDepthResolveTexture(QRhiTexture *tex)
设置深度（或深度-模板）解析纹理 `tex`。
tex 该纹理应为一个 2D 纹理或 2D 纹理数组，其格式需与通过setDepthTexture() 设置的纹理格式一致。
注意： 深度（或深度-模板）数据的解析 仅在运行时报告支持QRhi::ResolveDepthStencil 功能时才有效。并非所有图形 API 都支持深度-模板解析。因此，假设深度-模板解析无条件可用而进行的设计是不具备可移植性的，应予以避免。
注意： 特别是对于 OpenGL ES而言，还有 一项额外限制： 设置深度解析纹理仅在与setDepthTexture() 结合使用时才有效，而不能与setDepthStencilBuffer() 结合使用。
该函数在 Qt 6.8 中引入。
另请参阅 depthResolveTexture()、QRhiColorAttachment::setResolveTexture() 和setDepthTexture()。
void QRhiTextureRenderTargetDescription::setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)
设置深度-模板的renderBuffer 。此设置并非强制要求，例如，当该渲染目标的任何渲染通道中，其图形管道均未使用深度测试/写入或与模板相关的功能时，可将其保留为nullptr 。
注意： depthStencilBuffer() 和depthTexture() 不能同时设置（即不能同时为非空）。
将QRhiRenderBuffer 作为深度或深度/模板缓冲区，而非 2DQRhiTexture ，是一种非常常见的做法，也是推荐给应用程序的方法。 如果深度数据需要在后续被访问（例如在着色器中采样），或者涉及multiview rendering （因为此时深度纹理必须是纹理数组），则应使用QRhiTexture ，此时setDepthTexture()就变得重要了。
另请参阅 depthStencilBuffer() 和setDepthTexture()。
void QRhiTextureRenderTargetDescription::setDepthTexture(QRhiTexture *texture)
设置深度-模板的texture 。这是setDepthStencilBuffer()的替代方案，其中不使用QRhiRenderBuffer ，而是提供一个类型合适的QRhiTexture （例如，QRhiTexture::D32F ）。
注意： depthStencilBuffer() 和depthTexture() 不能同时设置（不能同时为非空）。
texture 可以是 2D 纹理，也可以是 2D 纹理数组（当支持纹理数组时）。指定纹理数组在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()。
© 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.
