Added documentation for the planets-qml example

Change-Id: I07734c6a30f49b05cd7815d3c3412cd867a09836
Task-number: QTBUG-46602
Reviewed-by: Mika Salmela <mika.salmela@theqtcompany.com>
Reviewed-by: Titta Heikkala <titta.heikkala@theqtcompany.com>
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@theqtcompany.com>

2 files changed, 70 insertions, 1 deletions

diff --git a/examples/qt3d/planets-qml/doc/images/planets-qml-example.jpg b/examples/qt3d/planets-qml/doc/images/planets-qml-example.jpg
new file mode 100644
index 000000000..d388d5ee4
--- /dev/null
+++ b/examples/qt3d/planets-qml/doc/images/planets-qml-example.jpg
diff --git a/examples/qt3d/planets-qml/doc/src/planets-qml.qdoc b/examples/qt3d/planets-qml/doc/src/planets-qml.qdoc
index d03e11325..d68a21b2d 100644
--- a/examples/qt3d/planets-qml/doc/src/planets-qml.qdoc
+++ b/examples/qt3d/planets-qml/doc/src/planets-qml.qdoc
@@ -38,7 +38,76 @@
     \example planets-qml
     \title Qt3D: Planets QML Example
     \ingroup qt3d-examples-qml
+    \brief Demonstrates combining Qt 3D rendering and Qt Quick 2 elements.
 
-    TODO
+    The Planets example demonstrates how to implement an application that combines the use of
+    Qt 3D rendering with Qt Quick 2D elements. The example shows the eight planets of our Solar
+    System with the Sun.
 
+    \image planets-qml-example.jpg
+
+    Planet texture maps are Copyright (c) by James Hastings-Trew
+    \l{http://planetpixelemporium.com/planets.html}{http://planetpixelemporium.com/planets.html}
+    used with permission.
+
+    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 2D Implementation
+
+    The Qt Quick Implementation \l{planets-qml/PlanetsMain.qml}{PlanetsMain.qml} of the
+    example renders the 3D content using the \c Scene3D type.
+
+    \snippet planets-qml/PlanetsMain.qml 0
+
+    The planet related information is stored into a \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 \l{planets-qml/PlanetsMain.qml}{PlanetsMain.qml}.
+
+    The selection buttons change the \c{focusedPlanet} property of the \c{mainview}. As the property
+    changes, the planet information is updated, and the camera is animated to the new position.
+
+    \snippet planets-qml/PlanetsMain.qml 1
+
+    The camera position and the camera look at point are updated based on values that are animated
+    in the \l{planets-qml/SolarSystem.qml}{SolarSystem.qml}, triggered from the
+    \c{changePlanetFocus()} function.
+
+    \snippet planets-qml/SolarSystem.qml 0
+
+    The sliders are used to adjust the rotation speed, the planet size, and the viewing distance.
+    When a slider value changes, a JavaScript function in \l{planets-qml/SolarSystem.qml}
+    {SolarSystem.qml} is called to adjust the given property. For example, changing the value of
+    the \e{Viewing Distance} slider calls the \c{changeCameraDistance()} method.
+
+    \snippet planets-qml/PlanetsMain.qml 2
+
+    \section1 Qt 3D Implementation
+
+    The main part of the implementation, including the movement and rotation maths for the planets,
+    is done in the \l{planets-qml/SolarSystem.qml}{SolarSystem.qml}.
+
+    First, a \c Camera, a \c{Light}, and a \c Configuration are added, followed by \c{Effect}s for
+    the planet \c{Material}s, and finally the planets themselves. For example, Earth is constructed
+    as follows:
+
+    \snippet planets-qml/SolarSystem.qml 1
+
+    Planet data, which is needed for the movement and rotation calculations, among other things, is
+    constructed with JavaScript in \l{planets-qml/planets.js}{planets.js} by calling
+    \c{loadPlanetData()} as the component completes. Other initializations, such as inserting the
+    planets into an array for easier handling, calculating the ring radii for Saturn and Uranus
+    rings, and setting the default scale, speed and camera offset, are done as well:
+
+    \snippet planets-qml/SolarSystem.qml 2
+
+    The scene is animated by calling the \c{animate()} function. That is also the place where the
+    time is advanced, and the new positions for all of the planets are calculated. The planets are
+    rotated in the \c{positionPlanet()} function based on their axial tilt and their sidereal
+    rotation period. Finally, the new camera position is calculated in the \c{updateCamera()}
+    function.
+
+    \snippet planets-qml/SolarSystem.qml 3
 */