Added documentation for Planets example

Change-Id: I6377e0f845cac98e8933e8ef503779a6bb6565a1
Reviewed-by: Tomi Korpipää <tomi.korpipaa@theqtcompany.com>
Reviewed-by: Pasi Keränen <pasi.keranen@digia.com>

5 files changed, 141 insertions, 9 deletions

diff --git a/examples/canvas3d/canvas3d/threejs/planets/doc/images/planets-example.jpg b/examples/canvas3d/canvas3d/threejs/planets/doc/images/planets-example.jpg
new file mode 100644
index 0000000..7177c27
--- /dev/null
+++ b/examples/canvas3d/canvas3d/threejs/planets/doc/images/planets-example.jpg
diff --git a/examples/canvas3d/canvas3d/threejs/planets/doc/src/planets.qdoc b/examples/canvas3d/canvas3d/threejs/planets/doc/src/planets.qdoc
new file mode 100644
index 0000000..8caf77e
--- /dev/null
+++ b/examples/canvas3d/canvas3d/threejs/planets/doc/src/planets.qdoc
@@ -0,0 +1,126 @@
+/****************************************************************************
+**
+** 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 canvas3d/threejs/planets
+    \since QtCanvas3D 1.0
+    \title Planets Example
+    \ingroup qtcanvas3d-examples
+    \brief Demonstrates combining Qt Quick and three.js rendering.
+
+    The Planets example demonstrates how to implement an application that combines the use of
+    three.js library-based Canvas3D rendering with Qt Quick 2D elements. The example shows the eight
+    planets of our Solar System with the Sun.
+
+    \image planets-example.png
+
+    The planets are rotating around the Sun based on their orbit at a given time. The rotation
+    starts at 2000 Jan 0.0 UT. The planet positions are calculated based on the formulas found here:
+    \l {http://www.stjarnhimlen.se/comp/ppcomp.html}{http://www.stjarnhimlen.se/comp/ppcomp.html}
+    and \l {http://www.davidcolarusso.com/astro/}{http://www.davidcolarusso.com/astro/}.
+
+    \section1 Qt Quick Implementation
+
+    The Qt Quick Implementation \l{canvas3d/threejs/planets/planets.qml}{planets.qml} of the example
+    renders the 3D content using Canvas3D type. The type calls JavaScript code that uses
+    \c{three.js} to initialize, paint, and resize the 3D view.
+
+    \snippet canvas3d/threejs/planets/planets.qml 0
+
+    The planet related information is stored into \c{ListModel}. The selection buttons for the
+    planets and the information sheet are created based on the model. The 2D elements, selection
+    buttons and sliders, are implemented in the QML side.
+
+    The selection buttons change the \c{focusedPlanet} property of the mainview. As the property
+    changes the planet information is updated and the camera is animated to the new position. The
+    camera position and the camera look at point are updated based on values that are animated on
+    QML side.
+
+    \snippet canvas3d/threejs/planets/planets.qml 1
+
+    The sliders are used to adjust the rotation speed, the planet size, and the viewing distance.
+    When the slider value changes, JavaScript code is called to adjust the given property. For
+    example, changing the value of the "Viewing Distance" slider calls the \c{setCameraDistence()}
+    method.
+
+    \snippet canvas3d/threejs/planets/planets.qml 2
+
+    \section1 The JavaScript Code
+
+    The JavaScript side of the implementation, \l{canvas3d/threejs/planets/planets.js}{planets.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 camera and the scene. It also adds the lights to the
+    scene and creates the planet meshes. The Canvas3D renderer needs to be created at initialization
+    phase too.
+
+    Planet texture maps are Copyright (c) by James Hastings-Trew
+    \l{http://planetpixelemporium.com/planets.html}{http://planetpixelemporium.com/planets.html}
+    used with permission. To calculate the ring geometry for the planets with rings, the
+    \c{_RingGeometry()} method from
+    \l{https://github.com/jeromeetienne/threex.planets}{three.xplanets} extension is used.
+
+    The scene is rendered in \c{paintGL()} method. That is also the place where the positions for
+    all of the planets are calculated. The planets are rotated based on their axial tilt and their
+    sidereal rotation period. In the \c{paintGL()} method the camera position and look at point are
+    updated based on the focused planet.
+
+    For more information on how to use \c {three.js} the documentation is available here:
+    \l{http://threejs.org/docs/}{three.js/docs}
+
+    \section1 Handling the Mouse Events
+
+    In order to handle the mouse event in JavaScript code the Canvas3D type has to include the
+    \c{ControlEventSource} type.
+
+    \snippet canvas3d/threejs/planets/planets.qml 3
+
+    This type is then passed to the JavaScript code on initialization.
+
+    \snippet canvas3d/threejs/planets/planets.qml 4
+
+    On JavaScript code in the \c{initializeGL()} method the \c{eventSource} object is saved to a
+    global variable. In this example \c{mouseDown} event is connected to the
+    \c{onDocumentMouseDown()} method.
+
+    \snippet canvas3d/threejs/planets/planets.js 5
+
+    Based on the mouse position variables passed to \c{onDocumentMouseDown()} method, it's checked
+    if the event takes place on top of a planet or not. The focused planet is changed according to
+    the mouse position.
+
+*/
diff --git a/examples/canvas3d/canvas3d/threejs/planets/planets.js b/examples/canvas3d/canvas3d/threejs/planets/planets.js
index 21a08aa..9788fdc 100644
--- a/examples/canvas3d/canvas3d/threejs/planets/planets.js
+++ b/examples/canvas3d/canvas3d/threejs/planets/planets.js
@@ -115,9 +115,9 @@ function initializeGL(canvas, eventSource, mainView) {
                 { canvas: canvas, antialias: true, devicePixelRatio: canvas.devicePixelRatio });
 
     renderer.setSize(canvas.width, canvas.height);
