- Qt 6.9
- Product information
- Supported Platforms
- Qt for Windows
- Qt for Windows - Graphics Acceleration
- Qt 6.9.2 Reference Documentation

Building from source ◦ Deployment

# Qt for Windows - Graphics Acceleration

For Qt Quick to work, a graphics driver that supports Direct 3D 11, Direct3D 12, Vulkan 1.0, or OpenGL 2.1 or higher is required. As of Qt 6, the default for Qt Quick on Windows is Direct3D 11. This is different from Qt 5, where the default was OpenGL, either directly, or through ANGLE, an OpenGL to Direct3D translator. ANGLE is no longer shipped with Qt in Qt 6.

To force using Direct3D's software rasterizer (WARP), set the environment variable `QSG_RHI_PREFER_SOFTWARE_RENDERER` to `1`. In some cases Qt Quick will perform such a fallback automatically, in order to allow running Qt applications without additional configuration. This happens when the drivers do not provide a sufficient level of D3D11 functionality, and occurs typically in virtual machines that do not have proper GPU acceleration and passthrough implemented. When in doubt what graphics device is being used, and when troubleshooting or reporting problems to Qt, run the application with the environment variable `QSG_INFO=1` set and inspect the debug output. Running the `qtdiag` tool can also provide useful information since it enumerates all available 3D APIs.

To request using Vulkan, OpenGL, or Direct 3D 12, set the environment variable `QSG_RHI_BACKEND` to `vulkan` or `opengl` or `d3d12`, or use the equivalent C++ API in `main()`. Note that some of these 3D APIs may require the appropriate drivers to be installed.

While not the default for Qt Quick, OpenGL is still commonly used in many Qt applications, for example in QWidget-based applications building on QOpenGLWindow or QOpenGLWidget. The following sections cover some OpenGL specifics of a Qt build.

## Dynamically Loading OpenGL

Qt supports choosing and loading the OpenGL implementation at runtime. This mode is the default, and can be explicitly requested by passing `-opengl dynamic` to the configure script.

     configure -opengl dynamic

This configuration is the most flexible because no dependencies or assumptions are hardcoded about the OpenGL implementation during build time. It allows robust application deployment. When a given environment fails to provide a proper OpenGL 2.0 implementation, it will fall back automatically to load an alternative to `opengl32.dll`, the default name of which is `opengl32sw.dll`. The pre-built Qt packages ship a build of Mesa llvmpipe, a software rasterizer implementation of OpenGL, under that name.

When configured with `-opengl dynamic`, neither Qt nor the applications built using `qmake` or `CMake` will link to opengl32.lib. Instead, the library is chosen and loaded at runtime. By default, Qt will determine whether the system's opengl32.dll provides OpenGL 2 functions. If these are present, opengl32.dll is used, otherwise it attempts to load `opengl32sw.dll`. See below for details.

The loading mechanism can be configured through the `QT_OPENGL` environment variable and the following application attributes:

- `Qt::AA_UseDesktopOpenGL` Equivalent to setting `QT_OPENGL` to `desktop`.
- `Qt::AA_UseOpenGLES` Has no effect in Qt 6.
- `Qt::AA_UseSoftwareOpenGL` Equivalent to setting `QT_OPENGL` to `software`.

When a certain configuration is requested explicitly, no checks are done at application startup, that is, the system-provided opengl32.dll will not be examined.

The dynamic loading has a significant impact on applications that contain native OpenGL calls: they may fail to link since opengl32.lib is not automatically specified to the linker. Instead, applications are expected to use the OpenGL functions via the QOpenGLFunctions class. Thus the direct dependency on the OpenGL library is removed and all calls will be routed during runtime to the implementation chosen by Qt. Alternatively, applications are free to make direct OpenGL function calls if they add opengl32.lib to their .pro project files: LIBS += opengl32.lib (Visual Studio) or LIBS += -lopengl32 (Mingw-w64). The result is, from the application's perspective, equivalent to the `-opengl desktop` build configuration of Qt.

`Qt::AA_UseSoftwareOpenGL` is special in the sense that it will try to load an OpenGL implementation with a non-standard name. The default name is `opengl32sw.dll`. This allows shipping a software-only OpenGL implementation, for example a build of Mesa with llvmpipe, under this name. If necessary, the filename can be overridden by setting the `QT_OPENGL_DLL` environment variable.

