QQuickRenderTarget Class Reference

The QQuickRenderTarget class provides an opaque container for native graphics resources specifying a render target, and associated metadata. More...

#include <qquickrendertarget.h>

Collaboration diagram for QQuickRenderTarget:

Public Types
enum class	Flag { MultisampleResolve = 0x01 }
	Flags for the static QQuickRenderTarget constructor functions. More...

Public Member Functions
	QQuickRenderTarget ()
	Constructs a default QQuickRenderTarget that does not reference any native objects.
	~QQuickRenderTarget ()
	Destructor.
	QQuickRenderTarget (const QQuickRenderTarget &other)
QQuickRenderTarget &	operator= (const QQuickRenderTarget &other)
bool	isNull () const
qreal	devicePixelRatio () const
void	setDevicePixelRatio (qreal ratio)
	Sets the device pixel ratio for this render target to ratio.
bool	mirrorVertically () const
void	setMirrorVertically (bool enable)
	Sets the size of the render target contents should be mirrored vertically to enable when drawing.
QRhiTexture *	depthTexture () const
void	setDepthTexture (QRhiTexture *texture)
	Requests using the given texture as the depth or depth-stencil buffer.

Static Public Member Functions
static QQuickRenderTarget	fromRhiRenderTarget (QRhiRenderTarget *renderTarget)
static QQuickRenderTarget	fromPaintDevice (QPaintDevice *device)

Friends
class	QQuickRenderTargetPrivate
bool	operator== (const QQuickRenderTarget &lhs, const QQuickRenderTarget &rhs) noexcept
bool	operator!= (const QQuickRenderTarget &lhs, const QQuickRenderTarget &rhs) noexcept

Detailed Description

The QQuickRenderTarget class provides an opaque container for native graphics resources specifying a render target, and associated metadata.

Since

6.0 \inmodule QtQuick

See also

QQuickWindow::setRenderTarget(), QQuickGraphicsDevice

Definition at line 25 of file qquickrendertarget.h.

Member Enumeration Documentation

Flag

enum class QQuickRenderTarget::Flag

strong

Flags for the static QQuickRenderTarget constructor functions.

\value MultisampleResolve Indicates the the sampleCount argument is not the number of samples for the provided texture (and that the texture is still a non-multisample texture), but rather the desired samples for multisample antialiasing. Triggers automatically creating and managing an intermediate multisample texture (or texture array) as the color buffer, transparently to the application. The samples are resolved into the provided texture at the end of the render pass automatically. When this flag is not set, and the sampleCount argument is greater than 1, it implies the provided texture is multisample. The flag has no effect is the sampleCount is 1 (indicating that multisampling is not involved).

Since

6.8

Enumerator
MultisampleResolve

Definition at line 28 of file qquickrendertarget.h.

Constructor & Destructor Documentation

QQuickRenderTarget() [1/2]

QQuickRenderTarget::QQuickRenderTarget

(

)

Constructs a default QQuickRenderTarget that does not reference any native objects.

Definition at line 45 of file qquickrendertarget.cpp.

~QQuickRenderTarget()

QQuickRenderTarget::~QQuickRenderTarget

(

)

Destructor.

Definition at line 79 of file qquickrendertarget.cpp.

References QBasicAtomicInteger< T >::deref(), and QQuickRenderTargetPrivate::ref.

Here is the call graph for this function:

QQuickRenderTarget() [2/2]

QQuickRenderTarget::QQuickRenderTarget

(

const QQuickRenderTarget &

other

)

Definition at line 61 of file qquickrendertarget.cpp.

References QBasicAtomicInteger< T >::ref(), and QQuickRenderTargetPrivate::ref.

Here is the call graph for this function:

Member Function Documentation

depthTexture()

QRhiTexture * QQuickRenderTarget::depthTexture

(

)

const

Returns

the currently set depth texture or, in most cases, \nullptr.

The value is only non-null when setDepthTexture() was called.

Since

6.8

Definition at line 172 of file qquickrendertarget.cpp.

References QQuickRenderTargetPrivate::customDepthTexture.

devicePixelRatio()

qreal QQuickRenderTarget::devicePixelRatio

(

)

const

Returns

the device pixel ratio for the render target. This is the ratio between {device pixels} and {device independent pixels}.

The default device pixel ratio is 1.0.

Since

6.3

See also

setDevicePixelRatio()

Definition at line 104 of file qquickrendertarget.cpp.

References QQuickRenderTargetPrivate::devicePixelRatio.

fromPaintDevice()

QQuickRenderTarget QQuickRenderTarget::fromPaintDevice ( QPaintDevice * device )

static

Returns

a new QQuickRenderTarget referencing a paint device object specified by device.

This option of redirecting rendering to a QPaintDevice is available only when running with the software backend of Qt Quick.

Note

The QQuickRenderTarget does not take ownship of device, it is the caller's responsibility to ensure the object exists as long as necessary.

Since

6.4

See also

