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: default avatarEskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io>
parent c87692a4
......@@ -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.
*/
......@@ -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
......
......@@ -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.
*/
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment