Greatly improved Scene Graph Overview documentation

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

11 files changed, 292 insertions, 100 deletions

diff --git a/src/quick/doc/images/sg-renderloop-singlethreaded.jpg b/src/quick/doc/images/sg-renderloop-singlethreaded.jpg
new file mode 100644
index 0000000000..c6d1577138
--- /dev/null
+++ b/src/quick/doc/images/sg-renderloop-singlethreaded.jpg
diff --git a/src/quick/doc/images/sg-renderloop-threaded.jpg b/src/quick/doc/images/sg-renderloop-threaded.jpg
new file mode 100644
index 0000000000..2f7d97591b
--- /dev/null
+++ b/src/quick/doc/images/sg-renderloop-threaded.jpg
diff --git a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
index 60c4cf15df..099c7eb443 100644
--- a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
@@ -51,7 +51,7 @@ reduction like this can greatly improve performance on some hardware.
 
 The scene graph is closely tied to Qt Quick 2.0 and can not be used
 stand-alone. The scene graph is managed and rendered by the
-QQuickWindow class and custom Item elements can add their graphical
+QQuickWindow class and custom Item types can add their graphical
 primitives into the scene graph through a call to
 QQuickItem::updatePaintNode().
 
@@ -63,54 +63,212 @@ graph will even be rendered on a dedicated render thread while the GUI
 thread is preparing the next frame's state.
 
 
+\section1 Qt Quick Scene Graph Structure
 
-\section1 Scene Graph Nodes
+The scene graph is composed of a number of predefined node types, each
+serving a dedicated purpose. Although we refer to it as a scene graph,
+a more precise definition is node tree. The tree is built from
+QQuickItem types in the QML scene and internally the scene is then
+processed by a renderer which draws the scene. The nodes themselves do
+\b not contain any active drawing code nor virtual \c paint()
+function.
 
-The scene graph can only contain a predefined set of node types, each
-serving a dedicated purpose.
+Even though the node tree is mostly built internally by the existing
+Qt Quick QML types, it is possible for users to also add complete
+subtrees with their own content, including subtrees that represent 3D
+models.
 
-\list
 
-\li QSGGeometryNode - for all rendered content in the scene
-graph. In most cases, it will be enough for a custom QQuickItem object to
-simply return a single QSGGeometryNode object from the
-QQuickItem::updatePaintNode() call. 
+\section2 Nodes
 
-\li QSGTransformNode - implements transformations in the scene
-graph. Nested transforms are multiplied together.
+The most important node for users is the \l QSGGeometryNode. It is
+used to define custom graphics by defining its geometry and
+material. The geometry is defined using \l QSGGeometry and describes
+the shape or mesh of the graphical primitive. It can be a line, a
+rectangle, a polygon, many disconnected rectangles, or complex 3D
+mesh. The material defines how the pixels in this shape are filled.
 
-\li QSGOpacityNode - for node opacity changes. Nested opacity nodes have
-cumulative effect.
+A node can have any number of children and geometry nodes will be
+rendered so they appear in child-order with parents behind their
+children. \note This does not say anything about the actual rendering
+order in the renderer. Only the visual output is guaranteed.
 
-\li QSGClipNode - implements clipping in the scene graph. Nested clips
-are intersected.
+The available nodes are:
+\annotatedlist{qtquick-scenegraph-nodes}
 
-\li QSGNode - base class for all nodes in the scene graph. Its primary purpose
-is provide the ability to insert nodes into the scene graph that do not affect
-the rendering, such as the shared root for a subtree of geometry nodes.
+Custom nodes are added to the scene graph by subclassing
+QQuickItem::updatePaintNode() and setting the
+\l {QQuickItem::ItemHasContents} flag.
 
-\endlist
+\warning It is crucial that OpenGL operations and interaction with the
+scene graph happens exclusively on the render thread, primarily
+during the updatePaintNode() call. The rule of thumb is to only
+use classes with the "QSG" prefix inside the
+QQuickItem::updatePaintNode() function.
+
+For more details, see the \l {Custom Geometry Example}.
+
+\section3 Preprocessing
+
+Nodes have a virtual QSGNode::preprocess() function, which will be
+called before the scene graph is rendered. Node subclasses can set the
+flag \l QSGNode::UsePreprocess and override the QSGNode::preprocess()
+function to do final preparation of their node. For example, dividing a
+bezier curve into the correct level of detail for the current scale
+factor or updating a section of a texture.
+
+\section3 Node Ownership
 
 Ownership of the nodes is either done explicitly by the creator or by
