diff options
Diffstat (limited to 'src/gui/doc/src/qtgui-overview.qdoc')
| -rw-r--r-- | src/gui/doc/src/qtgui-overview.qdoc | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/src/gui/doc/src/qtgui-overview.qdoc b/src/gui/doc/src/qtgui-overview.qdoc new file mode 100644 index 0000000000..446479c9be --- /dev/null +++ b/src/gui/doc/src/qtgui-overview.qdoc @@ -0,0 +1,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. +*/ |