diff options
author | Tomi Korpipää <tomi.korpipaa@theqtcompany.com> | 2015-06-11 12:47:36 +0300 |
---|---|---|
committer | Jani Heikkinen <jani.heikkinen@theqtcompany.com> | 2015-06-23 12:21:01 +0000 |
commit | dbe0950dfa2e6351af45a564e62b7a47ba6e7be2 (patch) | |
tree | 90c15dbce9e3d7c0d5b89097623f1f2bc590b451 /examples | |
parent | 520e2d32421f86958847b1bf9ee369606e0a83df (diff) |
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>
(cherry picked from commit fc662e5a4597b568561c3a19abb24151086a229d)
Diffstat (limited to 'examples')
-rw-r--r-- | examples/qt3d/planets-qml/PlanetsMain.qml | 6 | ||||
-rw-r--r-- | examples/qt3d/planets-qml/SolarSystem.qml | 8 | ||||
-rw-r--r-- | examples/qt3d/planets-qml/doc/images/planets-qml-example.jpg | bin | 0 -> 68712 bytes | |||
-rw-r--r-- | examples/qt3d/planets-qml/doc/src/planets-qml.qdoc | 71 | ||||
-rw-r--r-- | examples/qt3d/planets-qml/planets-qml.pro | 4 |
5 files changed, 87 insertions, 2 deletions
diff --git a/examples/qt3d/planets-qml/PlanetsMain.qml b/examples/qt3d/planets-qml/PlanetsMain.qml index 3c8ab417b..84705e696 100644 --- a/examples/qt3d/planets-qml/PlanetsMain.qml +++ b/examples/qt3d/planets-qml/PlanetsMain.qml @@ -50,6 +50,7 @@ Item { anchors.fill: parent color: "black" + //! [0] Scene3D { anchors.fill: parent anchors.margins: 10 @@ -58,6 +59,7 @@ Item { SolarSystem { id: solarsystem } } + //! [0] MouseArea { anchors.fill: parent @@ -71,6 +73,7 @@ Item { } } + //! [1] onFocusedPlanetChanged: { solarsystem.setFreeCamera(false) if (focusedPlanet == 100) { @@ -84,6 +87,7 @@ Item { solarsystem.changePlanetFocus(oldPlanet, focusedPlanet) oldPlanet = focusedPlanet } + //! [1] ListModel { id: planetModel @@ -285,7 +289,9 @@ Item { value: 1 minimumValue: 1 maximumValue: 2 + //! [2] onValueChanged: solarsystem.changeCameraDistance(value) + //! [2] } Text { y: distanceSlider.y + distanceSlider.height + width + 10 diff --git a/examples/qt3d/planets-qml/SolarSystem.qml b/examples/qt3d/planets-qml/SolarSystem.qml index 339643235..d34627735 100644 --- a/examples/qt3d/planets-qml/SolarSystem.qml +++ b/examples/qt3d/planets-qml/SolarSystem.qml @@ -156,6 +156,7 @@ Entity { light: light } + //! [2] QQ2.Component.onCompleted: { planetData = Planets.loadPlanetData() // Push in the correct order @@ -181,7 +182,9 @@ Entity { changeSpeed(0.2) setLookAtOffset(Planets.SUN) } + //! [2] + //! [0] QQ2.NumberAnimation { id: lookAtOffsetAnimation target: sceneRoot @@ -199,6 +202,7 @@ Entity { easing.type: Easing.InOutQuint duration: 2500 } + //! [0] QQ2.Behavior on cameraNear { QQ2.PropertyAnimation { @@ -408,6 +412,7 @@ Entity { cameraDistance = distance } + //! [3] function animate(focusedPlanet) { if (!ready || freeCamera) return @@ -418,6 +423,7 @@ Entity { updateCamera(focusedPlanet) } + //! [3] function updateCamera(focusedPlanet) { // Get the appropriate near plane position for the camera and animate it with QML animations @@ -602,6 +608,7 @@ Entity { // EARTH + //! [1] Planet { id: earth tilt: planetData[Planets.EARTH].tilt @@ -639,6 +646,7 @@ Entity { components: [ earth, materialEarth, transformEarth ] } + //! [1] // EARTH CLOUDS diff --git a/examples/qt3d/planets-qml/doc/images/planets-qml-example.jpg b/examples/qt3d/planets-qml/doc/images/planets-qml-example.jpg Binary files differnew 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 */ diff --git a/examples/qt3d/planets-qml/planets-qml.pro b/examples/qt3d/planets-qml/planets-qml.pro index f2ebf1f1b..7c27fc579 100644 --- a/examples/qt3d/planets-qml/planets-qml.pro +++ b/examples/qt3d/planets-qml/planets-qml.pro @@ -10,7 +10,9 @@ SOURCES += \ OTHER_FILES += \ *.qml \ planets.js \ - shaders\*.* + shaders/*.* \ + doc/src/*.* \ + doc/images/*.* RESOURCES += \ planets-qml.qrc \ |