-the scene graph by setting the flag \l QSGNode::OwnedByParent on
-it. Assigning ownership to the scene graph is often preferable as it
+the scene graph by setting the flag \l QSGNode::OwnedByParent.
+Assigning ownership to the scene graph is often preferable as it
 simplifies cleanup when the scene graph lives outside the GUI thread.
 
 
+\section2 Materials
+
+The material describes how the interior of a geometry in a \l
+QSGGeometryNode is filled. It encapsulates an OpenGL shader program
+and provides ample flexibility in what can be achieved, though most of
+the Qt Quick items themselves only use very basic materials, such as
+solid color and texture fills.
+
+For users who just want to apply custom shading to a QML Item type,
+it is possible to do this directly in QML using the \l ShaderEffect
+type.
 
-\section1 Rendering
+Below is a complete list of material classes:
+\annotatedlist{qtquick-scenegraph-materials}
+
+For more details, see the \l {Simple Material Example}
+
+
+\section2 Convenience Nodes
+
+The scene graph API is very low-level and focuses on performance
+rather than convenience. Writing custom geometries and materials from
+scratch, even the most basic ones, requires a non-trivial amount of
+code. For this reason, the API includes a few convenience classes to
+make the most common custom nodes readily available.
+
+\list
+\li \l QSGSimpleRectNode - a QSGGeometryNode subclass which defines a
+rectangular geometry with a solid color material.
+
+\li \l QSGSimpleTextureNode - a QSGGeometryNode subclass which defines
+a rectangular geometry with a texture material.
+\endlist
+
+
+
+\section1 Scene Graph and Rendering
 
 The rendering of the scene graph happens internally in the
-QQuickWindow class and is described under the \l{Scene Graph and
-Rendering} section.
+QQuickWindow class, and there is no public API to access it. There are
+however, a few places in the rendering pipeline where the user can
+attach application code. This can be to add custom scene graph
+content or render raw OpenGL content. The integration points are
+defined by the render loop.
+
+
+\section2 Threaded Render Loop
+
+On many configurations, the scene graph rendering will happen on a
+dedicated render thread. This is done to increase parallelism of
+multi-core processors and make better use of stall times such as
+waiting for a blocking swap buffer call. This offers significant
+performance improvements, but imposes certain restrictions on where
+and when interaction with the scene graph can happen.
 
-How to integrate QPainter based graphics is explained in \l{Custom
-Items using QPainter}.
+The following is a simple outline of how a frame gets
+composed with the threaded render loop.
 
-\section1 Mixing Scene Graph and OpenGL
+\image sg-renderloop-threaded.jpg
+
+\list 1
+
+\li A change occurs in the QML scene, causing \c QQuickItem::update()
+to be called. This can be the result of for instance an animation or
+user input. An event is posted to the render thread to initiate a new
+frame.
+
+\li The render thread prepares to draw a new frame and makes the
+OpenGL context current and initiates a blocks on the GUI thread.
+
+\li While the render thread is preparing the new frame, the GUI thread
+calls QQuickItem::updatePolish() to do final touch-up of items before
+they are rendered.
+
+\li GUI thread is blocked.
+
+\li The QQuickWindow::beforeSynchronizing() signal is emitted.
+Applications can make direct connections (using Qt::DirectConnection)
+to this signal to do any preparation required before calls to
+QQuickItem::updatePaintNode().
 
