QQuickRenderTarget Class

Member Function Documentation

QQuickRenderTarget::QQuickRenderTarget()

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

[noexcept] QQuickRenderTarget::~QQuickRenderTarget()

Destructor.

[since 6.8] 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.

This function was introduced in Qt 6.8.

See also setDepthTexture().

[since 6.3] 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.

This function was introduced in Qt 6.3.

See also setDevicePixelRatio().

[static, since 6.4] QQuickRenderTarget QQuickRenderTarget::fromD3D11Texture(void *texture, uint format, const QSize &pixelSize, int sampleCount = 1)

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.

This function was introduced in Qt 6.4.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static] QQuickRenderTarget QQuickRenderTarget::fromD3D11Texture(void *texture, const QSize &pixelSize, int sampleCount = 1)

This is an overloaded function.

Returns a new QQuickRenderTarget referencing a D3D11 texture object specified by texture. The texture is assumed to have a format of DXGI_FORMAT_R8G8B8A8_UNORM.

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.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static, since 6.8] QQuickRenderTarget QQuickRenderTarget::fromD3D11Texture(void *texture, uint format, QSize pixelSize, int sampleCount, QQuickRenderTarget::Flags flags)

This is an overloaded function.

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, except when flags contains MultisampleResolve. In that case, texture is assumed to be a non-multisample 2D texture and sampleCount defines the number of samples desired. The resulting QQuickRenderTarget will use an intermediate, automatically created multisample texture as its color attachment, and will resolve the samples into texture. This is the recommended approach to perform MSAA when the native texture is not already multisample.

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. When the color buffer is multisample, the depth-stencil buffer will automatically be multisample too.

This function was introduced in Qt 6.8.

See also QQuickWindow::setRenderTarget(), QQuickRenderControl, and fromD3D11Texture().

[static, since 6.6] QQuickRenderTarget QQuickRenderTarget::fromD3D12Texture(void *texture, int resourceState, uint format, const QSize &pixelSize, int sampleCount = 1)

Returns a new QQuickRenderTarget referencing a D3D12 texture object specified by texture.

resourceState must a valid bitmask with bits from D3D12_RESOURCE_STATES, specifying the resource's current state.

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.

This function was introduced in Qt 6.6.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static, since 6.8] QQuickRenderTarget QQuickRenderTarget::fromD3D12Texture(void *texture, int resourceState, uint format, uint viewFormat, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags)

This is an overloaded function.

Returns a new QQuickRenderTarget referencing a D3D12 2D texture or 2D texture array object specified by texture.

resourceState must a valid bitmask with bits from D3D12_RESOURCE_STATES, specifying the resource's current state.

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

viewFormat is the DXGI_FORMAT used for the render target view (RTV). Often the same as format. Functional only when relaxed format casting is supported by the driver, the argument is ignored otherwise. In practice support is expected to be always available on Windows 10 1703 and newer.

pixelSize specifies the size of the image, in pixels. Currently only 2D textures and 2D texture arrays 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, except when flags contains MultisampleResolve. In that case, texture is assumed to be a non-multisample 2D texture or 2D texture array, and sampleCount defines the number of samples desired. The resulting QQuickRenderTarget will use an intermediate, automatically created multisample texture (or texture array) as its color attachment, and will resolve the samples into texture. This is the recommended approach to perform MSAA when the native D3D12 texture is not already multisample.

The number of array elements (layers) is given in arraySize. When greater than 1, it implies multiview rendering (view instancing), which can be relevant with VR/AR especially. arraySize is the number of views, typically 2. See QSGMaterial::viewCount() for details on enabling multiview rendering within the Qt Quick scenegraph.

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. When the color buffer is multisample, the depth-stencil buffer will automatically be multisample too. For multiview rendering, the depth-stencil texture will automatically be made an array with a matching arraySize.

This function was introduced in Qt 6.8.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static, since 6.4] QQuickRenderTarget QQuickRenderTarget::fromMetalTexture(MTLTexture *texture, uint format, const QSize &pixelSize, int sampleCount = 1)

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.

