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>
qmake:	QT += quick
Since:	Qt 5.8
Inherits:	QSGNode

• List of all members, including inherited members

Public Types

class	RenderState
enum	RenderingFlag { BoundedRectRendering, DepthAwareRendering, OpaqueRendering }
flags	RenderingFlags
enum	StateFlag { DepthState, StencilState, ScissorState, ColorState, ..., RenderTargetState }
flags	StateFlags

Public Functions

	QSGRenderNode()
virtual	~QSGRenderNode() override
virtual QSGRenderNode::StateFlags	changedStates() const
const QSGClipNode *	clipList() const
virtual QSGRenderNode::RenderingFlags	flags() const
qreal	inheritedOpacity() const
const QMatrix4x4 *	matrix() const
virtual QRectF	rect() const
virtual void	releaseResources()
virtual void	render(const QSGRenderNode::RenderState *state) = 0

• 20 public functions inherited from QSGNode

Detailed Description

The QSGRenderNode class represents a set of custom rendering commands targeting the graphics API that is in use by the scenegraph.

Member Type Documentation

enum QSGRenderNode::RenderingFlagflags 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.

The RenderingFlags type is a typedef for QFlags<RenderingFlag>. It stores an OR combination of RenderingFlag values.

See also render() and rect().

enum QSGRenderNode::StateFlagflags 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

QSGRenderNode::QSGRenderNode()

Default constructs an instance of QSGRenderNode.

[override virtual] 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.

See also releaseResources().

[virtual] QSGRenderNode::StateFlags QSGRenderNode::changedStates() const

This function should return a mask where each bit represents graphics states changed by the render() function:

• 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

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().

With APIs other than OpenGL the relevant states are only those that are set via the command list (for example, OMSetRenderTargets, RSSetViewports, RSSetScissorRects, OMSetBlendFactor, OMSetStencilRef in case of D3D12), 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 (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.

Note: This function may be called before render().

const QSGClipNode *QSGRenderNode::clipList() const

Returns the current clip list.

[virtual] QSGRenderNode::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] 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.

[pure virtual] void QSGRenderNode::render(const QSGRenderNode::RenderState *state)

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 inheritedOpacity().

The projection matrix is available through state, while the model-view matrix can be fetched with 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.

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 QQuickFramebufferObject, QQuickWindow::beforeRendering(), or the equivalents of those for APIs other than OpenGL.

Clip information is calculated before the function is called, it is however not enabled. Implementations wishing to take clipping into account can set up scissoring or stencil based on the information in state. Some scenegraph backends, software in particular, use no scissor or stencil. There the clip region is provided as an ordinary QRegion.

For OpenGL the following states are set on the render thread's context before this function is called:

• glDepthMask(false)
• glDisable(GL_DEPTH_TEST)
• glStencilFunc(GL_EQUAL, state.stencilValue, 0xff) depending on clip
• glScissor(state.scissorRect.x(), state.scissorRect.y(), state.scissorRect.width(), state.scissorRect.height()) depending on clip
• glEnable(GL_BLEND)
• glBlendFunc(GL_ONE, GL_ONE_MINUS_SRC_ALPHA)
• glDisable(GL_CULL_FACE)

States that are not listed above, but are included in StateFlags, can have arbitrary values.

changedStates() should return which states this function changes. If a state is not covered by 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.

Note: Depth writes are disabled when this function is called (for example, glDepthMask(false) in case of OpenGL). Enabling depth writes can lead to unexpected results, depending on the scenegraph backend in use, so nodes should avoid this.

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.

See also QSGRendererInterface and QQuickWindow::rendererInterface().