QRhiTextureRenderTarget 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 |
| 继承自： | QRhiRenderTarget |
公共类型
| enum | Flag { PreserveColorContents, PreserveDepthStencilContents, DoNotStoreDepthStencilContents } |
| flags | Flags |
公共函数
| virtual bool | create() = 0 |
| QRhiTextureRenderTargetDescription | description() const |
| QRhiTextureRenderTarget::Flags | flags() const |
| virtual QRhiRenderPassDescriptor * | newCompatibleRenderPassDescriptor() = 0 |
| void | setDescription(const QRhiTextureRenderTargetDescription &desc) |
| void | setFlags(QRhiTextureRenderTarget::Flags f) |
重新实现的公共函数
| virtual QRhiResource::Type | resourceType() const override |
详细描述
纹理渲染目标允许渲染到一个或多个纹理中，可选地使用深度纹理或深度/模板渲染缓冲区。
对于多采样渲染，通常的做法是使用渲染缓冲区作为颜色附件，并将非多采样目标纹理设置为resolve texture 。有关更多信息，请阅读QRhiColorAttachment 类的详细说明。
注意： 与 QRhiTextureRenderTarget 配合使用的纹理必须 使用QRhiTexture::RenderTarget 标志进行创建。
以下是创建一个以纹理作为唯一颜色附件的渲染目标的最简单示例：
QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, size, 1, QRhiTexture::RenderTarget);
texture->create();
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ texture });
rp = rt->newCompatibleRenderPassDescriptor();
rt->setRenderPassDescriptor(rp);
rt->create();
// rt can now be used with beginPass()注意：这是一个 兼容性保证有限的 RHI API，详情请参阅QRhi 。
成员类型文档
enum QRhiTextureRenderTarget::Flag
flags QRhiTextureRenderTarget::Flags
描述渲染目标加载/存储行为的标志值。根据后端的不同，加载/存储行为可能会在后台被烘焙到原生资源中，因此需要提前确定，且无法在不重新构建（以及随之发布的操作和创建新原生资源）的情况下进行更改。
| 常量 | 值 | 描述 |
|---|---|---|
QRhiTextureRenderTarget::PreserveColorContents | 1 << 0 | 表示在开始渲染通道时，将加载颜色附件的内容，而不是将其清空。这可能会消耗更多资源，特别是在移动（分块）GPU上，但可以保留不同通道之间的现有内容。 在使用解析纹理集进行多采样渲染时，设置此标志还会要求将多采样颜色数据存储（写入）到多采样纹理或渲染缓冲区中。 （对于非多采样渲染，颜色数据始终会被存储；但在 MSAA 渲染中，存储多采样数据会降低某些 GPU 架构的效率，因此默认不将其写出） 但请注意，此功能不具备跨平台兼容性：在某些情况下，图形 API 层级并不存在中间多采样纹理，例如使用 OpenGL ES 的GL_EXT_multisampled_render_to_texture 时，因为该过程完全是隐式的，由 OpenGL ES 实现负责处理。在这种情况下，PreserveColorContents 很可能不会产生任何效果。 因此，在使用多采样渲染且颜色附件使用多采样QRhiTexture （而非QRhiRenderBuffer ）时，请避免依赖此标志。 |
QRhiTextureRenderTarget::PreserveDepthStencilContents | 1 << 1 | 表示在开始渲染通道时，应加载深度纹理的内容，而不是清空。仅当纹理用作深度缓冲区时适用（QRhiTextureRenderTargetDescription::depthTexture() 已设置），因为深度/模板渲染缓冲区可能没有物理后备，数据可能根本不会被写出。 |
QRhiTextureRenderTarget::DoNotStoreDepthStencilContents | 1 << 2 | 表示深度纹理的内容无需写出。 仅当使用QRhiTexture （而非QRhiRenderBuffer ）作为深度-模板缓冲区时才相关，因为对于QRhiRenderBuffer ，这是隐含的。当设置了depthResolveTexture时，该标志无关紧要，因为此时的行为就如同该标志已被设置一样。此枚举值在Qt 6.8中引入。 |
Flags 类型是QFlags<Flag> 的 typedef。它存储 Flag 值的按“或”（OR）运算组合。
成员函数文档
[pure virtual] bool QRhiTextureRenderTarget::create()
创建相应的本机图形资源。如果由于之前调用了 create() 但未调用相应的destroy()，导致已存在相关资源，则会首先隐式调用destroy()。
注意： 必须在调用 create() 之前设置renderPassDescriptor()。要获取与渲染目标兼容的QRhiRenderPassDescriptor ，请在调用 create() 之前、但设置完所有其他参数（如description() 和flags()）之后，调用newCompatibleRenderPassDescriptor()。为节省资源，请尽可能将同一个QRhiRenderPassDescriptor 重用于多个QRhiTextureRenderTarget 实例。 只有当渲染目标具有相同数量和类型的附件（实际纹理可以不同）以及相同的标志时，才可能共享同一个渲染通道描述符。
注意： 在description() 中引用的资源 （例如QRhiTexture 实例）必须已调用过 create() 方法。
成功时返回true ，图形操作失败时返回false 。无论返回值如何，调用destroy() 总是安全的。
QRhiTextureRenderTargetDescription QRhiTextureRenderTarget::description() const
返回渲染目标的描述。
另请参阅 setDescription()。
QRhiTextureRenderTarget::Flags QRhiTextureRenderTarget::flags() const
返回当前设置的标志。
另请参阅 setFlags()。
[pure virtual] QRhiRenderPassDescriptor *QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor()
返回一个与该渲染目标兼容的新QRhiRenderPassDescriptor 对象。
返回值有两种用法：可将其传递给setRenderPassDescriptor()和QRhiGraphicsPipeline::setRenderPassDescriptor()方法。渲染通道描述符（render pass descriptor）描述了附件（颜色、深度/模板）以及可能受flags()影响的加载/存储行为。渲染通道描述符（QRhiGraphicsPipeline ）只能与已设置渲染通道（compatible ）的渲染目标配合使用，详见QRhiRenderPassDescriptor 。
只要两个QRhiTextureRenderTarget 实例具有相同数量和类型的附件，它们就可以共享同一个渲染通道描述符。相关的QRhiTexture 或QRhiRenderBuffer 实例不属于渲染通道描述符的一部分，因此这两个QRhiTextureRenderTarget 实例中的这些实例可以不同。
注意： 在description()中引用的资源 （例如QRhiTexture 实例）必须已调用过create()方法。
另请参阅 create()。
[override virtual] QRhiResource::Type QRhiTextureRenderTarget::resourceType() const
重写了：QRhiResource::resourceType() const。
返回资源类型。
void QRhiTextureRenderTarget::setDescription(const QRhiTextureRenderTargetDescription &desc)
设置渲染目标描述desc 。
另请参阅 description()。
void QRhiTextureRenderTarget::setFlags(QRhiTextureRenderTarget::Flags f)
将标志设置为f 。
另请参阅 flags()。
© 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.
