\inmodule QtGui More...

#include <qrhi.h>

Collaboration diagram for QRhiColorAttachment:

Public Member Functions
	QRhiColorAttachment ()=default
	Constructs an empty color attachment description.

	QRhiColorAttachment (QRhiTexture *texture)
	Constructs a color attachment description that specifies texture as the associated color buffer.

	QRhiColorAttachment (QRhiRenderBuffer *renderBuffer)
	Constructs a color attachment description that specifies renderBuffer as the associated color buffer.

QRhiTexture *	texture () const

void	setTexture (QRhiTexture *tex)
	Sets the texture tex.

QRhiRenderBuffer *	renderBuffer () const

void	setRenderBuffer (QRhiRenderBuffer *rb)
	Sets the renderbuffer rb.

int	layer () const

void	setLayer (int layer)
	Sets the layer index.

int	level () const

void	setLevel (int level)
	Sets the mip level.

QRhiTexture *	resolveTexture () const

void	setResolveTexture (QRhiTexture *tex)
	Sets the resolve texture tex.

int	resolveLayer () const

void	setResolveLayer (int layer)
	Sets the resolve texture layer to use.

int	resolveLevel () const

void	setResolveLevel (int level)
	Sets the resolve texture mip level to use.

int	multiViewCount () const

void	setMultiViewCount (int count)
	Sets the view count.

Detailed Description

\inmodule QtGui

Since: 6.6

Describes the a single color attachment of a render target.

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.; This is a RHI API with limited compatibility guarantees, see \l QRhi for details.

See also: QRhiTextureRenderTargetDescription

Definition at line 567 of file qrhi.h.

Constructor & Destructor Documentation

◆ QRhiColorAttachment() [1/3]

QRhiColorAttachment::QRhiColorAttachment ( )

default

Constructs an empty color attachment description.

◆ QRhiColorAttachment() [2/3]

QRhiColorAttachment::QRhiColorAttachment ( QRhiTexture * texture )

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

Definition at line 2211 of file qrhi.cpp.

◆ QRhiColorAttachment() [3/3]

QRhiColorAttachment::QRhiColorAttachment ( QRhiRenderBuffer * renderBuffer )

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

Definition at line 2220 of file qrhi.cpp.

Member Function Documentation

◆ layer()

int QRhiColorAttachment::layer ( ) const

inline

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

Definition at line 580 of file qrhi.h.

Referenced by QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QRhiD3D11::endPass(), and QRhiGles2::endPass().

Here is the caller graph for this function:

◆ level()

int QRhiColorAttachment::level ( ) const

inline

Returns: the mip level. 0 by default.

Definition at line 583 of file qrhi.h.

Referenced by QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QNullTextureRenderTarget::create(), and QRhiGles2::endPass().

Here is the caller graph for this function:

◆ multiViewCount()

int QRhiColorAttachment::multiViewCount ( ) const

inline

Returns: the currently set number of views. Defaults to 0 which indicates the render target with this color attachment is not going to be used with multiview rendering.

Since: 6.7

Definition at line 595 of file qrhi.h.

Referenced by QGles2TextureRenderTarget::create(), and QRhiGles2::endPass().

Here is the caller graph for this function:

◆ renderBuffer()

QRhiRenderBuffer * QRhiColorAttachment::renderBuffer ( ) const

inline

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 \l{QRhiRenderBuffer::Type}{color} renderbuffer that is then resolved into a non-multisample texture at the end of the render pass.

Definition at line 577 of file qrhi.h.

Referenced by QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QNullTextureRenderTarget::create(), QRhiD3D11::endPass(), QRhiGles2::endPass(), QMetalTextureRenderTarget::newCompatibleRenderPassDescriptor(), and QRhiRenderTargetAttachmentTracker::updateResIdList().

Here is the caller graph for this function:

◆ resolveLayer()

int QRhiColorAttachment::resolveLayer ( ) const

inline

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

Definition at line 589 of file qrhi.h.

Referenced by QRhiD3D11::endPass(), and QRhiGles2::endPass().

Here is the caller graph for this function:

◆ resolveLevel()

int QRhiColorAttachment::resolveLevel ( ) const

inline

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

Definition at line 592 of file qrhi.h.

Referenced by QRhiD3D11::endPass(), and QRhiGles2::endPass().

Here is the caller graph for this function:

◆ resolveTexture()

QRhiTexture * QRhiColorAttachment::resolveTexture ( ) const

inline

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 texture or renderbuffer. The QRhiTexture in the resolveTexture() is then a non-multisample 2D texture (or texture array) 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.

Definition at line 586 of file qrhi.h.

Referenced by QRhiD3D11::endPass(), QRhiGles2::endPass(), QRhiGles2::enqueueBindFramebuffer(), and QRhiRenderTargetAttachmentTracker::updateResIdList().

Here is the caller graph for this function:

◆ setLayer()

void QRhiColorAttachment::setLayer ( int layer )

inline

Sets the layer index.

Definition at line 581 of file qrhi.h.

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

Here is the caller graph for this function:

◆ setLevel()

void QRhiColorAttachment::setLevel ( int level )

inline

Sets the mip level.

Definition at line 584 of file qrhi.h.

Referenced by QSSGRenderReflectionMap::addReflectionMapEntry(), and renderToKTXFileInternal().

Here is the caller graph for this function:

◆ setMultiViewCount()

void QRhiColorAttachment::setMultiViewCount ( int count )

inline

Sets the view count.

Setting a value larger than 1 indicates that the render target with this color attachment is going to be used with multiview rendering. The default value is 0. Values smaller than 2 indicate no multiview rendering.

