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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
/****************************************************************************
**
** Copyright (C) 2015 Klaralvdalens Datakonsult AB (KDAB).
** Contact: http://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 http://www.qt.io/terms-conditions. For further
** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example wireframe
\title Qt 3D: Wireframe QML Example
\ingroup qt3d-examples-qml
\brief A Qt3D QML application that implements a single-pass wireframe
rendering method.
\image qt3d-wireframe-rendering.png
\e {Qt3D Wireframe Rendering} illustrates how to draw a single entity
(a trefoil knot) using a custom set of shaders to implement a single-pass
wireframe rendering method.
\include examples-run.qdocinc
\section1 Creating Entities
The renderer aspect looks for entities that have some geometry, a material,
and optionally a transformation. These are all specified in the form of
subclasses of QComponent that have been exported to the QML engine in the
form of \l Mesh, \l Material, and \l Transform. We use these components to
create a custom QML item in \e TrefoilKnot.qml.
We start off by importing the \c {Qt3D 2.0} module that provides the
\l Entity type and value type helpers, such as Qt.vector3d(). We also import
the \c {Qt3D.Renderer} module that provides the components and other types
picked up by the renderer aspect:
\quotefromfile wireframe/TrefoilKnot.qml
\skipto import Qt3D
\printuntil Render
To use components from other aspects, we would need to import the
corresponding QML module, too.
We then use an \l Entity type as the root element of the custom QML type
exposing some custom properties just as you would with any other type in
QML:
\printuntil Material
In addition to aggregating components, the \l Entity type can be used to
group child objects together. This is analogous to how the \l Item type is
used in Qt Quick 2.
\section1 Specifying Transformations
We instantiate a \l Transform component and a \l Mesh component. The
\l Transform component specifies how the renderer should transform the
geometry when it is drawn with the OpenGL pipeline. We combine an ordered
set of transformations into a single \l Transform component. This
information will be automatically available to our shaders through standard
named uniform variables:
\skipto Transform
\printuntil phiRotation
\printuntil }
\section1 Loading Dynamic Per-Vertex Data
The \l Mesh component is very simple. We use its source property to load in
a static set of geometry (such as vertex positions, normal vectors, and
texture coordinates) from a file in the Wavefront Obj format. This data was
exported from the Blender application.
\printuntil }
In addition to the \l Mesh element, Qt3D also enables dynamic generation of
per-vertex attribute data through C++ hooks that are called by the
task-based engine.
\section1 Aggregating Components
Simply instantiating components is not enough, however. In order for them to
imbue special behavior on an entity, the entity must aggregate the
components by means of its components property:
\quotefromfile wireframe/TrefoilKnot.qml
\skipto components
\printuntil ]
This allows components to be shared between multiple entities very easily.
In this example, we have components for the transform and mesh that are
contained within the TrefoilKnot custom type. The final component, of type
\l Material, is provided by a property of the TrefoilKnot custom type. We
will later customize the appearance of the entity.
\section1 Rendering from Cameras
We use the TrefoilKnot custom type in \e main.qml to draw the trefoil knot
on the screen.
We use the same import statements as in \e TrefoilKnot.qml, with the
addition of a namespaced import for the Qt Quick module that we will
need for animations:
\quotefromfile wireframe/main.qml
\skipto import Qt3D
\printuntil QtQuick
We use an \l Entity type as the root type simply to act as a parent for
its children. In this sense, the \l Entity type is much like the \l Item
type:
\printuntil id
The FrameGraph component uses the ForwardRenderer type to completely
configure the renderer without touching any C++ code:
\printuntil ]
The \l BasicCamera type is a trivial wrapper around the built-in \l Camera
type that represents a virtual camera. It has properties for such things as
the near and far planes, field of view, aspect ratio, projection type,
position, and orientation:
\printuntil }
The \l Configuration type provides a temporary workaround for having mouse
control of the camera while the proper implementation that uses aspects and
components is being completed:
\printuntil }
It is trivial to use multiple cameras and choose between them using the
framegraph for all or part of the scene rendering.
\section1 Mapping Materials
Qt3D has a robust and very flexible \l {Qt3D Overview#Materials}{material
system} that allows multiple levels of customization. We use the
WireframeMaterial custom type to wrap the \l Material type:
\printuntil diffuse
We then instantiate the TrefoilKnot type and set the material on it:
\skipto TrefoilKnot
\printuntil }
The Qt3D engine in conjunction with the renderer aspect now has enough
information to finally render our mesh using the material we specified.
\section1 Using Animation Elements
We use the animation elements provided by Qt Quick 2 to animate the
properties of the TrefoilKnot and WireframeMaterial types. The properties of
the components of a type are updated by using the QML property binding
mechanism:
\quotefromfile wireframe/main.qml
\skipto SequentialAnimation
\printuntil PauseAnimation
\printuntil }
The property updates are noticed by the \l{Qt3D::}{QNode} base class
and automatically sent through to the corresponding objects in the renderer
aspect. The renderer then takes care of translating the property updates
to new values for uniform variables in the GLSL shader programs.
Run the example to view the trefoil knot with the width of the wireframe
lines pulsing. All the heavy lifting is being done by the GPU. The CPU only
has to run the property animations and to translate the scenegraph and
framegraph into raw OpenGL calls.
It is also possible to animate on the GPU via a custom shader program and
material.
*/
|
