Document the rendering changes

Change-Id: I100a516f6f5d8047b88f6d81cd8794979211df20
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@digia.com>
Reviewed-by: Tomi Korpipää <tomi.korpipaa@digia.com>

18 files changed, 83 insertions, 110 deletions

diff --git a/examples/datavisualization/qmlbars/main.cpp b/examples/datavisualization/qmlbars/main.cpp
index a42218ae..966d068a 100644
--- a/examples/datavisualization/qmlbars/main.cpp
+++ b/examples/datavisualization/qmlbars/main.cpp
@@ -16,8 +16,6 @@
 **
 ****************************************************************************/
 
-#include <QtDataVisualization/qutils.h>
-
 #include <QtGui/QGuiApplication>
 #include <QtCore/QDir>
 #include <QtQuick/QQuickView>
@@ -29,9 +27,6 @@ int main(int argc, char *argv[])
 
     QQuickView viewer;
 
-    // Enable antialiasing
-    viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
-
     // The following are needed to make examples run without having to install the module
     // in desktop environments.
 #ifdef Q_OS_WIN
diff --git a/examples/datavisualization/qmlcustominput/main.cpp b/examples/datavisualization/qmlcustominput/main.cpp
index 08cbf26d..d4658d41 100644
--- a/examples/datavisualization/qmlcustominput/main.cpp
+++ b/examples/datavisualization/qmlcustominput/main.cpp
@@ -16,8 +16,6 @@
 **
 ****************************************************************************/
 
-#include <QtDataVisualization/qutils.h>
-
 #include <QtGui/QGuiApplication>
 #include <QtCore/QDir>
 #include <QtQuick/QQuickView>
@@ -29,9 +27,6 @@ int main(int argc, char *argv[])
 
     QQuickView viewer;
 
-    // Enable antialiasing
-    viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
-
     // The following are needed to make examples run without having to install the module
     // in desktop environments.
 #ifdef Q_OS_WIN
diff --git a/examples/datavisualization/qmllegend/main.cpp b/examples/datavisualization/qmllegend/main.cpp
index a3bc1590..62016770 100644
--- a/examples/datavisualization/qmllegend/main.cpp
+++ b/examples/datavisualization/qmllegend/main.cpp
@@ -16,8 +16,6 @@
 **
 ****************************************************************************/
 
-#include <QtDataVisualization/qutils.h>
-
 #include <QtGui/QGuiApplication>
 #include <QtCore/QDir>
 #include <QtQuick/QQuickView>
@@ -29,9 +27,6 @@ int main(int argc, char *argv[])
 
     QQuickView viewer;
 
-    // Enable antialiasing
-    viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
-
     // The following are needed to make examples run without having to install the module
     // in desktop environments.
 #ifdef Q_OS_WIN
diff --git a/examples/datavisualization/qmlmultigraph/main.cpp b/examples/datavisualization/qmlmultigraph/main.cpp
index 270e5274..ef53d5ec 100644
--- a/examples/datavisualization/qmlmultigraph/main.cpp
+++ b/examples/datavisualization/qmlmultigraph/main.cpp
@@ -16,8 +16,6 @@
 **
 ****************************************************************************/
 
-#include <QtDataVisualization/qutils.h>
-
 #include <QtGui/QGuiApplication>
 #include <QtCore/QDir>
 #include <QtQuick/QQuickView>
@@ -29,9 +27,6 @@ int main(int argc, char *argv[])
 
     QQuickView viewer;
 
-    // Enable antialiasing
-    viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
-
     // The following are needed to make examples run without having to install the module
     // in desktop environments.
 #ifdef Q_OS_WIN
diff --git a/examples/datavisualization/qmloscilloscope/doc/src/qmloscilloscope.qdoc b/examples/datavisualization/qmloscilloscope/doc/src/qmloscilloscope.qdoc
index e5a84b86..c574950b 100644
--- a/examples/datavisualization/qmloscilloscope/doc/src/qmloscilloscope.qdoc
+++ b/examples/datavisualization/qmloscilloscope/doc/src/qmloscilloscope.qdoc
@@ -107,4 +107,20 @@
     DataSource at requested intervals. The label update is also triggered on each cycle:
 
     \snippet qmloscilloscope/qml/qmloscilloscope/main.qml 3
