QSGNode Class

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

头文件: #include <QSGNode>
CMake.QSGNode 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() 将通过QSGNode::DirtyNodeAdded 调用markDirty() 。

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

虚拟isSubtreeBlocked() 函数可用于完全禁用子树。被阻止的子树中的节点不会被预处理(),也不会被渲染。

注意: 所有带有 QSG 前缀的类都只能在场景图的渲染线程中使用。更多信息,请参阅场景图和渲染

成员类型文档

枚举 QSGNode::DirtyStateBit
标志 QSGNode::DirtyState

QSGNode::markDirty() 中用于指示场景图的变化情况。

常量说明
QSGNode::DirtyMatrix0x0100QSGTransformNode 中的矩阵已更改。
QSGNode::DirtyNodeAdded0x0400添加了一个节点。
QSGNode::DirtyNodeRemoved0x0800删除了一个节点。
QSGNode::DirtyGeometry0x1000QSGGeometryNode 的几何形状已更改。
QSGNode::DirtyMaterial0x2000QSGGeometryNode 的材质已更改。
QSGNode::DirtyOpacity0x4000QSGOpacityNode 的不透明度已更改。
QSGNode::DirtySubtreeBlocked0x0080子树已阻塞。

DirtyState 类型是QFlags<DirtyStateBit> 的类型定义。它存储 DirtyStateBit 值的 OR 组合。

另请参阅 QSGNode::markDirty().

枚举 QSGNode::Flag
flags QSGNode::Flags

QSGNode::Flag 枚举描述了关于QSGNode

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

Flags 类型是QFlags<Flag> 的类型定义。它存储 Flag 值的 OR 组合。

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)

after 指定的节点之后,将node 插入此节点的子节点列表。

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

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

node 插入此节点的子节点列表,然后再插入before 指定的节点。

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

[virtual] bool QSGNode::isSubtreeBlocked() const

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

被阻止的子树不会更新其 dirty 状态,也不会被渲染。

例如,当累积不透明度为 0 时,QSGOpacityNode 将返回一个已阻止的子树。

QSGNode *QSGNode::lastChild() const

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

子节点以链表形式存储。

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

通知所有连接的呈现器该节点有 dirtybits

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 为 true,则设置该节点的标志f ;否则清除该标志。

另请参阅 flags().

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

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

另请参阅 flags().

QSGNode::NodeType QSGNode::type() const

返回此节点的类型。节点类型必须是QSGNode::NodeType 中定义的预定义类型之一,并且可以安全地用于转换到相应的类。

© 2025 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.