Add documentation for Scene2D example

Change-Id: I2d47b9224e4f26b342cd8a9bbe3c9c5a5e410dc1
Reviewed-by: Antti Määttä <antti.maatta@qt.io>

3 files changed, 136 insertions, 1 deletions

diff --git a/examples/qt3d/scene2d/doc/images/scene2d.png b/examples/qt3d/scene2d/doc/images/scene2d.png
new file mode 100644
index 000000000..789148537
--- /dev/null
+++ b/examples/qt3d/scene2d/doc/images/scene2d.png
diff --git a/examples/qt3d/scene2d/doc/src/scene2d.qdoc b/examples/qt3d/scene2d/doc/src/scene2d.qdoc
new file mode 100644
index 000000000..66cf7dd21
--- /dev/null
+++ b/examples/qt3d/scene2d/doc/src/scene2d.qdoc
@@ -0,0 +1,134 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 Klaralvdalens Datakonsult AB (KDAB).
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example scene2d
+    \title Qt 3D: Scene2D QML Example
+    \ingroup qt3d-examples-qml
+    \brief A QML application that demonstrates using Qt Quick 2 within a Qt 3D scene
+
+    \image scene2d.png
+
+    \e {Scene2D} demonstrates rendering a Qt Quick 2 scene into a texture and utilising
+    the texture within a Qt 3D application including handling mouse events. The 3D scene
+    contains a single active camera and renders a 3D Qt logo along with some controls
+    declared with Qt Quick Controls.
+
+    \include examples-run.qdocinc
+
+    \section1 Setting up the 3D Scene
+
+    We set up the 3D scene in an Entity that acts as the root of the object tree. The
+    virtual camera is specified in \e main.qml:
+
+    \quotefromfile scene2d/main.qml
+    \skipto Camera {
+    \printuntil }
+
+    The RenderSettings specify the rendering algorithm used and also enable triangle
+    based picking which is needed to properly handle mouse events when projecting a
+    Qt Quick scene onto 3D geometry:
+
+    \skipto RenderSettings {
+    \printuntil }
+    \printuntil }
+
+    The 3D Qt logo that will be controlled by the controls in the Qt Quick scene is
+    declared with:
+
+    \skipto Entity {
+    \printuntil }
+    \printuntil }
+    \printuntil }
+    \printuntil }
+
+    It simply consists of a Mesh component to load the geometry; a PhongMaterial component
+    to give it a surface appearance, and a Transform component to specify its postion,
+    orientation, and scale. The properties of these components are bound to properties
+    on the logoControls element which we will discuss next.
+
+    \section1 Rendering Qt Quick into a Texture
+
+    We begin by declaring the Entity that will become our control panel. It consists of
+    a PlaneMesh onto which we will place the texture containing a rendering of the Qt Quick
+    scene. In this case we are using a simple flat plane for the geometry, but we could use
+    any valid 3D geometry as long as it has texture coordinates. The texture coordinates
+    are used for projecting the texture onto the 3D surface, and also for calculating the
+    coordinates of mouse events to be passed to the originating Qt Quick scene.
+
+    \skipto Entity {
+    \printto }
+    \printto }
+
+    Note that we enable the mirrored property on the PlaneMesh to ensure that the texture
+    coordinate vertical axis is aligned with the usual Qt window coordinate system.
+
+    We also include an ObjectPicker component so that we can interact with the controls
+    using the mouse:
+
+    \skipto ObjectPicker {
+    \printto }
+    \printto }
+
+    For this example we have chosen to use an interaction mechanism whereby you must
+    explicitly middle-click the controls to enable them.
+
+    To apply the texture to the mesh, we make use of the built in TextureMaterial:
+
+    \skipto TextureMaterial
+    \printto }
+
+    The final remaining piece is how to render the above texture from a Qt Quick scene.
+    This is done with the Scene2D element:
+
+    \skipto Scene2D
+    \printto }
+    \printto }
+    \printto }
+
+    where we have made use of the Texture2D and RenderTargetOutput types to create a
+    destination texture and attach it as the output of the Scene2D renderer.
+
+    Next, we tell the Scene2D object which entities may feed it input events and we
+    initially disable the handling of mouse events:
+
+    \printto mouseEnabled: false
+
+    Finally, we can specify the Qt Quick scene to render by adding a custom QML component
+    as a child to the Scene2D element:
+
+    \skipto LogoControls
+    \printto }
+
+    When the mouseEnabled property is set to true by the ObjectPicker, then the Scene2D
+    object will process mouse events from any ObjectPickers attached to the listed entities.
+    In this way, you have the freedom to use the texture generated by the Scene2D object in
+    any way you wish, even on more than one Entity.
+
+    The \e LogoControls.qml file is just a regular Qt Quick 2 scene which in this case
+    also makes use of the Qt Quick Controls components.
+*/
diff --git a/examples/qt3d/scene2d/scene2d.pro b/examples/qt3d/scene2d/scene2d.pro
index 26ed34ce7..0eb2bf550 100644
--- a/examples/qt3d/scene2d/scene2d.pro
+++ b/examples/qt3d/scene2d/scene2d.pro
@@ -11,4 +11,5 @@ RESOURCES += scene2d.qrc
 OTHER_FILES += \
     main.qml \
     Logo.qml \
-    LogoControls.qml
+    LogoControls.qml \
+    doc/src/*