+
+    \section1 Enabling direct rendering
+
+    Since this application potentially deals with a lot of rapidly changing data, we use direct
+    rendering mode for performance. To enable antialiasing in this mode the surface format of the application
+    window needs to be changed, as the default format used by QQuickView doesn't support antialiasing.
+    We use the utility function provided by Qt Data Visualization to change the surface format
+    in \c main.cpp:
+
+    \snippet qmloscilloscope/main.cpp 1
+    \dots 0
+    \snippet qmloscilloscope/main.cpp 2
+
+    On the QML side, direct rendering mode is enabled via \l{AbstractGraph3D::renderingMode}{renderingMode} property:
+
+    \snippet qmloscilloscope/qml/qmloscilloscope/main.qml 5
 */
diff --git a/examples/datavisualization/qmloscilloscope/main.cpp b/examples/datavisualization/qmloscilloscope/main.cpp
index 3e99c4a0..9ee46e21 100644
--- a/examples/datavisualization/qmloscilloscope/main.cpp
+++ b/examples/datavisualization/qmloscilloscope/main.cpp
@@ -17,7 +17,10 @@
 ****************************************************************************/
 
 #include "datasource.h"
+
+//! [2]
 #include <QtDataVisualization/qutils.h>
+//! [2]
 
 #include <QtGui/QGuiApplication>
 #include <QtCore/QDir>
@@ -31,8 +34,10 @@ int main(int argc, char *argv[])
 
     QQuickView viewer;
 
-    // Enable antialiasing
+    // Enable antialiasing in direct rendering mode
+    //! [1]
     viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
+    //! [1]
 
     // The following are needed to make examples run without having to install the module
     // in desktop environments.
