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 <[email protected]>

Author: eskilblomfeldt

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.
+
 */

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
 

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.
 */

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.