-
+    //! [5]
     eventSource.mouseDown.connect(onDocumentMouseDown);
-
+    //! [5]
 }
 
 function loadPlanetData() {
diff --git a/examples/canvas3d/canvas3d/threejs/planets/planets.pro b/examples/canvas3d/canvas3d/threejs/planets/planets.pro
index ccbf958..647740d 100644
--- a/examples/canvas3d/canvas3d/threejs/planets/planets.pro
+++ b/examples/canvas3d/canvas3d/threejs/planets/planets.pro
@@ -9,6 +9,8 @@ QT += qml quick
 SOURCES += main.cpp
 
 OTHER_FILES += *.qml \
-               planets.js
+               planets.js \
+               doc/src/* \
+               doc/images/*
 
 RESOURCES += planets.qrc
diff --git a/examples/canvas3d/canvas3d/threejs/planets/planets.qml b/examples/canvas3d/canvas3d/threejs/planets/planets.qml
index 1afebcf..9396056 100644
--- a/examples/canvas3d/canvas3d/threejs/planets/planets.qml
+++ b/examples/canvas3d/canvas3d/threejs/planets/planets.qml
@@ -78,7 +78,7 @@ Item {
             duration: 1000
         }
     }
-
+    //! [1]
     onFocusedPlanetChanged: {
 
         if (focusedPlanet == 100) {
@@ -97,15 +97,16 @@ Item {
         cameraOffsetAnimation.running = true;
 
     }
-
+    //! [1]
+    //! [0]
     Canvas3D {
         id: canvas3d
         anchors.fill: parent
-
+        //! [4]
         onInitializeGL: {
             GLCode.initializeGL(canvas3d, eventSource, mainview);
         }
-
+        //! [4]
         onPaintGL: {
             GLCode.paintGL(canvas3d);
             fpsDisplay.fps = canvas3d.fps;
@@ -114,14 +115,15 @@ Item {
         onResizeGL: {
             GLCode.onResizeGL(canvas3d);
         }
-
+        //! [3]
         ControlEventSource {
             anchors.fill: parent
             focus: true
             id: eventSource
         }
+        //! [3]
     }
-
+    //! [0]
     ListModel {
         id: planetModel
 
@@ -325,7 +327,9 @@ Item {
         value: 1
         minimumValue: 1
         maximumValue: 2
+        //! [2]
         onValueChanged: GLCode.setCameraDistance(value);
+        //! [2]
     }
     Text {
         y: distanceSlider.y + distanceSlider.height + width + 10