diff --git a/examples/datavisualization/qmloscilloscope/qml/qmloscilloscope/main.qml b/examples/datavisualization/qmloscilloscope/qml/qmloscilloscope/main.qml
index 6034109b..eeaeab40 100644
--- a/examples/datavisualization/qmloscilloscope/qml/qmloscilloscope/main.qml
+++ b/examples/datavisualization/qmloscilloscope/qml/qmloscilloscope/main.qml
@@ -49,6 +49,9 @@ Item {
             height: dataView.height
             shadowQuality: AbstractGraph3D.ShadowQualityNone
             selectionMode: AbstractGraph3D.SelectionSlice | AbstractGraph3D.SelectionItemAndRow
+            //! [5]
+            renderingMode: AbstractGraph3D.RenderDirectToBackground
+            //! [5]
 
             axisX.labelFormat: "%d ms"
             axisY.labelFormat: "%d W"
diff --git a/examples/datavisualization/qmlscatter/doc/src/qmlscatter.qdoc b/examples/datavisualization/qmlscatter/doc/src/qmlscatter.qdoc
index ec11970f..177cf7c1 100644
--- a/examples/datavisualization/qmlscatter/doc/src/qmlscatter.qdoc
+++ b/examples/datavisualization/qmlscatter/doc/src/qmlscatter.qdoc
@@ -35,16 +35,6 @@
 
     Before diving into the QML code, let's take a look at the application \c main.cpp.
 
-    Anti-aliasing for Qt Data Visualization graphs in Qt Quick 2 is not supported by default due
-    to technological limitations. To enable anti-aliasing, a custom surface format must be set to
-    the QQuickWindow we are using to show the application in the application \c main.cpp:
-
-    \snippet qmlscatter/main.cpp 1
-    \dots 0
-    \snippet qmlscatter/main.cpp 0
-
-    This will make the graphs nicer to look at.
-
     This application implements a 'Quit' button in the UI, so we want to connect the QQmlEngine::quit()
     signal to our application's QWindow::close() slot:
 
diff --git a/examples/datavisualization/qmlscatter/main.cpp b/examples/datavisualization/qmlscatter/main.cpp
index 425becd5..11684c84 100644
--- a/examples/datavisualization/qmlscatter/main.cpp
+++ b/examples/datavisualization/qmlscatter/main.cpp
@@ -16,10 +16,6 @@
 **
 ****************************************************************************/
 
-//! [1]
-#include <QtDataVisualization/qutils.h>
-//! [1]
-
 #include <QtGui/QGuiApplication>
 #include <QtCore/QDir>
 #include <QtQuick/QQuickView>
@@ -31,11 +27,6 @@ int main(int argc, char *argv[])
 
     QQuickView viewer;
 
-    // Enable antialiasing
-    //! [0]
-    viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
-    //! [0]
-
     // The following are needed to make examples run without having to install the module
     // in desktop environments.
 #ifdef Q_OS_WIN
diff --git a/examples/datavisualization/qmlsurface/main.cpp b/examples/datavisualization/qmlsurface/main.cpp
index 348533bb..71d79a2b 100644
--- a/examples/datavisualization/qmlsurface/main.cpp
+++ b/examples/datavisualization/qmlsurface/main.cpp
@@ -16,8 +16,6 @@
 **
 ****************************************************************************/
 
-#include <QtDataVisualization/qutils.h>
-
 #include <QtGui/QGuiApplication>
 #include <QtCore/QDir>
 #include <QtQuick/QQuickView>
@@ -29,9 +27,6 @@ int main(int argc, char *argv[])
 
     QQuickView viewer;
 
-    // Enable antialiasing
-    viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
-
     // The following are needed to make examples run without having to install the module
     // in desktop environments.
 #ifdef Q_OS_WIN
diff --git a/examples/datavisualization/qmlsurfacelayers/main.cpp b/examples/datavisualization/qmlsurfacelayers/main.cpp
index fc7393e6..eb895dd1 100644
--- a/examples/datavisualization/qmlsurfacelayers/main.cpp
+++ b/examples/datavisualization/qmlsurfacelayers/main.cpp
@@ -29,7 +29,7 @@ int main(int argc, char *argv[])
 
     QQuickView viewer;
 
-    // Enable antialiasing
+    // Enable antialiasing in direct rendering mode
     viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
 
     // The following are needed to make examples run without having to install the module
diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
index 076af455..5b251768 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
@@ -28,12 +28,6 @@
   Note that this type is uncreatable, but contains properties that are shared between
   the 3D visualizations.
 
-  \note QML doesn't support the type of anti-aliasing used by Qt Data Visualization graphs
-  by default. Setting the \c antialiasing property doesn't affect graphs. To enable
-  anti-aliasing for graphs, a custom surface format must be set up for the QQuickView
-  before showing it. You can use the convenience function
-  \c{QtDataVisualization::qDefaultSurfaceFormat()} to create the custom surface format object.
-
   For AbstractGraph3D enums, see \l QAbstract3DGraph::SelectionFlag and
   \l QAbstract3DGraph::ShadowQuality
 
@@ -68,7 +62,7 @@
 /*!
   \qmlproperty AbstractGraph3D.RenderingMode AbstractGraph3D::renderingMode
 
-  Defaults to RenderDirectToBackground.
+  Defaults to \c{RenderIndirect}.
 
   \table
        \header
@@ -76,38 +70,52 @@
            \li Description
        \row
            \li RenderDirectToBackground
-           \li Indicates that the graph should also clear the whole window before
-  rendering the graph, including the areas outside the graph.
-  Since the graphs in this rendering mode are drawn first under other QML items, the
-  regular QML window clearing before rendering is suppressed when there are any graphs
-  in the window; the graphs handle the clearing themselves instead.
-  If you have any other items besides graphs that do similar
-  custom drawing under other QML items, you need to set this property to RenderDirectToBackground_NoClear
-  on all graphs drawn to same window with the other custom items, or it is likely that the
-  other custom items do not render properly. If the graphics hardware and current configuration
-  supports antialiasing that will be used to provide a higher quality rendering with good performance.
-  See \c {QtDataVisualization::qDefaultSurfaceFormat}.
+           \li Indicates the graph will be rendered directly on the window background.
+  This mode also clears the whole window before rendering the graph, including the areas
+  outside the graph.
+  Since the graphs in this rendering mode are drawn on the window background under other QML
+  items, the regular QML window clearing before rendering is suppressed. The graphs handle the clearing
+  themselves instead.
+  If the surface format of the window supports antialiasing, it will be used (see
+  \c {QtDataVisualization::qDefaultSurfaceFormat()}).
+  This rendering mode offers the best performance at the expense of non-standard QML behavior. For example,
+  the graphs do not obey the Z ordering of QML items and the opacity value has no effect on them.
        \row
            \li RenderDirectToBackground_NoClear
-           \li Indicates the graph will not clear the whole window before rendering
-  the graph. The graphs in this renderind mode are drawn first under other QML items.
-  If the graphics hardware and current configuration supports antialiasing that will be
-  used to provide a higher quality rendering with good performance.
-  See \c {QtDataVisualization::qDefaultSurfaceFormat}.
+           \li Similar to RenderDirectToBackground mode, except that the graph will not clear the whole
+  window before rendering the graph. This mode is better for windows where you have other custom items
+  besides the graphs that also draw on the window background. In that case you need to either take care
+  of the window clearing yourself or ensure that all areas of the window are fully covered with opaque
+  items.
+  If one graph in the window uses either of the direct rendering modes, then all other graphs in the
+  same window also drawn in direct modes should use the exact same direct rendering mode.
+  Otherwise some graphs may not show up, depending on the drawing order of the graphs.
        \row
-           \li RenderIndirect_NoAA
+           \li RenderIndirect
            \li Indicates the graph will be first rendered to an offscreen surface that
-  is then drawn during normal QML item rendering to the correct Z order. No antialiasing
-  post processing is done on the graph, meaning the quality will be lower but performance
-  should be better.
+  is then drawn during normal QML item rendering. The rendered image is
+  antialiased using multisampling method if it is supported in the current environment and the
+  msaaSamples property value is greater than zero.
+  This rendering mode offers good quality and normal QML item behavior at the expense of performance.
   \endtable
 
-  \note If one graph in the window uses either RenderDirectToBackground or RenderDirectToBackground_NoClear, then all
-  other graphs in the window drawn in direct mode should use the same rendering mode in that window.
-  Otherwise some graphs may not show.
+  \note Antialiasing is not supported in OpenGL ES2 environments in any rendering mode.
+
+  \note Setting the \c antialiasing property of the graphs doesn't do anything. However, it is
+  set by the graph itself if the current rendering mode uses antialiasing.
 
-  \note If window clearing before rendering is suppressed, any areas of the window not fully
-  covered with opaque items may not draw properly.
+  \sa msaaSamples
+ */
+
+/*!
+  \qmlproperty int AbstractGraph3D::msaaSamples
+  The number of samples used in multisample antialiasing when renderingMode is \c RenderIndirect.
+  When renderingMode is \c RenderDirectToBackground or \c RenderDirectToBackground_NoClear, this
+  property value is read-only and returns the number of samples specified by the window surface
+  format.
+  Defaults to 4.
+
+  \sa renderingMode
  */
 
 /*!
diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc
index 443cebf6..6ee51742 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc
@@ -36,11 +36,6 @@
  *
  * See \l{Qt Quick 2 Bars Example} for more thorough usage example.
  *
- * \note Qt Data Visualization graphs are rendered behind any other QML elements on screen, including
- * the parent elements of the graph. To make the whole graph show, ensure that no other element
- * draws anything over the area the graph occupies. For example, having a non-transparent \c Rectangle
- * item as the parent of a graph causes the graph to be hidden.
- *
  * \sa Bar3DSeries, ItemModelBarDataProxy, Scatter3D, Surface3D, {Qt Data Visualization C++ Classes}
  */
 
diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc
index 76f68af4..4ea7888c 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc
@@ -36,11 +36,6 @@
 
   See \l{Qt Quick 2 Scatter Example} for more thorough usage example.
 
-  \note Qt Data Visualization graphs are rendered behind any other QML elements on screen, including
-  the parent elements of the graph. To make the whole graph show, ensure that no other element
-  draws anything over the area the graph occupies. For example, having a non-transparent \c Rectangle
-  item as the parent of a graph causes the graph to be hidden.
-
   \sa Scatter3DSeries, ScatterDataProxy, Bars3D, Surface3D, {Qt Data Visualization C++ Classes}
  */
 
diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
index 576496b9..23a9a004 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
@@ -36,11 +36,6 @@
 
   See \l{Qt Quick 2 Surface Example} for more thorough usage example.
 
-  \note Qt Data Visualization graphs are rendered behind any other QML elements on screen, including
-  the parent elements of the graph. To make the whole graph show, ensure that no other element
-  draws anything over the area the graph occupies. For example, having a non-transparent \c Rectangle
-  item as the parent of a graph causes the graph to be hidden.
-
   \sa Surface3DSeries, ItemModelSurfaceDataProxy, Bars3D, Scatter3D, {Qt Data Visualization C++ Classes}
  */
 
diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc
index c85b9dbb..e68a1086 100644
--- a/src/datavisualization/doc/src/qtdatavisualization.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc
@@ -301,24 +301,34 @@
  * \fn QSurfaceFormat QtDataVisualization::qDefaultSurfaceFormat(bool antialias = true)
  * \relates QAbstract3DGraph
  *
- * Anti-aliasing is turned on by default on C++ and turned off on QML, except in OpenGL ES2
- * environments, where anti-aliasing is not supported by Qt Data Visualization.
- * This convenience function can be used to construct a suitable surface format for use by
+ * This convenience function can be used to create a custom surface format suitable for use by
  * Qt Data Visualization graphs.
- * The \a{antialias} parameter specifies whether or not anti-aliasing is activated.
+ *
+ * The \a antialias parameter specifies whether or not antialiasing is activated.
+ *
  * Give the surface format returned by this function to the graph constructor (C++) or set
  * it as the window format for QQuickView (QML) before calling show on it.
  *
- * For example, disable anti-aliasing on C++ application:
+ * For example, disable antialiasing on C++ application:
  *
  * \code
+ * #include <QtDataVisualization/qutils.h>
+ *
+ * // ...
+ *
  * Q3DBars *graph = new Q3DBars(QtDataVisualization::qDefaultSurfaceFormat(false));
  * \endcode
  *
- * For example, enable anti-aliasing on QML application:
+ * For example, enable antialiasing for direct rendering modes on QML application:
  *
  * \code
- * QtQuick2ApplicationViewer viewer;
+ * #include <QtDataVisualization/qutils.h>
+ *
+ * // ...
+ *
+ * QQuickView viewer;
  * viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
  * \endcode
+ *
+ * \note Antialiasing is not supported in OpenGL ES2 environments.
  */
diff --git a/tests/qmlcamera/main.cpp b/tests/qmlcamera/main.cpp
index 0a8d9817..040eaed3 100644
--- a/tests/qmlcamera/main.cpp
+++ b/tests/qmlcamera/main.cpp
@@ -16,8 +16,6 @@
 **
 ****************************************************************************/
 
-#include <QtDataVisualization/qutils.h>
-
 #include <QtGui/QGuiApplication>
 #include <QtCore/QDir>
 #include <QtQuick/QQuickView>
@@ -29,9 +27,6 @@ int main(int argc, char *argv[])
 
     QQuickView viewer;
 
-    // Enable antialiasing
-    viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
-
     // The following are needed to make examples run without having to install the module
     // in desktop environments.
 #ifdef Q_OS_WIN
diff --git a/tests/qmldynamicdata/main.cpp b/tests/qmldynamicdata/main.cpp
index d87a2db5..fa3ea866 100644
--- a/tests/qmldynamicdata/main.cpp
+++ b/tests/qmldynamicdata/main.cpp
@@ -16,8 +16,6 @@
 **
 ****************************************************************************/
 
-#include <QtDataVisualization/qutils.h>
-
 #include <QtGui/QGuiApplication>
 #include <QtCore/QDir>
 #include <QtQuick/QQuickView>
@@ -29,9 +27,6 @@ int main(int argc, char *argv[])
 
     QQuickView viewer;
 
-    // Enable antialiasing
-    viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
-
     // The following are needed to make examples run without having to install the module
     // in desktop environments.
 #ifdef Q_OS_WIN