1 files changed, 82 insertions, 0 deletions
diff --git a/tests/manual/planets-qml/doc/src/planets-qml.qdoc b/tests/manual/planets-qml/doc/src/planets-qml.qdoc
new file mode 100644
index 000000000..a515a9721
--- /dev/null
+++ b/tests/manual/planets-qml/doc/src/planets-qml.qdoc
@@ -0,0 +1,82 @@
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \example planets-qml
+    \title Qt 3D: Planets QML Example
+    \ingroup qt3d-examples-qml
+    \brief Demonstrates combining Qt 3D rendering and Qt Quick 2 elements.
+
+    \image planets-qml-example.jpg
+
+    \e Planets 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.
+
+    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/}.
+
+    \include examples-run.qdocinc
+
+    \section1 Qt Quick 2D Implementation
+
+    The Qt Quick Implementation in \c {planets-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 \c {planets-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 \c {planets-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 \c {planets-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 \c {planets-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 \c {planets-qml/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
+*/