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

1/****************************************************************************
2**
3** Copyright (C) 2016 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 qt3drender-protips.html
30 \title Qt 3D Render Pro Tips
31
32 \brief This sections tries to make you aware of various pitfalls inherent
33 to 3D rendering and ways to prevent them.
34
35 To render even the simplest shapes, Qt 3D needs to perform various
36 operations through several stages. If anything goes wrong at any of these
37 stages you may end up, in the best cases with something different than what
38 you expected, in the worst cases with a black screen.
39
40 \list
41 \li \l {Technique Selection}
42 \li \l {Order Matters}
43 \li \l {Blending}
44 \li \l {Useful Tools}
45 \endlist
46
47 \section2 Technique Selection
48
49 Qt 3D provides a technique selection mechanism allowing you to provide
50 shaders for various rendering APIs and versions of these APIs.
51
52 In order to avoid unnecessary waste of your time, you should make sure
53 that your technique's API filter data is correct for the platform you are
54 targeting.
55
56 \section2 Order Matters
57
58 The order of the draw calls performed by the renderer is not necessarily
59 the same as the order of the entities in the scene.
60
61 The renderer tries to optimize calls that are sent to the graphics API.
62 It orders draw calls based on the material/shader being used, the render
63 states that are defined for a given material, their depth, the parameters
64 shared in common between two materials, etc.
65
66 If your rendering depends on a specific draw order you should then have
67 a few options:
68
69 \list
70
71 \li Filtering with a Qt3DRender::QLayer component and
72 Qt3DRender::QLayerFilter in the FrameGraph
73
74 \li RenderPass or Technique filtering using Qt3DRender::QRenderPassFilter
75 or Qt3DRender::QTechniqueFilter in the FrameGraph
76
77 \endlist
78
79 \section2 Blending
80
81 Mastering blending with proper arguments and functions is an art in
82 itself. Therefore obtaining the proper visual result is often hit and
83 miss.
84
85 \l {http://www.andersriggelsen.dk/glblendfunc.php}{Anders Riggelsen's
86 online visualizer} may help you find out which arguments and functions
87 work for you.
88
89 \section3 Blending with Scene3D
90
91 When rendering a Qt 3D scene through a Qt Quick scene with the Scene3D
92 element you should be aware that you might have to adjust the blending
93 arguments of your render state to obtain a sensible rendering. This is
94 because of the way Qt 3D first renders a scene into an offscreen texture
95 which is then blended in with the rest of the Qt Quick scene.
96
97 Sensible values are often Qt3DRender::QBlendEquationArguments::Zero for
98 the source alpha and Qt3DRender::QBlendEquationArguments::One for the
99 destination alpha.
100
101 \section2 Useful Tools
102
103 Given the rather limited of troubleshooting given by Qt 3D in its first
104 versions it sometimes helps to have tools to capture OpenGL draw calls and
105 get more clues about what's happening
106
107 \list
108 \li \l {https://github.com/apitrace/apitrace}{apitrace}
109 \li \l {https://github.com/ValveSoftware/vogl}{vogl}
110 \endlist
111
112 These tools allow you to gather traces of all the OpenGL calls being made
113 by a Qt 3D application. Having a look at a generated trace file may help
114 you verify that draw calls are being made, textures correctly uploaded,
115 uniforms set with proper values, ...
116
117 There are plans for Qt 3D tooling in later releases.
118 */
119

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