QSGRenderNode Class
The QSGRenderNode class represents a set of custom rendering commands targeting the graphics API that is in use by the scenegraph. More...
Header: | #include <QSGRenderNode> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
qmake: | QT += quick |
Inherits: | QSGNode |
Public Types
enum | RenderingFlag { BoundedRectRendering, DepthAwareRendering, OpaqueRendering, NoExternalRendering } |
flags | RenderingFlags |
enum | StateFlag { DepthState, StencilState, ScissorState, ColorState, BlendState, …, RenderTargetState } |
flags | StateFlags |
Public Functions
virtual | ~QSGRenderNode() override |
virtual StateFlags | changedStates() const |
const QSGClipNode * | clipList() const |
QRhiCommandBuffer * | commandBuffer() const |
virtual RenderingFlags | flags() const |
qreal | inheritedOpacity() const |
const QMatrix4x4 * | matrix() const |
virtual void | prepare() |
const QMatrix4x4 * | projectionMatrix() const |
virtual QRectF | rect() const |
virtual void | releaseResources() |
QRhiRenderTarget * | renderTarget() const |
Detailed Description
QSGRenderNode allows creating scene graph nodes that perform their own custom rendering via QRhi (the common approach from Qt 6.6 on), directly via a 3D graphics API such as OpenGL, Vulkan, or Metal, or, when the software
backend is in use, via QPainter.
QSGRenderNode is the enabler for one of the three ways to integrate custom 2D/3D rendering into a Qt Quick scene. The other two options are to perform the rendering before
or after
the Qt Quick scene's own rendering, or to generate a whole separate render pass targeting a dedicated render target (a texture) and then have an item in the scene display the texture. The QSGRenderNode-based approach is similar to the former, in the sense that no additional render passes or render targets are involved, and allows injecting custom rendering commands "inline" with the Qt Quick scene's own rendering.
See also Scene Graph - Custom QSGRenderNode.
Member Type Documentation
enum QSGRenderNode::RenderingFlag
flags QSGRenderNode::RenderingFlags
Possible values for the bitmask returned from flags().
Constant | Value | Description |
---|---|---|
QSGRenderNode::BoundedRectRendering | 0x01 | Indicates that the implementation of render() does not render outside the area reported from rect() in item coordinates. Such node implementations can lead to more efficient rendering, depending on the scenegraph backend. For example, the software backend can continue to use the more optimal partial update path when all render nodes in the scene have this flag set. |
QSGRenderNode::DepthAwareRendering | 0x02 | Indicates that the implementations of render() conforms to scenegraph expectations by only generating a Z value of 0 in scene coordinates which is then transformed by the matrices retrieved from RenderState::projectionMatrix() and matrix(), as described in the notes for render(). Such node implementations can lead to more efficient rendering, depending on the scenegraph backend. For example, the batching OpenGL renderer can continue to use a more optimal path when all render nodes in the scene have this flag set. |
QSGRenderNode::OpaqueRendering | 0x04 | Indicates that the implementation of render() writes out opaque pixels for the entire area reported from rect(). By default the renderers must assume that render() can also output semi or fully transparent pixels. Setting this flag can improve performance in some cases. |
QSGRenderNode::NoExternalRendering | 0x08 | Indicates that the implementation of prepare() and render() use the QRhi family of APIs, instead of directly calling a 3D API such as OpenGL, Vulkan, or Metal. |
The RenderingFlags type is a typedef for QFlags<RenderingFlag>. It stores an OR combination of RenderingFlag values.
See also render(), prepare(), rect(), and QRhi.
enum QSGRenderNode::StateFlag
flags QSGRenderNode::StateFlags
This enum is a bit mask identifying several states.
Constant | Value | Description |
---|---|---|
QSGRenderNode::DepthState | 0x01 | Depth |
QSGRenderNode::StencilState | 0x02 | Stencil |
QSGRenderNode::ScissorState | 0x04 | Scissor |
QSGRenderNode::ColorState | 0x08 | Color |
QSGRenderNode::BlendState | 0x10 | Blend |
QSGRenderNode::CullState | 0x20 | Cull |
QSGRenderNode::ViewportState | 0x40 | View poirt |
QSGRenderNode::RenderTargetState | 0x80 | Render target |
The StateFlags type is a typedef for QFlags<StateFlag>. It stores an OR combination of StateFlag values.
Member Function Documentation
[override virtual noexcept]
QSGRenderNode::~QSGRenderNode()
Destructs the render node. Derived classes are expected to perform cleanup similar to releaseResources() in here.
When a low-level graphics API is in use, the scenegraph will make sure there is a CPU-side wait for the GPU to complete all work submitted to the scenegraph's graphics command queue before the scenegraph's nodes are deleted. Therefore there is no need to issue additional waits here, unless the render() implementation is using additional command queues.
With QRhi and resources such as QRhiBuffer, QRhiTexture, QRhiGraphicsPipeline, etc., it is often good practice to use smart pointers, such as std::unique_ptr, which can often avoid the need to implement a destructor, and lead to more compact source code. Keep in mind however that implementing releaseResources(), most likely issuing a number of reset() calls on the unique_ptrs, is still important.
See also releaseResources().
[virtual]
StateFlags QSGRenderNode::changedStates() const
When the underlying rendering API is OpenGL, this function should return a mask where each bit represents graphics states changed by the render() function:
Constant | Description |
---|---|
DepthState | depth write mask, depth test enabled, depth comparison function |
StencilState | stencil write masks, stencil test enabled, stencil operations, stencil comparison functions |
ScissorState | scissor enabled, scissor test enabled |
ColorState | clear color, color write mask |
BlendState | blend enabled, blend function |
CullState | front face, cull face enabled |
ViewportState | viewport |
RenderTargetState | render target |
With APIs other than OpenGL, the only relevant values are the ones that correspond to dynamic state changes recorded on the command list/buffer. For example, RSSetViewports, RSSetScissorRects, OMSetBlendState, OMSetDepthStencilState in case of D3D11, or vkCmdSetViewport, vkCmdSetScissor, vkCmdSetBlendConstants, vkCmdSetStencilRef in case of Vulkan, and only when such commands were added to the scenegraph's command list queried via the QSGRendererInterface::CommandList resource enum. States set in pipeline state objects do not need to be reported here. Similarly, draw call related settings (pipeline states, descriptor sets, vertex or index buffer bindings, root signature, descriptor heaps, etc.) are always set again by the scenegraph so render() can freely change them.
RenderTargetState is no longer supported with APIs like Vulkan. This is by nature. render() is invoked while the Qt Quick scenegraph's main command buffer is recording a renderpass, so there is no possibility of changing the target and starting another renderpass (on that command buffer at least). Therefore returning a value with RenderTargetState set is not sensible.
Note: The software
backend exposes its QPainter and saves and restores before and after invoking render(). Therefore reporting any changed states from here is not necessary.
The function is called by the renderer so it can reset the states after rendering this node. This makes the implementation of render() simpler since it does not have to query and restore these states.
The default implementation returns 0, meaning no relevant state was changed in render().
Note: This function may be called before render().
Note: With Qt 6 and QRhi-based rendering the only relevant values are ViewportState and ScissorState. Other values can be returned but are ignored in practice.
const QSGClipNode *QSGRenderNode::clipList() const
Returns the current clip list.
[since 6.6]
QRhiCommandBuffer *QSGRenderNode::commandBuffer() const
Returns the current command buffer.
This function was introduced in Qt 6.6.
See also renderTarget().
[virtual]
RenderingFlags QSGRenderNode::flags() const
Returns flags describing the behavior of this render node.
The default implementation returns 0.
See also RenderingFlag and rect().
qreal QSGRenderNode::inheritedOpacity() const
Returns the current effective opacity.
const QMatrix4x4 *QSGRenderNode::matrix() const
Returns pointer to the current model-view matrix.
[virtual, since 6.0]
void QSGRenderNode::prepare()
Called from the frame preparation phase. There is a call to this function before each invocation of render().
Unlike render(), this function is called before the scenegraph starts recording the render pass for the current frame on the underlying command buffer. This is useful when doing rendering with graphics APIs, such as Vulkan, where copy type of operations will need to be recorded before the render pass.
The default implementation is empty.
When implementing a QSGRenderNode that uses QRhi to render, query the QRhi object from the QQuickWindow via QQuickWindow::rhi(). To get a QRhiCommandBuffer for submitting work to, call commandBuffer(). To query information about the active render target, call renderTarget(). See the {Scene Graph - Custom QSGRenderNode} example for details.
This function was introduced in Qt 6.0.
[since 6.5]
const QMatrix4x4 *QSGRenderNode::projectionMatrix() const
Returns pointer to the current projection matrix.
In render() this is the same matrix that is returned from RenderState::projectionMatrix(). This getter exists so that prepare() also has a way to query the projection matrix.
When working with a modern graphics API, or Qt's own graphics abstraction layer, it is more than likely that one will want to load *projectionMatrix() * *matrix()
into a uniform buffer. That is however something that needs to be done in prepare(), so outside the recording of a render pass. That is why both matrices are queriable directly from the QSGRenderNode, both in prepare() and render().
This function was introduced in Qt 6.5.
[virtual]
QRectF QSGRenderNode::rect() const
Returns the bounding rectangle in item coordinates for the area render() touches. The value is only in use when flags() includes BoundedRectRendering, ignored otherwise.
Reporting the rectangle in combination with BoundedRectRendering is particularly important with the software
backend because otherwise having a rendernode in the scene would trigger fullscreen updates, skipping all partial update optimizations.
For rendernodes covering the entire area of a corresponding QQuickItem the return value will be (0, 0, item->width(), item->height()).
Note: Nodes are also free to render outside the boundaries specified by the item's width and height, since the scenegraph nodes are not bounded by the QQuickItem geometry, as long as this is reported correctly from this function.
See also flags().
[virtual]
void QSGRenderNode::releaseResources()
This function is called when all custom graphics resources allocated by this node have to be freed immediately. In case the node does not directly allocate graphics resources (buffers, textures, render targets, fences, etc.) through the graphics API that is in use, there is nothing to do here.
Failing to release all custom resources can lead to incorrect behavior in graphics device loss scenarios on some systems since subsequent reinitialization of the graphics system may fail.
Note: Some scenegraph backends may choose not to call this function. Therefore it is expected that QSGRenderNode implementations perform cleanup both in their destructor and in releaseResources().
Unlike with the destructor, it is expected that render() can reinitialize all resources it needs when called after a call to releaseResources().
With OpenGL, the scenegraph's OpenGL context will be current both when calling the destructor and this function.
[since 6.6]
QRhiRenderTarget *QSGRenderNode::renderTarget() const
Returns the current render target.
This is provided mainly to enable prepare() and render() implementations that use QRhi accessing the QRhiRenderTarget's renderPassDescriptor or pixel size.
To build a QRhiGraphicsPipeline, which implies having to provide a QRhiRenderPassDescriptor, query the renderPassDescriptor from the render target. Be aware however that the render target may change over the lifetime of the custom QQuickItem and the QSGRenderNode. For example, consider what happens when dynamically setting layer.enabled: true
on the item or an ancestor of it: this triggers rendering into a texture, not directly to the window, which means the QSGRenderNode is going to work with a different render target from then on. The new render target may then have a different pixel format, which can make already built graphics pipelines incompatible. This can be handled with logic such as the following:
if (m_pipeline && renderTarget()->renderPassDescriptor()->serializedFormat() != m_renderPassFormat) { delete m_pipeline; m_pipeline = nullptr; } if (!m_pipeline) { // Build a new QRhiGraphicsPipeline. // ... // Store the serialized format for fast and simple comparisons later on. m_renderPassFormat = renderTarget()->renderPassDescriptor()->serializedFormat(); }
This function was introduced in Qt 6.6.
See also commandBuffer().