Document the QSG_VISUALIZE environment variable.

The explanations are taken from 3f8d5d0.

Change-Id: I9901b5f2c42f7bec6573101eb91eb9116089d4e9
Reviewed-by: Gunnar Sletta <gunnar.sletta@jollamobile.com>

6 files changed, 117 insertions, 0 deletions

diff --git a/src/quick/doc/images/visualize-batches.png b/src/quick/doc/images/visualize-batches.png
new file mode 100644
index 0000000000..eb6ebe3606
--- /dev/null
+++ b/src/quick/doc/images/visualize-batches.png
diff --git a/src/quick/doc/images/visualize-clip.png b/src/quick/doc/images/visualize-clip.png
new file mode 100644
index 0000000000..0a67b308cc
--- /dev/null
+++ b/src/quick/doc/images/visualize-clip.png
diff --git a/src/quick/doc/images/visualize-original.png b/src/quick/doc/images/visualize-original.png
new file mode 100644
index 0000000000..00a2de2e4b
--- /dev/null
+++ b/src/quick/doc/images/visualize-original.png
diff --git a/src/quick/doc/images/visualize-overdraw-1.png b/src/quick/doc/images/visualize-overdraw-1.png
new file mode 100644
index 0000000000..af2cf098d7
--- /dev/null
+++ b/src/quick/doc/images/visualize-overdraw-1.png
diff --git a/src/quick/doc/images/visualize-overdraw-2.png b/src/quick/doc/images/visualize-overdraw-2.png
new file mode 100644
index 0000000000..6872074808
--- /dev/null
+++ b/src/quick/doc/images/visualize-overdraw-2.png
diff --git a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
index 278733de8d..7a54b7a021 100644
--- a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
@@ -739,4 +739,121 @@ with multiple windows.
   {QSG_RENDER_TIMING=1} will output a number of useful timing
   parameters which can be useful in pinpointing where a problem lies.
 
+  \section1 Visualizing
+
+  To visualize the various aspects of the scene graph's default renderer, the
+  \c QSG_VISUALIZE environment variable can be set to one of the values
+  detailed in each section below. We provide examples of the output of
+  some of the variables using the following QML code:
+
+  \code
+  import QtQuick 2.2
+
+  Rectangle {
+      width: 200
+      height: 140
+
+      ListView {
+          id: clippedList
+          x: 20
+          y: 20
+          width: 70
+          height: 100
+          clip: true
+          model: ["Item A", "Item B", "Item C", "Item D"]
+
+          delegate: Rectangle {
+              color: "lightblue"
+              width: parent.width
+              height: 25
+
+              Text {
+                  text: modelData
+                  anchors.fill: parent
+                  horizontalAlignment: Text.AlignHCenter
+                  verticalAlignment: Text.AlignVCenter
+              }
+          }
+      }
+
+      ListView {
+          id: clippedDelegateList
+          x: clippedList.x + clippedList.width + 20
+          y: 20
+          width: 70
+          height: 100
+          clip: true
+          model: ["Item A", "Item B", "Item C", "Item D"]
+
+          delegate: Rectangle {
+              color: "lightblue"
+              width: parent.width
+              height: 25
+              clip: true
+
+              Text {
+                  text: modelData
+                  anchors.fill: parent
+                  horizontalAlignment: Text.AlignHCenter
+                  verticalAlignment: Text.AlignVCenter
+              }
+          }
+      }
+  }
+  \endcode
+
+  For the ListView on the left, we set its \l {Item::clip}{clip} property to
+  \c true. For the ListView on right, we also set each delegate's
+  \l {Item::clip}{clip} property to \c true to illustrate the effects of
+  clipping on batching.
+
+  \image visualize-original.png "Original"
+  Original
+
+  \note The visualized elements do not respect clipping, and rendering order is
+  arbitrary.
+
+  \section2 Visualizing Batches
+
+  Setting \c QSG_VISUALIZE to \c batches visualizes batches in the renderer.
+  Merged batches are drawn with a solid color and unmerged batches are drawn
+  with a diagonal line pattern. Few unique colors means good batching.
+  Unmerged batches are bad if they contain many individual nodes.
+
+  \image visualize-batches.png "batches"
+  \c QSG_VISUALIZE=batches
+
+  \section2 Visualizing Clipping
+
+  Setting \c QSG_VISUALIZE to \c clip draws red areas on top of the scene
+  to indicate clipping. As Qt Quick Items do not clip by default, no clipping
+  is usually visualized.
+
+  \image visualize-clip.png
+  \c QSG_VISUALIZE=clip
+
+  \section2 Visualizing Changes
+
+  Setting \c QSG_VISUALIZE to \c changes visualizes changes in the renderer.
+  Changes in the scenegraph are visualized with a flashing overlay of a random
+  color. Changes on a primitive are visualized with a solid color, while
+  changes in an ancestor, such as matrix or opacity changes, are visualized
+  with a pattern.
+
+  \section2 Visualizing Overdraw
+
+  Setting \c QSG_VISUALIZE to \c overdraw visualizes overdraw in the renderer.
+  Visualize all items in 3D to highlight overdraws. This mode can also be used
+  to detect geometry outside the viewport to some extent. Opaque items are
+  rendered with a green tint, while translucent items are rendered with a red
+  tint. The bounding box for the viewport is rendered in blue. Opaque content
+  is easier for the scenegraph to process and is usually faster to render.
+
+  Note that the root rectangle in the code above is superfluous as the window
+  is also white, so drawing the rectangle is a waste of resources in this case.
+  Changing it to an Item can give a slight performance boost.
+
+  \image visualize-overdraw-1.png "overdraw-1"
+  \image visualize-overdraw-2.png "overdraw-2"
+  \c QSG_VISUALIZE=overdraw
  */