From: Gunnar Sletta Date: Mon, 9 May 2011 08:33:24 +0000 (+0200) Subject: Documentation for the scenegraph nodes X-Git-Url: http://git.silmor.de/gitweb/?a=commitdiff_plain;h=66243440db487119b11d03dfb8be78c7481964b5;p=konrad%2Fqtdeclarative.git Documentation for the scenegraph nodes --- diff --git a/src/declarative/scenegraph/coreapi/qsgnode.cpp b/src/declarative/scenegraph/coreapi/qsgnode.cpp index 5d84086..7e19339 100644 --- a/src/declarative/scenegraph/coreapi/qsgnode.cpp +++ b/src/declarative/scenegraph/coreapi/qsgnode.cpp @@ -64,8 +64,9 @@ static void qt_print_node_count() The QSGNode class can be used as a child container. Children are added with the appendChildNode(), prependChildNode(), insertChildNodeBefore() and - insertChildNodeAfter(). Ordering is important as nodes are rendered in - order. Actually, the scene may reorder nodes freely, but the resulting visual + insertChildNodeAfter(). Ordering of nodes is important as geometry nodes + will be rendered in the order they are added to the scene graph. + Actually, the scene may reorder nodes freely, but the resulting visual order is still guaranteed. If nodes change every frame, the preprocess() function can be used to @@ -163,6 +164,14 @@ void QSGNode::destroy() Q_ASSERT(m_children.isEmpty()); } + +/*! + Prepends \a 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. + */ + void QSGNode::prependChildNode(QSGNode *node) { Q_ASSERT_X(!m_children.contains(node), "QSGNode::prependChildNode", "QSGNode is already a child!"); @@ -182,6 +191,13 @@ void QSGNode::prependChildNode(QSGNode *node) node->markDirty(DirtyNodeAdded); } +/*! + Appends \a 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. + */ + void QSGNode::appendChildNode(QSGNode *node) { Q_ASSERT_X(!m_children.contains(node), "QSGNode::appendChildNode", "QSGNode is already a child!"); @@ -201,6 +217,15 @@ void QSGNode::appendChildNode(QSGNode *node) node->markDirty(DirtyNodeAdded); } + + +/*! + Inserts \a node to this node's list of children before the node specified with \a before. + + 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) { Q_ASSERT_X(!m_children.contains(node), "QSGNode::insertChildNodeBefore", "QSGNode is already a child!"); @@ -225,6 +250,15 @@ void QSGNode::insertChildNodeBefore(QSGNode *node, QSGNode *before) node->markDirty(DirtyNodeAdded); } + + +/*! + Inserts \a node to this node's list of children after the node specified with \a after. + + Ordering of nodes is important as geometry nodes will be rendered in the + order they are added to the scene graph. + */ + void QSGNode::insertChildNodeAfter(QSGNode *node, QSGNode *after) { Q_ASSERT_X(!m_children.contains(node), "QSGNode::insertChildNodeAfter", "QSGNode is already a child!"); @@ -249,6 +283,12 @@ void QSGNode::insertChildNodeAfter(QSGNode *node, QSGNode *after) node->markDirty(DirtyNodeAdded); } + + +/*! + Removes \a node fromt his node's list of children. + */ + void QSGNode::removeChildNode(QSGNode *node) { Q_ASSERT(m_children.contains(node)); @@ -293,6 +333,14 @@ void QSGNode::setFlags(Flags f, bool enabled) } + +/*! + Marks this node with the states in \a flags as dirty. + + When a node is marked dirty, it recursively mark the parent chain + as dirty and notify all connected renderers that the has dirty states. + */ + void QSGNode::markDirty(DirtyFlags flags) { m_flags |= (flags & DirtyPropagationMask); @@ -307,6 +355,20 @@ void QSGNode::markDirty(DirtyFlags flags) } } + + +/*! + \class QSGBasicGeometryNode + \brief The QSGBasicGeometryNode serves as a baseclass for geometry based nodes + + The QSGBasicGeometryNode class should not be used by itself. It is only encapsulates + shared functionality between the QSGGeometryNode and QSGClipNode classes. + */ + + +/*! + Creates a new basic geometry node. + */ QSGBasicGeometryNode::QSGBasicGeometryNode() : m_geometry(0) , m_matrix(0) @@ -314,6 +376,14 @@ QSGBasicGeometryNode::QSGBasicGeometryNode() { } + +/*! + Deletes this QSGBasicGeometryNode. + + If the node has the flag QSGNode::OwnsGeometry set, it will also delete the + geometry object it is pointing to. This flag is not set by default. + */ + QSGBasicGeometryNode::~QSGBasicGeometryNode() { destroy(); @@ -321,6 +391,23 @@ QSGBasicGeometryNode::~QSGBasicGeometryNode() delete m_geometry; } + +/*! + \fn QSGGeometry *QSGBasicGeometryNode::geometry() const + + Returns this node's geometry. + + The geometry is null by default. + */ + + +/*! + Sets the geometry of this node to \a geometry. + + If the node has the flag QSGNode::OwnsGeometry set, it will also delete the + geometry object it is pointing to. This flag is not set by default. + */ + void QSGBasicGeometryNode::setGeometry(QSGGeometry *geometry) { if (flags() & OwnsGeometry) @@ -330,6 +417,31 @@ void QSGBasicGeometryNode::setGeometry(QSGGeometry *geometry) } + +/*! + \class QSGGeometryNode + \brief The QSGGeometryNode class is used for all rendered content in the scene graph. + + The QSGGeometryNode consists of geometry and material. The geometry defines the mesh, + the vertices and their structure, to be drawn. The Material defines how the shape is + filled. + + A geometry node must have both geometry and a normal material before it is added to + the scene graph. + + The geometry node supports two types of materials, the opaqueMaterial and the normal + material. The opaqueMaterial is used when the accumulated scene graph opacity at the + time of rendering is 1. The primary usecase is to special case opaque rendering + to avoid an extra operation in the fragment shader can have significant performance + impact on embedded graphics chips. The opaque material is optional. + + */ + + +/*! + Creates a new geometry node without geometry and material. + */ + QSGGeometryNode::QSGGeometryNode() : m_render_order(0) , m_material(0) @@ -338,6 +450,15 @@ QSGGeometryNode::QSGGeometryNode() { } + +/*! + Deletes this geometry node. + + The flags QSGNode::OwnsMaterial, QSGNode::OwnsOpaqueMaterial and + QSGNode::OwnsGeometry decides weither the geometry node should also + delete the materials and geometry. By default, these flags are disabled. + */ + QSGGeometryNode::~QSGGeometryNode() { destroy(); @@ -347,6 +468,17 @@ QSGGeometryNode::~QSGGeometryNode() delete m_opaque_material; } + + +/*! + \fn int QSGGeometryNode::renderOrder() const + + Returns the render order of this geometry node. + + \internal + */ + + /*! Sets the render order of this node to be \a order. @@ -370,7 +502,7 @@ void QSGGeometryNode::setRenderOrder(int order) /*! Sets the material of this geometry node to \a material. - GeometryNodes must have a material before they can be added to the + Geometry nodes must have a material before they can be added to the scene graph. */ void QSGGeometryNode::setMaterial(QSGMaterial *material) @@ -453,25 +585,80 @@ void QSGGeometryNode::setInheritedOpacity(qreal opacity) } +/*! + \class QSGClipNode + \brief The QSGClipNode implements the clipping functionality in the scene graph. + + Clipping applies to the node's subtree and can be nested. Multiple clip nodes will be + accumulated by intersecting all their geometries. The accumulation happens + as part of the rendering. + + Clip nodes must have a geometry before they can be added to the scene graph. + + Clipping is usually implemented by using the stencil buffer. + */ + + + +/*! + Creates a new QSGClipNode without a geometry. + + The clip node must have a geometry before it can be added to the + scene graph. + */ QSGClipNode::QSGClipNode() { } + + +/*! + Deletes this QSGClipNode. + + If the flag QSGNode::OwnsGeometry is set, the geometry will also be + deleted. + */ + QSGClipNode::~QSGClipNode() { destroy(); } + + +/*! + \fn bool QSGClipNode::isRectangular() const + + Returns if this clip node has a rectangular clip. + */ + + + /*! Sets whether this clip node has a rectangular clip to \a rectHint. + + This is an optimization hint which means that the renderer can + use scissoring instead of stencil, which is significnatly faster. + + When this hint is and it is applicable, the clip region will be + generated from clipRect() rather than geometry(). */ + void QSGClipNode::setIsRectangular(bool rectHint) { m_is_rectangular = rectHint; } + +/*! + \fn void QSGClipNode::clipRect() const + + Returns the clip rect of this node. + */ + + /*! Sets the clip rect of this clip node to \a rect. @@ -484,15 +671,49 @@ void QSGClipNode::setClipRect(const QRectF &rect) } +/*! + \class QSGTransformNode + \brief The QSGTransformNode implements transformations in the scene graph + + Transformations apply the node's subtree and can be nested. Multiple transform nodes + will be accumulated by intersecting all their matrices. The accumulation happens + as part of the rendering. + + The transform nodes implement a 4x4 matrix which in theory supports full 3D + transformations. However, because the renderer optimizes for 2D use-cases rather + than 3D use-cases, rendering a scene with full 3D transformations needs to + be done with some care. + */ + QSGTransformNode::QSGTransformNode() { } + + +/*! + Deletes this transform node. + */ + QSGTransformNode::~QSGTransformNode() { destroy(); } + + +/*! + \fn QMatrix4x4 QSGTransformNode::matrix() const + + Returns this transform node's matrix. + */ + + + +/*! + Sets this transform node's matrix to \a matrix. + */ + void QSGTransformNode::setMatrix(const QMatrix4x4 &matrix) { m_matrix = matrix; @@ -516,6 +737,32 @@ void QSGTransformNode::setCombinedMatrix(const QMatrix4x4 &matrix) +/*! + \class QSGRootNode + \brief The QSGRootNode is the toplevel root of any scene graph. + + The root node is used to attach a scene graph to a renderer. + + \internal + */ + + + +/*! + \fn QSGRootNode::QSGRootNode() + + Creates a new root node. + */ + + + +/*! + Deletes the root node. + + When a root node is deleted it removes itself from all of renderers + that are referencing it. + */ + QSGRootNode::~QSGRootNode() { while (!m_renderers.isEmpty()) @@ -524,6 +771,12 @@ QSGRootNode::~QSGRootNode() } + +/*! + Called to notify all renderers that \a node has been marked as dirty + with \a flags. + */ + void QSGRootNode::notifyNodeChange(QSGNode *node, DirtyFlags flags) { for (int i=0; i(0, opacity, 1); @@ -571,6 +857,20 @@ void QSGOpacityNode::setOpacity(qreal opacity) } + +/*! + \fn qreal QSGOpacityNode::combinedOpacity() const + + Returns this node's accumulated opacity. + + This vaule is calculated during rendering and only stored + in the opacity node temporarily. + + \internal + */ + + + /*! Sets the combined opacity of this node to \a opacity. @@ -580,18 +880,35 @@ void QSGOpacityNode::setOpacity(qreal opacity) \internal */ + void QSGOpacityNode::setCombinedOpacity(qreal opacity) { m_combined_opacity = opacity; } + +/*! + For performance reasons, we block the subtree when the nested opacity + gets below a certain threshold. + + \internal + */ + bool QSGOpacityNode::isSubtreeBlocked() const { return m_combined_opacity < 0.001; } + +/*! + \class QSGNodeVisitor + \bried The QSGNodeVisitor class is a helper class for traversing the scene graph. + + \internal + */ + QSGNodeVisitor::~QSGNodeVisitor() { @@ -811,6 +1128,16 @@ QDebug operator<<(QDebug d, const QSGNode *n) return d; } + +/*! + \class QSGNodeDumper + \brief The QSGNodeDumper class provides a way of dumping a scene grahp to the console. + + This class is solely for debugging purposes. + + \internal + */ + void QSGNodeDumper::dump(QSGNode *n) { QSGNodeDumper dump;