Back to Doc.qt.io
Contact Us Blog Download Qt

QRhiTextureRenderTargetDescription Class

Describes the color and depth or depth/stencil attachments of a render target. More...

Header: #include <rhi/qrhi.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate)
qmake: QT += gui-private
Since: Qt 6.6

Public Functions

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

Detailed Description

A texture render target has zero or more textures as color attachments, zero or one renderbuffer as combined depth/stencil buffer or zero or one texture as depth buffer.

Note: depthStencilBuffer() and depthTexture() cannot be both set (cannot be non-null at the same time).

Let's look at some example usages in combination with QRhiTextureRenderTarget.

Due to the constructors, the targeting a texture (and no depth/stencil buffer) is simple:

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(256, 256), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ texture }));

The following creates a texture render target that is set up to target mip level #2 of a texture:

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 });

Another example, this time to render into a depth texture:

QRhiTexture *shadowMap = rhi->newTexture(QRhiTexture::D32F, QSize(1024, 1024), 1, QRhiTexture::RenderTarget);
shadowMap->create();
QRhiTextureRenderTargetDescription rtDesc;
rtDesc.setDepthTexture(shadowMap);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);

A very common case, having a texture as the color attachment and a renderbuffer as depth/stencil to enable depth testing:

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);

Finally, to enable multisample rendering in a portable manner (so also supporting OpenGL ES 3.0), using a QRhiRenderBuffer as the (multisample) color buffer and then resolving into a regular (non-multisample) 2D texture. To enable depth testing, a depth-stencil buffer, which also must use the same sample count, is used as well:

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 });

Note: when multisample resolving is enabled, the multisample data may not be written out at all. This means that the multisample texture in a color attachment must not be used afterwards with shaders for sampling (or other purposes) whenever a resolve texture is set, since the multisample color buffer is merely an intermediate storage then that gets no data written back on some GPU architectures at all. See PreserveColorContents for more details.

Note: When using setDepthTexture(), not setDepthStencilBuffer(), and the depth (stencil) data is not of interest afterwards, set the DoNotStoreDepthStencilContents flag on the QRhiTextureRenderTarget. This allows indicating to the underlying 3D API that the depth/stencil data can be discarded, leading potentially to better performance with tiled GPU architectures. When the depth-stencil buffer is a QRhiRenderBuffer (and also for the multisample color texture, see previous note) this is implicit, but with a depth (stencil) QRhiTexture the intention needs to be declared explicitly. By default QRhi assumes that the data is of interest (e.g., the depth texture is sampled in a shader afterwards).

Note: This is a RHI API with limited compatibility guarantees, see QRhi for details.

See also QRhiColorAttachment and QRhiTextureRenderTarget.

Member Function Documentation

[constexpr noexcept] QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription()

Constructs an empty texture render target description.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment)

Constructs a texture render target description with one attachment described by colorAttachment.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiRenderBuffer *depthStencilBuffer)

Constructs a texture render target description with two attachments, a color attachment described by colorAttachment, and a depth/stencil attachment with depthStencilBuffer.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiTexture *depthTexture)

Constructs a texture render target description with two attachments, a color attachment described by colorAttachment, and a depth attachment with depthTexture.

Note: depthTexture must have a suitable format, such as QRhiTexture::D16 or QRhiTexture::D32F.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cbeginColorAttachments() const

Returns a const iterator pointing to the first item in the attachment list.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cendColorAttachments() const

Returns a const iterator pointing just after the last item in the attachment list.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::colorAttachmentAt(qsizetype index) const

Returns the color attachment at the specified index.

qsizetype QRhiTextureRenderTargetDescription::colorAttachmentCount() const

Returns the number of currently set color attachments.

[since 6.8] QRhiTexture *QRhiTextureRenderTargetDescription::depthResolveTexture() const

Returns the texture to which a multisample depth (or depth-stencil) texture (or texture array) is resolved to. nullptr if there is none, which is the most common case.

This function was introduced in Qt 6.8.

See also setDepthResolveTexture(), QRhiColorAttachment::resolveTexture(), and depthTexture().

QRhiRenderBuffer *QRhiTextureRenderTargetDescription::depthStencilBuffer() const

Returns the renderbuffer used as depth-stencil buffer, or nullptr if none was set.

