Back to Qt.io
Contact Us Blog Download Qt

QRhiTextureRenderTarget Class

纹理渲染目标资源。更多

Header： #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
继承： 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 。

成员类型文档

枚举 QRhiTextureRenderTarget::Flag
flags QRhiTextureRenderTarget::Flags

描述渲染目标的加载/存储行为的标志值。根据后端不同，加载/存储行为可能会被嵌入到原生资源中，因此需要预先知道，并且在不重建（因此释放和创建新的原生资源）的情况下无法更改。

常数值说明
QRhiTextureRenderTarget::PreserveColorContents1 << 0表示在开始渲染时加载颜色附件的内容，而不是清空。这可能会比较昂贵，尤其是在移动（平铺）GPU 上，但可以在两次渲染之间保留现有内容。在使用解析纹理设置进行多采样渲染时，设置此标记也会要求将多采样颜色数据存储（写出）到多采样纹理或渲染缓冲区中。(对于非多采样渲染，颜色数据始终会被存储，但对于 MSAA，存储多采样数据会降低某些 GPU 架构的效率，因此默认情况下不会将其写出）但请注意，这是不可移植的：在某些情况下，图形应用程序接口级别上没有中间多采样纹理，例如在使用 OpenGL ES 的GL_EXT_multisampled_render_to_texture 时，因为这都是隐式的，由 OpenGL ES 实现处理。在这种情况下，PreserveColorContents 很可能不起作用。因此，在使用多采样渲染且颜色附件使用多采样QRhiTexture （非QRhiRenderBuffer ）时，应避免依赖此标记。
QRhiTextureRenderTarget::PreserveDepthStencilContents1 << 1表示在开始渲染时加载深度纹理的内容，而不是清空。仅适用于将纹理用作深度缓冲区时（已设置QRhiTextureRenderTargetDescription::depthTexture( )），因为深度/模版渲染缓冲区可能没有任何物理支持，数据可能不会首先写出。
QRhiTextureRenderTarget::DoNotStoreDepthStencilContents1 << 2表示不需要写出深度纹理的内容。只有当QRhiTexture （而不是QRhiRenderBuffer ）被用作深度-模版缓冲区时才与此相关，因为对于QRhiRenderBuffer 来说，这是隐 含的。如果设置了深度纹理解析（depthResolveTexture），则与该标志无关，因为此时的行为与设置该标志时一样。该枚举值在 Qt 6.8 中引入。

Flags 类型是QFlags<Flag> 的类型定义。它存储 Flag 值的 OR 组合。

成员函数文档

[pure virtual] bool QRhiTextureRenderTarget::create()

创建相应的本地图形资源。如果由于之前的 create() 没有相应的destroy() 而导致资源已经存在，则会先隐式调用destroy()。

注意： 必须在调用 create() 之前设置renderPassDescriptor()。要获得与呈现目标兼容的QRhiRenderPassDescriptor ，可在调用 create() 之前调用newCompatibleRenderPassDescriptor() ，但应在设置description() 和flags() 等所有其他参数后调用。为节省资源，请尽可能在多个QRhiTextureRenderTarget 实例中重复使用同一个QRhiRenderPassDescriptor 。只有当呈现目标具有相同数量和类型的附件（实际纹理可能不同）以及相同的标记时，才有可能共享相同的呈现传递描述符。

注意： 在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() 。呈现传递描述符描述了可受flags() 影响的附件（颜色、深度/模板）和加载/存储行为。QRhiGraphicsPipeline 只能与设置了compatible QRhiRenderPassDescriptor 的呈现目标结合使用。

只要附件的数量和类型相同，两个QRhiTextureRenderTarget 实例就可以共享同一个呈现传递描述符。相关的QRhiTexture 或QRhiRenderBuffer 实例不属于呈现传递描述符的一部分，因此这两个QRhiTextureRenderTarget 实例中的相关内容可以不同。

注意： 在description() 中引用的资源（如QRhiTexture 实例）必须已经调用过create()。

另请参阅 create()。

[override virtual] QRhiResource::Type QRhiTextureRenderTarget::resourceType() const

重实现：QRhiResource::resourceType() 常量。

返回资源类型。

void QRhiTextureRenderTarget::setDescription(const QRhiTextureRenderTargetDescription &desc)

设置呈现目标描述desc 。

另请参阅 description() 。

void QRhiTextureRenderTarget::setFlags(QRhiTextureRenderTarget::Flags f)

将标志设置为f 。

另请参阅 flags() 。

© 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.