C++ API changes

Qt 6 introduces some source incompatible changes. Here we list some important ones, but you can find more complete lists in <Qt 6 Install Dir>/qtbase/dist/changes-6.x.x.

The following sections list the API changes in each module and provide recommendations for handling those changes.


  • On Windows, ANGLE, a third-party OpenGL ES to Direct 3D translator, is no longer included in Qt. This means Qt::AA_UseOpenGLES and the environment variable QT_OPENGL=angle no longer have any effect. In dynamic OpenGL builds there is no automatic fallback to ANGLE in case OpenGL proper fails to initialize. For QWindow or QWidget based applications using OpenGL directly, for example via QOpenGLWidget, this means that OpenGL proper is the only option at run time. However, the alternative of using a pure software OpenGL implementation, such as Mesa llvmpipe that is shipped with the pre-built Qt packages, is still available. For Qt Quick and Qt Quick 3D applications, Qt 6 introduces support for Direct 3D 11, Vulkan, and Metal, in addition to OpenGL. On Windows the default choice is Direct 3D, therefore the removal of ANGLE is alleviated by having support for graphics APIs other than OpenGL as well.

Qt Quick

  • QQuickItem's geometryChanged() function was renamed to geometryChange().
  • QQuickWidget is functional only when the scenegraph is rendering with OpenGL. It will not be functional when using another graphics API, such as Vulkan or Metal. Applications relying on QQuickWidget should force the usage of OpenGL by calling QQuickWindow::setSceneGraphBackend(QSGRendererInterface::OpenGLRhi) in their main() function.

Changes to Qt Quick Scenegraph

  • QSGMaterialShader has a changed interface. Implementations should not rely on OpenGL anymore, and cannot assume that functions, such as the now-removed updateState(), are called with a QOpenGLContext current. In the new, data-oriented interface updateState() is replaced by updateUniformData(), updateSampledImage(), and updateGraphicsPipelineState(). Instead of GLSL shader code provided as strings, shaders are now expected to be preprocessed by the tools from the Qt Shader Tools module, such as the qsb command line tool, thus ensuring the shader assets are usable regardless of which graphics API (Vulkan, Metal, OpenGL, or Direct 3D) is used at run time.
  • QSGEngine has been removed. In the unlikely case of an application utilizing this class, it is recommended to port to using QQuickRenderControl instead.
  • QSGAbstractRenderer is no longer public. The usage of this class made sense only in combination with QSGEngine, and with that class being removed QSGAbstractRenderer has been moved back to private.
  • The QSGSimpleMaterial convenience class has been removed. Applications are expected to use the revised, OpenGL-independent QSGMaterial APIs instead.
  • The QQuickFramebufferObject class is available with an unchanged API, but is only functional when the scenegraph is rendering with OpenGL. It will not be functional when using another graphics API, such as Vulkan or Metal. Applications relying on QQuickFramebufferObject should force the usage of OpenGL by calling QQuickWindow::setSceneGraphBackend(QSGRendererInterface::OpenGLRhi) in their main() function.
  • Subclasses of QSGImageNode are now required to override new additional virtuals, such as setAnisotropyLevel() and anisotropyLevel().
  • Subclasses of QSGTexture will likely need to be redesigned. Some of the OpenGL-specific virtual functions, such as bind() or updateBindOptions(), are no longer present, while there are new virtuals that are mandatory to implement, such as comparisonKey().
  • The existing QQuickWindow::setRenderTarget() overloads, and the related getters, are removed and replaced by a new function taking a QQuickRenderTarget. Applications performing redirected rendering in combination with QQuickRenderControl are now expected to use this new function to specify the render target in a manner that is not tied to OpenGL.
  • QQuickRenderControl has a slightly changed API: grab() is now removed, use QQuickWindow::grabWindow() instead, where applicable. The initialize() function no longer takes a QOpenGLContext. Applications are now also required to call QQuickRenderControl::beginFrame() and QQuickRenderControl::endFrame() as appropriate. When multisampling is desired, the new function QQuickRenderControl::setSamples() must be called to indicate the sample count.
  • Applications wishing to perform Qt Quick rendering in combination with an existing native graphics device or context object must take the new QQuickWindow::setGraphicsDevice() function into use as QQuickRenderControl no longer provides the initialize(QOpenGLContext*) function.
  • The deprecated QQuickWindow::createTextureFromId() function has been removed. Use QQuickWindow::createTextureFromNativeObject() instead.
  • Setting QQuickPaintedItem and Context2D to Framebuffer mode has no effect. It will behave as if the mode was set to the default Image mode.
  • The QQuickWindow::openglContextCreated() signal has been removed.
  • The QQuickWindow functions setPersistentOpenGLContext and isPersistentOpenGLContext are renamed, and are now QQuickWindow::setPersistentGraphics() and QQuickWindow::isPersistentGraphics().
  • The QQuickWindow::openglContext() function has been removed. When the application has ensured the scene graph is using OpenGL for rendering, it can query the QOpenGLContext from QSGRendererInterface::getResource().
  • Applications that rely on the QQuickWindow::beforeRendering() or afterRendering() signals to issue their own set of OpenGL rendering commands should call QQuickWindow::beginExternalCommands() before, and QQuickWindow::endExternalCommands() after, the OpenGL calls. This ensures that state changes made by the application code does not lead to confusion with regards to the scene graph renderer's own cached state. Note however, that, just like in Qt 5, changing OpenGL 3.x or 4.x state that is not used by the Qt Quick renderer can still lead to unexpected issues, so therefore application are advised to reset any such OpenGL state to the default value before returning from the slots or lambdas connected to these signals.
  • Applications wishing to integrate their own set of Vulkan, Metal, or Direct3D rendering commands should be aware of new QQuickWindow signals in addition to QQuickWindow::beforeRendering() and afterRendering(). The existing Qt 5 pattern of connecting to just beforeRendering or afterRendering is often not sufficient anymore on its own, and will likely need to be complemented by connecting to additional signals, such as beforeRenderPassRecording() or afterRenderPassRecording().
  • resetOpenGLState() has been moved from QQuickWindow to QQuickOpenGLUtils. Note that it may not be necessary to call this function anymore from QQuickFramebufferObject:Renderer subclasses, because the basic OpenGL state is now reset both before and after the render() implementation.
  • setClearBeforeRendering() and clearBeforeRendering() have been removed from QQuickWindow. There is no option for skipping the color buffer clearing in Qt 6. Calling setClearBeforeRendering() was often necessary in Qt 5 in combination with underlays, to prevent Qt Quick from clearing the content rendered into the color buffer. In Qt 6, there is a more robust approach: connecting to the beforeRenderPassRecording() signal, that is emitted after clearing, but before rendering Qt Quick's content.
  • The QQuickWindow::setSceneGraphBackend() overload taking a QSGRendererInterface::GraphicsApi argument has been renamed to setGraphicsApi().

Changes to Qt OpenGL

  • Classes with the QGL prefix, such as QGLWidget have been removed.
  • The helper and convenience classes with the the QOpenGL prefix, including QPainter's OpenGL paint engine, have been moved from Qt Gui to the Qt OpenGL module. Applications using these classes should add QT += opengl to their project files.
  • QOpenGLWidget has been moved to its own openglwidgets module. Applications relying on QOpenGLWidget should add QT += openglwidgets to their project file.
  • QOpenGLContext::versionFunctions() is replaced by QOpenGLVersionFunctionsFactory::get().

© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.