1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtgui-overview.html
\title Qt GUI Overview
\brief An overview of the Qt GUI module.
The Qt GUI module provides classes for windowing system integration, event
handling, OpenGL and OpenGL ES integration, 2D graphics, basic imaging,
fonts, and text. These classes are used internally by Qt's user interface
technologies but can also be used directly, for example to write
applications using low-level OpenGL ES graphics APIs.
For application developers writing user interfaces, Qt provides higher level
APIs, like Qt Quick, that are much more suitable than the enablers found in
the Qt GUI module.
\section1 Application Windows
The most important classes in the Qt GUI module are QGuiApplication and
QWindow. A Qt application that wants to show content on screen has to use
these. QGuiApplication contains the main event loop, where all events from
the window system and other sources are processed and dispatched. It also
handles the application's initialization and finalization.
The \l QWindow class represents a window in the underlying windowing system.
It provides a number of virtual functions to handle events (\l {QEvent})
from the windowing system, such as touch-input, exposure, focus, key
strokes, and geometry changes.
\section1 2D Graphics
The Qt GUI module contains classes for 2D graphics, imaging, fonts,
and advanced typography.
A \l QWindow created with the surface type \l {QSurface::RasterSurface} can
be used in combination with \l {QBackingStore} and \l {QPainter}, Qt's
highly optimized 2D vector graphics API. QPainter supports drawing lines,
polygons, vector paths, images, and text. For more information, see \l{Paint
System} and \l {Raster Window Example}.
Qt can load and save images using the \l QImage and \l QPixmap classes. By
default, Qt supports the most common image formats including JPEG and PNG
among others. Users can add support for additional formats via the \l
QImageIOPlugin class. For more information, see \l {Reading and Writing
Image Files}.
Typography in Qt is done with \l QTextDocument, which uses the \l QPainter
API in combination with Qt's font classes, primarily QFont. Applications
that prefer more low-level APIs to text and font handling can use classes
like QRawFont and QGlyphRun.
\section1 RHI Graphics
The Qt Rendering Hardware Interface is an abstraction for hardware accelerated
graphics APIs, such as, \l{https://www.khronos.org/opengl/}{OpenGL},
\l{https://www.khronos.org/opengles/}{OpenGL ES},
\l{https://docs.microsoft.com/en-us/windows/desktop/direct3d}{Direct3D},
\l{https://developer.apple.com/metal/}{Metal}, and
\l{https://www.khronos.org/vulkan/}{Vulkan}.
As an alternative to using OpenGL or Vulkan directly to render to a
QWindow, \l QRhi and the related classes provide a portable, cross-platform
3D graphics and compute API complemented by a shader conditioning and
transpiling pipeline. This way applications can avoid directly depending on
a single, and, in some cases, vendor or platform-specific 3D API.
Below is a list of the main RHI-related classes. These are complemented by
a number of additional classes and structs.
\list
\li QRhi
\li QShader
\li QShaderDescription
\li QRhiCommandBuffer
\li QRhiResourceUpdateBatch
\li QRhiBuffer
\li QRhiRenderBuffer
\li QRhiTexture
\li QRhiSampler
\li QRhiTextureRenderTarget
\li QRhiShaderResourceBindings
\li QRhiGraphicsPipeline
\li QRhiComputePipeline
\li QRhiSwapChain
\endlist
See the \l{RHI Window Example} for an introductory example of creating a
portable, cross-platform application that performs accelerated 3D rendering
onto a QWindow using QRhi.
Working directly with QWindow is the most advanced and often the most
flexible way of rendering with the QRhi API. It is the most low-level
approach, however, and limited in the sense that Qt's UI technologies,
widgets and Qt Quick, are not utilized at all. In many cases applications
will rather want to integrate QRhi-based rendering into a widget or Qt
Quick-based user interface. QWidget-based applications may choose to embed
the window as a native child into the widget hierarchy via
QWidget::createWindowContainer(), but in many cases \l QRhiWidget will
offer a more convenient enabler to integrate QRhi-based rendering into a
widget UI. Qt Quick provides its own set of enablers for extending the
2D/3D scene with QRhi-based custom rendering.
\note The RHI family of APIs are currently offered with a limited
compatibility guarantee, as opposed to regular Qt public APIs. See \l QRhi
for details.
\section1 3D Matrix and Vector Math
The Qt GUI module also contains a few math classes to aid with the most
common mathematical operations related to 3D graphics. These classes
include \l {QMatrix4x4}, \l {QVector2D}, \l {QVector3D}, \l {QVector4D},
and \l {QQuaternion}.
\section1 OpenGL and OpenGL ES Integration
QWindow supports rendering using OpenGL and OpenGL ES, depending on what the
platform supports. OpenGL rendering is enabled by setting the QWindow's
surface type to QSurface::OpenGLSurface, choosing the format attributes with
QSurfaceFormat, and then creating a QOpenGLContext to manage the native
OpenGL context. In addition, Qt has QOpenGLPaintDevice, which enables the
use of OpenGL accelerated QPainter rendering, as well as convenience classes
that simplify the writing of OpenGL code and hides the complexities of
extension handling and the differences between OpenGL ES 2 and desktop
OpenGL. The convenience classes include QOpenGLFunctions that lets an
application use all the OpenGL ES 2 functions on desktop OpenGL without
having to manually resolve the OpenGL function pointers. This enables
cross-platform development of applications targeting mobile or embedded
devices, and provides classes that wrap native OpenGL functionality in a
simpler Qt API:
\list
\li QOpenGLBuffer
\li QOpenGLFramebufferObject
\li QOpenGLShaderProgram
\li QOpenGLTexture
\li QOpenGLDebugLogger
\li QOpenGLTimerQuery
\li QOpenGLVertexArrayObject
\endlist
Finally, to provide better support for the newer versions (3.0 and
higher) of OpenGL, a versioned function wrapper mechanism is also available:
The QOpenGLFunction_N_N family of classes expose all the functions in a
given OpenGL version and profile, allowing easy development of desktop
applications that rely on modern, desktop-only OpenGL features.
For more information, see the \l {OpenGL Window Example}.
A \l {QWindow} created with the \l {QSurface::OpenGLSurface} can be used in
combination with \l QPainter and \l QOpenGLPaintDevice to have OpenGL
hardware-accelerated 2D graphics by sacrificing some of the visual quality.
\section1 Vulkan Integration
Qt GUI has support for the \l {Vulkan} API. Qt applications require the
presence of the \l{LunarG Vulkan SDK}.
On Windows, the SDK sets the environment variable \c {VULKAN_SDK},
which will be detected by the \c {configure} script.
On Android, Vulkan headers were added in API level 24 of the NDK.
The main relevant classes for low-level Vulkan support are:
\list
\li QVulkanInstance
\li QVulkanFunctions
\li QVulkanDeviceFunctions
\endlist
In addition, \l QVulkanWindow provides a convenience subclass of QWindow
that makes it easier to get started with implementing Vulkan-based
rendering targeting a QWindow. Using this helper class is completely
optional; applications with more advanced Vulkan-based renderers may
instead want to use a QWindow with the \l {QSurface::VulkanSurface} type
directly.
For more information, see the \l{Hello Vulkan Widget Example}
and the \l {Hello Vulkan Triangle Example}.
\section1 Drag and Drop
Qt GUI includes support for drag and drop. The \l{Drag and Drop} overview
has more information.
*/
|