From 0ffdd1265b7a082a583b26a18f6cf84358edd68a Mon Sep 17 00:00:00 2001 From: Sean Harmer Date: Mon, 8 May 2017 14:41:37 +0100 Subject: Add documentation for Scene2D example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: I2d47b9224e4f26b342cd8a9bbe3c9c5a5e410dc1 Reviewed-by: Antti Määttä --- examples/qt3d/scene2d/doc/images/scene2d.png | Bin 0 -> 45997 bytes examples/qt3d/scene2d/doc/src/scene2d.qdoc | 134 +++++++++++++++++++++++++++ examples/qt3d/scene2d/scene2d.pro | 3 +- 3 files changed, 136 insertions(+), 1 deletion(-) create mode 100644 examples/qt3d/scene2d/doc/images/scene2d.png create mode 100644 examples/qt3d/scene2d/doc/src/scene2d.qdoc (limited to 'examples/qt3d') 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 Binary files /dev/null and b/examples/qt3d/scene2d/doc/images/scene2d.png differ 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/* -- cgit v1.2.3