Qt 6.x
The Qt SDK
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 QRhiTextureRenderTarget
83 \li QRhiShaderResourceBindings
84 \li QRhiGraphicsPipeline
85 \li QRhiComputePipeline
86 \li QRhiSwapChain
87 \endlist
88
89 See the \l{RHI Window Example} for an introductory example of creating a
90 portable, cross-platform application that performs accelerated 3D rendering
91 onto a QWindow using QRhi.
92
93 \note The RHI family of APIs are currently offered with a limited
94 compatibility guarantee, as opposed to regular Qt public APIs. See \l QRhi
95 for details.
96
97 \section1 3D Matrix and Vector Math
98
99 The Qt GUI module also contains a few math classes to aid with the most
100 common mathematical operations related to 3D graphics. These classes
101 include \l {QMatrix4x4}, \l {QVector2D}, \l {QVector3D}, \l {QVector4D},
102 and \l {QQuaternion}.
103
104 \section1 OpenGL and OpenGL ES Integration
105
106 QWindow supports rendering using OpenGL and OpenGL ES, depending on what the
107 platform supports. OpenGL rendering is enabled by setting the QWindow's
108 surface type to QSurface::OpenGLSurface, choosing the format attributes with
109 QSurfaceFormat, and then creating a QOpenGLContext to manage the native
110 OpenGL context. In addition, Qt has QOpenGLPaintDevice, which enables the
111 use of OpenGL accelerated QPainter rendering, as well as convenience classes
112 that simplify the writing of OpenGL code and hides the complexities of
113 extension handling and the differences between OpenGL ES 2 and desktop
114 OpenGL. The convenience classes include QOpenGLFunctions that lets an
115 application use all the OpenGL ES 2 functions on desktop OpenGL without
116 having to manually resolve the OpenGL function pointers. This enables
117 cross-platform development of applications targeting mobile or embedded
118 devices, and provides classes that wrap native OpenGL functionality in a
119 simpler Qt API:
120
121 \list
122 \li QOpenGLBuffer
123 \li QOpenGLFramebufferObject
124 \li QOpenGLShaderProgram
125 \li QOpenGLTexture
126 \li QOpenGLDebugLogger
127 \li QOpenGLTimerQuery
128 \li QOpenGLVertexArrayObject
129 \endlist
130
131 Finally, to provide better support for the newer versions (3.0 and
132 higher) of OpenGL, a versioned function wrapper mechanism is also available:
133 The QOpenGLFunction_N_N family of classes expose all the functions in a
134 given OpenGL version and profile, allowing easy development of desktop
135 applications that rely on modern, desktop-only OpenGL features.
136
137 For more information, see the \l {OpenGL Window Example}.
138
139 A \l {QWindow} created with the \l {QSurface::OpenGLSurface} can be used in
140 combination with \l QPainter and \l QOpenGLPaintDevice to have OpenGL
141 hardware-accelerated 2D graphics by sacrificing some of the visual quality.
142
143 \section1 Vulkan Integration
144
145 Qt GUI has support for the \l {Vulkan} API. Qt applications require the
146 presence of the \l{LunarG Vulkan SDK}.
147
148 On Windows, the SDK sets the environment variable \c {VULKAN_SDK},
149 which will be detected by the \c {configure} script.
150
151 On Android, Vulkan headers were added in API level 24 of the NDK.
152
153 The main relevant classes for low-level Vulkan support are:
154
155 \list
156 \li QVulkanInstance
157 \li QVulkanFunctions
158 \li QVulkanDeviceFunctions
159 \endlist
160
161 In addition, \l QVulkanWindow provides a convenience subclass of QWindow
162 that makes it easier to get started with implementing Vulkan-based
163 rendering targeting a QWindow. Using this helper class is completely
164 optional; applications with more advanced Vulkan-based renderers may
165 instead want to use a QWindow with the \l {QSurface::VulkanSurface} type
166 directly.
167
168 For more information, see the \l{Hello Vulkan Widget Example}
169 and the \l {Hello Vulkan Triangle Example}.
170
171 \section1 Drag and Drop
172
173 Qt GUI includes support for drag and drop. The \l{Drag and Drop} overview
174 has more information.
175*/