\inmodule QtGui More...

#include <qrhi.h>

Inheritance diagram for QRhiTextureRenderTarget:

Collaboration diagram for QRhiTextureRenderTarget:

Public Types
enum	Flag { PreserveColorContents = 1 << 0 , PreserveDepthStencilContents = 1 << 1 }
	Flag values describing the load/store behavior for the render target. More...

Public Types inherited from QRhiResource
enum	Type { Buffer , Texture , Sampler , RenderBuffer , RenderPassDescriptor , SwapChainRenderTarget , TextureRenderTarget , ShaderResourceBindings , GraphicsPipeline , SwapChain , ComputePipeline , CommandBuffer }
	Specifies type of the resource. More...

Public Member Functions
QRhiResource::Type	resourceType () const override

QRhiTextureRenderTargetDescription	description () const

void	setDescription (const QRhiTextureRenderTargetDescription &desc)
	Sets the render target description desc.

Flags	flags () const

void	setFlags (Flags f)
	Sets the flags to f.

virtual QRhiRenderPassDescriptor *	newCompatibleRenderPassDescriptor ()=0

virtual bool	create ()=0
	Creates the corresponding native graphics resources.

Public Member Functions inherited from QRhiRenderTarget
virtual QSize	pixelSize () const =0

virtual float	devicePixelRatio () const =0

virtual int	sampleCount () const =0

QRhiRenderPassDescriptor *	renderPassDescriptor () const

void	setRenderPassDescriptor (QRhiRenderPassDescriptor *desc)
	Sets the QRhiRenderPassDescriptor desc for use with this render target.

Public Member Functions inherited from QRhiResource
virtual	~QRhiResource ()
	Destructor.

virtual Type	resourceType () const =0

virtual void	destroy ()=0
	Releases (or requests deferred releasing of) the underlying native graphics resources.

void	deleteLater ()
	When called without a frame being recorded, this function is equivalent to deleting the object.

QByteArray	name () const

void	setName (const QByteArray &name)
	Sets a name for the object.

quint64	globalResourceId () const

QRhi *	rhi () const

Protected Member Functions
	QRhiTextureRenderTarget (QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc_, Flags flags_)

Protected Member Functions inherited from QRhiRenderTarget
	QRhiRenderTarget (QRhiImplementation *rhi)

Protected Member Functions inherited from QRhiResource
	QRhiResource (QRhiImplementation *rhi)

Protected Attributes
QRhiTextureRenderTargetDescription	m_desc

Flags	m_flags

Protected Attributes inherited from QRhiRenderTarget
QRhiRenderPassDescriptor *	m_renderPassDesc = nullptr

Protected Attributes inherited from QRhiResource
QRhiImplementation *	m_rhi = nullptr

quint64	m_id

QByteArray	m_objectName

Detailed Description

\inmodule QtGui

Since: 6.6

Texture render target resource.

A texture render target allows rendering into one or more textures, optionally with a depth texture or depth/stencil renderbuffer.

For multisample rendering the common approach is to use a renderbuffer as the color attachment and set the non-multisample destination texture as the {resolve texture}.

Note: Textures used in combination with QRhiTextureRenderTarget must be created with the QRhiTexture::RenderTarget flag.

The simplest example of creating a render target with a texture as its single color attachment:

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, size, 1, QRhiTexture::RenderTarget);
texture->create();
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ texture });
rp = rt->newCompatibleRenderPassDescriptor();
rt->setRenderPassDescriptor(rt);
rt->create();
// rt can now be used with beginPass()

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

Definition at line 1160 of file qrhi.h.

Member Enumeration Documentation

◆ Flag

enum QRhiTextureRenderTarget::Flag

Flag values describing the load/store behavior for the render target.

The load/store behavior may be baked into native resources under the hood, depending on the backend, and therefore it needs to be known upfront and cannot be changed without rebuilding (and so releasing and creating new native resources).

\value PreserveColorContents Indicates that the contents of the color attachments is to be loaded when starting a render pass, instead of clearing. This is potentially more expensive, especially on mobile (tiled) GPUs, but allows preserving the existing contents between passes.

\value PreserveDepthStencilContents Indicates that the contents of the depth texture is to be loaded when starting a render pass, instead clearing. Only applicable when a texture is used as the depth buffer (QRhiTextureRenderTargetDescription::depthTexture() is set) because depth/stencil renderbuffers may not have any physical backing and data may not be written out in the first place.

Enumerator
PreserveColorContents
PreserveDepthStencilContents

Definition at line 1163 of file qrhi.h.

Constructor & Destructor Documentation

◆ QRhiTextureRenderTarget()

QRhiTextureRenderTarget::QRhiTextureRenderTarget	(	QRhiImplementation *	rhi,
		const QRhiTextureRenderTargetDescription &	desc_,
		Flags	flags_
	)

protected

Definition at line 4920 of file qrhi.cpp.

Member Function Documentation

◆ create()

bool QRhiTextureRenderTarget::create ( )

pure virtual

Creates the corresponding native graphics resources.

If there are already resources present due to an earlier create() with no corresponding destroy(), then destroy() is called implicitly first.

