本页内容

QSGNode Class

QSGNode 类是场景图中所有节点的基类。更多内容...

头文件: #include <QSGNode>
CMake: find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick
被继承者:

QSGBasicGeometryNode、QSGOpacityNode 、QSGRenderNode ,以及QSGTransformNode

公共类型

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 }

公共函数

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

详细说明

QSGNode 类可作为子容器使用。子节点可通过appendChildNode()、prependChildNode()、insertChildNodeBefore() 和insertChildNodeAfter() 添加。节点的顺序至关重要,因为几何节点是根据其在场景图中的排序顺序进行渲染的。

场景图节点包含一种机制,用于描述场景中哪些部分发生了变化。这包括组合矩阵、累积不透明度、节点层次结构的变化等。这些信息可用于场景图渲染器内部的优化。 为了使渲染器能够正确渲染节点,当节点发生变化时,用户必须使用正确的标志调用QSGNode::markDirty()。节点类上的大多数函数都会隐式调用markDirty()。例如,QSGNode::appendChildNode()会调用markDirty(),并传入QSGNode::DirtyNodeAdded 。

如果节点在每帧都会发生变化,则可以使用preprocess() 函数在每个渲染帧中对节点应用更改。必须通过在节点上设置QSGNode::UsePreprocess 标志来显式启用preprocess()。

虚拟函数isSubtreeBlocked() 可用作彻底禁用子树。被阻塞子树中的节点将不会被 preprocess() 处理,也不会被渲染。

注意:所有 以 QSG 为前缀的类应仅在场景图的渲染线程上使用。有关更多信息,请参阅“场景图与渲染”。

成员类型文档

enum QSGNode::DirtyStateBit
flags QSGNode::DirtyState

用于在 `QSGNode::markDirty()` 中指示场景图发生了哪些变化。

常量值描述
QSGNode::DirtyMatrix0x0100QSGTransformNode 中的矩阵已发生变化。
QSGNode::DirtyNodeAdded0x0400添加了一个节点。
QSGNode::DirtyNodeRemoved0x0800已删除一个节点。
QSGNode::DirtyGeometry0x1000QSGGeometryNode 的几何形状已发生变化。
QSGNode::DirtyMaterial0x2000QSGGeometryNode 的材质发生了变化。
QSGNode::DirtyOpacity0x4000QSGOpacityNode 的不透明度已发生变化。
QSGNode::DirtySubtreeBlocked0x0080子树已被封锁。

DirtyState 类型是QFlags<DirtyStateBit> 的 typedef。它存储了 DirtyStateBit 值的按“或”运算组合。

另请参阅 QSGNode::markDirty()。

enum QSGNode::Flag
flags QSGNode::Flags

QSGNode::Flag 枚举描述了QSGNode

常量值描述
QSGNode::OwnedByParent0x0001该节点由其父节点拥有,并在父节点被删除时被删除。
QSGNode::UsePreprocess0x0002在开始渲染之前,将调用该节点的虚拟函数preprocess()。
QSGNode::OwnsGeometry0x00010000仅对QSGGeometryNode 和QSGClipNode 有效。该节点拥有QSGGeometry 实例的所有权,并在节点被销毁或分配几何体时将其删除。
QSGNode::OwnsMaterial0x00020000仅适用于QSGGeometryNode 。该节点拥有该材质的所有权,并在节点被销毁或分配了新材质时将其删除。
QSGNode::OwnsOpaqueMaterial0x00040000仅适用于QSGGeometryNode 。该节点拥有不透明材质的所有权,并在节点被销毁或被分配材质时将其删除。
QSGNode::InternalReserved0x01000000保留供内部使用。

Flags 类型是QFlags<Flag> 的 typedef。它存储 Flag 值的按“或”运算组合。

enum QSGNode::NodeType

可用于确定节点的类型。

