Merge branch 'stable' into release

Change-Id: I13e80072db1e2c14a37b6a123276be81b085e87e

25 files changed, 278 insertions, 91 deletions

diff --git a/src/quick/doc/src/concepts/convenience/topic.qdoc b/src/quick/doc/src/concepts/convenience/topic.qdoc
index a4b1dad0d3..113b4952a6 100644
--- a/src/quick/doc/src/concepts/convenience/topic.qdoc
+++ b/src/quick/doc/src/concepts/convenience/topic.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/effects/particles.qdoc b/src/quick/doc/src/concepts/effects/particles.qdoc
index 0263996a8a..08a76511b6 100644
--- a/src/quick/doc/src/concepts/effects/particles.qdoc
+++ b/src/quick/doc/src/concepts/effects/particles.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/effects/sprites.qdoc b/src/quick/doc/src/concepts/effects/sprites.qdoc
index 9f32724bfb..ac3234b24c 100644
--- a/src/quick/doc/src/concepts/effects/sprites.qdoc
+++ b/src/quick/doc/src/concepts/effects/sprites.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/effects/topic.qdoc b/src/quick/doc/src/concepts/effects/topic.qdoc
index 03450d8a05..42b0291e44 100644
--- a/src/quick/doc/src/concepts/effects/topic.qdoc
+++ b/src/quick/doc/src/concepts/effects/topic.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/effects/transformations.qdoc b/src/quick/doc/src/concepts/effects/transformations.qdoc
index 7c632c4360..606260cdd4 100644
--- a/src/quick/doc/src/concepts/effects/transformations.qdoc
+++ b/src/quick/doc/src/concepts/effects/transformations.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/input/focus.qdoc b/src/quick/doc/src/concepts/input/focus.qdoc
index eb23e65653..7af1a26ee3 100644
--- a/src/quick/doc/src/concepts/input/focus.qdoc
+++ b/src/quick/doc/src/concepts/input/focus.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/input/mouse.qdoc b/src/quick/doc/src/concepts/input/mouse.qdoc
index 5617f6c64a..a1fbb6ce0e 100644
--- a/src/quick/doc/src/concepts/input/mouse.qdoc
+++ b/src/quick/doc/src/concepts/input/mouse.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/input/textinput.qdoc b/src/quick/doc/src/concepts/input/textinput.qdoc
index 1809d5050b..3c65b7e842 100644
--- a/src/quick/doc/src/concepts/input/textinput.qdoc
+++ b/src/quick/doc/src/concepts/input/textinput.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -50,10 +50,10 @@ The \e validator types enforce the type and format of
 
 \annotatedlist qtquick-text-validator
 
-\snippet doc/snippets/qml/texthandling.qml int validator
+\snippet qml/texthandling.qml int validator
 The validator types bind to \c {TextInput}'s \c validator property.
 
-\snippet doc/snippets/qml/texthandling.qml regexp validator
+\snippet qml/texthandling.qml regexp validator
 The regular expression in the snippet will only allow the inputted text to be
 \c {fruit basket}.
 
diff --git a/src/quick/doc/src/concepts/input/topic.qdoc b/src/quick/doc/src/concepts/input/topic.qdoc
index 51b6496c1d..e3349f350c 100644
--- a/src/quick/doc/src/concepts/input/topic.qdoc
+++ b/src/quick/doc/src/concepts/input/topic.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc b/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc
index 8fd24b00ec..8571879f78 100644
--- a/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc
+++ b/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -49,14 +49,16 @@ via the \e modelData role.
 Here is a ListView with a delegate that references its model item's
 value using the \c modelData role:
 
-\snippet examples/quick/modelviews/stringlistmodel/view.qml 0
+\snippet quick/models/stringlistmodel/view.qml 0
 
 A Qt application can load this QML document and set the value of \c myModel
 to a QStringList:
 
-\snippet examples/quick/modelviews/stringlistmodel/main.cpp 0
+\snippet quick/models/stringlistmodel/main.cpp 0
 
-The complete example is available in Qt's \l {quick/modelviews/stringlistmodel}{examples/quick/modelviews/stringlistmodel} directory.
+The complete source code for this example is available in
+\l {quick/modelviews/stringlistmodel}{examples/quick/modelviews/stringlistmodel}
+within the Qt install directory.
 
 \b{Note:} There is no way for the view to know that the contents of a QStringList
 have changed.  If the QStringList changes, it will be necessary to reset
@@ -68,15 +70,15 @@ the model by calling QQmlContext::setContextProperty() again.
 A list of QObject* values can also be used as a model. A QList<QObject*> provides
 the properties of the objects in the list as roles.
 
-The following application creates a \c DataObject class that with
+The following application creates a \c DataObject class with
 Q_PROPERTY values that will be accessible as named roles when a
 QList<DataObject*> is exposed to QML:
 