-The scene graph offers two methods for integrating OpenGL
-content. 
+\li Synchronization of the QML state into the scene graph. This is
+done by calling the QQuickItem::updatePaintNode() function on all
+items that have changed since the previous frame. This is the only
+time the QML items and the nodes in the scene graph interact.
+
+\li GUI thread block is released.
+
+\li The scene graph is rendered:
+    \list 1
+
+    \li The QQuickWindow::beforeRendering() signal is
+    emitted. Applications can make direct connections
+    (using Qt::DirectConnection) to this signal to use custom OpenGL calls
+    which will then stack visually beneath the QML scene.
+
+    \li Items that have specified QSGNode::UsePreprocess, will have their
+    QSGNode::preprocess() function invoked.
+
+    \li The renderer processes the nodes and calls OpenGL functions.
+
+    \li The QQuickWindow::afterRendering() signal is
+    emitted. Applications can make direct connections
+    (using Qt::DirectConnection) to this signal to use custom OpenGL calls
+    which will then stack visually over the QML scene.
+
+    \li The rendered frame is swapped and QQuickWindow::frameSwapped()
+    is emitted.
+
+    \endlist
+
+\li While the render thread is rendering, the GUI is free to advance
+animations, process events, etc.
+
+\endlist
+
+The threaded renderer is currently used by default on Linux, Mac OS X
+and EGLFS based QPA platforms, but this is subject to change. It is
+possible to force use of the threaded renderer by setting \c
+{QML_FORCE_THREADED_RENDERER=1} in the environment.
+
+
+\section2 Non-threaded Render Loop
+
+The non-threaded render loop is currently used by default on Windows
+and non-EGLFS based embedded platforms. This is mostly a precautionary
+measure, as not all combinations of OpenGL drivers and windowing
+systems have been tested.
+
+Even when using the non-threaded render loop, you should write your
+code as if you are using the threaded renderer, as failing to do so
+will make the code non-portable.
+
+The following is a simplified illustration of the frame rendering
+sequence in the non-threaded renderer.
+
+\image sg-renderloop-singlethreaded.jpg
+
+
+\section2 Mixing Scene Graph and OpenGL
+
+The scene graph offers two methods for integrating OpenGL content:
+by calling OpenGL commands directly and by creating a textured node
+in the scene graph.
 
 By connecting to the \l QQuickWindow::beforeRendering() and \l
 QQuickWindow::afterRendering() signals, applications can make OpenGL
@@ -122,6 +280,10 @@ needed to perform the rendering. The downside is that Qt Quick decides
 when to call the signals and this is the only time the OpenGL
 application is allowed to draw. 
 
+The \l {OpenGL Under QML} example gives an example on how to use use
+these signals.
+
+
 The other alternative is to create a FramebufferObject, render into it
 and use the result as a textured node in the scene graph, for instance
 using a QSGSimpleTextureNode. A simple way of doing the same is to use
@@ -131,7 +293,8 @@ the OpenGL rendering and QPainter::endNativePainting() after. When
 OpenGL content is integrated with a texture and FramebufferObject, the
 application has more control over when the content is rendered. For
 instance, the application can create a second QOpenGLContext on the
-GUI thread which shares memory with the scene graph's OpenGL context and drive the rendering manually.
+GUI thread which shares memory with the scene graph's OpenGL context
+and drive the rendering manually.
 
 \warning When mixing OpenGL content with scene graph rendering, it is
 important the application does not leave the OpenGL context in a state
@@ -143,6 +306,19 @@ behavior.
 rendering might be happening outside the GUI thread. 
 
 
+\section2 Custom Items using QPainter
+
+The QQuickItem provides a subclass, QQuickPaintedItem, which allows
+the users to render content using QPainter.
+
+\warning Using QQuickPaintedItem uses an indirect 2D surface to render
+its content, either using software rasterization or using an OpenGL
+framebuffer object (FBO), so the rendering is a two-step
+operation. First rasterize the surface, then draw the surface. Using
+scene graph API directly is always significantly faster.
+
+
+
 \section1 Scene Graph Backend
 
 In addition to the public API, the scene graph has an adaptation layer
@@ -155,7 +331,7 @@ It includes:
 
 \li Custom textures; specifically the implementation of
 QQuickWindow::createTextureFromImage and the internal representation
-of the texture used by \l Image and \l BorderImage elements.
+of the texture used by \l Image and \l BorderImage types.
 
 \li Custom renderer; the adaptation layer lets the plugin decide how
 the scene graph is traversed and rendered, making it possible to
@@ -163,7 +339,7 @@ optimize the rendering algorithm for a specific hardware or to make
 use of extensions which improve performance.
 
 \li Custom scene graph implementation of many of the default QML
-elements, including its text and font rendering.
+types, including its text and font rendering.
 
 \li Custom animation driver; allows the animation system to hook
 into the low-level display vertical refresh to get smooth rendering.
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()
  */
diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index d484d425bc..f812840782 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -859,87 +859,63 @@ void QQuickWindowPrivate::cleanup(QSGNode *n)
 
     For easily displaying a scene from a QML file, see \l{QQuickView}.
 
-    \section1 Scene Graph and Rendering
 
-    The QQuickWindow uses a scene graph on top of OpenGL to render. This scene graph is disconnected
-    from the QML scene and potentially lives in another thread, depending on the platform
-    implementation. Since the rendering scene graph lives independently from the QML scene, it can
-    also be completely released without affecting the state of the QML scene.
 
-    The sceneGraphInitialized() signal is emitted on the rendering thread before the QML scene is
-    rendered to the screen for the first time. If the rendering scene graph has been released
-    the signal will be emitted again before the next frame is rendered.
+    \section1 Rendering
 
-    The rendering of each frame is broken down into the following
-    steps, in the given order:
+    QQuickWindow uses a scene graph on top of OpenGL to
+    render. This scene graph is disconnected from the QML scene and
+    potentially lives in another thread, depending on the platform
+    implementation. Since the rendering scene graph lives
+    independently from the QML scene, it can also be completely
+    released without affecting the state of the QML scene.
 
-    \list 1
+    The sceneGraphInitialized() signal is emitted on the rendering
+    thread before the QML scene is rendered to the screen for the
+    first time. If the rendering scene graph has been released, the
+    signal will be emitted again before the next frame is rendered.
 
-    \li The QQuickWindow::beforeSynchronizing() signal is emitted.
-    Applications can make direct connections (Qt::DirectConnection)
-    to this signal to do any preparation required before calls to
-    QQuickItem::updatePaintNode().
-
-    \li Synchronization of the QML state into the scene graph. This is
-    done by calling the QQuickItem::updatePaintNode() function on all
-    items that have changed since the previous frame. When a dedicated
-    rendering thread is used, the GUI thread is blocked during this
-    synchroniation. This is the only time the QML items and the nodes
-    in the scene graph interact.
-
-    \li The window to be rendered is made current using
-    QOpenGLContext::makeCurrent().
-
-    \li The QQuickWindow::beforeRendering() signal is
-    emitted. Applications can make direct connections
-    (Qt::DirectConnection) to this signal to use custom OpenGL calls
-    which will then stack visually beneath the QML scene.
 
-    \li Items that have specified QSGNode::UsesPreprocess, will have their
-    QSGNode::preprocess() function invoked.
+    \section2 Integration with OpenGL
 
-    \li The QQuickWindow is cleared according to what is specified
-    using QQuickWindow::setClearBeforeRendering() and
-    QQuickWindow::setClearColor().
+    It is possible to integrate OpenGL calls directly into the
+    QQuickWindow using the same OpenGL context as the Qt Quick Scene
+    Graph. This is done by connecting to the
+    QQuickWindow::beforeRendering() or QQuickWindow::afterRendering()
+    signal.
 
-    \li The scene graph is rendered.
+    \note When using QQuickWindow::beforeRendering(), make sure to
+    disable clearing before rendering with
+    QQuickWindow::setClearBeforeRendering().
 
-    \li The QQuickWindow::afterRendering() signal is
-    emitted. Applications can make direct connections
-    (Qt::DirectConnection) to this signal to use custom OpenGL calls
-    which will then stack visually over the QML scene.
 
-    \li The rendered frame is swapped and QQuickWindow::frameSwapped()
-    is emitted.
+    \section2 Exposure and Visibility
 
-    \endlist
-
-    All of the above happen on the rendering thread, when applicable.
-
-    While the scene graph is being rendered on the rendering thread, the GUI will process animations
-    for the next frame. This means that as long as users are not using scene graph API
-    directly, the added complexity of a rendering thread can be completely ignored.
-
-    When a QQuickWindow is programatically hidden with hide() or setVisible(false), it will
-    stop rendering and its scene graph and OpenGL context might be released. The
-    sceneGraphInvalidated() signal will be emitted when this happens.
+    When a QQuickWindow instance is deliberately hidden with hide() or
+    setVisible(false), it will stop rendering and its scene graph and
+    OpenGL context might be released. The sceneGraphInvalidated()
+    signal will be emitted when this happens.
 
