Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qt6-changes.qdoc
Go to the documentation of this file.
1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \page qtquick3d-changes-qt6.html
6 \title Changes to Qt Quick 3D
7 \ingroup changes-qt-5-to-6
8 \brief Migrate Qt Quick 3D to Qt 6.
9
10 Qt 6 is a result of the conscious effort to make the framework more
11 efficient and easy to use.
12
13 We try to maintain binary and source compatibility for all the public
14 APIs in each release. But some changes were inevitable in an effort to
15 make Qt a better framework. Parts of the Qt Quick 3D API have been
16 substantially modified.
17
18 In this topic we summarize those changes in Qt Quick 3D, and provide
19 guidance to handle them.
20
21 \section1 RHI
22
23 From Qt 6.0 onwards, the default adaptation of Qt Quick always renders via a
24 graphics abstraction layer, the Qt Rendering Hardware Interface (RHI),
25 provided by the \l QtGui module. This means that, unlike Qt 5, no direct
26 OpenGL calls are made by the scene graph. Rather, it records resource and
27 draw commands by using the RHI APIs, which then translate the command stream
28 into OpenGL, Vulkan, Metal, or Direct 3D calls. Shader handling is also
29 unified by writing shader code once, compiling to
30 \l{https://www.khronos.org/spir/}{SPIR-V}, and then translating to the
31 language appropriate for the various graphics APIs.
32
33 For Qt Quick 3D the biggest change in Qt 6.0 is the migration to the common
34 Rendering Hardware Interface, which allows Qt Quick 3D to run on Direct3D,
35 Metal and Vulkan in addition to OpenGL and OpenGL ES.
36
37 Qt Quick and Qt Quick 3D are now fully unified in this regard. Any
38 configuration setting related to the RHI, for example, which graphics API to
39 choose to render with, are applicable to both.
40
41 See \l{Qt Quick 3D Graphics Requirements} for further details.
42
43 \section1 Other API changes
44
45 \section2 QML import version
46
47 Starting with Qt 6.0, the version number for QML import statements is the
48 same as the Qt version number. It is now also possible to import a module
49 without specifying a version: this will import the latest version of the module.
50
51
52 \section2 Lighting
53
54 \l {Light::brightness}{Light brightness} now represents an energy multiplier defaulting to 1.0, where
55 Qt 5 would use a percentage value defaulting to 100. In practice this
56 means that all \c brightness values should be divided by 100.
57
58 \c SceneEnvironment.probeBrightness is renamed to
59 \l {SceneEnvironment::probeExposure}{probeExposure} and is also redefined to
60 be a multiplier with a default value of 1.0. That is, all \c probeBrightness values
61 should be renamed to \c probeExposure and divided by 100.
62
63
64 \c AreaLight has been removed for performance reasons. In many cases it can be replaced
65 with \l SpotLight, which was added in Qt Quick 3D 5.15.
66
67 \section2 Custom Materials
68
69 The custom materials API has been completely reworked in 6.0. This means
70 any existing custom materials will have to be substantially rewritten.
71 See the \l CustomMaterial documentation for details of the new API.
72
73 \section2 Post-processing Effects
74
75 \l Effect has been enhanced to allow for shader code that is very close to
76 what \l CustomMaterial supports, following the same patterns when it comes
77 to structure and built-in keywords. This means that existing effects
78 involving custom shader code will need to be migrated before they can
79 function in Qt 6.0. See the \l Effect documentation for details.
80
81 \section2 Principled Material
82
83 The \l PrincipledMaterial QML type has been greatly improved in Qt Quick
84 6.0, and now more closely follows the principles of Physically Based
85 Rendering. Imported models should now render correctly without changing
86 properties of the materials. Existing materials will need to be changed to
87 undo any compensations for previous inaccuracies.
88
89 \table
90 \header
91 \li PrincipledMaterial in Qt 5
92 \li PrincipledMaterial in Qt 6
93 \row
94 \li \image quick3d-principled-qt5.png
95 {Teapot rendered with Qt 5 principled material}
96 \li \image quick3d-principled-qt6.png
97 {Teapot rendered with Qt 6 principled material}
98 \endtable
99
100 Some properties change their defaults:
101
102 \list
103 \li \l{PrincipledMaterial::metalness}{metalness} defaults to 0 instead of 1.
104 \li \l{PrincipledMaterial::specularAmount}{specularAmount} defaults to 0.5 instead of 0.
105 \endlist
106
107 \section2 Default Material
108
109 Some properties change their defaults:
110
111 \list
112 \li \l{DefaultMaterial::specularRoughness}{specularRoughness} defaults to 0 instead of 50.
113 \endlist
114
115 \section2 Predefined materials
116
117 There are no predefined materials included in QtQuick3D 6.0. Any
118 materials added in future releases will probably not be compatible with
119 the old ones. The Materials import does not exist. (The CustomMaterial
120 type is moved to the base QtQuick3D import.)
121
122 These are the material QML types that have been removed in Qt 6.0:
123
124 \list
125 \li AluminumAnodizedEmissiveMaterial
126 \li AluminumAnodizedMaterial
127 \li AluminumBrushedMaterial
128 \li AluminumEmissiveMaterial
129 \li AluminumMaterial
130 \li CopperMaterial
131 \li FrostedGlassMaterial
132 \li FrostedGlassSinglePassMaterial
133 \li GlassMaterial
134 \li GlassRefractiveMaterial
135 \li PaperArtisticMaterial
136 \li PaperOfficeMaterial
137 \li PlasticStructuredRedEmissiveMaterial
138 \li PlasticStructuredRedMaterial
139 \li SteelMilledConcentricMaterial
140 \endlist
141
142 \section2 Tessellation and displacement maps
143
144 Model tesselation mode is gone due to increased focus on supporting
145 embedded hardware. In addition, as a result, displacement map support has
146 been removed from materials. Similar effects can be achieved with a
147 \l {CustomMaterial}{custom material}.
148
149 \section2 Qt Quick \l{Item}s as children of 3D \l{Node}s
150
151 While syntactically identical, the way 2D child items are handled is quite
152 different internally. In Qt 6.0 there is no implicit render to texture
153 step. Rather, the 2D Qt Quick content is rendered in line, with the
154 appropriate perspective projection, in the same render pass, which provides
155 better performance, lower resource usage, and in some cases potentially
156 improved visual fidelity (with \l Text, for example). See \l{Qt Quick 3D
157 Scenes with 2D Content} for an overview.
158
159 If going through a texture is important for some reason (clipping, opacity),
160 make the 2D \l Item subtree a layer explicitly by setting \c{layer.enabled:
161 true}. This way the behavior is closer to what Qt 5.15 provided.
162
163 The 2D content is no longer centered at the parent Node's origin. Rather, it
164 is the top-level 2D Item's top-left corner that is placed to the 3D Node's
165 origin. Therefore, the top-level 2D Item will often want to specify an
166 anchor, such as, \c{anchors.centerIn: parent}, to get results matching Qt
167 5.15.
168
169*/