5 files changed, 145 insertions, 166 deletions
diff --git a/src/opengl/doc/src/dontdocument.qdoc b/src/opengl/doc/src/dontdocument.qdoc
index 72e997d933..b933f39982 100644
--- a/src/opengl/doc/src/dontdocument.qdoc
+++ b/src/opengl/doc/src/dontdocument.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2019 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2019 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
   \dontdocument (QOpenGLVersionStatus
diff --git a/src/opengl/doc/src/qt6-changes.qdoc b/src/opengl/doc/src/qt6-changes.qdoc
index 6ef8c69bbb..e227476868 100644
--- a/src/opengl/doc/src/qt6-changes.qdoc
+++ b/src/opengl/doc/src/qt6-changes.qdoc
@@ -1,35 +1,11 @@
-/****************************************************************************
-**
-** Copyright (C) 2020 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2020 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \page opengl-changes-qt6.html
-    \title Porting to Qt 6 - Qt OpenGL
-    \ingroup porting-guides-5-to-6
-    \brief Migrate Qt OpenGL to Qt 6.
+    \title Changes to Qt OpenGL
+    \ingroup changes-qt-5-to-6
+    \brief QOpenGL classes migrated, QOpenGLWidget class has been moved to Qt OpenGL Widgets.
 
     Qt 6 is a result of the conscious effort to make the framework more
     efficient and easy to use.
@@ -38,9 +14,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 The QOpenGLWidgets class
+
+    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-examples.qdoc b/src/opengl/doc/src/qtopengl-examples.qdoc
index 8770d6247e..3a98c16c70 100644
--- a/src/opengl/doc/src/qtopengl-examples.qdoc
+++ b/src/opengl/doc/src/qtopengl-examples.qdoc
@@ -1,33 +1,9 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \ingroup all-examples
-    \title OpenGL Examples from the Qt OpenGL module
+    \title Qt OpenGL Examples
     \brief Accessing OpenGL from Qt.
     \group examples-widgets-opengl
 
diff --git a/src/opengl/doc/src/qtopengl-index.qdoc b/src/opengl/doc/src/qtopengl-index.qdoc
index 53f1599c1b..7ea1635827 100644
--- a/src/opengl/doc/src/qtopengl-index.qdoc
+++ b/src/opengl/doc/src/qtopengl-index.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2020 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2020 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \page qtopengl-index.html
@@ -31,49 +7,78 @@
     \brief The Qt OpenGL module offers classes that make it easy to
     use OpenGL in Qt applications.
 
-    \warning This module should not be used anymore for new code. Please
-    use the corresponding OpenGL classes in \l{Qt GUI}.
 
-    \section1 Introduction
+    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 that have been
+    optimized for each of these types.
 
-    OpenGL is a standard API for rendering 3D graphics. OpenGL only
-    deals with 3D rendering and provides little or no support for GUI
-    programming issues. The user interface for an OpenGL application
-    must be created with another toolkit, such as Cocoa on the \macos
-    platform, Microsoft Foundation Classes (MFC) under Windows, or Qt
-    on both platforms.
+    It is possible to combine code written in the OpenGL graphics API
+    with both of 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 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 contains convenience classes to make this type of
+    integration easier and faster.
 
-    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 using the Qt
-    OpenGL module can take advantage of the whole Qt API for
-    non-OpenGL-specific GUI functionality.
+    \section1 Qt OpenGL and Qt Widgets
 
-    The \l{Qt OpenGL C++ Classes} page gives an overview over the available classes
-    in this module.
+    \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.
 
-    \include module-use.qdocinc using qt module
-    \snippet snippets/CMakeLists.txt cmake_use
+    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.
 
-    See also the \l[QtDoc]{Build with CMake} overview.
+    \section1 Qt OpenGL and Qt Quick
 
-    \include module-use.qdocinc building with qmake
-    \snippet snippets/snippets.pro qmake_use
+    \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 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 Using the Module
+
+    \include {module-use.qdocinc} {using the c++ api}
+
+    \section2 Building with CMake
+
+    \include {module-use.qdocinc} {building with cmake} {OpenGL}
+
+    \section2 Building with qmake
+
+    \include {module-use.qdocinc} {building_with_qmake} {opengl}
+
+    \section1 Examples
+
+    \list
+        \li \l {Qt OpenGL Examples}
+    \endlist
+
+    \section1 Reference
+
+    \list
+        \li \l {Qt OpenGL C++ Classes} {C++ Classes}
+    \endlist
 
     \section1 Module Evolution
-    \l{Porting to Qt 6 - Qt OpenGL} lists important changes in the module API
+    \l{Changes to Qt OpenGL} lists important changes in the module API
     and functionality that were done for the Qt 6 series of Qt.
 
     \section1 Licenses and Trademarks
 
-    The Qt OpenGL module is available under commercial licenses from \l{The Qt Company}.
-    In addition, it is available under free software licenses:
+    The Qt OpenGL module is available under commercial licenses from
+    \l{The Qt Company}. In addition, it is available under free software
+    licenses:
     The \l{GNU Lesser General Public License, version 3}, or
     the \l{GNU General Public License, version 2}.
     See \l{Qt Licensing} for further details.
diff --git a/src/opengl/doc/src/qtopengl-module.qdoc b/src/opengl/doc/src/qtopengl-module.qdoc
index 0ba78ed5dc..a2f344ba13 100644
--- a/src/opengl/doc/src/qtopengl-module.qdoc
+++ b/src/opengl/doc/src/qtopengl-module.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2020 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2020 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \module QtOpenGL
@@ -35,5 +11,21 @@
     \brief The Qt OpenGL module offers classes that make it easy to
     use OpenGL in Qt applications.
 
-    \warning This module should not be used anymore for new code.
+    The \l{Qt OpenGL} page contains information about how to use the module.
+
+    A separate \l{Qt OpenGL Widgets C++ Classes}{Qt OpenGL Widgets} library
+    provides a C++ widget class for rendering OpenGL graphics into widgets UIs.
+
+    \generatelist classesbymodule QtOpenGLWidgets
+*/
+
+/*
+    This "module" only exists so that classes in that separate library have
+    the correct build system documentation.
+*/
+/*!
+    \module QtOpenGLWidgets
+    \title Qt OpenGL Widgets C++ Classes
+    \qtcmakepackage OpenGLWidgets
+    \qtvariable openglwidgets
 */