QQuickRhiItemRenderer Class

Member Function Documentation

QQuickRhiItemRenderer::QQuickRhiItemRenderer()

Constructs a new renderer.

This function is called on the rendering thread during the scene graph sync phase when the GUI thread is blocked.

See also QQuickRhiItem::createRenderer().

[virtual noexcept] QQuickRhiItemRenderer::~QQuickRhiItemRenderer()

The Renderer is automatically deleted when the scene graph resources for the QQuickRhiItem item are cleaned up.

This function is called on the rendering thread.

Under certain conditions it is normal and expected that the renderer object is destroyed and then recreated. This is because the renderer's lifetime effectively follows the underlying scene graph node. For example, when changing the parent of a QQuickRhiItem object so that it then belongs to a different QQuickWindow, the scene graph nodes are all dropped and recreated due to the window change. This will also involve dropping and creating a new QQuickRhiItemRenderer.

Unlike QRhiWidget, QQuickRhiItemRenderer has no need to implement additional code paths for releasing (or early-relasing) graphics resources created via QRhi. It is sufficient to release everything in the destructor, or rely on smart pointers.

[protected] QRhiTexture *QQuickRhiItemRenderer::colorTexture() const

Returns the texture serving as the color buffer for the item.

Must only be called from initialize() and render().

Unlike the depth-stencil buffer and the QRhiRenderTarget, this texture is always available and is managed by the QQuickRhiItem, independent of the value of isAutoRenderTargetEnabled.

See also msaaColorBuffer(), depthStencilBuffer(), renderTarget(), and resolveTexture().

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::depthStencilBuffer() const

Returns the depth-stencil buffer used by the item's rendering.

Must only be called from initialize() and render().

Available only when isAutoRenderTargetEnabled is true. Otherwise the returned value is nullptr and it is up the reimplementation of initialize() to create and manage a depth-stencil buffer and a QRhiTextureRenderTarget.

See also colorTexture() and renderTarget().

[pure virtual protected] void QQuickRhiItemRenderer::initialize(QRhiCommandBuffer *cb)

Called when the item is initialized for the first time, when the associated texture's size, format, or sample count changes, or when the QRhi or texture change for any reason. The function is expected to maintain (create if not yet created, adjust and rebuild if the size has changed) the graphics resources used by the rendering code in render().

To query the QRhi, QRhiTexture, and other related objects, call rhi(), colorTexture(), depthStencilBuffer(), and renderTarget().

When the item size changes, the QRhi object, the color buffer texture, and the depth stencil buffer objects are all the same instances (so the getters return the same pointers) as before, but the color and depth/stencil buffers will likely have been rebuilt, meaning the size and the underlying native texture resource may be different than in the last invocation.

Reimplementations should also be prepared that the QRhi object and the color buffer texture may change between invocations of this function. For example, when the item is reparented so that it belongs to a new QQuickWindow, the the QRhi and all related resources managed by the QQuickRhiItem will be different instances than before in the subsequent call to this function. Is is then important that all existing QRhi resources previously created by the subclass are destroyed because they belong to the previous QRhi that should not be used anymore.

When isAutoRenderTargetEnabled is true, which is the default, a depth-stencil QRhiRenderBuffer and a QRhiTextureRenderTarget associated with the colorTexture() (or msaaColorBuffer()) and the depth-stencil buffer are created and managed automatically. Reimplementations of initialize() and render() can query those objects via depthStencilBuffer() and renderTarget(). When isAutoRenderTargetEnabled is set to false, these objects are no longer created and managed automatically. Rather, it will be up the the initialize() implementation to create buffers and set up the render target as it sees fit. When manually managing additional color or depth-stencil attachments for the render target, their size and sample count must always follow the size and sample count of colorTexture() (or msaaColorBuffer()), otherwise rendering or 3D API validation errors may occur.

The subclass-created graphics resources are expected to be released in the destructor implementation of the subclass.

cb is the QRhiCommandBuffer for the current frame. The function is called with a frame being recorded, but without an active render pass. The command buffer is provided primarily to allow enqueuing resource updates without deferring to render().

This function is called on the render thread, if there is one.

See also render().

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::msaaColorBuffer() const

Returns the renderbuffer serving as the multisample color buffer for the item.

