Merge branch 'develop'

Conflicts:
	.qmake.conf
	README
	src/datavisualization/global/qdatavisualizationglobal.h

Change-Id: Ia6941dcf3e6aa17e2e9ebc6f60fac16ef5049f11

4 files changed, 175 insertions, 28 deletions

diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
index 2cc3eece..b5a678e5 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
@@ -153,6 +153,32 @@
  */
 
 /*!
+ * \qmlproperty bool AbstractGraph3D::polar
+ * \since QtDataVisualization 1.2
+ *
+ * If \c {true}, the horizontal axes are changed into polar axes. The X axis becomes the
+ * angular axis and the Z axis becomes the radial axis.
+ * Polar mode is not available for bar graphs.
+ *
+ * Defaults to \c{false}.
+ *
+ * \sa orthoProjection, radialLabelOffset
+ */
+
+/*!
+ * \qmlproperty real AbstractGraph3D::radialLabelOffset
+ * \since QtDataVisualization 1.2
+ *
+ * This property specifies the normalized horizontal offset for the axis labels of the radial
+ * polar axis. The value 0.0 indicates the labels should be drawn next to the 0-angle angular
+ * axis grid line. The value 1.0 indicates the labels are drawn on their normal place at the edge
+ * of the graph background.
+ * This property is ignored if polar property value is \c{false}. Defaults to 1.0.
+ *
+ * \sa polar
+ */
+
+/*!
  * \qmlmethod void AbstractGraph3D::clearSelection()
  * Clears selection from all attached series.
  */
@@ -289,22 +315,123 @@
  * \qmlproperty real AbstractGraph3D::aspectRatio
  * \since QtDataVisualization 1.1
  *
- * Aspect ratio of the graph data. This is the ratio of data scaling between horizontal and
- * vertical axes. Defaults to \c{2.0}.
+ * The aspect ratio is the ratio of the graph scaling between the longest axis on the horizontal
+ * plane and the Y-axis. Defaults to \c{2.0}.
  *
  * \note Has no effect on Bars3D.
+ *
+ * \sa horizontalAspectRatio
+ */
+
+/*!
+ * \qmlproperty real AbstractGraph3D::horizontalAspectRatio
+ * \since QtDataVisualization 1.2
+ *
+ * The horizontal aspect ratio is the ratio of the graph scaling between the X and Z axes.
+ * Value of 0.0 indicates automatic scaling according to axis ranges.
+ * Defaults to \c{0.0}.
+ *
+ * \note Has no effect on Bars3D, which handles scaling on the horizontal plane via
+ * \l{Bars3D::barThickness}{barThickness} and \l{Bars3D::barSpacing}{barSpacing} properties.
+ * Polar graphs also ignore this property.
+ *
+ * \sa aspectRatio, polar, Bars3D::barThickness, Bars3D::barSpacing
  */
 
 /*!
  * \qmlproperty AbstractGraph3D.OptimizationHints AbstractGraph3D::optimizationHints
- * \since Qt Data Visualization 1.1
- *
- * Defines if the rendering optimization is default or static. Default mode provides the full feature set at
- * reasonable performance. Static is a beta level feature and currently supports only a subset of the
- * features on the Scatter graph. Missing features are object gradient for mesh objects, both gradients
- * for points, and diffuse and specular color on rotations. At this point static is intended just for
- * introducing a new feature. It 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.
- * Defaults to \c{OptimizationDefault}
+ * \since QtDataVisualization 1.1
+ *
+ * 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
+ */
+
+/*!
+ * \qmlproperty bool AbstractGraph3D::reflection
+ * \since QtDataVisualization 1.2
+ *
+ * Sets floor reflections on or off. Defaults to \c{false}.
+ *
+ * \note Affects only Bars3D.
+ *
+ * \note In Bars3D graphs holding both positive and negative values, reflections are not supported
+ * for custom items that intersect the floor plane. In that case, reflections should be turned off
+ * to avoid incorrect rendering.
+ *
+ * \sa reflectivity
+ */
+
+/*!
+ * \qmlproperty real AbstractGraph3D::reflectivity
+ * \since QtDataVisualization 1.2
+ *
+ * Adjusts floor reflectivity, larger number being more reflective. Valid range is \c{[0...1]}.
+ * Defaults to \c{0.5}.
+ *
+ * \note Affects only Bars3D.
+ *
+ * \sa reflection
+ */
+
+/*!
+ * \qmlproperty locale AbstractGraph3D::locale
+ * \since QtDataVisualization 1.2
+ *
+ * Sets the locale used for formatting various numeric labels.
+ * Defaults to \c{"C"} locale.
+ *
+ * \sa ValueAxis3D::labelFormat
+ */
+
+/*!
+ * \qmlproperty vector3d AbstractGraph3D::queriedGraphPosition
+ * \since QtDataVisualization 1.2
+ *
+ * This read-only property contains the latest graph position values along each axis queried using
+ * Scene3D::graphPositionQuery. The values are normalized to range \c{[-1, 1]}.
+ * If the queried position was outside the graph bounds, the values
+ * will not reflect the real position, but will instead be some undefined position outside
+ * the range \c{[-1, 1]}. The value will be undefined before any queries are made.
+ *
+ * There isn't a single correct 3D coordinate to match to each specific screen position, so to be
+ * consistent, the queries are always done against the inner sides of an invisible box surrounding
+ * the graph.
+ *
+ * \note Bar graphs only allow querying graph position at the graph floor level,
+ * so the Y-value is always zero for bar graphs and the valid queries can be only made at
+ * screen positions that contain the floor of the graph.
+ *
+ * \sa Scene3D::graphPositionQuery
+ */
+
+/*!
+ * \qmlproperty real AbstractGraph3D::margin
+ * \since QtDataVisualization 1.2
+ *
+ * This property contains the absolute value used for graph margin. The graph margin is the space
+ * left between the edge of the plottable graph area and the edge of the graph background.
+ * If the margin value is negative, the margins are determined automatically and can vary according
+ * to size of the items in the series and the type of the graph.
+ * The value is interpreted as a fraction of Y-axis range, provided the graph aspect ratios have
+ * not beed changed from the defaults.
+ * Defaults to \c{-1.0}.
+ *
+ * \note Having smaller than the automatically determined margin on scatter graph can cause
+ * the scatter items at the edges of the graph to overlap with the graph background.
+ *
+ * \note On scatter and surface graphs, if the margin is comparatively small to the axis label
+ * size, the positions of the edge labels of the axes are adjusted to avoid overlap with
+ * the edge labels of the neighboring axes.
  */
diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc
index 6ee51742..0348652a 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc
@@ -115,6 +115,14 @@
  */
 
 /*!
+ * \qmlproperty real Bars3D::floorLevel
+ *
+ * The desired floor level for the bar graph in Y-axis data coordinates.
+ * The actual floor level cannot go below Y-axis minimum or above Y-axis maximum.
+ * Defaults to zero.
+ */
+
+/*!
  * \qmlmethod void Bars3D::addSeries(Bar3DSeries series)
  * Adds the \a series to the graph. A graph can contain multiple series, but only one set of axes,
  * so the rows and columns of all series must match for the visualized data to be meaningful.
diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
index 23a9a004..2b83b807 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
@@ -73,11 +73,6 @@
  */
 
 /*!
-  \qmlproperty ColorGradient Surface3D::gradient
-  The current surface gradient. Setting this property replaces the previous gradient.
- */
-
-/*!
  * \qmlproperty list<Surface3DSeries> Surface3D::seriesList
  * \default
  * This property holds the series of the graph.
@@ -86,6 +81,22 @@
  */
 
 /*!
+ * \qmlproperty bool Surface3D::flipHorizontalGrid
+ * \since QtDataVisualization 1.2
+ *
+ * In some use cases the horizontal axis grid is mostly covered by the surface, so it can be more
+ * useful to display the horizontal axis grid on top of the graph rather than on the bottom.
+ * A typical use case for this is showing 2D spectrograms using orthoGraphic projection with
+ * a top-down viewpoint.
+ *
+ * If \c{false}, the horizontal axis grid and labels are drawn on the horizontal background
+ * of the graph.
+ * If \c{true}, the horizontal axis grid and labels are drawn on the opposite side of the graph
+ * from the horizontal background.
+ * Defaults to \c{false}.
+ */
+
+/*!
  * \qmlmethod void Surface3D::addSeries(Surface3DSeries series)
  * Adds the \a series to the graph.
  */
diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc
index af419814..b07074b1 100644
--- a/src/datavisualization/doc/src/qtdatavisualization.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc
@@ -37,7 +37,7 @@
 */
 
 /*!
-    \qmlmodule QtDataVisualization 1.1
+    \qmlmodule QtDataVisualization 1.2
     \title Qt Data Visualization QML Types
     \ingroup qmlmodules
 
@@ -98,7 +98,7 @@
     \row
       \li Windows (MSVC)           \li nmake
     \row
-      \li OSX                      \li make
+      \li OS X                     \li make
     \endtable
 
     The above generates the default makefiles for your configuration, which is typically
@@ -127,7 +127,7 @@
     make release
     \endcode
 
-    For both builds (Windows/Mac only):
+    For both builds (Windows/OS X only):
     \code
     qmake CONFIG+="debug_and_release build_all"
     make
@@ -323,20 +323,21 @@
     \title Qt Data Visualization Known Issues
 
     \list
-        \li Android doesn't support both widgets and OpenGL simultaneously, so only
-            the Qt Quick 2 API is usable in practice in Android.
+        \li Some platforms like Android and WinRT cannot handle multiple native windows properly,
+            so only the Qt Quick 2 graphs are available in practice for those platforms.
         \li Shadows are not supported with OpenGL ES2 (including Angle builds in Windows).
         \li Anti-aliasing doesn't work with OpenGL ES2 (including Angle builds in Windows).
+        \li QCustom3DVolume items are not supported with OpenGL ES2 (including Angle builds in
+            Windows).
         \li Surfaces with non-straight rows and columns do not always render properly.
         \li Q3DLight class (and Light3D QML item) are currently not usable for anything.
-        \li Changing any of Q3DScene properties affecting subviewports currently has no effect.
-        \li The color style Q3DTheme::ColorStyleObjectGradient doesn't work for surface graphs.
+        \li Changing most of Q3DScene properties affecting subviewports currently has no effect.
         \li Widget based examples layout incorrectly in iOS.
         \li Reparenting a graph to an item in another QQuickWindow is not supported.
-        \li There is a low-impact binary break between 1.0 and 1.1. The break is due to a QML type
-            registration conflict with QAbstractItemModel between QtDataVisualization and
-            QtCommercial.Charts. Introducing the binary break makes it possible to use both
-            Charts and Data Visualization in the same QML application.
+        \li Android builds of QML applications importing QtDataVisualization also require
+            "QT += datavisualization" in the pro file. This is because Qt Data Visualization
+            QML plugin has a dependency to Qt Data Visualization C++ library, which Qt Creator
+            doesn't automatically add to the deployment package.
     \endlist
 */