-    \warning It is crucial that OpenGL operations and interaction with the scene graph happens
-    exclusively on the rendering thread, primarily during the updatePaintNode() phase.
+    \warning It is crucial that OpenGL operations and interaction with
+    the scene graph happens exclusively on the rendering thread,
+    primarily during the updatePaintNode() phase.
 
-    \warning As signals related to rendering might be emitted from the rendering thread,
-    connections should be made using Qt::DirectConnection
+    \warning As signals related to rendering might be emitted from the
+    rendering thread, connections should be made using
+    Qt::DirectConnection.
 
 
     \section2 Resource Management
 
-    QML will typically try to cache images, scene graph nodes, etc to improve performance, but in
-    some low-memory scenarios it might be required to aggressively release these resources. The
-    releaseResources() can be used to force clean up of certain resources. Calling releaseResources()
-    may result in the entire scene graph and its OpenGL context being deleted. The
+    QML will try to cache images and scene graph nodes to
+    improve performance, but in some low-memory scenarios it might be
+    required to aggressively release these resources. The
+    releaseResources() can be used to force the clean up of certain
+    resources. Calling releaseResources() may result in the entire
+    scene graph and its OpenGL context being deleted. The
     sceneGraphInvalidated() signal will be emitted when this happens.
 
-    \sa {OpenGL Under QML Example}
+    \sa {OpenGL Under QML}
 
 */
 
diff --git a/src/quick/scenegraph/coreapi/qsgmaterial.cpp b/src/quick/scenegraph/coreapi/qsgmaterial.cpp
index f8f426fcda..0e40a01311 100644
--- a/src/quick/scenegraph/coreapi/qsgmaterial.cpp
+++ b/src/quick/scenegraph/coreapi/qsgmaterial.cpp
@@ -44,12 +44,21 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \group qtquick-scenegraph-materials
+    \title Qt Quick Scene Graph Material Classes
+    \brief classes used to define materials in the Qt Quick Scene Graph.
+
+    This page lists the material classes in \l {Qt Quick}'s
+    \l {scene graph}{Qt Quick Scene Graph}.
+ */
 
 /*!
     \class QSGMaterialShader
     \brief The QSGMaterialShader class represents an OpenGL shader program
     in the renderer.
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-materials
 
     The QSGMaterialShader API is very low-level. A more convenient API, which
     provides almost all the same features, is available through
@@ -479,6 +488,7 @@ static void qt_print_material_count()
     \class QSGMaterialType
     \brief The QSGMaterialType class is used as a unique type token in combination with QSGMaterial.
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-materials
 
     It serves no purpose outside the QSGMaterial::type() function.
  */
@@ -487,6 +497,7 @@ static void qt_print_material_count()
     \class QSGMaterial
     \brief The QSGMaterial class encapsulates rendering state for a shader program.
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-materials
 
     The QSGMaterial API is very low-level. A more convenient API, which
     provides almost all the same features, is available through
