1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qt 3D Studio.
**
** $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$
**
****************************************************************************/
/*!
\page qt3dstudio-opengl-runtime-gettingstarted.html
\title Getting Started
The \RUNTIME provides C++ and QML APIs for integrating Qt 3D
Studio scenes into Qt applications, as well as the viewer application that
is used in combination with the Qt 3D Studio application during the design
phase.
Below is an example scene in the Qt 3D Studio application.
\image intro-editor.png
During the design phase, the standalone viewer is typically launched from
the editor several times to check and verify the presentation in the
runtime.
\image intro-viewer.png
Once the design is done and the \c{.uia}, \c{.uip}, and other asset files
are available, these can be loaded, rendered, and manipulated in Qt
applications. This is done via the APIs provided in the \c studio3d
module and the \c QtStudio3D.OpenGL QML plugin.
Below is the same scene loaded into a simple Qt Quick application
(the \l{Qt 3D Studio Runtime: Simple QML Example}{simpleqml
example}) that composes the 3D content with the other Qt Quick
items, for example the ones provided by \l{Qt Quick Controls
2}. In addition to displaying the presentation, the application
can also control many aspects of it (slides, timeline, object
properties) and can react on certain conditions, such as when a 3D
object is clicked on (picked) by mouse or touch input.
\image intro-app.png
\section1 Rendering Scenes
APIs are provided for the following Qt UI technologies:
\list
\li Qt Quick: here applications import QtStudio3D.OpenGL \QtVer which
provides the \l [QML] Studio3D QML type, a Qt Quick item that can be
added to Qt Quick scenes. Under the hood this is similar to adding a
\l [QML] Scene3D (when working directly with the lower level Qt 3D
framework) or a custom item based on \l QQuickFramebufferObject into
the scene.
\li QWindow or offscreen render targets (OpenGL texture): Q3DSSurfaceViewer
can be used both to render to an on-screen QWindow, as well as off-screen
into an OpenGL texture. The latter allows reading back and saving the
frames, to generate pre-rendered video sequences for example.
\endlist
\section1 Manipulating Scenes
Rendering Qt 3D Studio scenes is only part of the story since many scenes
are not static and will not just display all their contents as they were
done by designers in the Qt 3D Studio application. Rather, properties of
scene objects (for example, the rotation property of a 3D model, or the
diffuse color of the material associated with such a model) may need to be
changed dynamically, at run time. The timeline or the current slide may
also need to be adjusted based on the user's actions or other application
state.
Above functionality is exposed via the following types:
\table
\header
\li C++ Class
\li QML Type
\row
\li Q3DSPresentation
\li \l [QML] Presentation
\row
\li Q3DSElement
\li \l Element
\row
\li Q3DSSceneElement
\li \l [QML] SceneElement
\row
\li Q3DSDataInput
\li \l [QML] DataInput
\endtable
Advanced scene manipulation (for example, dynamically spawning and
removing objects in a 3D scene) will be introduced in future versions.
*/
|
