1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page quick-changes-qt6.html
6 \title Changes to Qt Quick
7 \ingroup changes-qt-5-to-6
8 \brief Migrate Qt Quick to Qt 6.
10 Qt 6 is a result of the conscious effort to make the framework more
11 efficient and easy to use.
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.
17 In this topic we summarize those changes in Qt Quick, and provide
18 guidance to handle them.
21 \section1 Changes to Qt Quick QML Types
23 \section2 Changed Type of font.weight
25 The type of \c font.weight has been changed to \c int. The pre-defined
26 weight classes still exist, but it is now possible to use arbitrary integers
27 to select fonts which do not match any of these weight classes. This ensures
28 parity with the C++ API, where it has always been possible to express the
29 font weight as an arbitrary integer.
31 Most code will be unaffected by this change, except in the case where an
32 implicit conversion from a string to enum value was used.
38 This code will no longer parse correctly and has to be replaced by its
39 equivalent enum value, as demonstrated below.
42 font.weight: Font.Bold
45 \section2 FontLoader.name Is Now a Read-Only Property
47 In Qt 5, the \c name property of FontLoader was writable and would override
48 the source property of the item when set. This caused some confusion as to
49 its purpose and could cause undeterministic behavior if there was a race
50 condition between the setters for the conflicting properties.
52 This means that code such as the following will no longer work.
61 font.family: fontLoader.name
66 Instead, use a custom property to store font family names.
69 property string fontName: "Helvetica"
77 \section2 The OpenGLInfo QML Type Is Removed
79 In Qt 5.8, OpenGLInfo was deprecated and is removed for Qt 6.
80 Please use GraphicsInfo instead.
82 \section1 ShaderEffect No Longer Supports Inline GLSL Shader Strings
84 Just like with \l{QSGMaterial}{custom materials}, the effects are no longer
85 specified in form of GLSL shader strings. Rather, shaders are expected to be
86 preprocessed by the tools from the \l{Qt Shader Tools} module, such as the
87 \c qsb command line tool, thus ensuring the shader assets are usable
88 regardless of which graphics API (Vulkan, Metal, OpenGL, or Direct 3D) is
89 used at runtime. ShaderEffect items are expected to reference the resulting
92 \section2 ShaderEffect Source Properties Are Now URLs
94 The ShaderEffect properties \l{ShaderEffect::vertexShader}{vertexShader} and
95 \l{ShaderEffect::fragmentShader}{fragmentShader} both have a type of QUrl
96 now, instead of QByteArray. Their behavior is therefore identical to other
97 similar properties, such as \l{Image::source}{Image.source}. Existing code
98 that refers to files via the \c file or \c qrc scheme will continue to work
99 as-is. In addition, this change allows referring to files with a path
100 relative to the component's (the .qml file's) location. Specifying the
101 \c{file:} scheme is therefore optional now.
104 \section1 Changes to Qt Quick C++ APIs
106 \section2 Changes to QQuickItem
108 QQuickItem's geometryChanged() function was renamed to
109 \l{QQuickItem::}{geometryChange()}.
111 \section2 Changes to QQuickWidget
113 QQuickWidget is functional only when the scenegraph is rendering with
114 OpenGL. It will not be functional when using another graphics API, such as
115 Vulkan or Metal. Applications relying on QQuickWidget should force the usage
117 \c{QQuickWindow::setGraphicsApi(QSGRendererInterface::OpenGL)} in their
120 \section2 Changes to QQuick* APIs
124 \li Applications wishing to integrate their own set of Vulkan, Metal, or
125 Direct3D rendering commands should be aware of new QQuickWindow signals in
126 addition to QQuickWindow::beforeRendering() and afterRendering(). The
127 existing Qt 5 pattern of connecting to just beforeRendering or
128 afterRendering is often not sufficient anymore on its own, and will likely
129 need to be complemented by connecting to additional signals, such as
130 \l{QQuickWindow::beforeRenderPassRecording()}{beforeRenderPassRecording()}
131 or \l{QQuickWindow::afterRenderPassRecording()}{afterRenderPassRecording()}.
133 \li Applications that rely on the QQuickWindow::beforeRendering() or
134 afterRendering() signals to issue their own set of OpenGL rendering commands
135 should call QQuickWindow::beginExternalCommands() before, and
136 QQuickWindow::endExternalCommands() after, the OpenGL calls. This ensures
137 that state changes made by the application code does not lead to confusion
138 with regards to the scene graph renderer's own cached state. Note however,
139 that, just like in Qt 5, changing OpenGL 3.x or 4.x state that is not used
140 by the Qt Quick renderer can still lead to unexpected issues, so therefore
141 application are advised to reset any such OpenGL state to the default value
142 before returning from the slots or lambdas connected to these signals.
144 \li The existing QQuickWindow::setRenderTarget() overloads, and the
145 related getters, are removed and replaced by a new function taking a
146 QQuickRenderTarget. Applications performing redirected rendering in
147 combination with QQuickRenderControl are now expected to use this new
148 function to specify the render target in a manner that is not tied to
151 \li The QQuickWindow::setSceneGraphBackend() overload taking a
152 QSGRendererInterface::GraphicsApi argument has been renamed to
153 \l{QQuickWindow::setGraphicsApi()}{setGraphicsApi()}.
155 \li The QQuickWindow functions setPersistentOpenGLContext and
156 isPersistentOpenGLContext are renamed, and are now
157 QQuickWindow::setPersistentGraphics() and
158 QQuickWindow::isPersistentGraphics().
160 \li setClearBeforeRendering() and clearBeforeRendering() have been removed
161 from QQuickWindow. There is no option for skipping the color buffer clearing
162 in Qt 6. Calling setClearBeforeRendering() was often necessary in Qt 5 in
163 combination with underlays, to prevent Qt Quick from clearing the content
164 rendered into the color buffer. In Qt 6, there is a more robust approach:
165 connecting to the \c beforeRenderPassRecording() signal,
166 that is emitted after clearing, but before rendering Qt Quick's content.
169 \li The QQuickWindow::openglContext() function has been removed. When the
170 application has ensured the scene graph is using OpenGL for rendering, it
171 can query the QOpenGLContext from QSGRendererInterface::getResource().
173 \li The QQuickWindow::openglContextCreated() signal has been removed.
175 \li The deprecated QQuickWindow::createTextureFromId() function has been
176 removed. Instead, use the fromNative() function from
177 QPlatformInterface::QSGOpenGLTexture, QPlatformInterface::QSGVulkanTexture,
178 QPlatformInterface::QSGD3D11Texture, or QPlatformInterface::QSGMetalTexture.
180 \li The QQuickFramebufferObject class is available with an unchanged API,
181 but is only functional when the scenegraph is rendering with OpenGL. It will
182 not be functional when using another graphics API, such as Vulkan or Metal.
183 Applications relying on QQuickFramebufferObject should force the usage of
185 \c{QQuickWindow::setGraphicsApi(QSGRendererInterface::OpenGL)} in their
188 \li QQuickRenderControl has a slightly changed API: grab() is now
189 removed, use QQuickWindow::grabWindow() instead, where applicable. The
190 initialize() function no longer takes a QOpenGLContext. Applications are
191 now also required to call QQuickRenderControl::beginFrame() and
192 QQuickRenderControl::endFrame() as appropriate. When multisampling is
193 desired, the new function QQuickRenderControl::setSamples() must be
194 called to indicate the sample count.
196 \li Applications wishing to perform Qt Quick rendering in combination
197 with an existing native graphics device or context object must take the
198 new QQuickWindow::setGraphicsDevice() function into use as
199 QQuickRenderControl no longer provides the
200 \c{initialize(QOpenGLContext*)} function.
202 \li Setting QQuickPaintedItem and Context2D to \c Framebuffer mode has
203 no effect. It will behave as if the mode was set to the default Image
206 \li The environment variable \c{QSG_NO_DEPTH_BUFFER} is still supported in
207 Qt 6.0, but its usage is recommended to be replaced by calling
208 \l{QQuickGraphicsConfiguration::setDepthBufferFor2D()}{setDepthBufferFor2D()}
209 on a QQuickGraphicsConfiguration that is then associated with the
214 \section1 Changes to QSG* APIs
218 \li QSGMaterialShader has a changed interface. Implementations should
219 not rely on OpenGL anymore, and cannot assume that functions, such as
220 the now-removed updateState(), are called with a QOpenGLContext
221 current. In the new, data-oriented interface updateState() is replaced
222 by \l{QSGMaterialShader::updateUniformData()}{updateUniformData()},
223 \l{QSGMaterialShader::updateSampledImage()}{updateSampledImage()}, and
224 \l{QSGMaterialShader::updateGraphicsPipelineState()}{updateGraphicsPipelineState()}.
225 Instead of GLSL shader code provided as strings, shaders are now
226 expected to be preprocessed by the tools from the Qt Shader Tools
227 module, such as the \c qsb command line tool, thus ensuring the shader
228 assets are usable regardless of which graphics API (Vulkan, Metal,
229 OpenGL, or Direct 3D) is used at run time.
231 \li QSGEngine has been removed. In the unlikely case of an application
232 utilizing this class, it is recommended to port to using
233 QQuickRenderControl instead.
235 \li QSGAbstractRenderer is no longer public. The usage of this class made
236 sense only in combination with QSGEngine, and with that class being
237 removed QSGAbstractRenderer has been moved back to private.
239 \li The QSGSimpleMaterial convenience class has been
240 removed. Applications are expected to use the revised, OpenGL-independent
241 QSGMaterial APIs instead.
243 \li To access the underlying native texture object for a QSGTexture,
244 textureId() is no longer available. Instead, use
245 QSGTexture::platformInterface() with QPlatformInterface::QSGOpenGLTexture,
246 QPlatformInterface::QSGVulkanTexture, QPlatformInterface::QSGD3D11Texture,
247 or QPlatformInterface::QSGMetalTexture.
249 \li Subclasses of QSGImageNode are now required to override new
250 additional virtuals, such as setAnisotropyLevel() and anisotropyLevel().
252 \li Subclasses of QSGTexture will likely need to be redesigned. Some of
253 the OpenGL-specific virtual functions, such as bind() or
254 updateBindOptions(), are no longer present, while there are new virtuals
255 that are mandatory to implement, such as
256 \l{QSGTexture::comparisonKey()}{comparisonKey()}.
260 \section1 Changes to OpenGL Use in Qt Quick
262 While it will present no breaks for many applications, application
263 developers should be aware that, OpenGL is not always the default choice
264 anymore for Qt Quick rendering in Qt 6. Unless the \c software backend is
265 used, a Qt Quick application could use OpenGL, Vulkan, Metal, or Direct3D 11
266 at runtime. When no explicit request is made, either via the
267 \c QSG_RHI_BACKEND environment variable or the
268 QQuickWindow::setSceneGraphBackend() function, a platform-specific
269 default is chosen by Qt Quick.
271 For more information, visit the \l{Qt Quick Scene Graph} and the
272 \l{Qt Quick Scene Graph Default Renderer} pages.
1.10.0