From d8efe51303a08e93240766c620d2a7be3df0dd04 Mon Sep 17 00:00:00 2001 From: Eskil Abrahamsen Blomfeldt Date: Mon, 9 Nov 2020 08:31:40 +0100 Subject: Update Qt OpenGL docs and add porting docs This fleshes out the Qt OpenGL documentation, since this is now a first class citizen and no longer a compatibility module. It also adds Qt OpenGL-related info on porting to Qt 6. Fixes: QTBUG-88150 Change-Id: I85fcaa2eb5ae574416dcebcc0104bf97428ff42d Reviewed-by: Eskil Abrahamsen Blomfeldt --- src/gui/doc/src/qt6-changes.qdoc | 15 +++++++++ src/opengl/doc/qtopengl.qdocconf | 2 +- src/opengl/doc/src/qt6-changes.qdoc | 58 ++++++++++++++++++++++++++++++++-- src/opengl/doc/src/qtopengl-index.qdoc | 53 ++++++++++++++++++++++++------- 4 files changed, 114 insertions(+), 14 deletions(-) diff --git a/src/gui/doc/src/qt6-changes.qdoc b/src/gui/doc/src/qt6-changes.qdoc index c0c12e1502..72bf9c9bf1 100644 --- a/src/gui/doc/src/qt6-changes.qdoc +++ b/src/gui/doc/src/qt6-changes.qdoc @@ -102,4 +102,19 @@ \section2 QIntValidator and QDoubleValidator The \l{QIntValidator::}{setRange()} method is no longer marked as virtual. + + \section1 OpenGL classes + + With the introduction of Qt RHI as the rendering foundation in Qt, + most classes prefixed by \c QOpenGL have been moved into the \l{Qt OpenGL} + module. + + More details can be found in \l{Changes to Qt OpenGL}{the Qt OpenGL porting guide}. + + One notable exception is the class \l QOpenGLContext, which still resides in + Qt GUI. + + In addition, the class \l QOpenGLWidget has been moved to a new module, named + Qt OpenGL Widgets. + */ diff --git a/src/opengl/doc/qtopengl.qdocconf b/src/opengl/doc/qtopengl.qdocconf index 3d9b0ac3fb..4073bd140e 100644 --- a/src/opengl/doc/qtopengl.qdocconf +++ b/src/opengl/doc/qtopengl.qdocconf @@ -28,7 +28,7 @@ exampledirs += ../../../examples/opengl \ imagedirs += images \ ../../../examples/opengl/doc/images -depends += qtcore qtgui qtwidgets qtdoc qmake qtcmake +depends += qtcore qtgui qtwidgets qtdoc qmake qtcmake qtquick examplesinstallpath = opengl diff --git a/src/opengl/doc/src/qt6-changes.qdoc b/src/opengl/doc/src/qt6-changes.qdoc index d7e058bf65..a64f71d22e 100644 --- a/src/opengl/doc/src/qt6-changes.qdoc +++ b/src/opengl/doc/src/qt6-changes.qdoc @@ -38,9 +38,63 @@ APIs in each release. But some changes were inevitable in an effort to make Qt a better framework. - In this topic we summarize those changes in Qt OpenGL, and provide + In this topic we summarize those changes in \l{Qt OpenGL}, and provide guidance to handle them. - \section1 ADD STUFF HERE + \section1 Deprecated classes removed + The \l{Qt OpenGL} module was deprecated for the life time of Qt 5, and the + classes it contained have been removed in Qt 6. + + This refers specifically to the classes prefixed by \c{QGL}. + + \section1 QOpenGL classes migrated + + In Qt 5, a replacement set of OpenGL-support classes were added to Qt Gui. + This was in order to support OpenGL as the cross-platform graphics API that + served as foundation for graphics in Qt. + + In Qt 6, these have been migrated to the \l{Qt OpenGL} module. They are still + usable and fully supported for applications depending on OpenGL directly. + However, they are no longer considered foundational, since Qt has been extended + to support other graphics APIs in its foundation, such as Direct3D, Metal and + Vulkan. + + Existing application code will largely continue working, but should now + include \l{Qt OpenGL} in project files, as well as include the headers if + these were previously included indirectly through Qt Gui. + + \note A notable exception is \l QOpenGLContext, which still resides in + Qt Gui. + + \section1 QOpenGLWidgets + + Another exception is the \l QOpenGLWidget class. This has been moved to a new + module named \c{Qt OpenGL Widgets} and should be included from there. + + \section1 Selecting the OpenGL backend for RHI + + In addition to adjusting project files and including headers, the application + should also manually set the rendering backend to OpenGL in order to use + this functionality when working with Qt Quick. By default, Qt will use the most + appropriate graphics API on the target platform. See the + \l{Rendering via the Qt Rendering Hardware Interface}{RHI rendering documentation} + for more details. + + \section1 Removal of ANGLE + + On Windows, ANGLE, a third-party OpenGL ES to Direct 3D translator, is no + longer included in Qt 6. This means \c Qt::AA_UseOpenGLES and the + environment variable \c{QT_OPENGL=angle} no longer has 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 runtime. However, the use of 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, Qt 6 + defaults to Direct 3D, therefore the effect of the removal of ANGLE is + lessened by the addition of support to other graphics APIs. */ diff --git a/src/opengl/doc/src/qtopengl-index.qdoc b/src/opengl/doc/src/qtopengl-index.qdoc index d09d508fb3..f6d7ef81a6 100644 --- a/src/opengl/doc/src/qtopengl-index.qdoc +++ b/src/opengl/doc/src/qtopengl-index.qdoc @@ -31,19 +31,50 @@ \brief The Qt OpenGL module offers classes that make it easy to use OpenGL in Qt applications. + OpenGL is a low-level, cross-platform API for graphics. In Qt, + it can optionally be used as the foundation for rendering. + \section1 Introduction - The Qt OpenGL module makes it easy to use OpenGL in Qt applications. - It provides an OpenGL widget class that can be used just like any - other Qt widget, except that it opens an OpenGL display buffer where - you can use the OpenGL API to render the contents. - - The Qt OpenGL module is implemented as a platform-independent Qt/C++ - wrapper around the platform-dependent GLX (version 1.3 or later), - WGL, or AGL C APIs. Although the basic functionality provided is very - similar to Mark Kilgard's GLUT library, applications can use the - other \l{All Modules}{Qt modules} to implement the rest of the user - interface. + Qt has two main approaches to UI development: \l[QtQuick]{Qt Quick} and + \l{Qt Widgets}. They exist to support different types of user + interfaces, and build on separate graphics engines which have been + optimized for each of these types. + + It is possible to combine code written in the OpenGL graphics API + with both these user interface types in Qt. This can be useful + when the application has its own OpenGL-dependent code, or when it + is integrating with a third-party OpenGL-based renderer. + + The Qt OpenGL module contains convenience classes to make this type of + integration easier and faster. + + \section1 Qt OpenGL and Qt Widgets + + \l{Qt Widgets} is typically rendered by a highly optimized and accurate + software rasterizer, and the final content reproduced on screen using a + method appropriate for the platform where the application is running. + + But it is also possible to combine \l{Qt Widgets} with OpenGL. The main entry + point for this is the \l{QOpenGLWidget} class. This class can be used to + enable OpenGL rendering for a certain part of the widget tree, and the + classes in the Qt OpenGL module can be used to facilitate any application-side + OpenGL code. + + \section1 Qt OpenGL and Qt Quick + + \l[QtQuick]{Qt Quick} is optimized for hardware-accelerated rendering. By default, + it will be built on the low-level graphics API most appropriate for the + target platform. + + For instance, it will default to \c Direct3D on Windows, whereas on macOS, + it will default to \c Metal. But the it is also possible to manually + select OpenGL as the active graphics API on platforms where this is supported. + + For more details on enabling OpenGL with \l[QtQuick]{Qt Quick}, see + \l{Rendering via the Qt Rendering Hardware Interface}{scenegraph renderer documentation}. + + \section1 Overview The \l{Qt OpenGL C++ Classes} page gives an overview over the available classes in this module. -- cgit v1.2.3