Qt GUI Overview

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.

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 QWindow class represents a window in the underlying windowing system. It provides a number of virtual functions to handle events (QEvent) from the windowing system, such as touch-input, exposure, focus, key strokes, and geometry changes.

2D Graphics

The Qt GUI module contains classes for 2D graphics, imaging, fonts, and advanced typography.

A QWindow created with the surface type RasterSurface can be used in combination with QBackingStore and QPainter , Qt’s highly optimized 2D vector graphics API. QPainter supports drawing lines, polygons, vector paths, images, and text. For more information, see Paint System and Raster Window Example .

Qt can load and save images using the QImage and 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 QImageIOPlugin class. For more information, see Reading and Writing Image Files .

Typography in Qt is done with QTextDocument , which uses the 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 .

RHI Graphics

The Qt Rendering Hardware Interface is an abstraction for hardware accelerated graphics APIs, such as, OpenGL , OpenGL ES , Direct3D , Metal , and Vulkan .

As an alternative to using OpenGL or Vulkan directly to render to a QWindow , 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.

  • QRhi

  • QShader

  • QShaderDescription

  • QRhiCommandBuffer

  • QRhiResourceUpdateBatch

  • QRhiBuffer

  • QRhiRenderBuffer

  • QRhiTexture

  • QRhiSampler

  • QRhiTextureRenderTarget

  • QRhiShaderResourceBindings

  • QRhiGraphicsPipeline

  • QRhiComputePipeline

  • QRhiSwapChain

See the 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 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 QRhi for details.

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 QMatrix4x4 , QVector2D , QVector3D , QVector4D , and QQuaternion .

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 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:

  • QOpenGLBuffer

  • QOpenGLFramebufferObject

  • QOpenGLShaderProgram

  • QOpenGLTexture

  • QOpenGLDebugLogger

  • QOpenGLTimerQuery

  • QOpenGLVertexArrayObject

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 OpenGL Window Example.

A QWindow created with the OpenGLSurface can be used in combination with QPainter and QOpenGLPaintDevice to have OpenGL hardware-accelerated 2D graphics by sacrificing some of the visual quality.

Vulkan Integration

Qt GUI has support for the Vulkan API. Qt applications require the presence of the LunarG Vulkan SDK .

On Windows, the SDK sets the environment variable VULKAN_SDK, which will be detected by the 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:

  • QVulkanInstance

  • QVulkanFunctions

  • QVulkanDeviceFunctions

In addition, 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 VulkanSurface type directly.

For more information, see the Hello Vulkan Widget Example and the Hello Vulkan Triangle Example .

Drag and Drop

Qt GUI includes support for drag and drop. The Drag and Drop overview has more information.