When count is set to 2 or greater, the color attachment must be associated with a 2D texture array. layer() and multiViewCount() together define the range of texture array elements that are targeted during multiview rendering.

For example, if layer is 0 and multiViewCount is 2, the texture array must have 2 (or more) elements, and the multiview rendering will target elements 0 and 1. The {gl_ViewIndex} variable in the shaders has a value of 0 or 1 then, where view 0 corresponds to the texture array element 0, and view 1 to the array element 1.

Note: Setting a count larger than 1, using a texture array as texture(), and calling \l{QRhiCommandBuffer::beginPass()}{beginPass()} on a QRhiTextureRenderTarget with this color attachment implies multiview rendering for the entire render pass. multiViewCount() should not be set unless multiview rendering is wanted. Multiview cannot be used with texture types other than 2D texture arrays. (although 3D textures may work, depending on the graphics API and backend; applications are nonetheless advised not to rely on that and only use 2D texture arrays as the render targets of multiview rendering)

See \l{https://registry.khronos.org/OpenGL/extensions/OVR/OVR_multiview.txt}{GL_OVR_multiview} for more details regarding multiview rendering. Do note that Qt requires \l{https://registry.khronos.org/OpenGL/extensions/OVR/OVR_multiview2.txt}{GL_OVR_multiview2} as well, when running on OpenGL (ES).

Multiview rendering is available only when the \l{QRhi::MultiView}{MultiView} feature is reported as supported from \l{QRhi::isFeatureSupported()}{isFeatureSupported()}.

Note: For portability, be aware of limitations that exist for multiview rendering with some of the graphics APIs. It is recommended that multiview render passes do not rely on any of the features that \l{https://registry.khronos.org/OpenGL/extensions/OVR/OVR_multiview.txt}{GL_OVR_multiview} declares as unsupported. The one exception is shader stage outputs other than {gl_Position} depending on {gl_ViewIndex}: that can be relied on (even with OpenGL) because QRhi never reports multiview as supported without {GL_OVR_multiview2} also being present.; Multiview rendering is not supported in combination with tessellation or geometry shaders, even though some implementations of some graphics APIs may allow this.

Since: 6.7

Definition at line 596 of file qrhi.h.

◆ setRenderBuffer()

void QRhiColorAttachment::setRenderBuffer ( QRhiRenderBuffer * rb )

inline

Sets the renderbuffer rb.

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

Definition at line 578 of file qrhi.h.

Referenced by QQuick3DSceneRenderer::synchronize().

Here is the caller graph for this function:

◆ setResolveLayer()

void QRhiColorAttachment::setResolveLayer ( int layer )

inline

Sets the resolve texture layer to use.

Definition at line 590 of file qrhi.h.

◆ setResolveLevel()

void QRhiColorAttachment::setResolveLevel ( int level )

inline

Sets the resolve texture mip level to use.

Definition at line 593 of file qrhi.h.

◆ setResolveTexture()

void QRhiColorAttachment::setResolveTexture ( QRhiTexture * tex )

inline

Sets the resolve texture tex.

tex is expected to be a 2D texture or a 2D texture array. In either case, resolving targets a single mip level of a single layer (array element) of tex. The mip level and array layer are specified by resolveLevel() and resolveLayer().

An exception is \l{setMultiViewCount()}{multiview}: when the color attachment is associated with a texture array and multiview is enabled, the resolve texture must also be a texture array with sufficient elements for all views. In this case all elements that correspond to views are resolved automatically; the behavior is similar to the following pseudo-code: \badcode for (i = 0; i < multiViewCount(); ++i) resolve texture's layer() + i into resolveTexture's resolveLayer() + i

Setting a non-multisample texture to resolve a multisample texture or renderbuffer automatically at the end of the render pass is often preferable to working with multisample textures (and not setting a resolve texture), because it avoids the need for writing dedicated fragment shaders that work exclusively with multisample textures (sampler2DMS, texelFetch, etc.), and rather allows using the same shader as one would if the attachment's texture was not multisampled to begin with. This comes at the expense of an additional resource (the non-multisample tex).

Definition at line 587 of file qrhi.h.

Referenced by QQuick3DSceneRenderer::synchronize().

Here is the caller graph for this function:

◆ setTexture()

void QRhiColorAttachment::setTexture ( QRhiTexture * tex )

inline

Sets the texture tex.

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

Definition at line 575 of file qrhi.h.

Referenced by QSSGRenderShadowMap::addShadowMapEntry().

Here is the caller graph for this function:

◆ texture()

QRhiTexture * QRhiColorAttachment::texture ( ) const

inline

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

Definition at line 574 of file qrhi.h.

Referenced by QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QNullTextureRenderTarget::create(), QRhiD3D11::endPass(), QRhiGles2::endPass(), QRhiGles2::enqueueBindFramebuffer(), QMetalTextureRenderTarget::newCompatibleRenderPassDescriptor(), renderToKTXFileInternal(), and QRhiRenderTargetAttachmentTracker::updateResIdList().

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ QRhiColorAttachment() [1/3]

◆ QRhiColorAttachment() [2/3]

◆ QRhiColorAttachment() [3/3]

Member Function Documentation

◆ layer()

◆ level()

◆ multiViewCount()

◆ renderBuffer()

◆ resolveLayer()

◆ resolveLevel()

◆ resolveTexture()

◆ setLayer()

◆ setLevel()

◆ setMultiViewCount()

◆ setRenderBuffer()

◆ setResolveLayer()

◆ setResolveLevel()

◆ setResolveTexture()

◆ setTexture()

◆ texture()