Documentation for textured surface example

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

5 files changed, 99 insertions, 4 deletions

diff --git a/examples/datavisualization/texturesurface/custominputhandler.cpp b/examples/datavisualization/texturesurface/custominputhandler.cpp
index 9072a0b4..0f79feef 100644
--- a/examples/datavisualization/texturesurface/custominputhandler.cpp
+++ b/examples/datavisualization/texturesurface/custominputhandler.cpp
@@ -46,6 +46,7 @@ void CustomInputHandler::mousePressEvent(QMouseEvent *event, const QPoint &mouse
     Q3DInputHandler::mousePressEvent(event, mousePos);
 }
 
+//! [1]
 void CustomInputHandler::wheelEvent(QWheelEvent *event)
 {
     float delta = float(event->delta());
@@ -62,6 +63,7 @@ void CustomInputHandler::wheelEvent(QWheelEvent *event)
     m_axisY->setRange(100.0f, y);
     m_axisZ->setRange(m_axisZMinValue, m_axisZMaxValue);
 }
+//! [1]
 
 void CustomInputHandler::mouseMoveEvent(QMouseEvent *event, const QPoint &mousePos)
 {
@@ -115,6 +117,7 @@ void CustomInputHandler::handleAxisDragging()
 
     // Adjust axes
     switch (m_state) {
+//! [0]
     case StateDraggingX:
         distance = (move.x() * xMulX - move.y() * xMulY) * m_speedModifier;
         m_axisXMinValue -= distance;
@@ -131,6 +134,7 @@ void CustomInputHandler::handleAxisDragging()
         }
         m_axisX->setRange(m_axisXMinValue, m_axisXMaxValue);
         break;
+//! [0]
     case StateDraggingZ:
         distance = (move.x() * zMulX + move.y() * zMulY) * m_speedModifier;
         m_axisZMinValue += distance;
@@ -154,6 +158,7 @@ void CustomInputHandler::handleAxisDragging()
 
 void CustomInputHandler::checkConstraints()
 {
+//! [2]
     if (m_axisXMinValue < m_areaMinValue)
         m_axisXMinValue = m_areaMinValue;
     if (m_axisXMaxValue > m_areaMaxValue)
@@ -164,6 +169,7 @@ void CustomInputHandler::checkConstraints()
         m_axisXMinValue -= adjust;
         m_axisXMaxValue += adjust;
     }
+//! [2]
 
     if (m_axisZMinValue < m_areaMinValue)
         m_axisZMinValue = m_areaMinValue;
diff --git a/examples/datavisualization/texturesurface/doc/src/texturesurface.qdoc b/examples/datavisualization/texturesurface/doc/src/texturesurface.qdoc
index ee93dd0a..a4aa219e 100644
--- a/examples/datavisualization/texturesurface/doc/src/texturesurface.qdoc
+++ b/examples/datavisualization/texturesurface/doc/src/texturesurface.qdoc
@@ -18,9 +18,88 @@
 
 /*!
     \example texturesurface
-    \title Texture Surface Example
+    \title Textured Surface Example
     \ingroup qtdatavisualization_examples
     \brief Using texture with Q3DSurface.
 
-	TODO
+    The textured surface example shows how to add an image as a texture for a surface. The example
+    shows also how to:
+
+    \list
+        \li Create a surface series from an image
+        \li Highlight an area of the surface
+        \li Use custom input handler to enable zooming and panning
+    \endlist
+
+    \image texturesurface-example.png
+
+    \section1 Texture to a surface series
+
+    The image to be set as a texture to a surface can be set using QSurface3DSeries::setTextureFile().
+    In this example we have added a check box to control if the texture is set or not. The
+    following code extract is for reacting to the check box selections. The image in this
+    example is read from the resource file where it is as a JPG file. Setting an empty file
+    with the method clears the texture, and the surface uses the gradients or colors from the theme.
+
+    \snippet texturesurface/surfacegraph.cpp 0
+
+    \section1 Topographic surface series
+
+    The topographic data for this example is obtained from National Land Survey of Finland. It
+    provides a product called \c{Elevation Model 2 m}, which was suitable for our needs. We selected
+    Levi fell to be shown. The accuracy of the data was well beyond our needs and therefore it
+    is compressed and encoded into a PNG file. The height value from the original ASCII data is
+    encoded into RGB format using a multiplier, which you will see later on a code extract.
+    The multiplier is calculated simply by dividing the largest 24 bit value with the highest point
+    in Finland.
+
+    Qt Data Visualization has a special proxy for height map image files, but it converts
+    only one byte values. So to utilize the bigger accuracy on the data from National Land
+    Survey of Finland, we read the data from the PNG file and decode it into QSurface3DSeries.
+    The following code samples show how this is done.
+
+    First the encoding multiplier.
+    \snippet texturesurface/topographicseries.cpp 0
+
+    And then the actual decoding.
+    \snippet texturesurface/topographicseries.cpp 1
+
+    \section1 Highlight an area of the surface
+
+    The main idea on creating a highlight on the surface is to create a copy of the series and add
+    a bit of offset to the y value. On this example the class \c HighlightSeries implements the
+    creation of the copy on its \c handlePositionChange method. Firstly the \c HighlightSeries
+    needs to get the pointer to the original series and then it starts to listen the
+    QSurface3DSeries::selectedPointChanged signal.
+
+    \snippet texturesurface/highlightseries.cpp 0
+
+    When the signal arrives, first thing is to check that the position is valid. Then the ranges
+    for the  copied area are calculated and checked that they stay within the bounds. Finally
+    we simply fill the data array of the highlight series with the range from the data array of
+    topography series.
+
+    \snippet texturesurface/highlightseries.cpp 1
+
+    \section1 Use custom input handler to enable zooming and panning
+
+    For the panning the implementation is similar to the \l{Axis Range Dragging With Labels Example}.
+    The difference is that in this example we follow only dragging of X and Z axis and we don't
+    allow dragging the surface outside the graph. The control for this is very simple and done as
+    on the following example for the X axis.
+
+    \snippet texturesurface/custominputhandler.cpp 0
+
+    For the zooming we catch the \c wheelEvent and adjust the X and Y axis ranges according to delta
+    value on QWheelEvent. The Y axis is also adjusted so that the aspect ratio between Y axis and
+    XZ plane stays the same, and we don't get silly looking graph with height exaggerated too much.
+
+    \snippet texturesurface/custominputhandler.cpp 1
+
+    In this case we want to control the zoom level so that it won't get too near to or far from the
+    surface. For instance, if the value for the X axis gets below the allowed, i.e. zooming gets too
+    far, the value is set to the minimum allowed value. If the range is going to below the range
+    minimum, both ends of the axis are adjusted so that the range stays at the limit.
+
+    \snippet texturesurface/custominputhandler.cpp 2
 */
diff --git a/examples/datavisualization/texturesurface/highlightseries.cpp b/examples/datavisualization/texturesurface/highlightseries.cpp
index 3584d1d4..7e5f7efb 100644
--- a/examples/datavisualization/texturesurface/highlightseries.cpp
+++ b/examples/datavisualization/texturesurface/highlightseries.cpp
@@ -35,6 +35,7 @@ HighlightSeries::~HighlightSeries()
 {
 }
 
+//! [0]
 void HighlightSeries::setTopographicSeries(TopographicSeries *series)
 {
     m_topographicSeries = series;
@@ -44,7 +45,9 @@ void HighlightSeries::setTopographicSeries(TopographicSeries *series)
     QObject::connect(m_topographicSeries, &QSurface3DSeries::selectedPointChanged,
                      this, &HighlightSeries::handlePositionChange);
 }
+//! [0]
 
+//! [1]
 void HighlightSeries::handlePositionChange(const QPoint &position)
 {
     m_position = position;
@@ -89,3 +92,4 @@ void HighlightSeries::handlePositionChange(const QPoint &position)
     dataProxy()->resetArray(dataArray);
     setVisible(true);
 }
+//! [1]
diff --git a/examples/datavisualization/texturesurface/surfacegraph.cpp b/examples/datavisualization/texturesurface/surfacegraph.cpp
index 6f62c6e1..f85ef5c8 100644
--- a/examples/datavisualization/texturesurface/surfacegraph.cpp
+++ b/examples/datavisualization/texturesurface/surfacegraph.cpp
@@ -74,6 +74,7 @@ SurfaceGraph::~SurfaceGraph()
     delete m_graph;
 }
 