See also setDepthStencilBuffer().

QRhiTexture *QRhiTextureRenderTargetDescription::depthTexture() const

Returns the currently referenced depth texture, or nullptr if none was set.

See also setDepthTexture().

void QRhiTextureRenderTargetDescription::setColorAttachments(std::initializer_list<QRhiColorAttachment> list)

Sets the list of color attachments.

template <typename InputIterator> void QRhiTextureRenderTargetDescription::setColorAttachments(InputIterator first, InputIterator last)

Sets the list of color attachments via the iterators first and last.

[since 6.8] void QRhiTextureRenderTargetDescription::setDepthResolveTexture(QRhiTexture *tex)

Sets the depth (or depth-stencil) resolve texture tex.

tex is expected to be a 2D texture or a 2D texture array with a format matching the texture set via setDepthTexture().

Note: Resolving depth (or depth-stencil) data is only functional when the QRhi::ResolveDepthStencil feature is reported as supported at run time. Support for depth-stencil resolve is not universally available among the graphics APIs. Designs assuming unconditional availability of depth-stencil resolve are therefore non-portable, and should be avoided.

Note: As an additional limitation for OpenGL ES in particular, setting a depth resolve texture may only be functional in combination with setDepthTexture(), not with setDepthStencilBuffer().

This function was introduced in Qt 6.8.

See also depthResolveTexture(), QRhiColorAttachment::setResolveTexture(), and setDepthTexture().

void QRhiTextureRenderTargetDescription::setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)

Sets the renderBuffer for depth-stencil. Not mandatory, e.g. when no depth test/write or stencil-related features are used within any graphics pipelines in any of the render passes for this render target, it can be left set to nullptr.

Note: depthStencilBuffer() and depthTexture() cannot be both set (cannot be non-null at the same time).

Using a QRhiRenderBuffer over a 2D QRhiTexture as the depth or depth/stencil buffer is very common, and is the recommended approach for applications. Using a QRhiTexture, and so setDepthTexture() becomes relevant if the depth data is meant to be accessed (e.g. sampled in a shader) afterwards, or when multiview rendering is involved (because then the depth texture must be a texture array).

See also depthStencilBuffer() and setDepthTexture().

void QRhiTextureRenderTargetDescription::setDepthTexture(QRhiTexture *texture)

Sets the texture for depth-stencil. This is an alternative to setDepthStencilBuffer(), where instead of a QRhiRenderBuffer a QRhiTexture with a suitable type (e.g., QRhiTexture::D32F) is provided.

Note: depthStencilBuffer() and depthTexture() cannot be both set (cannot be non-null at the same time).

texture can either be a 2D texture or a 2D texture array (when texture arrays are supported). Specifying a texture array is relevant in particular with multiview rendering.

Note: If texture is a format with a stencil component, such as QRhiTexture::D24S8, it will serve as the stencil buffer as well.

See also depthTexture() and setDepthStencilBuffer().

[since 6.9] void QRhiTextureRenderTargetDescription::setShadingRateMap(QRhiShadingRateMap *map)

Associates with the specified QRhiShadingRateMap map. This is functional only when the QRhi::VariableRateShadingMap feature is reported as supported.

When QRhiCommandBuffer::setShadingRate() is also called, the higher of two the shading rates are used for each tile. There is currently no control offered over the combiner behavior.

Note: When the render target had already been built (create() was called successfully), setting a shading rate map implies that a different, new QRhiRenderPassDescriptor is needed and thus a rebuild is needed. Call setRenderPassDescriptor() again (outside of a render pass) and then rebuild by calling create(). This has other rolling consequences as well, for example for graphics pipelines: those also need to be associated with the new QRhiRenderPassDescriptor and then rebuilt. See QRhiRenderPassDescriptor::serializedFormat() for some suggestions on how to deal with this. Remember to set the QRhiGraphicsPipeline::UsesShadingRate flag as well.

This function was introduced in Qt 6.9.

See also shadingRateMap().

[since 6.9] QRhiShadingRateMap *QRhiTextureRenderTargetDescription::shadingRateMap() const

Returns the currently set QRhiShadingRateMap. By default this is nullptr.

This function was introduced in Qt 6.9.

See also setShadingRateMap().

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