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.