-\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 0
+\snippet quick/models/objectlistmodel/dataobject.h 0
 \dots 4
-\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 1
+\snippet quick/models/objectlistmodel/dataobject.h 1
 \codeline
-\snippet examples/quick/modelviews/objectlistmodel/main.cpp 0
+\snippet quick/models/objectlistmodel/main.cpp 0
 \dots
 
 The QObject* is available as the \c modelData property.  As a convenience,
@@ -84,17 +86,19 @@ the properties of the object are also made available directly in the
 delegate's context. Here, \c view.qml references the \c DataModel properties in
 the ListView delegate:
 
-\snippet examples/quick/modelviews/objectlistmodel/view.qml 0
+\snippet quick/models/objectlistmodel/view.qml 0
 
-Note the use of the fully qualified access to the \c color property.
+Note the use of \c color property with qualifier.
 The properties of the object are not replicated in the \c model
-object, since they are easily available via the \c modelData
+object, as they are easily available via the \c modelData
 object.
 
-The complete example is available in Qt's \l {quick/modelviews/objectlistmodel}{examples/quick/modelviews/objectlistmodel} directory.
+The complete source code for this example is available in
+\l {quick/modelviews/objectlistmodel}{examples/quick/modelviews/objectlistmodel}
+within the Qt install directory.
 
 Note: There is no way for the view to know that the contents of a QList
-have changed.  If the QList changes, it will be necessary to reset
+has changed.  If the QList changes, it is necessary to reset
 the model by calling QQmlContext::setContextProperty() again.
 
 
@@ -103,10 +107,11 @@ the model by calling QQmlContext::setContextProperty() again.
 A model can be defined by subclassing QAbstractItemModel. This is the
 best approach if you have a more complex model that cannot be supported
 by the other approaches. A QAbstractItemModel can also automatically
-notify a QML view when the model data has changed.
+notify a QML view when the model data changes.
 
-The roles of a QAbstractItemModel subclass can be exposed to QML by calling
-QAbstractItemModel::setRoleNames(). The default role names set by Qt are:
+The roles of a QAbstractItemModel subclass can be exposed to QML by
+reimplementing QAbstractItemModel::roleNames(). The default role names
+set by Qt are:
 
 \table
 \header
@@ -120,39 +125,42 @@ QAbstractItemModel::setRoleNames(). The default role names set by Qt are:
 \li decoration
 \endtable
 
-Here is an application with a QAbstractListModel subclass named \c AnimalModel
-that has \e type and \e size roles. It reimplements QAbstractItemModel::roleNames() to set the
-role names for accessing the properties via QML:
+Here is an application with a QAbstractListModel subclass named \c AnimalModel,
+which exposes the \e type and \e sizes roles. It reimplements
+QAbstractItemModel::roleNames() to expose the role names, so that they can be
+accessed via QML:
 
-\snippet examples/quick/modelviews/abstractitemmodel/model.h 0
+\snippet quick/models/abstractitemmodel/model.h 0
 \dots
-\snippet examples/quick/modelviews/abstractitemmodel/model.h 1
+\snippet quick/models/abstractitemmodel/model.h 1
 \dots
-\snippet examples/quick/modelviews/abstractitemmodel/model.h 2
+\snippet quick/models/abstractitemmodel/model.h 2
 \codeline
-\snippet examples/quick/modelviews/abstractitemmodel/model.cpp 0
+\snippet quick/models/abstractitemmodel/model.cpp 0
 \codeline
-\snippet examples/quick/modelviews/abstractitemmodel/main.cpp 0
+\snippet quick/models/abstractitemmodel/main.cpp 0
 \dots
 
 This model is displayed by a ListView delegate that accesses the \e type and \e size
 roles:
 
-\snippet examples/quick/modelviews/abstractitemmodel/view.qml 0
+\snippet quick/models/abstractitemmodel/view.qml 0
 
 QML views are automatically updated when the model changes. Remember the model
 must follow the standard rules for model changes and notify the view when
 the model has changed by using QAbstractItemModel::dataChanged(),
-QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for
+QAbstractItemModel::beginInsertRows(), and so on. See the \l {Model subclassing reference} for
 more information.
 
-The complete example is available in Qt's \l {quick/modelviews/abstractitemmodel}{examples/quick/modelviews/abstractitemmodel} directory.
+The complete source code for this example is available in
+\l {quick/modelviews/abstractitemmodel}{examples/quick/modelviews/abstractitemmodel}
+within the Qt install directory.
 
 QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML
 can only display list data.
-In order to display child lists of a hierarchical model
-the VisualDataModel element provides several properties and functions for use
-with models of type QAbstractItemModel:
+In order to display the child lists of a hierarchical model,
+use the VisualDataModel type, which provides the following properties and functions to be used
+with list models of QAbstractItemModel type:
 
 \list
 \li \e hasModelChildren role property to determine whether a node has child nodes.