This function was introduced in Qt 6.4.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static] QQuickRenderTarget QQuickRenderTarget::fromMetalTexture(MTLTexture *texture, const QSize &pixelSize, int sampleCount = 1)

This is an overloaded function.

Returns a new QQuickRenderTarget referencing a Metal texture object specified by texture. The texture is assumed to have a format of MTLPixelFormatRGBA8Unorm.

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.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static, since 6.8] QQuickRenderTarget QQuickRenderTarget::fromMetalTexture(MTLTexture *texture, uint format, uint viewFormat, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags)

This is an overloaded function.

Returns a new QQuickRenderTarget referencing a Metal 2D texture or 2D texture array given in texture.

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

viewFormat is usually set to the same value as format. In some cases, such as when rendering into a texture with a _SRGB format and the implicit linear->sRGB conversion on shader writes is not wanted, the value can be different. Note however that the value may be ignored by Qt, when at run time QRhi reports that the QRhi::TextureViewFormat feature is unsupported.

pixelSize specifies the size of the image, in pixels. Currently only 2D textures and 2D texture arrays 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, except when flags contains MultisampleResolve. In that case, texture is assumed to be a non-multisample 2D texture or 2D texture array, and sampleCount defines the number of samples desired. The resulting QQuickRenderTarget will use an intermediate, automatically created multisample texture (or texture array) as its color attachment, and will resolve the samples into texture. This is the recommended approach to perform MSAA when the native Metal texture is not already multisample.

The number of array elements (layers) is given in arraySize. When greater than 1, it implies multiview rendering, which can be relevant with VR/AR especially. arraySize is the number of views, typically 2. See QSGMaterial::viewCount() for details on enabling multiview rendering within the Qt Quick scenegraph.

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. When the color buffer is multisample, the depth-stencil buffer will automatically be multisample too. For multiview rendering, the depth-stencil texture will automatically be made an array with a matching arraySize.

This function was introduced in Qt 6.8.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static, since 6.2] QQuickRenderTarget QQuickRenderTarget::fromOpenGLRenderBuffer(uint renderbufferId, const QSize &pixelSize, int sampleCount = 1)

Returns a new QQuickRenderTarget referencing an OpenGL renderbuffer object specified by renderbufferId.

The renderbuffer will be used as the color attachment for the internal framebuffer object. This function is provided to allow targeting renderbuffers that are created by the application with some external buffer underneath, such as an EGLImageKHR. Once the application has called glEGLImageTargetRenderbufferStorageOES, the renderbuffer can be passed to this function.

pixelSize specifies the size of the image, in pixels.

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 renderbuffer.

This function was introduced in Qt 6.2.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static, since 6.4] QQuickRenderTarget QQuickRenderTarget::fromOpenGLTexture(uint textureId, uint format, const QSize &pixelSize, int sampleCount = 1)

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.

This function was introduced in Qt 6.4.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static] QQuickRenderTarget QQuickRenderTarget::fromOpenGLTexture(uint textureId, const QSize &pixelSize, int sampleCount = 1)

This is an overloaded function.

Returns a new QQuickRenderTarget referencing an OpenGL texture object specified by textureId. The texture is assumed to have a format of GL_RGBA (GL_RGBA8).

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.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static, since 6.8] QQuickRenderTarget QQuickRenderTarget::fromOpenGLTexture(uint textureId, uint format, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags)

This is an overloaded function.

Returns a new QQuickRenderTarget referencing an OpenGL 2D texture or texture array 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 and 2D texture arrays 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, except when flags contains MultisampleResolve. In that case, textureId is assumed to be a non-multisample 2D texture or 2D texture array, and sampleCount defines the number of samples desired. The resulting QQuickRenderTarget will use an intermediate, automatically created multisample texture (or texture array) as its color attachment, and will resolve the samples into textureId. This is the recommended approach to perform MSAA when the native OpenGL texture is not already multisample.