diff --git a/src/quick/scenegraph/coreapi/qsgnode.cpp b/src/quick/scenegraph/coreapi/qsgnode.cpp
index fa56c3b471..5995dc862d 100644
--- a/src/quick/scenegraph/coreapi/qsgnode.cpp
+++ b/src/quick/scenegraph/coreapi/qsgnode.cpp
@@ -59,10 +59,19 @@ static void qt_print_node_count()
 #endif
 
 /*!
+    \group qtquick-scenegraph-nodes
+    \title Qt Quick Scene Graph Node classes
+    \brief Nodes that can be used as part of the scene graph.
+
+    This page lists the nodes in \l {Qt Quick}'s \l {scene graph}{Qt Quick Scene Graph}.
+ */
+
+/*!
     \class QSGNode
     \brief The QSGNode class is the base class for all nodes in the scene graph.
 
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-nodes
 
     The QSGNode class can be used as a child container. Children are added with
     the appendChildNode(), prependChildNode(), insertChildNodeBefore() and
@@ -739,6 +748,7 @@ void QSGBasicGeometryNode::setGeometry(QSGGeometry *geometry)
     \brief The QSGGeometryNode class is used for all rendered content in the scene graph.
 
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-nodes
 
     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
@@ -964,6 +974,7 @@ void QSGGeometryNode::setInheritedOpacity(qreal opacity)
     \brief The QSGClipNode class implements the clipping functionality in the scene graph.
 
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-nodes
 
     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
@@ -1052,6 +1063,7 @@ void QSGClipNode::setClipRect(const QRectF &rect)
     \brief The QSGTransformNode class implements transformations in the scene graph
 
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-nodes
 
     Transformations apply the node's subtree and can be nested. Multiple transform nodes
     will be accumulated by intersecting all their matrices. The accumulation happens
@@ -1188,6 +1200,7 @@ void QSGRootNode::notifyNodeChange(QSGNode *node, DirtyState state)
     \brief The QSGOpacityNode class is used to change opacity of nodes.
 
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-nodes
 
     Opacity applies to its subtree and can be nested. Multiple opacity nodes
     will be accumulated by multiplying their opacity. The accumulation happens
diff --git a/src/quick/scenegraph/util/qsgflatcolormaterial.cpp b/src/quick/scenegraph/util/qsgflatcolormaterial.cpp
index 4c76f65e19..307201277c 100644
--- a/src/quick/scenegraph/util/qsgflatcolormaterial.cpp
+++ b/src/quick/scenegraph/util/qsgflatcolormaterial.cpp
@@ -124,6 +124,7 @@ const char *FlatColorMaterialShader::fragmentShader() const {
     solid colored geometry in the scene graph.
 
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-materials
 
     The flat color material will fill every pixel in a geometry using
     a solid color. The color can contain transparency.
diff --git a/src/quick/scenegraph/util/qsgsimplematerial.cpp b/src/quick/scenegraph/util/qsgsimplematerial.cpp
index 612dbbe5e6..bed1b710ca 100644
--- a/src/quick/scenegraph/util/qsgsimplematerial.cpp
+++ b/src/quick/scenegraph/util/qsgsimplematerial.cpp
@@ -46,6 +46,7 @@
     building custom materials for the scene graph.
 
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-materials
 
     Where the QSGMaterial and QSGMaterialShader API requires a bit of
     boilerplate code to create a functioning material, the
@@ -221,6 +222,7 @@
     \class QSGSimpleMaterial
 
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-materials
 
     \brief The QSGSimpleMaterial class is a template generated class
     used to store the state used with a QSGSimpleMateralShader.
diff --git a/src/quick/scenegraph/util/qsgtexturematerial.cpp b/src/quick/scenegraph/util/qsgtexturematerial.cpp
index 3100a84749..ff91109a2a 100644
--- a/src/quick/scenegraph/util/qsgtexturematerial.cpp
+++ b/src/quick/scenegraph/util/qsgtexturematerial.cpp
@@ -131,6 +131,8 @@ void QSGOpaqueTextureMaterialShader::updateState(const RenderState &state, QSGMa
     \class QSGOpaqueTextureMaterial
     \brief The QSGOpaqueTextureMaterial class provides a convenient way of
     rendering textured geometry in the scene graph.
+    \inmodule QtQuick
+    \ingroup qtquick-scenegraph-materials
 
     The opaque textured material will fill every pixel in a geometry with
     the supplied texture. The material does not respect the opacity of the
@@ -323,6 +325,8 @@ int QSGOpaqueTextureMaterial::compare(const QSGMaterial *o) const
     \class QSGTextureMaterial
     \brief The QSGTextureMaterial class provides a convenient way of
     rendering textured geometry in the scene graph.
+    \inmodule QtQuick
+    \ingroup qtquick-scenegraph-materials
 
     The textured material will fill every pixel in a geometry with
     the supplied texture.
diff --git a/src/quick/scenegraph/util/qsgvertexcolormaterial.cpp b/src/quick/scenegraph/util/qsgvertexcolormaterial.cpp
index 7536712ca4..29f95e56b0 100644
--- a/src/quick/scenegraph/util/qsgvertexcolormaterial.cpp
+++ b/src/quick/scenegraph/util/qsgvertexcolormaterial.cpp
@@ -114,6 +114,7 @@ const char *QSGVertexColorMaterialShader::fragmentShader() const {
     colored geometry in the scene graph.
 
     \inmodule QtQuick
+    \ingroup qtquick-scenegraph-materials
 
     The vertex color material will give each vertex in a geometry a color. Pixels between
     vertices will be linearly interpolated. The colors can contain transparency.