Warning: That file was not part of the compilation database. It may have many parsing errors.

1/****************************************************************************
2**
3** Copyright (C) 2015 Klaralvdalens Datakonsult AB (KDAB).
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file. Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \page qt3d-overview.html
30 \title Qt 3D Overview
31
32 \brief Qt 3D provides C++ and QML APIs to incorporate 3D content into Qt
33 applications.
34
35 Qt 3D provides a fully configurable renderer that enables developers to
36 quickly implement any rendering pipeline that they need. Further, Qt 3D
37 provides a generic framework for near-realtime simulations beyond rendering.
38
39 Qt 3D is cleanly separated into a core and any number of \e aspects that can
40 implement any functionality they wish. The aspects interact with
41 \e components and \e entities to provide some slice of functionality.
42 Examples of aspects include physics, audio, collision, artificial
43 intelligence (AI), and path finding.
44
45 \section1 Basic 3D Features
46
47 Qt 3D is a 3D framework that enables the drawing of 3D shapes and moving
48 them around, as well as moving the camera. It supports the following basic
49 features:
50
51 \list
52 \li 2D and 3D \l {Qt3DRender}{rendering} for C++ and Qt Quick applications
53 \li \l{Qt3DRender::QMesh}{Meshes} and \l {Qt 3D Render Geometry}{Geometry}
54 \li \l {Materials}
55 \li \l {Shaders}
56 \li \l {Shadow Mapping}{Shadow mapping}
57 \li \l {Qt3DExtras::QMetalRoughMaterial::ambientOcclusion}{Ambient occlusion}
58 \li High dynamic range
59 \li \l {Deferred Renderer}{Deferred rendering}
60 \li Multitexturing
61 \li \l {Instanced Rendering}{Instanced rendering}
62 \li \l {Uniform Buffer Objects}
63 \li \l {Qt 3D Render Pro Tips}{Pro Tips}
64 \endlist
65
66 \section2 Materials
67
68 Qt 3D has a robust and very flexible material system that allows multiple
69 levels of customization. It caters for different rendering approaches on
70 different platforms or OpenGL versions, enables multiple rendering passes
71 with different state sets, provides mechanisms for overriding of parameters
72 at different levels, and allows easy switching of shaders. All this from C++
73 or using QML property bindings.
74
75 The properties of a \l Material type can easily be mapped through to uniform
76 variables in a GLSL shader program that is itself specified in the
77 referenced effect property.
78
79 For examples of using materials, see the following examples:
80 \list
81 \li \l {Qt 3D: Simple Custom Material QML Example}
82 \li \l {Qt 3D: Advanced Custom Material QML Example}
83 \li \l {Qt 3D: PBR Materials QML Example}
84 \endlist
85
86 \section2 Shaders
87
88 Qt 3D supports all of the OpenGL programmable rendering pipeline stages:
89 vertex, tessellation control, tessellation evaluation, geometry, and
90 fragment shaders. Compute shaders are planned for a future release.
91
92 For examples of using shaders, see the \l {Simple Shader Example},
93 \l {Qt 3D: Shadow Map QML Example}, \l{Qt 3D: Wireframe QML Example}, and
94 \l {Qt 3D: Wave QML Example}.
95
96 \section2 Shadow Mapping
97
98 Shadows are not directly supported by OpenGL, but there are countless
99 techniques that can be employed to generate them. Shadow mapping is simple
100 to use for generating good-looking shadows, while having a very small
101 performance cost.
102
103 Shadow mapping is typically implemented using a two pass rendering. In the
104 first pass, the shadow information is generated. In the second pass, the
105 scene is generated using a particular rendering technique, while at the
106 same time using the information gathered in the first pass to draw the
107 shadows.
108
109 The idea behind shadow mapping is that only the closest fragments to the
110 light are lit. Fragments \e behind other fragments are occluded, and
111 therefore in shadow.
112
113 Therefore, in the first pass, the scene is drawn from the point of view of
114 the light. The information that is stored is simply the distance of the
115 closest fragment in this \e {light space}. In OpenGL terms, this corresponds
116 to having a Framebuffer Object, or FBO, with a depth texture attached to it.
117 In fact, the \e {distance from the eye} is the definition of the depth,
118 and the default depth testing done by OpenGL will actually store only the
119 depth for the closest fragment.
120
121 A color texture attachment is not even needed, because there is no need to
122 shade fragments, only to calculate their depth.
123
124 The following image displays a scene with a self-shadowed plane and trefoil
125 knot:
126
127 \image shadowmapping-qt3d.png
128
129 The following image shows an exaggerated shadow map texture of the scene:
130
131 \image shadowmapping-depth.png
132
133 The image indicates the depth stored when rendering the scene from the light
134 point of view. Darker colors represent a shallow depth (that is, closer to
135 the camera). In this scene, the light is placed somewhere above the objects
136 in the scene, on the right side with respect to the main camera (compare
137 this with the first screenshot). This matches with the fact that the toy
138 plane is closer to the camera than the other objects.
139
140 Once the shadow map has been generated, the second rendering pass is done.
141 In this second pass, rendering is done using the normal scene's camera. Any
142 effect can be used here, such as Phong shading. It is important that the
143 shadow map algorithm is applied in the fragment shader. That is, the
144 fragment that is closest to the light is drawn lit, whereas the other
145 fragments are drawn in shadow.
146
147 The shadow map generated in the first pass provides the necessary
148 information about the distance of fragments to light. It then suffices to
149 remap the fragment in light space, thereby calculating its depth from the
150 light point of view, as well as where its coordinates are on the shadow map
151 texture. The shadow map texture can then be sampled at the given coordinates
152 and the fragment's depth can be compared with the result of the sampling. If
153 the fragment is further away, then it is in shadow; otherwise it is lit.
154
155 For example code, see the \l {Qt 3D: Shadow Map QML Example}.
156
157 \section2 Instanced Rendering
158
159 \e Instancing is a way of getting the GPU to draw many copies (instances) of
160 a base object that varies in some way for each copy. Often, in position,
161 orientation, color, material properties, scale, and so on. Qt 3D provides an
162 API similar to the Qt Quick \l Repeater element. In this case, the delegate
163 is the base object and the model provides the per-instance data. So whereas
164 an entity with a \l Mesh component attached eventually gets transformed into
165 a call to glDrawElements, an entity with a instanced component will be
166 translated into a call to glDrawElementsInstanced.
167
168 Instanced rendering is planned for a future release.
169
170 \section2 Uniform Buffer Objects
171
172 A Uniform Buffer Object (UBO) can be bound to OpenGL shader programs to make
173 large amounts of data readily available. Typical use cases for UBOs are for
174 sets of material or lighting parameters.
175
176 \section2 Useful Tips
177
178 Some very useful programming tips for 3D rendering can be found on this
179 page: \l {Qt 3D Render Pro Tips}.
180
181 \section1 Configurable Renderer
182
183 To combine support for both C++ and QML APIs with having a fully
184 configurable renderer, the concept of a \e framegraph was introduced. While
185 a \e scenegraph is a data-driven description of \e what to render, a \l
186 {Qt 3D Render Framegraph}{framegraph} is a data-driven description of \e
187 how to render it.
188
189 A framegraph enables developers to choose between a simple forward renderer,
190 including a z-fill pass, or using a deferred renderer for example. It also
191 gives them control over when to render any transparent objects, and so on.
192 Since this is all configured purely from data, it is very easy to modify even
193 dynamically at runtime without touching any C++ code. It is possible to
194 extend Qt 3D by creating your own framegraphs that implement custom
195 rendering algorithms.
196
197 \section1 3D Extensions
198
199 Beyond the essentials of displaying 3D content on the screen, Qt 3D is
200 extensible and flexible enough to act as a host for the following types of
201 extensions related to the 3D objects:
202
203 \list
204 \li Physics simulation
205 \li Collision detection
206 \li 3D positional audio
207 \li Rigid body, skeletal, and morph target animation
208 \li Path finding and other AI
209 \li Picking
210 \li Particles
211 \li Object spawning
212 \endlist
213
214 \section1 Performance
215
216 Qt 3D is designed to perform well and scale up with the number of available
217 CPU cores, because modern hardware improves performance by increasing the
218 numbers of cores rather than base clock speed. Using multiple cores works
219 well, because many tasks are independent of each other. For example, the
220 operations performed by a path finding module do not overlap strongly with
221 the tasks performed by a renderer, except maybe when rendering debug
222 information or statistics.
223
224 \section1 Qt 3D Architecture
225
226 The main use cases of Qt 3D are simulating objects in near-realtime and
227 rendering the state of those objects onto the screen. The Space Invaders
228 example contains the following objects:
229
230 \image Space-invaders.jpg
231
232 \list
233 \li The player's ground cannon
234 \li The ground
235 \li The defensive blocks
236 \li The enemy space invader ships
237 \li The enemy boss flying saucer
238 \li The bullets shot by the enemies and the player
239 \endlist
240
241 In a traditional C++ design, these types of object would typically be
242 implemented as classes arranged in some kind of inheritance tree. Various
243 branches in the inheritance tree might add additional functionality to the
244 root class for features such as:
245
246 \list
247 \li Accepts user input
248 \li Plays a sound
249 \li Is animated
250 \li Collides with other objects
251 \li Is drawn on screen
252 \endlist
253
254 The types in the Space Invaders example can be classified against these
255 features. However, designing an elegant inheritance tree for even such a
256 simple example is not easy.
257
258 This approach and other variations on inheritance present a number of
259 problems:
260
261 \list
262 \li Deep and wide inheritance hierarchies are difficult to understand,
263 maintain and extend.
264 \li The inheritance taxonomy is set in stone at compile time.
265 \li Each level in the class inheritance tree can only classify upon a
266 single criteria or axis.
267 \li Shared functionality tends to \e {bubble up} the class hierarchy
268 over time.
269 \li It is impossible to predict what the developers will want to do.
270 \endlist
271
272 Extending deep and wide inheritance trees usually requires understanding,
273 and agreeing with, the taxonomy used by the original author. Therefore,
274 Qt 3D places focus on aggregation instead of inheritance as the means of
275 imparting functionality onto an instance of an object. Specifically, Qt 3D
276 implements an Entity Component System (ECS).
277
278 \section2 Using an ECS
279
280 In an ECS, an entity represents a simulated object, but by itself it is devoid
281 of any specific behavior or characteristics. Additional behavior can be
282 grafted onto an entity by having the entity aggregate one or more
283 components. Each component is a vertical slice of behavior of an object
284 type.
285
286 In the Space Invaders example, the ground is an entity with an attached
287 component that tells the system that the entity needs rendering and what
288 kind of rendering it needs. An enemy space invader ship is another entity
289 with attached components that cause the ship to be rendered, but also enable
290 it to emit sounds, be collided with, be animated, and be controlled by a
291 simple AI.
292
293 The player's ground cannon entity has mostly similar components to the enemy
294 space invader ship, except that it does not have the AI component. In its
295 place, the cannon has an input component to enable the player to move it
296 around and to fire bullets.
297
298 \section2 ECS Backend
299
300 \image ecs-2.png
301
302 The backend of Qt 3D implements the \e system part of the ECS paradigm in
303 the form of \e aspects. An aspect implements the particular vertical slice
304 of the functionality provided to entities by a combination of one or more
305 of their aggregated components.
306
307 For example, the renderer aspect looks for entities that have mesh,
308 material, and optionally transformation components. If the renderer aspect
309 finds such an entity, it knows how to take that data and draw something nice
310 from it. If an entity does not have those components, the renderer aspect
311 ignores it.
312
313 Qt 3D builds custom entities by aggregating components that provide
314 additional capabilities. The Qt 3D engine uses aspects to process and
315 update entities with specific components.
316
317 For example, a physics aspect looks for entities that have some kind of
318 collision volume component and another component that specifies other
319 properties needed by such simulations like mass, coefficient of friction,
320 and so on. An entity that emits sound has a component that specifies it is
321 a sound emitter, as well as specifying when and which sounds to play.
322
323 Because ECS uses aggregation rather than inheritance, it is possible to
324 dynamically change how an object behaves at runtime simply by adding or
325 removing components.
326
327 For example, to enable a player to suddenly run through walls after a
328 power-up, that entity's collision volume component can be removed
329 temporarily, until the power-up times out. There is no need to create a
330 special one-off subclass for \c PlayerWhoRunsThroughWalls.
331
332 \section2 Qt 3D ECS Implementation
333
334 Qt 3D implements ECS as a simple class hierarchy. The Qt 3D base class is
335 Qt3DCore::QNode, which is a subclass of QObject. Qt3DCore::QNode adds to QObject the ability to
336 automatically communicate property changes to aspects and an ID that is
337 unique throughout an application. The aspects exist in additional threads
338 and Qt3DCore::QNode simplifies the data transfer between the user-facing objects and
339 the aspects.
340
341 Typically, subclasses of Qt3DCore::QNode provide additional supporting data that is
342 referenced by components. For example, the QShaderProgram class specifies
343 the GLSL code to be used when rendering a set of entities.
344
345 \image ecs-1.png
346
347 Components in Qt 3D are implemented by subclassing Qt3DCore::QComponent and adding the
348 data necessary for the corresponding aspect to do its work. For example, the
349 mesh component is used by the renderer aspect to retrieve the per-vertex
350 data that should be sent down the OpenGL pipeline.
351
352 Finally, Qt3DCore::QEntity is simply an object that can aggregate zero or more
353 Qt3DCore::QComponent instances.
354
355 \section1 Extending Qt 3D
356
357 Adding functionality to Qt 3D, either as part of Qt or specific to your
358 own applications to benefit from the multi-threaded back-end consists of the
359 following tasks:
360
361 \list
362 \li Identify and implement any necessary components and supporting data.
363 \li Register the components with the QML engine (only if you use the QML
364 API).
365 \li Subclass QAbstractAspect and implement the subsystem functionality.
366 \endlist
367
368 \section1 Qt 3D Task-Based Engine
369
370 In Qt 3D, aspects are asked in each frame for a set of \e tasks to execute
371 along with the \e dependencies between them. The tasks are distributed
372 across all the configured cores by a scheduler to improve performance.
373
374 \section1 Qt 3D's Aspects
375
376 By default, Qt 3D provides the Qt3DRender and Qt3DInput aspects. The
377 components and other supporting classes provided by these aspects are
378 discussed in the documentation for those modules.
379
380 Additional aspects providing more capabilities will be added in future
381 versions of Qt 3D.
382*/
383

Warning: That file was not part of the compilation database. It may have many parsing errors.