Clearly point out the distinction between GUI and Render threads.

This is something it is easy to get wrong, so try to make it as
visible as possible.

Change-Id: I2253ae63214cef0fb91c8b9423d7918ffc20e888
Reviewed-by: Laszlo Agocs <laszlo.agocs@digia.com>

8 files changed, 49 insertions, 12 deletions

diff --git a/src/quick/items/qquickframebufferobject.cpp b/src/quick/items/qquickframebufferobject.cpp
index 268c2d5342..10d281b7a1 100644
--- a/src/quick/items/qquickframebufferobject.cpp
+++ b/src/quick/items/qquickframebufferobject.cpp
@@ -70,7 +70,7 @@ public:
  * for integrating OpenGL rendering using a framebuffer object (FBO)
  * with Qt Quick.
  *
- * On most platforms, the rendering will occur on a dedicated thread.
+ * On most platforms, the rendering will occur on a \l {Scene Graph and Rendering}{dedicated thread}.
  * For this reason, the QQuickFramebufferObject class enforces a strict
  * separation between the item implementation and the FBO rendering. All
  * item logic, such as properties and UI-related helper functions needed by
@@ -99,7 +99,7 @@ public:
  * to \c false and return a texture of your choosing from
  * QQuickFramebufferObject::Renderer::createFramebufferObject().
  *
- * \sa {Scene Graph - Rendering FBOs}
+ * \sa {Scene Graph - Rendering FBOs}, {Scene Graph and Rendering}
  */
 
 /*!
diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index 9b67e9bbea..90e565926f 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -1681,8 +1681,8 @@ void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus)
     thumb is to only use classes with the "QSG" prefix inside the
     QQuickItem::updatePaintNode() function.
 
-    To read more about how the scene graph rendering works, see
-    \l{Scene Graph and Rendering}
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
 
     \section1 Custom QPainter Items
 
@@ -3423,6 +3423,9 @@ void QQuickItem::geometryChanged(const QRectF &newGeometry, const QRectF &oldGeo
     in this function. Similarly for signals, these will be emitted on the render
     thread and will thus often be delivered via queued connections.
 
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
+
     \sa QSGMaterial, QSGSimpleMaterial, QSGGeometryNode, QSGGeometry,
     QSGFlatColorMaterial, QSGTextureMaterial, QSGNode::markDirty()
  */
diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index b501261cbc..d7acc07908 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -976,8 +976,6 @@ void QQuickWindowPrivate::cleanup(QSGNode *n)
 
     For easily displaying a scene from a QML file, see \l{QQuickView}.
 
-
-
     \section1 Rendering
 
     QQuickWindow uses a scene graph on top of OpenGL to
@@ -1032,6 +1030,9 @@ void QQuickWindowPrivate::cleanup(QSGNode *n)
     scene graph and its OpenGL context being deleted. The
     sceneGraphInvalidated() signal will be emitted when this happens.
 
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
+
     \sa {Scene Graph - OpenGL Under QML}
 
 */
diff --git a/src/quick/scenegraph/coreapi/qsggeometry.cpp b/src/quick/scenegraph/coreapi/qsggeometry.cpp
index 40e0a014ab..43ff1b6240 100644
--- a/src/quick/scenegraph/coreapi/qsggeometry.cpp
+++ b/src/quick/scenegraph/coreapi/qsggeometry.cpp
@@ -286,6 +286,9 @@ const QSGGeometry::AttributeSet &QSGGeometry::defaultAttributes_ColoredPoint2D()
 
     \sa QSGGeometryNode, {Scene Graph - Custom Geometry}
 
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
+
  */
 
 /*!
diff --git a/src/quick/scenegraph/coreapi/qsgmaterial.cpp b/src/quick/scenegraph/coreapi/qsgmaterial.cpp
index 4954fe20bb..22fe29959e 100644
--- a/src/quick/scenegraph/coreapi/qsgmaterial.cpp
+++ b/src/quick/scenegraph/coreapi/qsgmaterial.cpp
@@ -166,8 +166,8 @@ static bool qsg_leak_check = !qgetenv("QML_LEAK_CHECK").isEmpty();
         };
     \endcode
 
-    \warning Instances of QSGMaterialShader belongs to the Scene Graph rendering
-    thread, and cannot be used from the GUI thread.
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
 
  */
 