+//! [0]
 void SurfaceGraph::toggleSurfaceTexture(bool enable)
 {
     if (enable)
@@ -81,3 +82,4 @@ void SurfaceGraph::toggleSurfaceTexture(bool enable)
     else
         m_topography->setTextureFile("");
 }
+//! [0]
diff --git a/examples/datavisualization/texturesurface/topographicseries.cpp b/examples/datavisualization/texturesurface/topographicseries.cpp
index 1d94aead..a1c61f56 100644
--- a/examples/datavisualization/texturesurface/topographicseries.cpp
+++ b/examples/datavisualization/texturesurface/topographicseries.cpp
@@ -22,8 +22,10 @@
 
 using namespace QtDataVisualization;
 
+//! [0]
 // Value used to encode height data as RGB value on PNG file
 const float packingFactor = 11983.0f;
+//! [0]
 
 TopographicSeries::TopographicSeries()
 {
@@ -37,6 +39,7 @@ TopographicSeries::~TopographicSeries()
 
 void TopographicSeries::setTopographyFile(const QString file, float width, float height)
 {
+//! [1]
     QImage heightMapImage(file);
     uchar *bits = heightMapImage.bits();
     int imageHeight = heightMapImage.height();
@@ -62,8 +65,9 @@ void TopographicSeries::setTopographyFile(const QString file, float width, float
         *dataArray << newRow;
     }
 
+    dataProxy()->resetArray(dataArray);
+//! [1]
+
     m_sampleCountX = float(imageWidth);
     m_sampleCountZ = float(imageHeight);
-
-    dataProxy()->resetArray(dataArray);
 }