diff --git a/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc b/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc
index dc4de0a4ca..7c424dd286 100644
--- a/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc
+++ b/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/modelviewsdata/topic.qdoc b/src/quick/doc/src/concepts/modelviewsdata/topic.qdoc
index 5acc7c996d..6939c3131f 100644
--- a/src/quick/doc/src/concepts/modelviewsdata/topic.qdoc
+++ b/src/quick/doc/src/concepts/modelviewsdata/topic.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/positioning/anchors.qdoc b/src/quick/doc/src/concepts/positioning/anchors.qdoc
index bec0949fb3..d0a14f7392 100644
--- a/src/quick/doc/src/concepts/positioning/anchors.qdoc
+++ b/src/quick/doc/src/concepts/positioning/anchors.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -140,7 +140,8 @@ carefully ordered, or they may produce unexpected outcomes. The following exampl
 \table
 \row
 \li
-    \badcode
+    \code
+    //bad code
     Rectangle {
         width: 50
         anchors.left: parent.left
@@ -185,7 +186,8 @@ conditional bindings, as this can lead to the ordering issue described above. In
 the Rectangle will eventually grow to the full width of its parent, because both left and right anchors
 will be simultaneously set during binding update.
 
-\badcode
+\code
+//bad code
 Rectangle {
     width: 50; height: 50
     anchors.left: state == "right" ? undefined : parent.left;
@@ -201,7 +203,8 @@ ordering issues internally.
 For performance reasons, you can only anchor an item to its siblings and direct parent. For example,
 the following anchor is invalid and would produce a warning:
 
-\badcode
+\code
+//bad code
 Item {
     id: group1
     Rectangle { id: rect1; ... }
diff --git a/src/quick/doc/src/concepts/positioning/layouts.qdoc b/src/quick/doc/src/concepts/positioning/layouts.qdoc
index 9d52d4b2e6..0981bddb3d 100644
--- a/src/quick/doc/src/concepts/positioning/layouts.qdoc
+++ b/src/quick/doc/src/concepts/positioning/layouts.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/positioning/righttoleft.qdoc b/src/quick/doc/src/concepts/positioning/righttoleft.qdoc
index b9fba98ec6..44bb03f394 100644
--- a/src/quick/doc/src/concepts/positioning/righttoleft.qdoc
+++ b/src/quick/doc/src/concepts/positioning/righttoleft.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/positioning/topic.qdoc b/src/quick/doc/src/concepts/positioning/topic.qdoc
index 8b40407395..799f578d6e 100644
--- a/src/quick/doc/src/concepts/positioning/topic.qdoc
+++ b/src/quick/doc/src/concepts/positioning/topic.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/statesanimations/animations.qdoc b/src/quick/doc/src/concepts/statesanimations/animations.qdoc
index 3eb9d61fc1..438804ce41 100644
--- a/src/quick/doc/src/concepts/statesanimations/animations.qdoc
+++ b/src/quick/doc/src/concepts/statesanimations/animations.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/statesanimations/behaviors.qdoc b/src/quick/doc/src/concepts/statesanimations/behaviors.qdoc
index c6953b6d75..9c213fdf9f 100644
--- a/src/quick/doc/src/concepts/statesanimations/behaviors.qdoc
+++ b/src/quick/doc/src/concepts/statesanimations/behaviors.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/statesanimations/states.qdoc b/src/quick/doc/src/concepts/statesanimations/states.qdoc
index 28fc535033..7ef05ac2ac 100644
--- a/src/quick/doc/src/concepts/statesanimations/states.qdoc
+++ b/src/quick/doc/src/concepts/statesanimations/states.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/statesanimations/topic.qdoc b/src/quick/doc/src/concepts/statesanimations/topic.qdoc
index 050a770d71..bbcee5a7d2 100644
--- a/src/quick/doc/src/concepts/statesanimations/topic.qdoc
+++ b/src/quick/doc/src/concepts/statesanimations/topic.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc b/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc
index 3f49de540f..fead7d7777 100644
--- a/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
index 6e9d963d8d..099c7eb443 100644
--- a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -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/doc/src/concepts/visualcanvas/topic.qdoc b/src/quick/doc/src/concepts/visualcanvas/topic.qdoc
index 5ef6ef090c..c70c86ff3f 100644
--- a/src/quick/doc/src/concepts/visualcanvas/topic.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/topic.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc b/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc
index 4c9dbdc2dc..37b0b6084f 100644
--- a/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
diff --git a/src/quick/doc/src/concepts/visualtypes/topic.qdoc b/src/quick/doc/src/concepts/visualtypes/topic.qdoc
index 4f5c419eea..af8e673640 100644
--- a/src/quick/doc/src/concepts/visualtypes/topic.qdoc
+++ b/src/quick/doc/src/concepts/visualtypes/topic.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.