/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example qmlsurface
    \title Qt Quick 2 Surface Example
    \ingroup qtdatavisualization_examples
    \brief Using Surface3D in a QML application.

    The Qt Quick 2 surface example shows how to make a simple 3D surface plot using Surface3D with
    Qt Quick 2.

    \image qmlsurface-example.png

    The focus in this example is on generating a surface graph from height data, so in this section
    we skip explaining the application creation. For more detailed QML example documentation,
    see \l{Qt Quick 2 Scatter Example}.

    \include examples-run.qdocinc

    \section1 Adding Data to the Graph

    This example shows two methods to set data to surface graph, using the HeightMapSurfaceDataProxy
    and ItemModelSurfaceDataProxy. First we go through setting the data using the height map specific
    data proxy. It is done with the code snippet below. The proxy itself is contained in a
    Surface3DSeries. Inside the HeightMapSurfaceDataProxy the \c heightMapFile specifies the
    image file containing the height data. The value properties in the proxy define the minimum
    and maximum values for surface area width and depth. This example shows the terrain around Tycho
    crater at imaginary position from 67 to 97 and from 30 to 60. Note that on the graph the scale
    on the Y dimension exaggerates the height.

    \snippet qmlsurface/qml/qmlsurface/main.qml 4

    The other method to set surface data used in this example is with model mapping. We do that by
    first defining a \c ListModel containing the data for the surface:

    \snippet qmlsurface/qml/qmlsurface/Data.qml 0
    \dots 4

    Then we set up a Surface3DSeries with a ItemModelSurfaceDataProxy:

    \snippet qmlsurface/qml/qmlsurface/main.qml 5
    \dots

    We add the actual data to the \c itemModel of the ItemModelSurfaceDataProxy. We also define the
    roles for columns, rows and values. In this example the row holds values for longitude, column
    for latitude and the value is for height.

    \dots 0
    \snippet qmlsurface/qml/qmlsurface/main.qml 6

    \section1 Showing Data

    In the \c main.qml, we set up the Surface3D element to show the data and various UI elements
    to illustrate few interesting features.

    First is the gradient to be used for the surface, which can be defined as seen in the following
    snippet. With the ColorGradient we set example colors from position 0.0 to 1.0.

    \snippet qmlsurface/qml/qmlsurface/main.qml 0

    This element is set into the \c baseGradients property in the \c theme used in Surface3D:

    \snippet qmlsurface/qml/qmlsurface/main.qml 7

    Other interesting features can be controlled with buttons.

    The first button is to toggle on and off the surface grid, for which we use the following code:

    \snippet qmlsurface/qml/qmlsurface/main.qml 1

    Second button is for surface shading mode, which is controlled with this code:

    \snippet qmlsurface/qml/qmlsurface/main.qml 2

    Third button is for series visibility, which is controlled with this code:

    \snippet qmlsurface/qml/qmlsurface/main.qml 8

    Notice that the \c drawMode and \c flatShadingEnable properties are set for both series.

    Fourth and fifth buttons are for controlling background features.

    The last button is for switching between the two series, one of which uses
    HeightMapSurfaceDataProxy and the other one ItemModelSurfaceDataProxy. For this we use the
    following code:

    \snippet qmlsurface/qml/qmlsurface/main.qml 3

    We also set the maximum value to 500 in model proxy to make the surface flatter and
    250 on height map proxy to show exaggerated height. At the same time the middle color position
    on the gradient is modified to match the value range change.

    \section1 Example Contents
*/