QRhiTextureRenderTargetDescription Class Reference

\inmodule QtGui More...

#include <qrhi.h>

Collaboration diagram for QRhiTextureRenderTargetDescription:

Public Member Functions
	QRhiTextureRenderTargetDescription ()=default
	Constructs an empty texture render target description.
	QRhiTextureRenderTargetDescription (const QRhiColorAttachment &colorAttachment)
	Constructs a texture render target description with one attachment described by colorAttachment.
	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 (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.
void	setColorAttachments (std::initializer_list< QRhiColorAttachment > list)
	Sets the list of color attachments.
template<typename InputIterator >
void	setColorAttachments (InputIterator first, InputIterator last)
	Sets the list of color attachments via the iterators first and last.
const QRhiColorAttachment *	cbeginColorAttachments () const
const QRhiColorAttachment *	cendColorAttachments () const
const QRhiColorAttachment *	colorAttachmentAt (qsizetype index) const
qsizetype	colorAttachmentCount () const
QRhiRenderBuffer *	depthStencilBuffer () const
void	setDepthStencilBuffer (QRhiRenderBuffer *renderBuffer)
	Sets the renderBuffer for depth-stencil.
QRhiTexture *	depthTexture () const
void	setDepthTexture (QRhiTexture *texture)
	Sets the texture for depth-stencil.

Detailed Description

\inmodule QtGui

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:

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 \l QRhi for details.

See also

QRhiColorAttachment, QRhiTextureRenderTarget

Definition at line 611 of file qrhi.h.

Constructor & Destructor Documentation

QRhiTextureRenderTargetDescription() [1/4]

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription ( )

default

Constructs an empty texture render target description.

QRhiTextureRenderTargetDescription() [2/4]

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription

(

const QRhiColorAttachment &

colorAttachment

)

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

Definition at line 2502 of file qrhi.cpp.

References QVarLengthArray< T, Prealloc >::append().

Here is the call graph for this function:

QRhiTextureRenderTargetDescription() [3/4]

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.

Definition at line 2512 of file qrhi.cpp.

References QVarLengthArray< T, Prealloc >::append().

Here is the call graph for this function:

QRhiTextureRenderTargetDescription() [4/4]

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.

Definition at line 2527 of file qrhi.cpp.

References QVarLengthArray< T, Prealloc >::append().

Here is the call graph for this function:

Member Function Documentation

cbeginColorAttachments()

const QRhiColorAttachment * QRhiTextureRenderTargetDescription::cbeginColorAttachments ( ) const

inline

Returns

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

Definition at line 626 of file qrhi.h.

Referenced by QRhiVulkan::activateTextureRenderTarget(), QRhiMetal::beginPass(), QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QMetalTextureRenderTarget::create(), QNullTextureRenderTarget::create(), QVkTextureRenderTarget::create(), QRhiD3D11::endPass(), QRhiGles2::endPass(), QRhiGles2::enqueueBindFramebuffer(), QVkTextureRenderTarget::newCompatibleRenderPassDescriptor(), and renderToKTXFileInternal().

Here is the caller graph for this function:

cendColorAttachments()

const QRhiColorAttachment * QRhiTextureRenderTargetDescription::cendColorAttachments ( ) const

inline

Returns

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

Definition at line 627 of file qrhi.h.

Referenced by QRhiVulkan::activateTextureRenderTarget(), QRhiMetal::beginPass(), QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QMetalTextureRenderTarget::create(), QNullTextureRenderTarget::create(), QVkTextureRenderTarget::create(), QRhiD3D11::endPass(), QRhiGles2::endPass(), QRhiGles2::enqueueBindFramebuffer(), and QVkTextureRenderTarget::newCompatibleRenderPassDescriptor().

Here is the caller graph for this function:

colorAttachmentAt()

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

inline

Returns

the color attachment at the specified index.

Definition at line 628 of file qrhi.h.

Referenced by QMetalTextureRenderTarget::newCompatibleRenderPassDescriptor().

Here is the caller graph for this function:

colorAttachmentCount()

qsizetype QRhiTextureRenderTargetDescription::colorAttachmentCount ( ) const

inline

Returns

the number of currently set color attachments.

Definition at line 629 of file qrhi.h.

Referenced by QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QMetalTextureRenderTarget::create(), QVkTextureRenderTarget::create(), and QMetalTextureRenderTarget::newCompatibleRenderPassDescriptor().

Here is the caller graph for this function:

depthStencilBuffer()

QRhiRenderBuffer * QRhiTextureRenderTargetDescription::depthStencilBuffer ( ) const

inline

Returns

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

Definition at line 631 of file qrhi.h.

Referenced by QRhiVulkan::activateTextureRenderTarget(), QRhiMetal::beginPass(), QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QMetalTextureRenderTarget::create(), QNullTextureRenderTarget::create(), QVkTextureRenderTarget::create(), QMetalTextureRenderTarget::newCompatibleRenderPassDescriptor(), and QVkTextureRenderTarget::newCompatibleRenderPassDescriptor().

Here is the caller graph for this function:

depthTexture()

QRhiTexture * QRhiTextureRenderTargetDescription::depthTexture ( ) const

inline

Returns

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

Definition at line 634 of file qrhi.h.

Referenced by QRhiVulkan::activateTextureRenderTarget(), QRhiMetal::beginPass(), QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QMetalTextureRenderTarget::create(), QNullTextureRenderTarget::create(), QVkTextureRenderTarget::create(), QRhiGles2::enqueueBindFramebuffer(), QMetalTextureRenderTarget::newCompatibleRenderPassDescriptor(), and QVkTextureRenderTarget::newCompatibleRenderPassDescriptor().

Here is the caller graph for this function:

setColorAttachments() [1/2]

template<typename InputIterator >

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

inline

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

Definition at line 621 of file qrhi.h.

setColorAttachments() [2/2]

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

inline

Sets the list of color attachments.

Definition at line 619 of file qrhi.h.

References list.

Referenced by QSSGRenderReflectionMap::addReflectionMapEntry(), QSSGRenderShadowMap::addShadowMapEntry(), renderToKTXFileInternal(), and QQuick3DSceneRenderer::synchronize().

Here is the caller graph for this function:

setDepthStencilBuffer()

void QRhiTextureRenderTargetDescription::setDepthStencilBuffer ( QRhiRenderBuffer *  renderBuffer )

inline

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 632 of file qrhi.h.

Referenced by QSSGRenderReflectionMap::addReflectionMapEntry(), QSSGRenderShadowMap::addShadowMapEntry(), createRhiRenderTarget(), QSGRhiSupport::grabOffscreen(), and QQuick3DSceneRenderer::synchronize().

Here is the caller graph for this function:

setDepthTexture()

void QRhiTextureRenderTargetDescription::setDepthTexture ( QRhiTexture *  texture )

inline

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 \l{QRhiColorAttachment::setMultiViewCount()}{multiview rendering}.

Note

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

See also

setDepthStencilBuffer()

Definition at line 635 of file qrhi.h.

Referenced by RenderHelpers::rhiPrepareDepthTexture().

Here is the caller graph for this function:

---

The documentation for this class was generated from the following files:

• qtbase/src/gui/rhi/qrhi.h
• qtbase/src/gui/rhi/qrhi.cpp