Greatly improved Scene Graph Overview documentation

Change-Id: I86b6bb9007d268ec039614a1693ecd839901e6d9
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

1 files changed, 14 insertions, 6 deletions

diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index 3907c911b2..08f60aeb1e 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -1552,7 +1552,7 @@ void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus)
     You can subclass QQuickItem to provide your own custom visual item
     that inherits these features.
 
-    \section2 Custom Items using Scene Graph
+    \section1 Custom Scene Graph Items
 
     All visual QML items are rendered using the scene graph, a
     low-level, high-performance rendering stack, closely tied to
@@ -1570,7 +1570,7 @@ void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus)
     To read more about how the scene graph rendering works, see
     \l{Scene Graph and Rendering}
 
-    \section2 Custom Items using QPainter
+    \section1 Custom QPainter Items
 
     The QQuickItem provides a subclass, QQuickPaintedItem, which
     allows the users to render content using QPainter.
@@ -2972,9 +2972,11 @@ void QQuickItem::geometryChanged(const QRectF &newGeometry, const QRectF &oldGeo
 }
 
 /*!
-    Called by the rendering thread, as a result of
-    QQuickItem::update(), when it is time to sync the state of the QML
-    objects with the scene graph objects.
+    Called on the render thread when it is time to sync the state
+    of the item with the scene graph.
+
+    The function is called as a result of QQuickItem::update(), if
+    the user has set the QQuickItem::ItemHasContents flag on the item.
 
     The function should return the root of the scene graph subtree for
     this item. Most implementations will return a single
@@ -3005,11 +3007,17 @@ void QQuickItem::geometryChanged(const QRectF &newGeometry, const QRectF &oldGeo
     the visual outcome is identical.
 
     \warning It is crucial that OpenGL operations and interaction with
-    the scene graph happens exclusively on the rendering thread,
+    the scene graph happens exclusively on the render thread,
     primarily during the QQuickItem::updatePaintNode() call. The best
     rule of thumb is to only use classes with the "QSG" prefix inside
     the QQuickItem::updatePaintNode() function.
 
+    \warning This function is called on the render thread. This means any
+    QObjects or thread local storage that is created will have affinity to the
+    render thread, so apply caution when doing anything other than rendering
+    in this function. Similarily for signals, these will be emitted on the render
+    thread and will thus often be delivered via queued connections.
+
     \sa QSGMaterial, QSGSimpleMaterial, QSGGeometryNode, QSGGeometry,
     QSGFlatColorMaterial, QSGTextureMaterial, QSGNode::markDirty()
  */