QRhiColorAttachment Class

Describes the a single color attachment of a render target. More...

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

Public Functions

QRhiColorAttachment()
QRhiColorAttachment(QRhiTexture *texture)
QRhiColorAttachment(QRhiRenderBuffer *renderBuffer)
int layer() const
int level() const
QRhiRenderBuffer *renderBuffer() const
int resolveLayer() const
int resolveLevel() const
QRhiTexture *resolveTexture() const
void setLayer(int layer)
void setLevel(int level)
void setRenderBuffer(QRhiRenderBuffer *rb)
void setResolveLayer(int layer)
void setResolveLevel(int level)
void setResolveTexture(QRhiTexture *tex)
void setTexture(QRhiTexture *tex)
QRhiTexture *texture() const

Detailed Description

A color attachment is either a QRhiTexture or a QRhiRenderBuffer. The former, i.e. when texture() is set, is used in most cases. QRhiColorAttachment is commonly used in combination with QRhiTextureRenderTargetDescription.

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

Setting renderBuffer instead is recommended only when multisampling is needed. Relying on QRhi::MultisampleRenderBuffer is a better choice than QRhi::MultisampleTexture in practice since the former is available in more run time configurations (e.g. when running on OpenGL ES 3.0 which has no support for multisample textures, but does support multisample renderbuffers).

When targeting a non-multisample texture, the layer() and level() indicate the targeted layer (face index 0-5 for cubemaps) and mip level. For 3D textures layer() specifies the slice (one 2D image within the 3D texture) to render to. For texture arrays layer() is the array index.

When texture() or renderBuffer() is multisample, resolveTexture() can be set optionally. When set, samples are resolved automatically into that (non-multisample) texture at the end of the render pass. When rendering into a multisample renderbuffers, this is the only way to get resolved, non-multisample content out of them. Multisample textures allow sampling in shaders so for them this is just one option.

Note: when resolving is enabled, the multisample data may not be written out at all. This means that the multisample texture() must not be used afterwards with shaders for sampling when resolveTexture() is set.

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

See also QRhiTextureRenderTargetDescription.

Member Function Documentation

[constexpr noexcept] QRhiColorAttachment::QRhiColorAttachment()

Constructs an empty color attachment description.

QRhiColorAttachment::QRhiColorAttachment(QRhiTexture *texture)

Constructs a color attachment description that specifies texture as the associated color buffer.

QRhiColorAttachment::QRhiColorAttachment(QRhiRenderBuffer *renderBuffer)

Constructs a color attachment description that specifies renderBuffer as the associated color buffer.

int QRhiColorAttachment::layer() const

Returns the layer index (cubemap face or array layer). 0 by default.

See also setLayer().

int QRhiColorAttachment::level() const

Returns the mip level. 0 by default.

See also setLevel().

QRhiRenderBuffer *QRhiColorAttachment::renderBuffer() const

Returns the renderbuffer this attachment description references, or nullptr if there is none.

In practice associating a QRhiRenderBuffer with a QRhiColorAttachment makes the most sense when setting up multisample rendering via a multisample color renderbuffer that is then resolved into a non-multisample texture at the end of the render pass.

See also setRenderBuffer().

int QRhiColorAttachment::resolveLayer() const

Returns the currently set resolve texture layer. Defaults to 0.

See also setResolveLayer().

int QRhiColorAttachment::resolveLevel() const

Returns the currently set resolve texture mip level. Defaults to 0.

See also setResolveLevel().

QRhiTexture *QRhiColorAttachment::resolveTexture() const

Returns the resolve texture this attachment description references, or nullptr if there is none.

Setting a non-null resolve texture is applicable when the attachment references a multisample, color renderbuffer. (i.e., renderBuffer() is set) The QRhiTexture in the resolveTexture() is then a regular, 2D, non-multisample texture with the same size (but a sample count of 1). The multisample content is automatically resolved into this texture at the end of each render pass.

See also setResolveTexture().

void QRhiColorAttachment::setLayer(int layer)

Sets the layer index.

See also layer().

void QRhiColorAttachment::setLevel(int level)

Sets the mip level.

See also level().

void QRhiColorAttachment::setRenderBuffer(QRhiRenderBuffer *rb)

Sets the renderbuffer rb.

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

See also renderBuffer().

void QRhiColorAttachment::setResolveLayer(int layer)

Sets the resolve texture layer to use.

See also resolveLayer().

void QRhiColorAttachment::setResolveLevel(int level)

Sets the resolve texture mip level to use.

See also resolveLevel().

void QRhiColorAttachment::setResolveTexture(QRhiTexture *tex)

Sets the resolve texture tex.

See also resolveTexture().

void QRhiColorAttachment::setTexture(QRhiTexture *tex)

Sets the texture tex.

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

See also texture().

QRhiTexture *QRhiColorAttachment::texture() const

Returns the texture this attachment description references, or nullptr if there is none.

See also setTexture().

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