@@ -550,6 +550,9 @@ static void qt_print_material_count()
     \ingroup qtquick-scenegraph-materials
 
     It serves no purpose outside the QSGMaterial::type() function.
+
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
  */
 
 /*!
@@ -585,8 +588,8 @@ static void qt_print_material_count()
         };
     \endcode
 
-    \warning Instances of QSGMaterial belongs to the Scene Graph rendering thread,
-    and cannot be used from the GUI thread.
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
  */
 
 /*!
diff --git a/src/quick/scenegraph/coreapi/qsgnode.cpp b/src/quick/scenegraph/coreapi/qsgnode.cpp
index 5c196b252c..b0a4f20149 100644
--- a/src/quick/scenegraph/coreapi/qsgnode.cpp
+++ b/src/quick/scenegraph/coreapi/qsgnode.cpp
@@ -99,8 +99,8 @@ static void qt_print_node_count()
     together. Nodes in a blocked subtree will not be preprocessed() and not
     rendered.
 
-    \warning Anything related to QSGNode should happen on the scene graph
-    rendering thread.
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
  */
 
 /*!
@@ -683,6 +683,9 @@ void qsgnode_set_description(QSGNode *node, const QString &description)
 
     The QSGBasicGeometryNode class should not be used by itself. It is only encapsulates
     shared functionality between the QSGGeometryNode and QSGClipNode classes.
+
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
   */
 
 
@@ -824,6 +827,9 @@ void QSGBasicGeometryNode::setGeometry(QSGGeometry *geometry)
     to avoid an extra operation in the fragment shader can have significant performance
     impact on embedded graphics chips. The opaque material is optional.
 
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
+
     \sa QSGGeometry, QSGMaterial, QSGSimpleMaterial
  */
 
@@ -1036,6 +1042,9 @@ void QSGGeometryNode::setInheritedOpacity(qreal opacity)
     Clip nodes must have a geometry before they can be added to the scene graph.
 
     Clipping is usually implemented by using the stencil buffer.
+
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
  */
 
 
@@ -1127,6 +1136,10 @@ void QSGClipNode::setClipRect(const QRectF &rect)
     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.
+
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
+
  */
 
 
@@ -1264,6 +1277,8 @@ void QSGRootNode::notifyNodeChange(QSGNode *node, DirtyState state)
     be marked as blocked, causing isSubtreeBlocked() to return true. This
     is done for performance reasons.
 
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
  */
 
 
diff --git a/src/quick/scenegraph/util/qsgsimplematerial.cpp b/src/quick/scenegraph/util/qsgsimplematerial.cpp
index a247b37d77..ada4dd6c4f 100644
--- a/src/quick/scenegraph/util/qsgsimplematerial.cpp
+++ b/src/quick/scenegraph/util/qsgsimplematerial.cpp
@@ -142,6 +142,9 @@
     the unique QSGSimpleMaterialShader implementation must be
     instantiated with a unique C++ type.
 
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
+
     \sa {Scene Graph - Simple Material}
  */
 
@@ -244,6 +247,9 @@
 
     \inmodule QtQuick
 
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
+
     \sa QSGSimpleMaterialShader
 */
 
diff --git a/src/quick/scenegraph/util/qsgtexture.cpp b/src/quick/scenegraph/util/qsgtexture.cpp
index d9e29f6ec0..ec563273a1 100644
--- a/src/quick/scenegraph/util/qsgtexture.cpp
+++ b/src/quick/scenegraph/util/qsgtexture.cpp
@@ -235,6 +235,9 @@ static void qt_debug_remove_texture(QSGTexture* texture)
     the function removedFromAtlas() can be used to extract a
     non-atlassed copy.
 
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
+
     \sa {Scene Graph - Rendering FBOs}, {Scene Graph - Rendering FBOs in a thread}
  */
 
@@ -766,6 +769,9 @@ void QSGPlainTexture::bind()
 
     To update the content of the texture, call updateTexture() explicitly. Simply calling bind()
     will not update the texture.
+
+    \note All classes with QSG prefix should be used solely on the scene graph's
+    rendering thread. See \l {Scene Graph and Rendering} for more information.
  */