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