From 6dac44843da96a963f74cae5c77763aaba46ea79 Mon Sep 17 00:00:00 2001 From: Gunnar Sletta Date: Thu, 3 May 2012 16:05:13 +0200 Subject: [PATCH] Added some documentatio notes on QSGNode::markDirty() MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Change-Id: I631d85596113c38c9f19da9e65e9cae90c3bfebf Reviewed-by: Geir Vattekar Reviewed-by: Samuel Rødal --- src/quick/scenegraph/coreapi/qsgnode.cpp | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/src/quick/scenegraph/coreapi/qsgnode.cpp b/src/quick/scenegraph/coreapi/qsgnode.cpp index de44631..496a8d0 100644 --- a/src/quick/scenegraph/coreapi/qsgnode.cpp +++ b/src/quick/scenegraph/coreapi/qsgnode.cpp @@ -71,6 +71,16 @@ static void qt_print_node_count() Actually, the scene may reorder nodes freely, but the resulting visual order is still guaranteed. + 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, etc. 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(), + e.g. 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 its rendered. The use of preprocess() must be explicitly enabled by setting the QSGNode::UsePreprocess flag @@ -80,7 +90,7 @@ static void qt_print_node_count() together. Nodes in a blocked subtree will not be preprocessed() and not rendered. - Anything related to QSGNode should happen on the scene graph rendering thread. + \warning Anything related to QSGNode should happen on the scene graph rendering thread. */ QSGNode::QSGNode() @@ -540,6 +550,11 @@ QSGBasicGeometryNode::~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. + + If the geometry is changed whitout calling setGeometry() again, the user + must also mark the geometry as dirty using QSGNode::markDirty(). + + \sa markDirty */ void QSGBasicGeometryNode::setGeometry(QSGGeometry *geometry) @@ -582,7 +597,9 @@ void QSGBasicGeometryNode::setGeometry(QSGGeometry *geometry) \endcode A geometry node must have both geometry and a normal material before it is added to - the scene graph. + the scene graph. When the geometry and materials are changed after the node has + been added to the scene graph, the user should also mark them as dirty using + QSGNode::markDirty(). 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 @@ -660,6 +677,10 @@ void QSGGeometryNode::setRenderOrder(int order) Geometry nodes must have a material before they can be added to the scene graph. + + If the material is changed whitout calling setMaterial() again, the user + must also mark the material as dirty using QSGNode::markDirty(). + */ void QSGGeometryNode::setMaterial(QSGMaterial *material) { @@ -686,6 +707,11 @@ void QSGGeometryNode::setMaterial(QSGMaterial *material) The opaqueness refers to scene graph opacity, the material is still allowed to set QSGMaterial::Blending to true and draw transparent pixels. + + If the material is changed whitout calling setOpaqueMaterial() + again, the user must also mark the opaque material as dirty using + QSGNode::markDirty(). + */ void QSGGeometryNode::setOpaqueMaterial(QSGMaterial *material) { -- 2.7.4