It is possible to provide a JSON-format configuration file specifying which OpenGL implementation to use depending on the graphics card and driver version. The location is given by the environment variable `QT_OPENGL_BUGLIST`. Relative paths are resolved using `QLibraryInfo::SettingsPath` or `QStandardPaths::ConfigLocation`. The file utilizes the format of the driver bug list used in The Chromium Projects. It consists of a list of entries each of which specifies a set of conditions and a list of feature keywords. Typically, device id and vendor id are used to match a specific graphics card. They can be found in the output of the `qtdiag6` or `dxdiag` tool.

The following feature keywords are relevant for choosing the OpenGL implementation:

Note: In Qt 6, the legacy ANGLE related keywords (`disable_angle`, `disable_d3d11`, `disable_d3d9`) are accepted, but have no effect.

- `disable_desktopgl` - Disables OpenGL. This ensures that Qt does not attempt to use regular OpenGL (opengl32.dll), and that it starts with ANGLE right away. This is useful to prevent bad OpenGL drivers from crashing the application.
- `disable_rotation` - Forces the application to run in landscape orientation always. It has no effect when using a software OpenGL implementation. This is intended for drivers that have issues with rotation.
- `disable_program_cache` - Disable storing shader program binaries on disk.

A sample file looks like:

     {
     "entries": [
     {
       "id": 1,
       "description": "Disable D3D11 on older nVidia drivers",
       "os": {
         "type": "win"
       },
       "vendor_id": "0x10de",
       "device_id": ["0x0DE9"],
       "driver_version": {
         "op": "<=",
         "value": "8.17.12.6973"
       },
       "features": [
         "disable_d3d11"
       ]
     },
     ...

When `QT_OPENGL_BUGLIST` is not specified, a built-in list will be used. This typically includes some older, less-capable graphics cards with `disable_desktopgl` set, in order to prevent Qt from using their unstable desktop OpenGL implementations and instead fall back to attempting to load the software-based alternative library right away.

In practice the most common combinations are expected to be the following:

- `disable_desktopgl` - In case the system provides OpenGL 2.0 or newer, but the driver is known to be unstable and prone to crash.
- `disable_desktopgl`, disable_angle - When no accelerated path is desired. This ensures that the only option Qt tries is the software rasterizer (opengl32sw.dll). Can be useful in virtual machines and applications that are deployed on a wide range of old systems.

The supported keys for matching a given card or driver are the following. Note that some of these are specific to Qt.

- `os.type` - Operating system: `win`, `linux`, `macosx`, `android`
- `os.version` - Kernel version
- `os.release` - Specifies a list of operating system releases on Windows: `xp`, `vista`, `7`, `8`, `8.1`, `10`.
- `vendor_id` - Vendor from the adapter identifier
- `device_id` - List of PCI device IDs.
- `driver_version` - Driver version from the adapter identifier
- `driver_description` - Matches when the value is a substring of the driver description from the adapter identifier
- `gl_vendor` - Matches when the value is a substring of the `GL_VENDOR` string

To disable all blacklisting, set the environment variable `QT_NO_OPENGL_BUGLIST` to any value. This will skip reading any configuration files, and instead will assume that nothing is disabled, regardless of the driver or OS.

Note: While not typically needed, `QT_NO_OPENGL_BUGLIST` can become relevant in certain virtual environments, with multiple, possibly virtual, graphics adapters present. If the logs from categories like `qt.qpa.gl` indicate that the detection of the driver and display adapter leads to incorrectly disabling OpenGL, it is then recommended to set this environment variable in order to enable the application to run normally. This environment variable was introduced in Qt 5.15.

## Direct dependency to opengl32.dll

An alternative to the default `dynamic` OpenGL builds is to depend directly on opengl32.dll. For this mode, pass the command line options `-opengl desktop` to the configure script.

     configure -opengl desktop

Note: Using EGL and OpenGL ES is not supported on Windows. In Qt 6, OpenGL on Windows always implies using WGL as the windowing system interface.

In such Qt builds, many Qt shared libraries, and also Qt applications will have a dependency to opengl32.dll, and therefore using an alternative library is not possible.

Building from source ◦ Deployment