Windows 版 Qt - 图形加速

要 Qt Quick 功能正常运行，需要一个支持 Direct3D 11、Direct3D 12、Vulkan 1.0 或 OpenGL 2.1 及以上版本的图形驱动程序。 从 Qt 6 开始，Windows 系统上Qt Quick 的默认值为 Direct3D 11。这与 Qt 5 不同，Qt 5 的默认值为 OpenGL（无论是直接使用，还是通过 OpenGL 到 Direct3D 的转换器 ANGLE 实现）。ANGLE 已不再随 Qt 6 一起发布。

若要强制使用 Direct3D 的软件光栅化器（WARP），请将环境变量 `QSG_RHI_PREFER_SOFTWARE_RENDERER ` 设置为 `1`。在某些情况下，`Qt Quick ` 会自动执行此类回退，以便在无需额外配置的情况下运行 Qt 应用程序。 这种情况通常发生在驱动程序无法提供足够的 D3D11 功能时，常见于未正确实现 GPU 加速和直通的虚拟机中。若不确定正在使用哪种图形设备，或在向 Qt 进行故障排除或报告问题时，请将环境变量QSG_INFO=1 设置后运行应用程序，并检查调试输出。 运行qtdiag 工具也能提供有用的信息，因为它会列举所有可用的 3D API。

若要请求使用 Vulkan、OpenGL 或 Direct 3D 12，请将环境变量QSG_RHI_BACKEND 设置为vulkan 、opengl 或d3d12 ，或使用等效的C++ API （位于main() 中）。请注意，其中某些 3D API 可能需要安装相应的驱动程序。

虽然 OpenGL 并非 Qt Quick，OpenGL在许多Qt应用程序中仍被广泛使用，例如基于QWidget 且构建于QOpenGLWindow 或QOpenGLWidget 之上的应用程序。以下各节将介绍Qt构建中与OpenGL相关的具体内容。

动态加载 OpenGL

Qt 支持在运行时选择并加载 OpenGL 实现。此模式为默认模式，可通过向 configure 脚本传递-opengl dynamic 来显式请求。

configure -opengl dynamic

这种配置具有最大的灵活性，因为在构建时不会对 OpenGL 实现硬编码任何依赖关系或假设。它能够实现稳健的应用程序部署。 当特定环境无法提供合适的 OpenGL 2.0 实现时，系统会自动回退并加载opengl32.dll 的替代方案，其默认名称为opengl32sw.dll 。预编译的 Qt 软件包中包含一个名为 Mesa llvmpipe 的构建版本，这是 OpenGL 的软件光栅化器实现。

当配置为-opengl dynamic 时，无论是 Qt 本身，还是使用qmake 或CMake 构建的应用程序，都不会与 opengl32.lib 进行链接。相反，该库将在运行时被选定并加载。 默认情况下，Qt 会判断系统中的 opengl32.dll 是否提供 OpenGL 2 函数。如果提供，则使用 opengl32.dll；否则，它将尝试加载opengl32sw.dll 。详情请参见下文。

该加载机制可通过环境变量 `QT_OPENGL ` 以及以下应用程序属性进行配置：

• Qt::AA_UseDesktopOpenGL 这相当于将QT_OPENGL 设置为desktop 。
• Qt::AA_UseOpenGLES 在 Qt 6 中无效。
• Qt::AA_UseSoftwareOpenGL 相当于将QT_OPENGL 设置为software 。

当显式请求特定配置时，应用程序启动时不会进行任何检查，即不会检查系统提供的 opengl32.dll。

动态加载对包含本机 OpenGL 调用的应用程序有显著影响：由于 opengl32.lib 不会自动指定给链接器，因此这些应用程序可能会链接失败。 相反，应用程序应通过QOpenGLFunctions 类使用 OpenGL 函数。这样就消除了对 OpenGL 库的直接依赖，所有调用都将在运行时路由到 Qt 选择的实现。 或者，如果应用程序将 opengl32.lib 添加到其 .pro 项目文件中，则可以自由地直接调用 OpenGL 函数：LIBS += opengl32.lib（Visual Studio）或LIBS += -lopengl32（Mingw-w64）。 从应用程序的角度来看，其效果等同于 Qt 的-opengl desktop 构建配置。

