PySide6.QtQuick.QSGRenderNode¶
- class QSGRenderNode¶
The
QSGRenderNode
class represents a set of custom rendering commands targeting the graphics API that is in use by the scenegraph.Details
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 thesoftware
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 renderingbefore
orafter
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. TheQSGRenderNode
-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 Qt Quick Scene Graph for a further discussion of the three approaches.See also
Scene Graph - Custom QSGRenderNode
Synopsis¶
Methods¶
def
__init__()
def
clipList()
def
commandBuffer()
def
matrix()
def
renderTarget()
Virtual methods¶
def
changedStates()
def
flags()
def
prepare()
def
rect()
def
render()
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
- class StateFlag¶
(inherits
enum.Flag
) This enum contains the possible values for use in the bitmask returned fromchangedStates()
.Constant
Description
QSGRenderNode.ViewportState
Viewport
QSGRenderNode.ScissorState
Scissor test enabled state, scissor rectangle
QSGRenderNode.DepthState
This value has no effect in Qt 6.
QSGRenderNode.StencilState
This value has no effect in Qt 6.
QSGRenderNode.ColorState
This value has no effect in Qt 6.
QSGRenderNode.BlendState
This value has no effect in Qt 6.
QSGRenderNode.CullState
This value has no effect in Qt 6.
QSGRenderNode.RenderTargetState
This value has no effect in Qt 6.
- class RenderingFlag¶
(inherits
enum.Flag
) Possible values for the bitmask returned fromflags()
.Constant
Description
QSGRenderNode.BoundedRectRendering
Indicates that the implementation of
render()
does not render outside the area reported fromrect()
in item coordinates. Such node implementations can lead to more efficient rendering, depending on the scenegraph backend. For example, thesoftware
backend can continue to use the more optimal partial update path when all render nodes in the scene have this flag set.QSGRenderNode.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 fromprojectionMatrix()
andmatrix()
, as described in the notes forrender()
. 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
Indicates that the implementation of
render()
writes out opaque pixels for the entire area reported fromrect()
. By default the renderers must assume thatrender()
can also output semi or fully transparent pixels. Setting this flag can improve performance in some cases.QSGRenderNode.NoExternalRendering
Indicates that the implementations of
prepare()
andrender()
exclusively use the QRhi family of APIs, instead of directly calling a 3D API such as OpenGL, Vulkan, or Metal.
- __init__()¶
This function should return a mask where each bit represents graphics states changed by the
render()
function.Note
With Qt 6 and QRhi-based rendering the only relevant values are
ViewportState
andScissorState
. Other values can be returned but are ignored in practice.ViewportState
Viewport
Note
The
software
backend exposes its QPainter and saves and restores before and after invokingrender()
. Therefore reporting any changed states from here is not necessary.The default implementation returns 0, meaning no relevant state was changed in
render()
.Note
This function may be called before
render()
.- clipList()¶
- Return type:
Returns the current clip list.
- commandBuffer()¶
- Return type:
QRhiCommandBuffer
Returns the current command buffer.
See also
- flags()¶
- Return type:
Combination of
RenderingFlag
Returns flags describing the behavior of this render node.
The default implementation returns 0.
See also
- inheritedOpacity()¶
- Return type:
float
Returns the current effective opacity.
- matrix()¶
- Return type:
Returns pointer to the current model-view matrix.
- 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 theQQuickWindow
viarhi()
. To get a QRhiCommandBuffer for submitting work to, callcommandBuffer()
. To query information about the active render target, callrenderTarget()
. See the {Scene Graph - Custom QSGRenderNode} example for details.- projectionMatrix()¶
- Return type:
Returns pointer to the current projection matrix.
In
render()
this is the same matrix that is returned fromprojectionMatrix()
. This getter exists so thatprepare()
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 inprepare()
, so outside the recording of a render pass. That is why both matrices are queriable directly from theQSGRenderNode
, both inprepare()
andrender()
.- projectionMatrix(index)
- Parameters:
index – int
- Return type:
Returns the bounding rectangle in item coordinates for the area
render()
touches. The value is only in use whenflags()
includesBoundedRectRendering
, ignored otherwise.Reporting the rectangle in combination with
BoundedRectRendering
is particularly important with thesoftware
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
- 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.
- abstract render(state)¶
- Parameters:
state –
RenderState
This function is called by the renderer and should paint this node with directly invoking commands via QRhi or directly via the underlying graphics API (OpenGL, Direct3D, etc.).
The effective opacity can be retrieved with
inheritedOpacity()
.The projection matrix is available through
state
, while the model-view matrix can be fetched withmatrix()
. 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 correspondingQQuickItem
‘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.Note
QSGRenderNode
is provided as a means to implement custom 2D or 2.5D Qt Quick items. It is not intended for integrating true 3D content into the Qt Quick scene. That use case is better supported by the other methods for integrating custom rendering.Note
QSGRenderNode
can perform significantly better than texture-based approaches (such as,QQuickRhiItem
), especially on systems where the fragment processing power is limited. This is because it avoids rendering to a texture and then drawing a textured quad. Rather,QSGRenderNode
allows recording draw calls in line with the scenegraph’s other commands, avoiding an additional render target and the potentially expensive texturing and blending.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.
When implementing a
QSGRenderNode
that uses QRhi to render, query the QRhi object from theQQuickWindow
viarhi()
. To get a QRhiCommandBuffer for submitting work to, callcommandBuffer()
. To query information about the active render target, callrenderTarget()
. See the {Scene Graph - Custom QSGRenderNode} example for details.With Qt 6 and its QRhi-based scene graph renderer, no assumptions should be made about the active (OpenGL) state when this function is called, even when OpenGL is in use. Assume nothing about the pipelines and dynamic states bound on the command list/buffer when this function is called.
Note
Depth writes are expected to be disabled. Enabling depth writes can lead to unexpected results, depending on the scenegraph backend in use and the content in the scene, so exercise caution with this.
Note
In Qt 6,
changedStates()
has limited use. See the documentation forchangedStates()
for more information.With some graphics APIs, including when using QRhi directly, it can be necessary to reimplement
prepare()
in addition, or alternatively connect to thebeforeRendering()
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 inprepare()
or the slot connected to beforeRendering (with DirectConnection).See also
- renderTarget()¶
- Return type:
QRhiRenderTarget
Returns the current render target.
This is provided mainly to enable
prepare()
andrender()
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 theQSGRenderNode
. For example, consider what happens when dynamically settinglayer.enabled: true
on the item or an ancestor of it: this triggers rendering into a texture, not directly to the window, which means theQSGRenderNode
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(); }
See also
- class RenderState¶
Provides information about the projection matrix and clipping.
Details
The render state contains information for the renderer when invoking commands to the scenegraph backends.
See also
Synopsis¶
Virtual methods¶
def
clipRegion()
def
get()
def
scissorEnabled()
def
scissorRect()
def
stencilEnabled()
def
stencilValue()
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
Returns the current clip region or null for backends where clipping is implemented via stencil or scissoring.
The
software
backend uses no projection, scissor or stencil, meaning most of the render state is not in use. However, the clip region that can be set on the QPainter still has to be communicated since reconstructing this manually inrender()
is not reasonable. It can therefore be queried via this function. The region is in world coordinates and can be passed to QPainter::setClipRegion() with Qt::ReplaceClip. This must be done before calling QPainter::setTransform() since the clip region is already mapped to the transform provided inmatrix()
.- get(state)¶
- Parameters:
state – str
- Return type:
void
Returns pointer to a
state
value.Reserved for future use.
- abstract projectionMatrix()¶
- Return type:
Returns pointer to the current projection matrix.
The model-view matrix can be retrieved with
matrix()
. Typicallyprojection * modelview
is the matrix that is then used in the vertex shader to transform the vertices.- abstract scissorEnabled()¶
- Return type:
bool
Returns the current state of scissoring.
Note
Only relevant for graphics APIs that have a dedicated on/off state of scissoring.
Returns the current scissor rectangle when clipping is active. x and y are the bottom left coordinates.
- abstract stencilEnabled()¶
- Return type:
bool
Returns the current state of stencil testing.
Note
With graphics APIs where stencil testing is enabled in pipeline state objects, instead of individual state-setting commands, it is up to the implementation of
render()
to enable stencil testing with operationsKEEP
, comparison functionEQUAL
, and a read and write mask of0xFF
.- abstract stencilValue()¶
- Return type:
int
Returns the current stencil reference value when clipping is active.