QQuickWindow::setRenderTarget(), QQuickRenderControl

Definition at line 1153 of file qquickrendertarget.cpp.

References d, device, and QQuickRenderTargetPrivate::get().

Here is the call graph for this function:

fromRhiRenderTarget()

QQuickRenderTarget QQuickRenderTarget::fromRhiRenderTarget ( QRhiRenderTarget * renderTarget )

static

Returns

a new QQuickRenderTarget referencing an OpenGL texture object specified by textureId.

format specifies the native internal format of the texture. Only texture formats that are supported by Qt's rendering infrastructure should be used.

pixelSize specifies the size of the image, in pixels. Currently only 2D textures are supported.

sampleCount specifies the number of samples. 0 or 1 means no multisampling, while a value like 4 or 8 states that the native object is a multisample texture.

The texture is used as the first color attachment of the render target used by the Qt Quick scenegraph. A depth-stencil buffer, if applicable, is created and used automatically.

The OpenGL object name textureId must be a valid name in the rendering context used by the Qt Quick scenegraph.

Note

the resulting QQuickRenderTarget does not own any native resources, it merely contains references and the associated metadata of the size and sample count. It is the caller's responsibility to ensure that the native resource exists as long as necessary.

Since

6.4

See also

QQuickWindow::setRenderTarget(), QQuickRenderControl

Returns

a new QQuickRenderTarget referencing a D3D11 texture object specified by texture.

format specifies the DXGI_FORMAT of the texture. Only texture formats that are supported by Qt's rendering infrastructure should be used.

pixelSize specifies the size of the image, in pixels. Currently only 2D textures are supported.

sampleCount specifies the number of samples. 0 or 1 means no multisampling, while a value like 4 or 8 states that the native object is a multisample texture.

The texture is used as the first color attachment of the render target used by the Qt Quick scenegraph. A depth-stencil buffer, if applicable, is created and used automatically.

Note

the resulting QQuickRenderTarget does not own any native resources, it merely contains references and the associated metadata of the size and sample count. It is the caller's responsibility to ensure that the native resource exists as long as necessary.

Since

6.4

See also

QQuickWindow::setRenderTarget(), QQuickRenderControl

Returns

a new QQuickRenderTarget referencing a Metal texture object specified by texture.

format specifies the MTLPixelFormat of the texture. Only texture formats that are supported by Qt's rendering infrastructure should be used.

pixelSize specifies the size of the image, in pixels. Currently only 2D textures are supported.

sampleCount specifies the number of samples. 0 or 1 means no multisampling, while a value like 4 or 8 states that the native object is a multisample texture.

The texture is used as the first color attachment of the render target used by the Qt Quick scenegraph. A depth-stencil buffer, if applicable, is created and used automatically.

Note

the resulting QQuickRenderTarget does not own any native resources, it merely contains references and the associated metadata of the size and sample count. It is the caller's responsibility to ensure that the native resource exists as long as necessary.

Since

6.4

See also

QQuickWindow::setRenderTarget(), QQuickRenderControl

Returns

a new QQuickRenderTarget referencing a Vulkan image object specified by image. The current layout of the image must be provided as well.

format specifies the VkFormat of the image. Only image formats that are supported by Qt's rendering infrastructure should be used.

pixelSize specifies the size of the image, in pixels. Currently only 2D textures are supported.

sampleCount specifies the number of samples. 0 or 1 means no multisampling, while a value like 4 or 8 states that the native object is a multisample texture.

The image is used as the first color attachment of the render target used by the Qt Quick scenegraph. A depth-stencil buffer, if applicable, is created and used automatically.

Note

the resulting QQuickRenderTarget does not own any native resources, it merely contains references and the associated metadata of the size and sample count. It is the caller's responsibility to ensure that the native resource exists as long as necessary.

Since

6.4

See also

QQuickWindow::setRenderTarget(), QQuickRenderControl

Returns

a new QQuickRenderTarget referencing an existing renderTarget.

renderTarget will in most cases be a QRhiTextureRenderTarget, which allows directing the Qt Quick scene's rendering into a QRhiTexture.

Note

the resulting QQuickRenderTarget does not own renderTarget and any underlying native resources, it merely contains references and the associated metadata of the size and sample count. It is the caller's responsibility to ensure that the referenced resources exists as long as necessary.

Since

6.6

See also

QQuickWindow::setRenderTarget(), QQuickRenderControl

Definition at line 1121 of file qquickrendertarget.cpp.

References d, QQuickRenderTargetPrivate::get(), QRhiRenderTarget::pixelSize(), qWarning, and QRhiRenderTarget::sampleCount().

Referenced by QSGRhiSupport::grabOffscreen().

Here is the call graph for this function:

Here is the caller graph for this function:

isNull()

bool QQuickRenderTarget::isNull

(

)

const

Returns

true if this QQuickRenderTarget is default constructed, referencing no native objects.

Definition at line 89 of file qquickrendertarget.cpp.