Qt::AA_UseSoftwareOpenGL QT_OPENGL_DLL 的特殊之处在于，它会尝试加载一个名称非标准的 OpenGL 实现。默认名称为 。这允许将纯软件实现的 OpenGL（例如opengl32sw.dll使用 llvmpipe 构建的Mesa）以该名称打包发布。如有必要，可通过设置 环境变量来覆盖该文件名。

可以提供一个 JSON 格式的配置文件，根据显卡和驱动程序版本指定要使用的 OpenGL 实现。该文件的位置由环境变量QT_OPENGL_BUGLIST 指定。相对路径将通过QLibraryInfo::SettingsPath 或QStandardPaths::ConfigLocation 进行解析。该文件采用Chromium 项目中使用的驱动程序错误列表格式。 该文件由一系列条目组成，每个条目指定一组条件和一组功能关键字。通常，设备 ID 和供应商 ID 用于匹配特定的显卡。这些信息可在qtdiag6 或dxdiag 工具的输出中找到。

以下功能关键字与选择 OpenGL 实现相关：

• disable_desktopgl - 禁用 OpenGL。这可确保 Qt 不会尝试使用常规 OpenGL（opengl32.dll），而是直接启动 ANGLE。此设置有助于防止存在问题的 OpenGL 驱动程序导致应用程序崩溃。
• disable_rotation - 强制应用程序始终以横向模式运行。当使用软件 OpenGL 实现时，此设置无效。该设置主要针对在旋转方面存在问题的驱动程序。
• disable_program_cache - 禁用将着色器程序二进制文件存储到磁盘。

示例文件如下：

{
"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"
  ]
},
...

若未指定QT_OPENGL_BUGLIST ，将使用内置列表。该列表通常包含一些较旧、性能较弱的显卡（其disable_desktopgl 已设置），以防止Qt使用这些显卡不稳定的桌面OpenGL实现，而是直接回退并尝试加载基于软件的替代库。

实际上，最常见的组合预计如下：

• disable_desktopgl - 系统提供 OpenGL 2.0 或更高版本，但已知驱动程序不稳定且容易崩溃。
• disable_desktopgl, disable_angle - 当不希望使用加速路径时。这可确保 Qt 仅尝试使用软件光栅化器（opengl32sw.dll）。在虚拟机以及部署在各种旧系统上的应用程序中可能很有用。

用于匹配特定显卡或驱动程序的支持键如下。请注意，其中部分键是 Qt 专有的。

• os.type - 操作系统：win 、linux 、macosx 、android
• os.version - 内核版本
• os.release - 指定 Windows 操作系统版本列表：xp 、vista 、7 、8 、8.1 、10 。
• vendor_id - 根据适配器标识符确定的供应商
• device_id - PCI 设备 ID 列表。
• driver_version - 来自适配器标识符的驱动程序版本
• driver_description - 当该值是适配器标识符中驱动程序描述的子字符串时，匹配
• gl_vendor - 当该值是“GL_VENDOR ”字符串的子字符串时，即视为匹配

要禁用所有黑名单功能，请将环境变量QT_NO_OPENGL_BUGLIST 设置为任意值。这将跳过读取任何配置文件，并默认认为没有任何功能被禁用，无论驱动程序或操作系统如何。

直接依赖 opengl32.dll

除了默认的dynamic OpenGL构建方式外，还可以直接依赖opengl32.dll。要启用此模式，请向configure脚本传递命令行选项-opengl desktop 。

configure -opengl desktop

在此类 Qt 构建中，许多 Qt 共享库以及 Qt 应用程序都会依赖 opengl32.dll，因此无法使用替代库。