\inmodule QtGuiPrivate \inheaderfile rhi/qrhi.h
- Since
- 6.6
Describes the color and depth or depth/stencil attachments of a render target.
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:
\inmodule QtGuiPrivate \inheaderfile rhi/qrhi.h
\inmodule QtGuiPrivate \inheaderfile rhi/qrhi.h
The following creates a texture render target that is set up to target mip level #2 of a texture:
colorAtt.setLevel(2);
\inmodule QtGuiPrivate \inheaderfile rhi/qrhi.h
Another example, this time to render into a depth texture:
void setDepthTexture(QRhiTexture *texture)
Sets the texture for depth-stencil.
QRhiTextureRenderTargetDescription()=default
Constructs an empty texture render target description.
virtual bool create()=0
Creates the corresponding native graphics resources.
A very common case, having a texture as the color attachment and a renderbuffer as depth/stencil to enable depth testing:
\inmodule QtGuiPrivate \inheaderfile rhi/qrhi.h
virtual bool create()=0
Creates the corresponding native graphics resources.
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:
colorAtt.setResolveTexture(
texture);
- 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 \l{QRhiTextureRenderTarget::Flag}{PreserveColorContents} for more details.
-
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).
-
This is a RHI API with limited compatibility guarantees, see \l QRhi for details.
- See also
- QRhiColorAttachment, QRhiTextureRenderTarget
Definition at line 620 of file qrhi.h.
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 \l{QRhiColorAttachment::setMultiViewCount()}{multiview rendering} is involved (because then the depth texture must be a texture array).
- See also
- setDepthTexture()
Definition at line 641 of file qrhi.h.
1.14.0