- Qt 6.7
- Qt GUI
- C++ Classes
- QRhiTextureRenderTargetDescription
- Qt 6.7.3 Reference Documentation

# QRhiTextureRenderTargetDescription Class

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

Header: | #include <QRhiTextureRenderTargetDescription>
CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: | QT += gui
Since: | Qt 6.6

- List of all members, including inherited members

## 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
QRhiRenderBuffer * | depthStencilBuffer() const
QRhiTexture * | depthTexture() const
void | setColorAttachments(std::initializer_list<QRhiColorAttachment> list)
void | setColorAttachments(InputIterator first, InputIterator last)
void | setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)
void | setDepthTexture(QRhiTexture *texture)

## 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: 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.

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

### 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().