/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the QtCanvas3D module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL3$
** 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 http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPLv3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or later as published by the Free
** Software Foundation and appearing in the file LICENSE.GPL included in
** the packaging of this file. Please review the following information to
** ensure the GNU General Public License version 2.0 requirements will be
** met: http://www.gnu.org/licenses/gpl-2.0.html.
**
** $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.
*/