When arraySize is greater than 1, it implies multiview rendering (GL_OVR_multiview, QRhiColorAttachment::setMultiViewCount()), which can be relevant with VR/AR especially. In this case arraySize is the number of views, typically 2. See QSGMaterial::viewCount() for details on enabling multiview rendering within the Qt Quick scenegraph.

A depth-stencil buffer, if applicable, is created and used automatically. When the color buffer is multisample, the depth-stencil buffer will automatically be multisample too. For multiview rendering, the depth-stencil texture will automatically be made an array with a matching arraySize.

The OpenGL object name textureId must be a valid 2D texture name in the rendering context used by the Qt Quick scenegraph. When arraySize is greater than 1, textureId must be a valid 2D texture array name.

This function was introduced in Qt 6.8.

See also QQuickWindow::setRenderTarget(), QQuickRenderControl, and fromOpenGLTexture().

[static, since 6.4] QQuickRenderTarget QQuickRenderTarget::fromPaintDevice(QPaintDevice *device)

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.

This function was introduced in Qt 6.4.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static, since 6.6] QQuickRenderTarget QQuickRenderTarget::fromRhiRenderTarget(QRhiRenderTarget *renderTarget)

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.

This function was introduced in Qt 6.6.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static, since 6.4] QQuickRenderTarget QQuickRenderTarget::fromVulkanImage(VkImage image, VkImageLayout layout, VkFormat format, const QSize &pixelSize, int sampleCount = 1)

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.

This function was introduced in Qt 6.4.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static] QQuickRenderTarget QQuickRenderTarget::fromVulkanImage(VkImage image, VkImageLayout layout, const QSize &pixelSize, int sampleCount = 1)

This is an overloaded function.

Returns a new QQuickRenderTarget referencing a Vulkan image object specified by image. The image is assumed to have a format of VK_FORMAT_R8G8B8A8_UNORM.

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.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

[static, since 6.8] QQuickRenderTarget QQuickRenderTarget::fromVulkanImage(VkImage image, VkImageLayout layout, VkFormat format, VkFormat viewFormat, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags)

This is an overloaded function.

Returns a new QQuickRenderTarget referencing a Vulkan image object specified by image. The current layout of the image must be provided as well. The image must be either a 2D texture or 2D texture array.

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

viewFormat is usually set to the same value as format. In some cases, such as when rendering into a texture with a _SRGB format and the implicit linear->sRGB conversion on shader writes is not wanted, the value can be different. (for example, a format of VK_FORMAT_R8G8B8A8_SRGB and viewFormat of VK_FORMAT_R8G8B8A8_UNORM).

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, except when flags contains MultisampleResolve. In that case, image is assumed to be a non-multisample 2D texture or 2D texture array, and sampleCount defines the number of samples desired. The resulting QQuickRenderTarget will use an intermediate, automatically created multisample texture (or texture array) as its color attachment, and will resolve the samples into image. This is the recommended approach to perform MSAA when the native Vulkan image is not already multisample.

The number of array elements (layers) is given in arraySize. When greater than 1, it implies multiview rendering (VK_KHR_multiview), which can be relevant with VR/AR especially. arraySize is the number of views, typically 2. See QSGMaterial::viewCount() for details on enabling multiview rendering within the Qt Quick scenegraph.

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. When the color buffer is multisample, the depth-stencil buffer will automatically be multisample too. For multiview rendering, the depth-stencil texture will automatically be made an array with a matching arraySize.

This function was introduced in Qt 6.8.

See also QQuickWindow::setRenderTarget() and QQuickRenderControl.

bool QQuickRenderTarget::isNull() const

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

[since 6.4] bool QQuickRenderTarget::mirrorVertically() const

Returns Returns whether the render target is mirrored vertically.

The default value is false.

This function was introduced in Qt 6.4.

See also setMirrorVertically().

[since 6.8] 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 OpenXR and its extensions such as 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.

This function was introduced in Qt 6.8.

See also depthTexture().

[since 6.3] 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.

This function was introduced in Qt 6.3.

See also devicePixelRatio().

[since 6.4] 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.

This function was introduced in Qt 6.4.

See also mirrorVertically().