/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCanvas3D module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:BSD$
** 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.
**
** BSD License Usage
** Alternatively, you may use this file under the terms of the BSD license
** as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
**   * Redistributions of source code must retain the above copyright
**     notice, this list of conditions and the following disclaimer.
**   * Redistributions in binary form must reproduce the above copyright
**     notice, this list of conditions and the following disclaimer in
**     the documentation and/or other materials provided with the
**     distribution.
**   * Neither the name of The Qt Company Ltd nor the names of its
**     contributors may be used to endorse or promote products derived
**     from this software without specific prior written permission.
**
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example threejs/cellphone
    \since QtCanvas3D 1.1
    \title Interactive Mobile Phone Example
    \ingroup qtcanvas3d-examples
    \brief Demonstrates using Qt Quick item as a texture with three.js.

    This example demonstrates how to implement an application that uses Qt Quick 2D element
    as a texture in a three.js scene. The example shows a 3D model of a mobile phone with an UI
    implemented with Qt Quick. When the phone is not rotating, the UI can be interacted with.

    \image cellphone-example.png

    \section1 Qt Quick Implementation

    The Qt Quick Implementation \l{threejs/cellphone/qml/cellphone/main.qml}{main.qml}
    of the example renders the 3D model of the mobile phone using Canvas3D type.
    The phone UI is composed of the \c textureSource Qt Quick item and its children.
    To make it possible to use the item as a texture source for Canvas3D,
    we must enable the layer of the item:

    \snippet threejs/cellphone/qml/cellphone/main.qml 0
    \dots

    The texture mirroring is disabled so that the OpenGL texture generated from the item
    is oriented as the three.js expects.

    The \c textureSource item is passed as a parameter to the JavaScript function handling the
    OpenGL initialization in Canvas3D:

    \snippet threejs/cellphone/qml/cellphone/cellphonecanvas.qml 1

    The texture generated from the \c textureSource is not interactable by itself, as it is just a
    regular texture. To make it appear interactable, we make it so that the phone UI is interactable
    only when the phone is not rotating and superimpose the actual \c textureSource item over the
    Canvas3D so that both the 3D model and the \c textureSource items are perfectly aligned.
    The 3D model and the Qt Quick UI are aligned by careful positioning of the model and
    scaling of the \c textureSource item using its \l{Item::transform}{transform} property.
    The \c textureSource item is set fully transparent so that there are no visual artifacts:

    \snippet threejs/cellphone/qml/cellphone/main.qml 2

    To ensure user cannot interact with the UI when the phone is rotating, we hide the
    \c textureSource item behind the Canvas3D by adjusting its \l{Item::z}{z} property when the
    phone starts its rotation animation.

    \section1 The JavaScript Code

    The JavaScript side of the implementation,
    \l{threejs/cellphone/qml/cellphone/cellphone.js}{cellphone.js},
    is done using a version of \c{three.js} that is ported for \l{Qt Canvas 3D}:
    \l{https://github.com/tronlec/three.js}{three.js}.

    The \c{initializeGL()} method creates the scene. It also adds the lights and the camera to the
    scene and creates materials and meshes used in the scene. The part relevant to the main point
    of this example is how the \c textureSource is handled. It is very simple to create a texture
    from a Qt Quick texture source: simply create a new \c{THREE.QtQuickItemTexture} with the
    \c textureSource as a parameter and you are done:

    \snippet threejs/cellphone/qml/cellphone/cellphone.js 0

    The texture created this way can be used as a map to a material just like a regular texture:

    \snippet threejs/cellphone/qml/cellphone/cellphone.js 1

    The scene is rendered in \c{paintGL()} method, which simply adjusts the rotations of the
    phone meshes, repositions the camera and light, and renders the scene.

    For more information on how to use \c {three.js} the documentation is available here:
    \l{http://threejs.org/docs/}{three.js/docs}

    The background sphere uses Pluto texture map, which is Copyright (c) by James Hastings-Trew
    \l{http://planetpixelemporium.com/planets.html}{http://planetpixelemporium.com/planets.html}.
    Used with permission.
*/
