![]() |
Qt 6.x
The Qt SDK
|
The QSGRenderNode class represents a set of custom rendering commands targeting the graphics API that is in use by the scenegraph. More...
#include <qsgrendernode.h>
Classes | |
struct | RenderState |
Public Types | |
enum | StateFlag { DepthState = 0x01 , StencilState = 0x02 , ScissorState = 0x04 , ColorState = 0x08 , BlendState = 0x10 , CullState = 0x20 , ViewportState = 0x40 , RenderTargetState = 0x80 } |
This enum is a bit mask identifying several states. More... | |
enum | RenderingFlag { BoundedRectRendering = 0x01 , DepthAwareRendering = 0x02 , OpaqueRendering = 0x04 , NoExternalRendering = 0x08 } |
Possible values for the bitmask returned from flags(). More... | |
![]() | |
enum | NodeType { BasicNodeType , GeometryNodeType , TransformNodeType , ClipNodeType , OpacityNodeType , RootNodeType , RenderNodeType } |
Can be used to figure out the type of node. More... | |
enum | Flag { OwnedByParent = 0x0001 , UsePreprocess = 0x0002 , OwnsGeometry = 0x00010000 , OwnsMaterial = 0x00020000 , OwnsOpaqueMaterial = 0x00040000 , IsVisitableNode = 0x01000000 } |
The QSGNode::Flag enum describes flags on the QSGNode. More... | |
enum | DirtyStateBit { DirtySubtreeBlocked = 0x0080 , DirtyMatrix = 0x0100 , DirtyNodeAdded = 0x0400 , DirtyNodeRemoved = 0x0800 , DirtyGeometry = 0x1000 , DirtyMaterial = 0x2000 , DirtyOpacity = 0x4000 , DirtyForceUpdate = 0x8000 , DirtyUsePreprocess = UsePreprocess , DirtyPropagationMask } |
Used in QSGNode::markDirty() to indicate how the scene graph has changed. More... | |
Public Member Functions | |
QSGRenderNode () | |
~QSGRenderNode () override | |
Destructs the render node. | |
virtual StateFlags | changedStates () const |
When the underlying rendering API is OpenGL, this function should return a mask where each bit represents graphics states changed by the \l render() function: | |
virtual void | prepare () |
Called from the frame preparation phase. | |
virtual void | render (const RenderState *state)=0 |
This function is called by the renderer and should paint this node with directly invoking commands in the graphics API (OpenGL, Direct3D, etc.) currently in use. | |
virtual void | releaseResources () |
This function is called when all custom graphics resources allocated by this node have to be freed immediately. | |
virtual RenderingFlags | flags () const |
virtual QRectF | rect () const |
const QMatrix4x4 * | projectionMatrix () const |
const QMatrix4x4 * | matrix () const |
const QSGClipNode * | clipList () const |
qreal | inheritedOpacity () const |
QRhiRenderTarget * | renderTarget () const |
QRhiCommandBuffer * | commandBuffer () const |
![]() | |
QSGNode () | |
Constructs a new node. | |
virtual | ~QSGNode () |
Destroys the node. | |
QSGNode * | parent () const |
Returns the parent node of this node. | |
void | removeChildNode (QSGNode *node) |
Removes node from this node's list of children. | |
void | removeAllChildNodes () |
Removes all child nodes from this node's list of children. | |
void | prependChildNode (QSGNode *node) |
Prepends node to this node's the list of children. | |
void | appendChildNode (QSGNode *node) |
Appends node to this node's list of children. | |
void | insertChildNodeBefore (QSGNode *node, QSGNode *before) |
Inserts node to this node's list of children before the node specified with before. | |
void | insertChildNodeAfter (QSGNode *node, QSGNode *after) |
Inserts node to this node's list of children after the node specified with after. | |
void | reparentChildNodesTo (QSGNode *newParent) |
int | childCount () const |
Returns the number of child nodes. | |
QSGNode * | childAtIndex (int i) const |
Returns the child at index i. | |
QSGNode * | firstChild () const |
Returns the first child of this node. | |
QSGNode * | lastChild () const |
Returns the last child of this node. | |
QSGNode * | nextSibling () const |
Returns the node after this in the parent's list of children. | |
QSGNode * | previousSibling () const |
Returns the node before this in the parent's list of children. | |
NodeType | type () const |
Returns the type of this node. | |
QT_DEPRECATED void | clearDirty () |
void | markDirty (DirtyState bits) |
Notifies all connected renderers that the node has dirty bits. | |
QT_DEPRECATED DirtyState | dirtyState () const |
virtual bool | isSubtreeBlocked () const |
Returns whether this node and its subtree is available for use. | |
Flags | flags () const |
Returns the set of flags for this node. | |
void | setFlag (Flag, bool=true) |
Sets the flag f on this node if enabled is true; otherwise clears the flag. | |
void | setFlags (Flags, bool=true) |
Sets the flags f on this node if enabled is true; otherwise clears the flags. | |
virtual void | preprocess () |
Override this function to do processing on the node before it is rendered. | |
Friends | |
class | QSGRenderNodePrivate |
Additional Inherited Members | |
![]() | |
QSGNode (NodeType type) | |
Constructs a new node with the given node type. | |
QSGNode (QSGNodePrivate &dd, NodeType type) | |
Constructs a new node with the given node type. | |
![]() | |
QScopedPointer< QSGNodePrivate > | d_ptr |
The QSGRenderNode class represents a set of custom rendering commands targeting the graphics API that is in use by the scenegraph.
\inmodule QtQuick
Definition at line 15 of file qsgrendernode.h.
Possible values for the bitmask returned from flags().
\value BoundedRectRendering 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.
\value DepthAwareRendering 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.
\value OpaqueRendering 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.
\omitvalue NoExternalRendering
Enumerator | |
---|---|
BoundedRectRendering | |
DepthAwareRendering | |
OpaqueRendering | |
NoExternalRendering |
Definition at line 30 of file qsgrendernode.h.
This enum is a bit mask identifying several states.
\value DepthState Depth \value StencilState Stencil \value ScissorState Scissor \value ColorState Color \value BlendState Blend \value CullState Cull \value ViewportState View poirt \value RenderTargetState Render target
Enumerator | |
---|---|
DepthState | |
StencilState | |
ScissorState | |
ColorState | |
BlendState | |
CullState | |
ViewportState | |
RenderTargetState |
Definition at line 18 of file qsgrendernode.h.
QSGRenderNode::QSGRenderNode | ( | ) |
Definition at line 17 of file qsgrendernode.cpp.
|
override |
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.
Definition at line 35 of file qsgrendernode.cpp.
|
virtual |
When the underlying rendering API is OpenGL, this function should return a mask where each bit represents graphics states changed by the \l render() function:
\value DepthState depth write mask, depth test enabled, depth comparison function \value StencilState stencil write masks, stencil test enabled, stencil operations, stencil comparison functions \value ScissorState scissor enabled, scissor test enabled \value ColorState clear color, color write mask \value BlendState blend enabled, blend function \value CullState front face, cull face enabled \value ViewportState viewport \value 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.
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().
Reimplemented in QQuickShapeSoftwareRenderNode, QSGMapboxGLRenderNode, and QQuick3DSGRenderNode.
Definition at line 94 of file qsgrendernode.cpp.
const QSGClipNode * QSGRenderNode::clipList | ( | ) | const |
Definition at line 356 of file qsgrendernode.cpp.
References QSGRenderNodePrivate::m_clip_list.
QRhiCommandBuffer * QSGRenderNode::commandBuffer | ( | ) | const |
Definition at line 417 of file qsgrendernode.cpp.
References QSGRenderTarget::cb, and QSGRenderNodePrivate::m_rt.
|
virtual |
The default implementation returns 0.
Reimplemented in QQuickShapeSoftwareRenderNode, and QQuick3DSGRenderNode.
Definition at line 295 of file qsgrendernode.cpp.
qreal QSGRenderNode::inheritedOpacity | ( | ) | const |
Definition at line 364 of file qsgrendernode.cpp.
References QSGRenderNodePrivate::m_opacity.
Referenced by QQuickShapeSoftwareRenderNode::render().
const QMatrix4x4 * QSGRenderNode::matrix | ( | ) | const |
Definition at line 348 of file qsgrendernode.cpp.
References QSGRenderNodePrivate::m_matrix.
Referenced by QQuick3DSGRenderNode::prepare(), and QQuickShapeSoftwareRenderNode::render().
|
virtual |
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.
Reimplemented in QQuick3DSGRenderNode.
Definition at line 113 of file qsgrendernode.cpp.
const QMatrix4x4 * QSGRenderNode::projectionMatrix | ( | ) | const |
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().
Definition at line 340 of file qsgrendernode.cpp.
References QSGRenderNodePrivate::m_projectionMatrix.
|
virtual |
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()).
Reimplemented in QQuickShapeSoftwareRenderNode.
Definition at line 319 of file qsgrendernode.cpp.
|
virtual |
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.
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.
Reimplemented in QQuickShapeSoftwareRenderNode, and QQuick3DSGRenderNode.
Definition at line 236 of file qsgrendernode.cpp.
|
pure virtual |
This function is called by the renderer and should paint this node with directly invoking commands in the graphics API (OpenGL, Direct3D, etc.) currently in use.
The effective opacity can be retrieved with \l inheritedOpacity().
The projection matrix is available through state, while the model-view matrix can be fetched with \l matrix(). The combined matrix is then the projection matrix times the model-view matrix. The correct stacking of the items in the scene is ensured by the projection matrix.
When using the provided matrices, the coordinate system for vertex data follows the usual QQuickItem conventions: top-left is (0, 0), bottom-right is the corresponding QQuickItem's width() and height() minus one. For example, assuming a two float (x-y) per vertex coordinate layout, a triangle covering half of the item can be specified as (width - 1, height - 1), (0, 0), (0, height - 1) using counter-clockwise direction.
Clip information is calculated before the function is called. Implementations wishing to take clipping into account can set up scissoring or stencil based on the information in state. The stencil buffer is filled with the necessary clip shapes, but it is up to the implementation to enable stencil testing.
Some scenegraph backends, software in particular, use no scissor or stencil. There the clip region is provided as an ordinary QRegion.
With the legacy, direct OpenGL based renderer, the following states are set on the render thread's context before this function is called:
\list
States that are not listed above, but are covered by \l StateFlags, can have arbitrary values.
\l changedStates() should return which states this function changes. If a state is not covered by \l StateFlags, the state should be set to the default value according to the OpenGL specification. For other APIs, see the documentation for changedStates() for more information.
For APIs other than OpenGL, it will likely be necessary to query certain API-specific resources (for example, the graphics device or the command list/buffer to add the commands to). This is done via QSGRendererInterface.
Assume nothing about the pipelines and dynamic states bound on the command list/buffer when this function is called.
With some graphics APIs it can be necessary to reimplement prepare() in addition, or alternatively connect to the QQuickWindow::beforeRendering() signal. These are called/emitted before recording the beginning of a renderpass on the command buffer (vkCmdBeginRenderPass with Vulkan, or starting to encode via MTLRenderCommandEncoder in case of Metal. Recording copy operations cannot be done inside render() with such APIs. Rather, do such operations either in prepare() or the slot connected to beforeRendering (with DirectConnection).
Implemented in QQuickShapeSoftwareRenderNode, QSGMapboxGLRenderNode, and QQuick3DSGRenderNode.
QRhiRenderTarget * QSGRenderNode::renderTarget | ( | ) | const |
This is provided mainly to enable prepare() and render() implementations that use QRhi accessing the QRhiRenderTarget's \l{QRhiRenderPassDescriptor}{renderPassDescriptor} or \l{QRhiRenderTarget::pixelSize()}{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:
Definition at line 405 of file qsgrendernode.cpp.
References QSGRenderNodePrivate::m_rt, and QSGRenderTarget::rt.
|
friend |
Definition at line 68 of file qsgrendernode.h.