Must only be called from initialize() and render().

When sampleCount is larger than 1, and so multisample antialising is enabled, the returned QRhiRenderBuffer has a matching sample count and serves as the color buffer. Graphics pipelines used to render into this buffer must be created with the same sample count, and the depth-stencil buffer's sample count must match as well. The multisample content is expected to be resolved into the texture returned from resolveTexture(). When isAutoRenderTargetEnabled is true, renderTarget() is set up automatically to do this, by setting up msaaColorBuffer() as the renderbuffer of color attachment 0 and resolveTexture() as its resolveTexture.

When MSAA is not in use, the return value is nullptr. Use colorTexture() instead then.

Depending on the underlying 3D graphics API, there may be no practical difference between multisample textures and color renderbuffers with a sample count larger than 1 (QRhi may just map both to the same native resource type). Some older APIs however may differentiate between textures and renderbuffers. In order to support OpenGL ES 3.0, where multisample renderbuffers are available, but multisample textures are not, QQuickRhiItem always performs MSAA by using a multisample QRhiRenderBuffer as the color attachment (and never a multisample QRhiTexture).

See also colorTexture(), depthStencilBuffer(), renderTarget(), and resolveTexture().

[pure virtual protected] void QQuickRhiItemRenderer::render(QRhiCommandBuffer *cb)

Called when the backing color buffer's contents needs updating.

There is always at least one call to initialize() before this function is called.

To request updates, call QQuickItem::update() when calling from QML or from C++ code on the main/GUI thread (e.g. when in a property setter), or update() when calling from within a QQuickRhiItemRenderer callback. Calling QQuickRhiItemRenderer's update() from within render() will lead to triggering updates continuously.

cb is the QRhiCommandBuffer for the current frame. The function is called with a frame being recorded, but without an active render pass.

This function is called on the render thread, if there is one.

See also initialize() and synchronize().

[protected] QRhiRenderTarget *QQuickRhiItemRenderer::renderTarget() const

Returns the render target object that must be used with QRhiCommandBuffer::beginPass() in reimplementations of render().

Must only be called from initialize() and render().

Available only when isAutoRenderTargetEnabled is true. Otherwise the returned value is nullptr and it is up the reimplementation of initialize() to create and manage a depth-stencil buffer and a QRhiTextureRenderTarget.

When creating graphics pipelines, a QRhiRenderPassDescriptor is needed. This can be queried from the returned QRhiTextureRenderTarget by calling renderPassDescriptor().

See also colorTexture(), depthStencilBuffer(), and QQuickWindow::effectiveDevicePixelRatio().

[protected] QRhiTexture *QQuickRhiItemRenderer::resolveTexture() const

Returns the non-multisample texture to which the multisample content is resolved.

The result is nullptr when multisample antialiasing is not enabled.

Must only be called from initialize() and render().

With MSAA enabled, this is the texture that gets used by the item's underlying scene graph node when texturing a quad in the main render pass of Qt Quick. However, the QQuickRhiItemRenderer's rendering must target the (multisample) QRhiRenderBuffer returned from msaaColorBuffer(). When isAutoRenderTargetEnabled is true, this is taken care of by the QRhiRenderTarget returned from renderTarget(). Otherwise, it is up to the subclass code to correctly configure a render target object with both the color buffer and resolve textures.

See also colorTexture().

[protected] QRhi *QQuickRhiItemRenderer::rhi() const

Returns the current QRhi object.

Must only be called from initialize() and render().

[pure virtual protected] void QQuickRhiItemRenderer::synchronize(QQuickRhiItem *item)

This function is called on the render thread, if there is one, while the main/GUI thread is blocked. It is called from the item's synchronize step, and allows reading and writing data belonging to the main and render threads. Typically property values stored in the QQuickRhiItem are copied into the QQuickRhiItemRenderer, so that they can be safely read afterwards in render() when the render and main threads continue to work in parallel.

See also initialize() and render().

[protected] void QQuickRhiItemRenderer::update()

Call this function when the content of the offscreen color buffer should be updated. (i.e. to request that render() is called again; the call will happen at a later point, and note that updates are typically throttled to the presentation rate)

This function can be called from render() to schedule an update.