class QQuickRhiItemRenderer#

A QQuickRhiItemRenderer implements the rendering logic of a QQuickRhiItem . More…

New in version 6.7.

Synopsis#

Methods#

def __init__()
def colorTexture()
def depthStencilBuffer()
def msaaColorBuffer()
def renderTarget()
def resolveTexture()
def rhi()
def update()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description#

Note

QQuickRhiItem and QQuickRhiItemRenderer are in tech preview in Qt 6.7. The API is under development and subject to change.

See also

QQuickRhiItem QRhi

__init__()#

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

createRenderer()

colorTexture()#

Return type:: QRhiTexture

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

Note

When sampleCount is larger than 1, and so multisample antialiasing is enabled, the return value is None. Instead, query the QRhiRenderBuffer by calling msaaColorBuffer() .

Note

The backing texture size and sample count can also be queried via the QRhiRenderTarget returned from renderTarget() . This can be more convenient and compact than querying from the QRhiTexture or QRhiRenderBuffer, because it works regardless of multisampling is in use or not.

depthStencilBuffer()#

Return type:: QRhiRenderBuffer

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

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

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

See also

colorTexture() renderTarget()

abstract initialize(cb)#

Parameters:: cb – QRhiCommandBuffer

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 autoRenderTarget 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 autoRenderTarget 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()

msaaColorBuffer()#

Return type:: QRhiRenderBuffer

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 autoRenderTarget 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 None. 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).

Note

abstract render(cb)#

Parameters:: cb – QRhiCommandBuffer

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 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() synchronize()

renderTarget()#

Return type:: QRhiRenderTarget

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

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

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

Note

The returned QRhiTextureRenderTarget always reports a devicePixelRatio() of 1. This is because only swapchains and the associated window have a concept of device pixel ratio, not textures, and the render target here always refers to a texture. If the on-screen scale factor is relevant for rendering, query and store it via the item’s window()->effectiveDevicePixelRatio() in synchronize() . When doing so, always prefer using effectiveDevicePixelRatio() over the base class’ devicePixelRatio().

resolveTexture()#

Return type:: QRhiTexture

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

The result is None 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 autoRenderTarget 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()

rhi()#

Return type:: QRhi

Returns the current QRhi object.

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

abstract synchronize(item)#

Parameters:: item – QQuickRhiItem

This function is called on the render thread, if there is one, while the main/GUI thread is blocked. It is called from item :meth:` <PySide6.QtQuick.QQuickItem.updatePaintNode>` ‘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() render()

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.

Note

This function should be used from inside the renderer. To update the item on the GUI thread, use update() .