 |
Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
|
|
Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
|
\inmodule QtQuick More...
#include <qquickrhiitem.h>
Inheritance diagram for QQuickRhiItemRenderer: Collaboration diagram for QQuickRhiItemRenderer:Public Member Functions | |
| QQuickRhiItemRenderer () | |
| Constructs a new renderer. | |
| virtual | ~QQuickRhiItemRenderer () |
| The Renderer is automatically deleted when the scene graph resources for the QQuickRhiItem item are cleaned up. | |
Protected Member Functions | |
| virtual void | initialize (QRhiCommandBuffer *cb)=0 |
| 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. | |
| virtual void | synchronize (QQuickRhiItem *item)=0 |
| This function is called on the render thread, if there is one, while the main/GUI thread is blocked. | |
| virtual void | render (QRhiCommandBuffer *cb)=0 |
| Called when the backing color buffer's contents needs updating. | |
| void | update () |
| Call this function when the content of the offscreen color buffer should be updated. | |
| QRhi * | rhi () const |
| QRhiTexture * | colorTexture () const |
| QRhiRenderBuffer * | msaaColorBuffer () const |
| QRhiTexture * | resolveTexture () const |
| QRhiRenderBuffer * | depthStencilBuffer () const |
| QRhiRenderTarget * | renderTarget () const |
Friends | |
| class | QQuickRhiItem |
| class | QQuickRhiItemNode |
\inmodule QtQuick
A QQuickRhiItemRenderer implements the rendering logic of a QQuickRhiItem.
\preliminary
Definition at line 20 of file qquickrhiitem.h.
| 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.
Definition at line 847 of file qquickrhiitem.cpp.
|
virtual |
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 \l 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 \l 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.
Definition at line 870 of file qquickrhiitem.cpp.
|
protected |
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 \l {QQuickRhiItem::}{autoRenderTarget}.
Definition at line 921 of file qquickrhiitem.cpp.
References QQuickRhiItemNode::m_colorTexture.
|
protected |
Must only be called from initialize() and render().
Available only when \l {QQuickRhiItem::}{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.
Definition at line 1003 of file qquickrhiitem.cpp.
References QQuickRhiItemNode::m_depthStencilBuffer.
|
protectedpure virtual |
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 \l{QRhiTexture::pixelSize()}{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 \l {QQuickRhiItem::}{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 \l {QQuickRhiItem::}{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 \l{QRhiCommandBuffer::resourceUpdate()}{resource updates} without deferring to render().
This function is called on the render thread, if there is one.
Implemented in ExampleRhiItemRenderer.
|
protected |
Must only be called from initialize() and render().
When \l {QQuickRhiItem::}{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 \l {QQuickRhiItem::}{autoRenderTarget} is true, renderTarget() is set up automatically to do this, by setting up msaaColorBuffer() as the \l{QRhiColorAttachment::renderBuffer()}{renderbuffer} of color attachment 0 and resolveTexture() as its \l{QRhiColorAttachment::resolveTexture()}{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).
Definition at line 963 of file qquickrhiitem.cpp.
References QQuickRhiItemNode::m_msaaColorBuffer.
|
protectedpure virtual |
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 \l QQuickItem::update() when calling from QML or from C++ code on the main/GUI thread (e.g. when in a property setter), or \l 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.
Implemented in ExampleRhiItemRenderer.
|
protected |
Must only be called from initialize() and render().
Available only when \l {QQuickRhiItem::}{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 \l{QRhiGraphicsPipeline}{graphics pipelines}, a QRhiRenderPassDescriptor is needed. This can be queried from the returned QRhiTextureRenderTarget by calling \l{QRhiTextureRenderTarget::renderPassDescriptor()}{renderPassDescriptor()}.
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 Definition at line 1036 of file qquickrhiitem.cpp.
References QQuickRhiItemNode::m_renderTarget.
Referenced by ExampleRhiItemRenderer::initialize(), and ExampleRhiItemRenderer::render().
Here is the caller graph for this function:
|
protected |
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 \l {QQuickRhiItem::}{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.
Definition at line 986 of file qquickrhiitem.cpp.
References QQuickRhiItemNode::m_resolveTexture.
|
protected |
Must only be called from initialize() and render().
Definition at line 896 of file qquickrhiitem.cpp.
References QQuickRhiItemNode::m_rhi.
Referenced by ExampleRhiItemRenderer::initialize().
Here is the caller graph for this function:
|
protectedpure virtual |
This function is called on the render thread, if there is one, while the main/GUI thread is blocked.
It is called from \l{QQuickItem::updatePaintNode()}{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.
Implemented in ExampleRhiItemRenderer.
|
protected |
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.
Definition at line 885 of file qquickrhiitem.cpp.
References QQuickRhiItemNode::scheduleUpdate().
Here is the call graph for this function:
|
friend |
Definition at line 42 of file qquickrhiitem.h.
|
friend |
Definition at line 43 of file qquickrhiitem.h.
1.10.0