QSGNode Class

The QSGNode class is the base class for all nodes in the scene graph. More...

Header:	#include <QSGNode>
CMake:	find_package(Qt6 COMPONENTS Quick REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake:	QT += quick
Inherited By:	QSGBasicGeometryNode, QSGOpacityNode, QSGRenderNode, and QSGTransformNode

• List of all members, including inherited members

Public Types

flags	DirtyState
enum	DirtyStateBit { DirtyMatrix, DirtyNodeAdded, DirtyNodeRemoved, DirtyGeometry, DirtyMaterial, …, DirtySubtreeBlocked }
enum	Flag { OwnedByParent, UsePreprocess, OwnsGeometry, OwnsMaterial, OwnsOpaqueMaterial, InternalReserved }
flags	Flags
enum	NodeType { BasicNodeType, GeometryNodeType, TransformNodeType, ClipNodeType, OpacityNodeType, RenderNodeType }

Public Functions

	QSGNode()
virtual	~QSGNode()
void	appendChildNode(QSGNode *node)
QSGNode *	childAtIndex(int i) const
int	childCount() const
QSGNode *	firstChild() const
QSGNode::Flags	flags() const
void	insertChildNodeAfter(QSGNode *node, QSGNode *after)
void	insertChildNodeBefore(QSGNode *node, QSGNode *before)
virtual bool	isSubtreeBlocked() const
QSGNode *	lastChild() const
void	markDirty(QSGNode::DirtyState bits)
QSGNode *	nextSibling() const
QSGNode *	parent() const
void	prependChildNode(QSGNode *node)
virtual void	preprocess()
QSGNode *	previousSibling() const
void	removeAllChildNodes()
void	removeChildNode(QSGNode *node)
void	setFlag(QSGNode::Flag f, bool enabled = true)
void	setFlags(QSGNode::Flags f, bool enabled = true)
QSGNode::NodeType	type() const

Detailed Description

The QSGNode class can be used as a child container. Children are added with the appendChildNode(), prependChildNode(), insertChildNodeBefore() and insertChildNodeAfter(). The order of nodes is important as geometry nodes are rendered according to their ordering in the scene graph.

The scene graph nodes contains a mechanism to describe which parts of the scene has changed. This includes the combined matrices, accumulated opacity, changes to the node hierarchy, and so on. This information can be used for optimizations inside the scene graph renderer. For the renderer to properly render the nodes, it is important that users call QSGNode::markDirty() with the correct flags when nodes are changed. Most of the functions on the node classes will implicitly call markDirty(). For example, QSGNode::appendChildNode() will call markDirty() passing in QSGNode::DirtyNodeAdded.

If nodes change every frame, the preprocess() function can be used to apply changes to a node for every frame it is rendered. The use of preprocess() must be explicitly enabled by setting the QSGNode::UsePreprocess flag on the node.

The virtual isSubtreeBlocked() function can be used to disable a subtree all together. Nodes in a blocked subtree will not be preprocessed() and not rendered.

Note: All classes with QSG prefix should be used solely on the scene graph's rendering thread. See Scene Graph and Rendering for more information.

Member Type Documentation

enum QSGNode::DirtyStateBitflags QSGNode::DirtyState

Used in QSGNode::markDirty() to indicate how the scene graph has changed.

Constant	Value	Description
QSGNode::DirtyMatrix	0x0100	The matrix in a QSGTransformNode has changed.
QSGNode::DirtyNodeAdded	0x0400	A node was added.
QSGNode::DirtyNodeRemoved	0x0800	A node was removed.
QSGNode::DirtyGeometry	0x1000	The geometry of a QSGGeometryNode has changed.
QSGNode::DirtyMaterial	0x2000	The material of a QSGGeometryNode has changed.
QSGNode::DirtyOpacity	0x4000	The opacity of a QSGOpacityNode has changed.
QSGNode::DirtySubtreeBlocked	0x0080	The subtree has been blocked.

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

See also QSGNode::markDirty().

enum QSGNode::Flagflags QSGNode::Flags

The QSGNode::Flag enum describes flags on the QSGNode

Constant	Value	Description
QSGNode::OwnedByParent	0x0001	The node is owned by its parent and will be deleted when the parent is deleted.
QSGNode::UsePreprocess	0x0002	The node's virtual preprocess() function will be called before rendering starts.
QSGNode::OwnsGeometry	0x00010000	Only valid for QSGGeometryNode and QSGClipNode. The node has ownership over the QSGGeometry instance and will delete it when the node is destroyed or a geometry is assigned.
QSGNode::OwnsMaterial	0x00020000	Only valid for QSGGeometryNode. The node has ownership over the material and will delete it when the node is destroyed or a material is assigned.
QSGNode::OwnsOpaqueMaterial	0x00040000	Only valid for QSGGeometryNode. The node has ownership over the opaque material and will delete it when the node is destroyed or a material is assigned.
QSGNode::InternalReserved	0x01000000	Reserved for internal use.

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

enum QSGNode::NodeType

Can be used to figure out the type of node.

Constant	Value	Description
QSGNode::BasicNodeType	0	The type of QSGNode
QSGNode::GeometryNodeType	1	The type of QSGGeometryNode
QSGNode::TransformNodeType	2	The type of QSGTransformNode
QSGNode::ClipNodeType	3	The type of QSGClipNode
QSGNode::OpacityNodeType	4	The type of QSGOpacityNode
QSGNode::RenderNodeType	6	The type of QSGRenderNode

See also type().

Member Function Documentation

QSGNode::QSGNode()

Constructs a new node

[virtual] QSGNode::~QSGNode()

Destroys the node.

Every child of this node that has the flag QSGNode::OwnedByParent set, will also be deleted.

void QSGNode::appendChildNode(QSGNode *node)

Appends node to this node's list of children.

Ordering of nodes is important as geometry nodes will be rendered in the order they are added to the scene graph.

QSGNode *QSGNode::childAtIndex(int i) const

Returns the child at index i.

Children are stored internally as a linked list, so iterating over the children via the index is suboptimal.

int QSGNode::childCount() const

Returns the number of child nodes.

QSGNode *QSGNode::firstChild() const

Returns the first child of this node.

The children are stored in a linked list.

QSGNode::Flags QSGNode::flags() const

Returns the set of flags for this node.

See also setFlags().

void QSGNode::insertChildNodeAfter(QSGNode *node, QSGNode *after)

Inserts node to this node's list of children after the node specified with after.

Ordering of nodes is important as geometry nodes will be rendered in the order they are added to the scene graph.

void QSGNode::insertChildNodeBefore(QSGNode *node, QSGNode *before)

Inserts node to this node's list of children before the node specified with before.

Ordering of nodes is important as geometry nodes will be rendered in the order they are added to the scene graph.

[virtual] bool QSGNode::isSubtreeBlocked() const

Returns whether this node and its subtree is available for use.

Blocked subtrees will not get their dirty states updated and they will not be rendered.

The QSGOpacityNode will return a blocked subtree when accumulated opacity is 0, for instance.

QSGNode *QSGNode::lastChild() const

Returns the last child of this node.

The children are stored as a linked list.

void QSGNode::markDirty(QSGNode::DirtyState bits)

Notifies all connected renderers that the node has dirty bits.

QSGNode *QSGNode::nextSibling() const

Returns the node after this in the parent's list of children.

The children are stored as a linked list.

QSGNode *QSGNode::parent() const

Returns the parent node of this node.

void QSGNode::prependChildNode(QSGNode *node)

Prepends node to this node's the list of children.

Ordering of nodes is important as geometry nodes will be rendered in the order they are added to the scene graph.

[virtual] void QSGNode::preprocess()

Override this function to do processing on the node before it is rendered.

Preprocessing needs to be explicitly enabled by setting the flag QSGNode::UsePreprocess. The flag needs to be set before the node is added to the scene graph and will cause the preprocess() function to be called for every frame the node is rendered.

Warning: Beware of deleting nodes while they are being preprocessed. It is possible, with a small performance hit, to delete a single node during its own preprocess call. Deleting a subtree which has nodes that also use preprocessing may result in a segmentation fault. This is done for performance reasons.

QSGNode *QSGNode::previousSibling() const

Returns the node before this in the parent's list of children.

The children are stored as a linked list.

void QSGNode::removeAllChildNodes()

Removes all child nodes from this node's list of children.

void QSGNode::removeChildNode(QSGNode *node)

Removes node from this node's list of children.

void QSGNode::setFlag(QSGNode::Flag f, bool enabled = true)

Sets the flag f on this node if enabled is true; otherwise clears the flag.

See also flags().

void QSGNode::setFlags(QSGNode::Flags f, bool enabled = true)

Sets the flags f on this node if enabled is true; otherwise clears the flags.

See also flags().

QSGNode::NodeType QSGNode::type() const

Returns the type of this node. The node type must be one of the predefined types defined in QSGNode::NodeType and can safely be used to cast to the corresponding class.