Documentation for the scenegraph nodes

1 files changed, 330 insertions, 3 deletions

diff --git a/src/declarative/scenegraph/coreapi/qsgnode.cpp b/src/declarative/scenegraph/coreapi/qsgnode.cpp
index 5d84086457..7e19339edc 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<m_renderers.size(); ++i) {
@@ -531,6 +784,24 @@ void QSGRootNode::notifyNodeChange(QSGNode *node, DirtyFlags flags)
     }
 }
 
+
+
+/*!
+    \class QSGOpacityNode
+    \brief The QSGOpacityNode is used
+
+    Opacity apply to its subtree and can be nested. Multiple opacity nodes
+    will be accumulated by multiplying their opacity. The accumulation happens
+    as part of the rendering.
+
+    When nested opacity gets below a certain threshold, the subtree might
+    be marked as blocked, causing isSubtreeBlocked() to return true. This
+    is done for performance reasons.
+
+ */
+
+
+
 /*!
     Constructs an opacity node with a default opacity of 1.
 
@@ -547,12 +818,26 @@ QSGOpacityNode::QSGOpacityNode()
 }
 
 
+
+/*!
+    Deletes the opacity node.
+ */
+
 QSGOpacityNode::~QSGOpacityNode()
 {
     destroy();
 }
 
 
+
+/*!
+    \fn qreal QSGOpacityNode::opacity() const
+
+    Returns this opacity node's opacity.
+ */
+
+
+
 /*!
     Sets the opacity of this node to \a opacity.
 
@@ -561,6 +846,7 @@ QSGOpacityNode::~QSGOpacityNode()
 
     The value will be bounded to the range 0 to 1.
  */
+
 void QSGOpacityNode::setOpacity(qreal opacity)
 {
     opacity = qBound<qreal>(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;