/****************************************************************************
**
** Copyright (C) 2014 Digia Plc
** All rights reserved.
** For any questions to Digia, please use contact form at http://qt.digia.com
**
** This file is part of the QtDataVisualization module.
**
** Licensees holding valid Qt Enterprise licenses may use this file in
** accordance with the Qt Enterprise License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.
**
** If you have questions regarding the use of this file, please use
** contact form at http://qt.digia.com
**
****************************************************************************/

/*!
    \example texturesurface
    \title Textured Surface Example
    \ingroup qtdatavisualization_examples
    \brief Using texture with Q3DSurface.

    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
*/