References QQuickRenderTargetPrivate::type.

mirrorVertically()

bool QQuickRenderTarget::mirrorVertically

(

)

const

Returns

Returns whether the render target is mirrored vertically.

The default value is {false}.

Since

6.4

See also

setMirrorVertically()

Definition at line 139 of file qquickrendertarget.cpp.

References QQuickRenderTargetPrivate::mirrorVertically.

operator=()

QQuickRenderTarget & QQuickRenderTarget::operator=

(

const QQuickRenderTarget &

other

)

Definition at line 70 of file qquickrendertarget.cpp.

References other(), and qAtomicAssign().

Here is the call graph for this function:

setDepthTexture()

void QQuickRenderTarget::setDepthTexture

(

QRhiTexture *

texture

)

Requests using the given texture as the depth or depth-stencil buffer.

Ownership of texture is not taken.

The request is only taken into account when relevant. For example, calling this function has no effect with fromRhiRenderTarget(), fromPaintDevice(), or fromOpenGLRenderBuffer().

Normally a depth-stencil buffer is created automatically, transparently to the user of QQuickRenderTarget. Therefore, there is no need to call this function in most cases when working with QQuickRenderTarget. In special circumstances, it can however become essential to be able to provide a texture to render depth (or depth and stencil) data into, instead of letting Qt Quick create its own intermediate textures or buffers. An example of this is \l{https://www.khronos.org/openxr/}{OpenXR} and its extensions such as \l{https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#XR_KHR_composition_layer_depth}{XR_KHR_composition_layer_depth}. In order to "submit the depth buffer" to the XR compositor, one has to, in practice, retrieve an already created depth (depth-stencil) texture from OpenXR (from the XrSwapchain) and use that texture as the render target for depth data. That would not be possible without this function.

Note

The texture is always expected to be a non-multisample 2D texture or texture array (for multiview). If MSAA is involved, the samples are resolved into texture at the end of the render pass, regardless of having the MultisampleResolve flag set or not. MSAA is only supported for depth (depth-stencil) textures when the underlying 3D API supports this, and this support is not universally available. See \l{QRhi::ResolveDepthStencil}{the relevant QRhi feature flag} for details. When this is not supported and multisampling is requested in combination with a custom depth texture, texture is not going to be touched during rendering and a warning is printed.

Since

6.8

Note

When it comes to OpenGL and OpenGL ES, using depth textures is not functional on OpenGL ES 2.0 and requires at least OpenGL ES 3.0. Multisample (MSAA) support is not available without at least OpenGL ES 3.1, or OpenGL 3.0 on desktop.

Definition at line 216 of file qquickrendertarget.cpp.

References QQuickRenderTargetPrivate::customDepthTexture.

Referenced by QOpenXRGraphicsOpenGL::renderTarget(), QOpenXRGraphicsOpenGLES::renderTarget(), and QOpenXRGraphicsVulkan::renderTarget().

Here is the caller graph for this function:

setDevicePixelRatio()

void QQuickRenderTarget::setDevicePixelRatio

(

qreal

ratio

)

Sets the device pixel ratio for this render target to ratio.

This is the ratio between {device pixels} and {device independent pixels}.

Note that the specified device pixel ratio value will be ignored if QQuickRenderControl::renderWindow() is re-implemented to return a valid QWindow.

Since

6.3

See also

devicePixelRatio()

Definition at line 121 of file qquickrendertarget.cpp.

References QQuickRenderTargetPrivate::devicePixelRatio.

setMirrorVertically()

void QQuickRenderTarget::setMirrorVertically

(

bool

enable

)

Sets the size of the render target contents should be mirrored vertically to enable when drawing.

This allows easy integration of third-party rendering code that does not follow the standard expectations.

Note

This function should not be used when using the software backend.

Since

6.4

See also

mirrorVertically()

Definition at line 156 of file qquickrendertarget.cpp.

References QQuickRenderTargetPrivate::mirrorVertically.

Friends And Related Symbol Documentation

operator!=

bool QQuickRenderTarget::operator!= ( const QQuickRenderTarget & a, const QQuickRenderTarget & b )

friend

Returns

true if a and b refer to a different set of native objects, or the associated data (size, sample count) does not match.

Definition at line 90 of file qquickrendertarget.h.

operator==

bool QQuickRenderTarget::operator== ( const QQuickRenderTarget & a, const QQuickRenderTarget & b )

friend

Returns

true if a and b refer to the same set of native objects and have matching associated data (size, sample count).

Definition at line 88 of file qquickrendertarget.h.

QQuickRenderTargetPrivate

friend class QQuickRenderTargetPrivate

friend

Definition at line 86 of file qquickrendertarget.h.

---

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

• qtdeclarative/src/quick/items/qquickrendertarget.h (8e45b822d4e880f4625da542abb1cc016b1ab2e4)
• qtdeclarative/src/quick/items/qquickrendertarget.cpp (8e45b822d4e880f4625da542abb1cc016b1ab2e4)