summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io>2020-11-09 08:31:40 +0100
committerEskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io>2020-11-13 10:08:49 +0100
commitd8efe51303a08e93240766c620d2a7be3df0dd04 (patch)
tree3269d08ad5cf9a8c223644f01cb9d21bde89875c
parentc87692a48b053b830ca192a2580f7d27723f16df (diff)
Update Qt OpenGL docs and add porting docsv6.0.0-beta5
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 <eskil.abrahamsen-blomfeldt@qt.io>
-rw-r--r--src/gui/doc/src/qt6-changes.qdoc15
-rw-r--r--src/opengl/doc/qtopengl.qdocconf2
-rw-r--r--src/opengl/doc/src/qt6-changes.qdoc58
-rw-r--r--src/opengl/doc/src/qtopengl-index.qdoc53
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.