A QQuickRhiItemRenderer implements the rendering logic of a QQuickRhiItem . 更多...
| 头： | #include <QQuickRhiItemRenderer> |
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| Since: | Qt 6.7 |
| 状态： | Preliminary |
该类在开发且可能改变。
| QQuickRhiItemRenderer () | |
| virtual | ~QQuickRhiItemRenderer () |
| QRhiTexture * | colorTexture () const |
| QRhiRenderBuffer * | depthStencilBuffer () const |
| virtual void | initialize (QRhiCommandBuffer * cb ) = 0 |
| QRhiRenderBuffer * | msaaColorBuffer () const |
| virtual void | render (QRhiCommandBuffer * cb ) = 0 |
| QRhiRenderTarget * | renderTarget () const |
| QRhiTexture * | resolveTexture () const |
| QRhi * | rhi () const |
| virtual void | synchronize (QQuickRhiItem * item ) = 0 |
| void | update () |
注意： QQuickRhiItem and QQuickRhiItemRenderer are in tech preview in Qt 6.7. The API is under development and subject to change.
另请参阅 QQuickRhiItem and QRhi .
Constructs a new renderer.
This function is called on the rendering thread during the scene graph sync phase when the GUI thread is blocked.
另请参阅 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 .
不像 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 () 和 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.
注意：
当
sampleCount
is larger than 1, and so multisample antialiasing is enabled, the return value is
nullptr
. Instead, query the
QRhiRenderBuffer
通过调用
msaaColorBuffer
().
注意： 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.
另请参阅 msaaColorBuffer (), depthStencilBuffer (), renderTarget ()，和 resolveTexture ().
[protected]
QRhiRenderBuffer
*QQuickRhiItemRenderer::
depthStencilBuffer
() const
Returns the depth-stencil buffer used by the item's rendering.
Must only be called from initialize () 和 render ().
Available only when autoRenderTarget 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
.
另请参阅 colorTexture () 和 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 ()，和 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
和
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
() 和
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 是 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.
另请参阅 render ().
[protected]
QRhiRenderBuffer
*QQuickRhiItemRenderer::
msaaColorBuffer
() const
Returns the renderbuffer serving as the multisample color buffer for the item.
Must only be called from initialize () 和 render ().
当
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
nullptr
。使用
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 ).
注意： 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.
另请参阅 colorTexture (), depthStencilBuffer (), renderTarget ()，和 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 是 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.
另请参阅 initialize () 和 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 () 和 render ().
Available only when autoRenderTarget 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 ， QRhiRenderPassDescriptor is needed. This can be queried from the returned QRhiTextureRenderTarget 通过调用 renderPassDescriptor ().
注意：
返回的
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
().
另请参阅 colorTexture (), depthStencilBuffer ()，和 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 () 和 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.
另请参阅 colorTexture ().
[protected]
QRhi
*QQuickRhiItemRenderer::
rhi
() const
返回当前 QRhi 对象。
Must only be called from initialize () 和 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.
另请参阅 initialize () 和 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.
注意： This function should be used from inside the renderer. To update the item on the GUI thread, use QQuickRhiItem::update ().