Updating OneQt documentation.

Change-Id: If482e713c834fdbaf14c63281984309cc23ad48e
Reviewed-by: Titta Heikkala <titta.heikkala@theqtcompany.com>
Reviewed-by: Pasi Keränen <pasi.keranen@digia.com>

4 files changed, 73 insertions, 51 deletions

diff --git a/examples/canvas3d/canvas3d/threejs/oneqt/ImageCube.qml b/examples/canvas3d/canvas3d/threejs/oneqt/ImageCube.qml
index cc2ab0b..f08988c 100644
--- a/examples/canvas3d/canvas3d/threejs/oneqt/ImageCube.qml
+++ b/examples/canvas3d/canvas3d/threejs/oneqt/ImageCube.qml
@@ -42,11 +42,9 @@ import "imagecube.js" as GLCode
 Canvas3D {
     id: cube
     //! [0]
+    state: "image6"
     property color backgroundColor: "#FCFCFC"
     property real angleOffset: -180 / 8.0
-    property real xRotation: 0
-    property real yRotation: 0
-    property real zRotation: 0
     property string image1: ""
     //! [0]
     property string image2: ""
@@ -54,7 +52,9 @@ Canvas3D {
     property string image4: ""
     property string image5: ""
     property string image6: ""
-    state: "image6"
+    property real xRotation: 0
+    property real yRotation: 0
+    property real zRotation: 0
 
     onBackgroundColorChanged: { GLCode.setBackgroundColor(cube.backgroundColor); }
 
@@ -125,7 +125,7 @@ Canvas3D {
     }
 
     onResizeGL: {
-        GLCode.onResizeGL(cube);
+        GLCode.resizeGL(cube);
     }
     //! [3]
 
diff --git a/examples/canvas3d/canvas3d/threejs/oneqt/doc/src/oneqt.qdoc b/examples/canvas3d/canvas3d/threejs/oneqt/doc/src/oneqt.qdoc
index 759d023..54f535d 100644
--- a/examples/canvas3d/canvas3d/threejs/oneqt/doc/src/oneqt.qdoc
+++ b/examples/canvas3d/canvas3d/threejs/oneqt/doc/src/oneqt.qdoc
@@ -35,91 +35,113 @@
 ****************************************************************************/
 
 /*!
-    \example threejs/oneqt
+    \example canvas3d/threejs/oneqt
     \since QtCanvas3D 1.0
     \title One Qt Example
     \ingroup qtcanvas3d-examples
-    \brief Demonstrates combining Qt Quick and three.js based rendering.
+    \brief Demonstrates combining Qt Quick and three.js rendering.
 
-    One Qt example demonstrates how to implement an application that combines the use of three.js
-    library based Canvas3D rendering with Qt Quick 2D elements.
+    One Qt example demonstrates how to implement a simple QML 3D control that combines the use
+    of \c{three.js} library-based Canvas3D rendering with Qt Quick 2D elements. The example shows
+    a view with various benefits of using Qt with related images picked from
+    \l {http://qt.io} {http://qt.io}. The images are displayed on the side of a spinning 3D cube
+    that spins to show the correct image when the tabs at the top of the application are selected.
+    You can also use swipe gestures to spin the cube to navigate between the tabs. The 3D cube
+    control has been implemented as a simple QML type that internaly uses \c{three.js} library and
+    \l{Qt Canvas 3D}.
 
     \image oneqt-example.png
 
-    \section1 Qt Quick Implementation
+    \section1 Main QML File
 
-    In \l{threejs/oneqt/oneqt.qml}{oneqt.qml}, we build the 2D content as normally in Qt Quick.
-    Then we add a custom \c ImageCube element in to the scene behind the text elements. This custom
-    component handles the painting of the 3D cube in to the area reserved for the element.
+    In \l{canvas3d/threejs/oneqt/oneqt.qml}{oneqt.qml}, we build the 2D content as normal in QML.
+    Then we add a custom \c {ImageCube} type into the scene behind the text elements.
+    This custom type, implemented using \c{three.js} library, handles the painting of the 3D
+    cube.
 
-    \snippet threejs/oneqt/oneqt.qml 0
+    \snippet canvas3d/threejs/oneqt/oneqt.qml 0
     \dots
 
-    The custom component takes six images that it loads and places to the sides of the cube.
-    In addition the component has a state that defines which of these images is visible and
-    a \c backgroundColor property that is used when painting the 3D cube.
+    \note The \c {ImageCube} 3D UI component can be created and anchored just like any other
+    QML type.
 
-    \section2 The Custom 3D Qt Quick Element
+    \section1 The Custom 3D QML Control
 
-    In \l{threejs/oneqt/ImageCube.qml}{ImageCube.qml}, we define the cube rotation related
-    properties and properties that contain the image file URLs to be loaded for the cube sides.
+    The \l{canvas3d/threejs/oneqt/ImageCube.qml}{ImageCube.qml} takes six images that it loads
+    and places to the sides of the cube. In addition, the type has a state that defines which of
+    these images are visible and a \c {backgroundColor} property that is used when painting the 3D
+    cube. The \c {angleOffset} property can be used to adjust the cube's direction when displaying
+    the selected image. In this example the cube component sits on the right edge of the screen so
+    we twist it slightly to the left so that it appears to be facing the rest of the content.
+    This angle is also used by the 3D light so that the light always illuminates the selected face
+    of the cube.
 
-    \snippet threejs/oneqt/ImageCube.qml 0
+    \snippet canvas3d/threejs/oneqt/ImageCube.qml 0
     \dots
 
-    The custom component defines six states, one for each side of the cube along with the x, y and
-    z rotations that must be set to show that face of the cube.
+    The custom type defines six states, one for each side of the cube along with the x-, y-, and
+    z-rotations, that must be set to show the face of the cube corresponding to the state.
 
-    \snippet threejs/oneqt/ImageCube.qml 1
+    \snippet canvas3d/threejs/oneqt/ImageCube.qml 1
     \dots
 
-    We use Qt Quick transitions to animate between the angles to get smooth transitions between
-    different cube orientations.
+    We use \c {RotationAnimation} to animate the transition between angles. It enables us to get
+    smooth transitions between different cube orientations and to always rotate the cube along the
+    shortest possible angle distance.
 
-    \snippet threejs/oneqt/ImageCube.qml 2
+    \snippet canvas3d/threejs/oneqt/ImageCube.qml 2
     \dots
 
-    Finally we call the JavaScript code that uses three.js to do the rendering of the cube, calling
-    it on the initializeGL, paintGL and resizeGL signals.
+    We call the JavaScript code that uses \c{three.js} to do the rendering of the cube, calling
+    it on the \c{initializeGL}, \c{paintGL}, and \c{resizeGL} signals.
 
-    \snippet threejs/oneqt/ImageCube.qml 3
+    \snippet canvas3d/threejs/oneqt/ImageCube.qml 3
 
-    \section2 The three.js Code
+    \section1 The JavaScript Code
 
-    In \l{threejs/oneqt/imagecube.js}{imagecube.js}, we start by creating the camera and scene.
+    The JavaScript side of the implementation,
+    \l{canvas3d/threejs/oneqt/imagecube.js}{imagecube.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}.
 
-    \snippet threejs/oneqt/imagecube.js 0
+    In \l{canvas3d/threejs/oneqt/imagecube.js}{imagecube.js}, we start by creating the camera and
+    the scene that contains all the rest of the \c{three.js} objects.
+
+    \snippet canvas3d/threejs/oneqt/imagecube.js 0
     \dots
 
     Then we start the asynchronous loading of the textures and create a material array for the sides
     of the cube (note that the cube needs 12 materials as each side consists of two triangles).
 
-    \snippet threejs/oneqt/imagecube.js 1
+    \snippet canvas3d/threejs/oneqt/imagecube.js 1
     \dots
 
-    We then create the needed geometry as BoxGeometry binding the just created materials to the
-    faces of the cube. We then create a MeshFaceMaterial from the array of materials.
+    We then create the needed geometry as \c {BoxGeometry} binding the created materials to the
+    faces of the cube. We then create a \c {MeshFaceMaterial} from the array of materials.
 
-    \snippet threejs/oneqt/imagecube.js 2
+    \snippet canvas3d/threejs/oneqt/imagecube.js 2
 
-    Finally we create the cube mesh from the geometry and material, we position it and add it
+    Finally we create the cube mesh from the geometry and material, position it, and add it
     to the 3D scene.
 
-    \snippet threejs/oneqt/imagecube.js 3
+    \snippet canvas3d/threejs/oneqt/imagecube.js 3
 
-    Next we create and add some lights to the scene. AmbientLight defines the "surrounding light"
-    amount and the directional light is positioned so that it highlights the face of the cube facing
-    directly towards the camera.
+    Next we create and add some lights to the scene. \c{AmbientLight} defines the surrounding light
+    amount and the directional light is positioned so that it highlights the face of the cube that
+    is currently selected.
 
-    \snippet threejs/oneqt/imagecube.js 6
+    \snippet canvas3d/threejs/oneqt/imagecube.js 6
 
-    Final step in the initialization phase is create the Canvas3D renderer and set the
+    Final step in the initialization phase is to create the \c {Canvas3D} renderer and set the
     initial size and clear color (color of the background) to the renderer.
 
-    \snippet threejs/oneqt/imagecube.js 4
+    \snippet canvas3d/threejs/oneqt/imagecube.js 4
+
+    When we need to render the scene in response to the \c{paintGL} signal from Canvas3D, we just
+    copy the current rotation values from the QML side to the cube mesh in the \c{paintGL()} method.
 
-    When we need to render the scene in response to the paintGL signal from Canvas3D we just copy
-    the current rotation values from the Qt Quick component to the cube mesh in paintGL method.
+    \snippet canvas3d/threejs/oneqt/imagecube.js 5
 
-    \snippet threejs/oneqt/imagecube.js 5
+    For more information on how to use \c {three.js} the documentation is available here:
+    \l{http://threejs.org/docs/}{three.js/docs}
 */
diff --git a/examples/canvas3d/canvas3d/threejs/oneqt/imagecube.js b/examples/canvas3d/canvas3d/threejs/oneqt/imagecube.js
index 8d482f2..bc6a3b1 100644
--- a/examples/canvas3d/canvas3d/threejs/oneqt/imagecube.js
+++ b/examples/canvas3d/canvas3d/threejs/oneqt/imagecube.js
@@ -120,7 +120,7 @@ function setBackgroundColor(backgroundColor) {
         renderer.setClearColor(color);
 }
 
-function onResizeGL(canvas) {
+function resizeGL(canvas) {
     if (camera === undefined) return;
 
     camera.aspect = canvas.width / canvas.height;
diff --git a/examples/canvas3d/canvas3d/threejs/oneqt/oneqt.qml b/examples/canvas3d/canvas3d/threejs/oneqt/oneqt.qml
index 20e30f5..cc1a16c 100644
--- a/examples/canvas3d/canvas3d/threejs/oneqt/oneqt.qml
+++ b/examples/canvas3d/canvas3d/threejs/oneqt/oneqt.qml
@@ -62,7 +62,8 @@ Rectangle {
         height: 512 * (parent.height / 768)
         anchors.bottom: parent.bottom
         anchors.right: parent.right
-
+        //! [0]
+        angleOffset: -180 / 8.0
         backgroundColor: "#FCFCFC"
         state: "image6"
         image1: "qrc:/textures/devices.png"
@@ -154,7 +155,6 @@ Rectangle {
             }
         }
     }
-    //! [0]
 
     Rectangle {
         id: menuBar