Doc: Add Basic documentation for Scenegraph Adaptations

Now that there are multiple scenegraph adaptations, there needs to be a
bit more documentation describing each.  Really the only fully supported
additional backend is the Software adaptation, so the relevant docs have
been transferred from the 2D Renderer documentation, and the old docs
are now removed.

Change-Id: I951f87357a03a37bacb14185748b67ac9ae9a9cf
Reviewed-by: Laszlo Agocs <laszlo.agocs@theqtcompany.com>

3 files changed, 103 insertions, 10 deletions

diff --git a/src/quick/doc/src/concepts/visualcanvas/adaptations.qdoc b/src/quick/doc/src/concepts/visualcanvas/adaptations.qdoc
new file mode 100644
index 0000000000..d7d2fea281
--- /dev/null
+++ b/src/quick/doc/src/concepts/visualcanvas/adaptations.qdoc
@@ -0,0 +1,86 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\title Scene Graph Adaptations
+\page qtquick-visualcanvas-adaptations.html
+
+\section1 Scene Graph Adaptations in Qt Quick
+
+Originally Qt Quick only had one available renderer for parsing the
+scene graph and rendering the results to a render target.  This renderer
+is now the default OpenGL Renderer which supports rendering either using
+the OpenGL ES 2.0 or OpenGL 2.0 APIs.  The Qt Quick APIs are designed
+with the assumption that these two APIs are always available.  It is
+however possible now to use other graphics API's to render Qt Quick
+scenes using the scene graph APIs.
+
+\section1 OpenGL ES 2.0 and OpenGL 2.0 Adaptation
+
+The default adaptation capable of providing the full Qt Quick 2 feature
+set is the OpenGL adaptation.  All of the details of the OpenGL
+adpatation can are available here
+\l{qtquick-visualcanvas-scenegraph-renderer.html}{OpenGL Adaptation}
+
+\section1 Software Adaptation
+
+The Software adaptation is an alternative renderer for \l {Qt Quick} 2 that uses the Raster
+paint engine to render the contents of the scene graph instead of OpenGL.
+As a result of not using OpenGL to render the scene graph, some features
+and optimizations are no longer available. Most Qt Quick 2 applications
+will run without modification though any attempts to use unsupported
+features will be ignored. By using the Software adpatation it is possible to run Qt
+Quick 2 applications on hardware and platforms that do not have OpenGL
+support.
+
+The Software adaptation was previously known as the Qt Quick 2D Renderer.
+
+\section2 Shader Effects
+ShaderEffect components in QtQuick 2 can not be rendered by the Software adptation.
+
+\section2 Qt Graphical Effects Module
+\l {Qt Graphical Effects} uses ShaderEffect items to render effects. If you use
+graphical effects from this module, then you should not hide the source
+item so that the original item can still be rendered.
+
+\section2 Particle Effects
+It is not possible to render particle effects with the Software adaptation. Whenever
+possible, remove particles completely from the scene. Otherwise they will still
+require some processing, even though they are not visible.
+
+\section2 Sprites
+The Sprite item depends on OpenGL functions and will not be visible.
+
+\section2 Rendering Text
+The text rendering with the Software adaptation is based on software
+rasterization and does not respond as well to transformations such as scaling
+as when using OpenGL. The quality is similar to choosing \l [QML] {Text::renderType}
+{Text.NativeRendering} with \l [QML] {Text} items.
+
+\section1 Direct3D 12 (experimental)
+
+*/
diff --git a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
index 443d189f58..ea62603f06 100644
--- a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
@@ -31,9 +31,10 @@
 
 \section1 The Scene Graph in Qt Quick
 
-Qt Quick 2 makes use of a dedicated scene graph based on OpenGL ES 2.0
-or OpenGL 2.0 for its rendering. Using a scene graph for graphics
-rather than the traditional imperative painting systems (QPainter and
+Qt Quick 2 makes use of a dedicated scene graph based and a series of
+adpatations of which the default uses OpenGL ES 2.0 or OpenGL 2.0 for
+its rendering. Using a scene graph for graphics rather than the
+traditional imperative painting systems (QPainter and
 similar), means the scene to be rendered can be retained between
 frames and the complete set of primitives to render is known before
 rendering starts. This opens up for a number of optimizations, such as
@@ -62,6 +63,11 @@ independently of the state of the items. On many platforms, the scene
 graph will even be rendered on a dedicated render thread while the GUI
 thread is preparing the next frame's state.
 
+\note Much of the information listed on this page is specific to the
+default OpenGL adaptation of the Qt Quick Scene graph. For more information
+about the different scene graph adaptations see
+\l{qtquick-visualcanvas-adaptations.html}{Scene Graph Adaptations}.
+
 
 \section1 Qt Quick Scene Graph Structure
 
diff --git a/src/quick/doc/src/concepts/visualcanvas/topic.qdoc b/src/quick/doc/src/concepts/visualcanvas/topic.qdoc
index 30fba97474..168c616d06 100644
--- a/src/quick/doc/src/concepts/visualcanvas/topic.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/topic.qdoc
@@ -55,12 +55,13 @@ See the documentation about the \l{qtquick-visualcanvas-visualparent.html}
 
 \section1 Scene Graph
 
-Modern computer systems and devices use OpenGL to draw graphics.  Qt Quick
-requires OpenGL and it is used to display applications developed with
-Qt Quick in QML.  In particular, Qt Quick defines a scene graph which is then
-rendered.  See the documentation about the
-\l{qtquick-visualcanvas-scenegraph.html}{Scene Graph} for in-depth
-information about the concept of a scene graph and why it is beneficial, and
-about the scene graph implementation provided by Qt Quick.
+Modern computer systems and devices use graphics processing units or GPUs to
+render graphics.  Qt Quick can leverage this graphics hardware by using graphics
+APIs like OpenGL.  The default graphics adpatation for Qt Quick requires OpenGL and
+it is used to display applications developed with Qt Quick in QML.  In particular,
+Qt Quick defines a scene graph which is then rendered.  See the documentation about the
+\l{qtquick-visualcanvas-scenegraph.html}{Scene Graph} for in-depth information about
+the concept of a scene graph and why it is beneficial, and about the scene graph
+adaptations provided by Qt Quick.
 
 */