Note: renderPassDescriptor() must be set before calling create(). To obtain a QRhiRenderPassDescriptor compatible with the render target, call newCompatibleRenderPassDescriptor() before create() but after setting all other parameters, such as description() and flags(). To save resources, reuse the same QRhiRenderPassDescriptor with multiple QRhiTextureRenderTarget instances, whenever possible. Sharing the same render pass descriptor is only possible when the render targets have the same number and type of attachments (the actual textures can differ) and the same flags.; resources, such as QRhiTexture instances, referenced in description() must already have create() called on them.

Returns: true when successful, false when a graphics operation failed. Regardless of the return value, calling destroy() is always safe.

Implemented in QD3D11TextureRenderTarget, QGles2TextureRenderTarget, QMetalTextureRenderTarget, QNullTextureRenderTarget, and QVkTextureRenderTarget.

Referenced by QSSGRenderReflectionMap::addReflectionMapEntry(), QSSGRenderShadowMap::addShadowMapEntry(), RenderHelpers::rhiPrepareAoTexture(), RenderHelpers::rhiPrepareDepthTexture(), RenderHelpers::rhiPrepareScreenTexture(), and QQuick3DSceneRenderer::synchronize().

Here is the caller graph for this function:

◆ description()

QRhiTextureRenderTargetDescription QRhiTextureRenderTarget::description ( ) const

inline

Returns: the render target description.

Definition at line 1171 of file qrhi.h.

Referenced by QRhiVulkan::activateTextureRenderTarget(), QRhiD3D11::beginPass(), QRhiGles2::beginPass(), QRhiMetal::beginPass(), QRhiNull::beginPass(), and renderToKTXFileInternal().

Here is the caller graph for this function:

◆ flags()

QRhiTextureRenderTarget::Flags QRhiTextureRenderTarget::flags ( ) const

inline

Returns: the currently set flags.

Definition at line 1174 of file qrhi.h.

◆ newCompatibleRenderPassDescriptor()

QRhiRenderPassDescriptor * QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor ( )

pure virtual

Returns: a new QRhiRenderPassDescriptor that is compatible with this render target.

The returned value is used in two ways: it can be passed to setRenderPassDescriptor() and QRhiGraphicsPipeline::setRenderPassDescriptor(). A render pass descriptor describes the attachments (color, depth/stencil) and the load/store behavior that can be affected by flags(). A QRhiGraphicsPipeline can only be used in combination with a render target that has a \l{QRhiRenderPassDescriptor::isCompatible()}{compatible} QRhiRenderPassDescriptor set.

Two QRhiTextureRenderTarget instances can share the same render pass descriptor as long as they have the same number and type of attachments. The associated QRhiTexture or QRhiRenderBuffer instances are not part of the render pass descriptor so those can differ in the two QRhiTextureRenderTarget instances.

Note: resources, such as QRhiTexture instances, referenced in description() must already have create() called on them.

See also: create()

Implemented in QD3D11TextureRenderTarget, QGles2TextureRenderTarget, QMetalTextureRenderTarget, QNullTextureRenderTarget, and QVkTextureRenderTarget.

Referenced by QSSGRenderReflectionMap::addReflectionMapEntry(), QSSGRenderShadowMap::addShadowMapEntry(), RenderHelpers::rhiPrepareAoTexture(), RenderHelpers::rhiPrepareDepthTexture(), RenderHelpers::rhiPrepareScreenTexture(), RenderHelpers::rhiRenderReflectionMap(), and QQuick3DSceneRenderer::synchronize().

Here is the caller graph for this function:

◆ resourceType()

QRhiResource::Type QRhiTextureRenderTarget::resourceType ( ) const

overridevirtual

Returns: the resource type.

Implements QRhiResource.

Definition at line 4932 of file qrhi.cpp.

References QRhiResource::TextureRenderTarget.

◆ setDescription()

void QRhiTextureRenderTarget::setDescription ( const QRhiTextureRenderTargetDescription & desc )

inline

Sets the render target description desc.

Definition at line 1172 of file qrhi.h.

References desc.

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

Here is the caller graph for this function:

◆ setFlags()

void QRhiTextureRenderTarget::setFlags ( Flags f )

inline

Sets the flags to f.

Definition at line 1175 of file qrhi.h.

Member Data Documentation

◆ m_desc

QRhiTextureRenderTargetDescription QRhiTextureRenderTarget::m_desc

protected

Definition at line 1183 of file qrhi.h.

◆ m_flags

Flags QRhiTextureRenderTarget::m_flags

protected

Definition at line 1184 of file qrhi.h.

Referenced by QRhiD3D11::beginPass(), QRhiMetal::beginPass(), QRhiGles2::enqueueBindFramebuffer(), and QVkTextureRenderTarget::newCompatibleRenderPassDescriptor().

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

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

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Flag

Constructor & Destructor Documentation

◆ QRhiTextureRenderTarget()

Member Function Documentation

◆ create()

◆ description()

◆ flags()

◆ newCompatibleRenderPassDescriptor()

◆ resourceType()

◆ setDescription()

◆ setFlags()

Member Data Documentation

◆ m_desc

◆ m_flags