常量值描述
QSGNode::BasicNodeType0节点的类型QSGNode
QSGNode::GeometryNodeType1类型QSGGeometryNode
QSGNode::TransformNodeType2类型QSGTransformNode
QSGNode::ClipNodeType3类型QSGClipNode
QSGNode::OpacityNodeType4类型QSGOpacityNode
QSGNode::RenderNodeType6类型QSGRenderNode

另请参阅 type()。

成员函数文档

QSGNode::QSGNode()

创建一个新节点

[virtual noexcept] QSGNode::~QSGNode()

删除该节点。

该节点的每个子节点,只要设置了QSGNode::OwnedByParent 标志,也将被删除。

void QSGNode::appendChildNode(QSGNode *node)

将node 添加到该节点的子节点列表中。

节点的顺序非常重要,因为几何节点将按照它们被添加到场景图中的顺序进行渲染。

QSGNode *QSGNode::childAtIndex(int i) const

返回索引为i 的子节点。

子节点在内部以链表形式存储,因此通过索引遍历子节点并非最优方案。

int QSGNode::childCount() const

返回子节点的数量。

QSGNode *QSGNode::firstChild() const

返回该节点的第一个子节点。

子节点存储在链表中。

QSGNode::Flags QSGNode::flags() const

返回该节点的标志集。

另请参阅 setFlags()。

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

将node 插入到该节点的子节点列表中,位置在由after 指定的节点之后。

节点的顺序非常重要,因为几何节点将按照它们被添加到场景图中的顺序进行渲染。

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

将node 插入到该节点的子节点列表中,位置位于before 指定的节点之前。

节点的顺序非常重要,因为几何节点将按照它们被添加到场景图中的顺序进行渲染。

[virtual] bool QSGNode::isSubtreeBlocked() const

返回该节点及其子树是否可用。

被阻塞的子树不会更新其“已修改”状态,也不会被渲染。

例如,当累积不透明度为 0 时,QSGOpacityNode 会返回一个被屏蔽的子树。

QSGNode *QSGNode::lastChild() const

返回该节点的最后一个子节点。

子节点以链表的形式存储。

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

通知所有已连接的渲染器,该节点存在未保存的更改(bits )。

QSGNode *QSGNode::nextSibling() const

返回父节点子节点列表中紧随其后的节点。

子节点以链表的形式存储。

QSGNode *QSGNode::parent() const

返回该节点的父节点。

void QSGNode::prependChildNode(QSGNode *node)

将node 添加到该节点的子节点列表开头。

节点的顺序非常重要,因为几何节点将按照它们被添加到场景图中的顺序进行渲染。

[virtual] void QSGNode::preprocess()

重写此函数,以便在节点渲染之前对其进行处理。

需要通过设置标志QSGNode::UsePreprocess 来显式启用预处理。该标志必须在节点添加到场景图之前设置,且会导致在节点渲染的每一帧中调用 preprocess() 函数。

警告:请注意 ,在节点处于预处理过程中时,切勿 删除该节点。虽然在单个节点的预处理调用期间,可以删除该节点(但会带来轻微的性能损失),但若删除包含同样使用预处理功能的节点的子树,可能会导致分段错误。此限制是出于性能考虑。

QSGNode *QSGNode::previousSibling() const

返回父节点子节点列表中位于该节点之前的节点。

子节点以链表的形式存储。

void QSGNode::removeAllChildNodes()

从该节点的子节点列表中移除所有子节点。

void QSGNode::removeChildNode(QSGNode *node)

将node 从该节点的子节点列表中移除。

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

如果 `enabled ` 为真,则在此节点上设置 `f ` 标志;否则清除该标志。

另请参阅 flags()。

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

如果enabled 为真,则在此节点上设置标志f ;否则清除这些标志。

另请参阅 flags()。

QSGNode::NodeType QSGNode::type() const

返回该节点的类型。该节点类型必须是QSGNode::NodeType 中定义的预定义类型之一,且可安全地将其强制转换为相应的类。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.