Document the issue with large surfaces and static scatters.

OpenGL ES2 and/or 32bit environments can have relatively low maximum
supported vertex counts per draw call, so large surfaces and static
scatters may not get rendered.

Task-number: QTRD-3364
Change-Id: I7fd024b0428548ac7e2ca043a06d01d2442dd226
Reviewed-by: Tomi Korpipää <tomi.korpipaa@digia.com>

3 files changed, 30 insertions, 8 deletions

diff --git a/src/datavisualization/data/qsurfacedataproxy.cpp b/src/datavisualization/data/qsurfacedataproxy.cpp
index dbe7cc49..12b24465 100644
--- a/src/datavisualization/data/qsurfacedataproxy.cpp
+++ b/src/datavisualization/data/qsurfacedataproxy.cpp
@@ -53,6 +53,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \note Surfaces with less than two rows or columns are not considered valid surfaces and will
  * not be rendered.
  *
+ * \note On some environments, surfaces with a lot of visible vertices may not render, because
+ * they exceed the per-draw vertex count supported by the graphics driver.
+ * This is mostly an issue on 32bit and/or OpenGL ES2 platforms.
+ *
  * \sa {Qt Data Visualization Data Handling}
  */
 
diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
index b26f0818..b5a678e5 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
@@ -342,11 +342,20 @@
  * \qmlproperty AbstractGraph3D.OptimizationHints AbstractGraph3D::optimizationHints
  * \since QtDataVisualization 1.1
  *
- * Defines if the rendering optimization is default or static. Default mode provides the full feature set at
- * reasonable performance. Static optimizes graph rendering and is ideal for large non-changing data sets.
- * It is slower with dynamic data changes and item rotations. Selection is not optimized, so using it with
- * massive data sets is not advisable. Static works only on the Scatter graph.
+ * Defines if the rendering optimization is default or static. Default mode provides the full
+ * feature set at reasonable performance. Static mode optimizes graph rendering and is ideal for
+ * large non-changing data sets. It is slower with dynamic data changes and item rotations.
+ * Selection is not optimized, so using it with massive data sets is not advisable.
+ * Static works only on the Scatter graph.
  * Defaults to \c{OptimizationDefault}.
+ *
+ * \note On some environments, large graphs using static optimization may not render, because
+ * all of the items are rendered using a single draw call, and different graphics drivers have
+ * different maximum vertice counts per call that they support.
+ * This is mostly an issue on 32bit and/or OpenGL ES2 platforms.
+ * To work around this issue, choose an item mesh with low vertex count or use the point mesh.
+ *
+ * \sa Abstract3DSeries::mesh
  */
 
 /*!
diff --git a/src/datavisualization/engine/qabstract3dgraph.cpp b/src/datavisualization/engine/qabstract3dgraph.cpp
index df6ed597..47802c89 100644
--- a/src/datavisualization/engine/qabstract3dgraph.cpp
+++ b/src/datavisualization/engine/qabstract3dgraph.cpp
@@ -647,11 +647,20 @@ qreal QAbstract3DGraph::aspectRatio() const
 /*!
  * \property QAbstract3DGraph::optimizationHints
  *
- * Defines if the rendering optimization is default or static. Default mode provides the full feature set at
- * reasonable performance. Static optimizes graph rendering and is ideal for large non-changing data sets.
- * It is slower with dynamic data changes and item rotations. Selection is not optimized, so using it with
- * massive data sets is not advisable. Static works only on the Scatter graph.
+ * Defines if the rendering optimization is default or static. Default mode provides the full
+ * feature set at reasonable performance. Static mode optimizes graph rendering and is ideal for
+ * large non-changing data sets. It is slower with dynamic data changes and item rotations.
+ * Selection is not optimized, so using it with massive data sets is not advisable.
+ * Static works only on the Scatter graph.
  * Defaults to \c{OptimizationDefault}.
+ *
+ * \note On some environments, large graphs using static optimization may not render, because
+ * all of the items are rendered using a single draw call, and different graphics drivers have
+ * different maximum vertice counts per call that they support.
+ * This is mostly an issue on 32bit and/or OpenGL ES2 platforms.
+ * To work around this issue, choose an item mesh with low vertex count or use the point mesh.
+ *
+ * \sa QAbstract3DSeries::mesh
  */
 void QAbstract3DGraph::setOptimizationHints(OptimizationHints hints)
 {