高 DPI

高 DPI 显示器（也称为视网膜显示器）是指相对于物理尺寸（毫米）具有高分辨率（像素）的显示器，因此像素密度高，或每英寸点数（DPI）高。分辨率的提高用于在屏幕上提供更详细的内容（更流畅的文本、更详细的图标），而不是更多的内容（更多的窗口、更大的窗口尺寸）。

Qt 支持所有平台上的高 DPI 显示，并提供了一个统一的应用程序接口（API）来抽象任何平台差异。在使用更高级的 API（如Qt Widgets 和Qt Quick ）时，Qt 会自动考虑显示分辨率，应用程序只需提供高分辨率资产，如图像和图标。平台用户偏好的变化会被自动接收。

低级图形绘制（如 OpenGL 代码）需要具有高分辨率感知能力，但可以使用跨平台 Qt OpenGL API 来了解平台的显示分辨率。

概念模型

Qt 使用的模型是应用程序坐标系与显示设备分辨率无关。应用程序在独立于设备的像素中运行，然后通过一个缩放因子（即设备像素比）将其映射到显示器的物理像素上。比例因子以浮点数表示，例如1.0 或2.0 ，或非正式地表示为1x 和2x 。

例如，创建QWindow 或QWidget ，并将其大小设置为 200x200，在普通密度显示屏（设备像素比为 1.0）上将覆盖 200x200 显示像素，但在高密度显示屏（设备像素比为 2.0）上将覆盖 400x400 像素。

此模型适用于更高级Qt GUI 、小工具和快速应用程序接口中的大多数单位，包括小工具和项目几何图形、事件几何图形、桌面、窗口和屏幕几何图形以及动画速度。

绘图

当使用绘图 API（如QPainter ），或在Qt Quick 中渲染图形基元或文本时，Qt 将自动利用高 DPI 显示器密度增加的优势。

因此，应用程序可以在一个统一的坐标系中运行，而无需考虑应用程序运行时可能的显示密度。

不过，在使用较低级的绘图 API（如 OpenGL）时，应用程序需要考虑显示器的设备像素比。这既可以通过QWindow::devicePixelRatio() （在显示器之间移动时跟踪窗口的设备像素比例）来实现，也可以通过QScreen::devicePixelRatio() 来实现。

图像缓冲区（如QImage 和QPixmap ）表示原始像素，因此不在前面所述的独立于设备的坐标系中运行。尺寸为 400x400 的QImage （设备像素比为 2.0）在高密度（2x）显示器上适合 200x200 的QWindow ，如果使用普通密度（1x）显示器，则在绘制过程中将自动缩放为 200x200。详情请查看Drawing High Resolution Versions of Pixmaps and Images 。

图像资产

为充分利用高密度显示屏的像素密度，应用程序还应包含高密度显示屏版本的静态图像资产。这可以通过为高密度资产使用特殊的命名约定来实现，例如logo@2x.png ，并将普通密度图像和高密度图像加载到QIcon 中。Qt 会在运行时自动为目标显示屏选择最佳表现形式。详见High DPI Icons 。

独立于设备的屏幕几何

Qt 应用程序通常在独立于设备的像素中运行。这包括向应用程序报告的窗口和屏幕几何图形。

这意味着QScreen::geometry() 可能不会返回屏幕的物理像素数或操作系统报告的像素大小。这对虚拟桌面几何图形有影响：

现代桌面操作系统通常会为所有连接的屏幕创建一个共享坐标系，并允许用户通常通过配置对话框来定位屏幕，以匹配其物理屏幕设置。如果定位是在与 Qt 的设备独立像素相当的坐标系中完成（如在 macOS 上），那么QScreen 几何图形将与原生屏幕布局相匹配。如果以屏幕物理像素进行定位（如在 Windows 上），那么 Qt 对屏幕几何的处理可能会在任何屏幕都未使用的虚拟桌面几何中引入 "间隙"。

具体来说，Qt Positioning 会缩放屏幕尺寸（正缩放系数会导致屏幕 "变小"），但不会改变屏幕位置。这将产生 "屏幕孤岛 "类型的虚拟桌面几何图形。

应用程序代码不应假定紧邻一个屏幕和屏幕外的位置就是邻近屏幕上的有效位置。相反，应使用QGuiApplication::screens() 获取屏幕列表，并使用该列表对可用屏幕几何图形进行推理。

配置

作为最终用户，你可能需要调整 DPI 或缩放比例设置以匹配显示硬件，或考虑观看距离和个人偏好。这些调整应使用平台的本机显示设置来完成，这样所有应用程序都会同意相同的 DPI 或缩放因子值。Qt 不提供终端用户配置 Qt 高 DPI 支持行为的工具。

操作系统可将缩放因子表示为系数（1.5）、百分比（150%）或每英寸点数（144 DPI）。Qt 会将其转换为应用程序看到的设备像素比例。在后一种情况下，Qt 假定一个 "基本 "DPI（如 X11 上的 96），并据此计算设备像素比例。

整数缩放因子（如 1.0 或 2.0）可获得最佳效果。将比例因子 "四舍五入 "到 25% 的增量也能获得不错的效果。将缩放因子或 DPI 设置为精确的物理显示 DPI 可能不会带来良好的视觉效果，这是因为涉及到分数缩放。如果应用程序在这种情况下受到视觉假象的影响，可以使用QGuiApplication::setHighDpiScaleFactorRoundingPolicy() 来限制它能看到的缩放因子。

平台详细信息

下表介绍了如何在各种平台上配置高 DPI。

配置 X11

Qt 所需的配置输入是每屏逻辑 DPI。目前，X11 提供全局逻辑 DPI 或每屏幕物理 DPI。这两种方式都不完全符合 Qt 的需求，因此 X11 上的 DPI 配置比其他平台上的更为复杂。

Ubuntu 和 Kubntu 等桌面环境为缺乏逻辑 DPI 提供了变通方法，并提供了易于配置的高 DPI 支持。如果你想手动配置 X11 DPI 设置，本节将介绍 Qt 会读取哪些 X11 设置。

有些 X11 配置工作流程涉及覆盖屏幕的物理尺寸，以便使 DPI 计算产生特定的 DPI 值。Qt 支持这种工作流程，但需要选择加入，如下所述。

具体的配置优先级如下，Qt 使用第一个可用选项。请注意，行为取决于所使用的 Qt 版本。Qt 5 行为假定 AA_EnableHighDpiScaling 已被设置（Qt 6 不需要此标记）。

QT_USE_PHYSICAL_DPI 覆盖值

设置 QT_USE_PHYSICAL_DPI=1，可使 Qt 无条件使用 RandR 物理 DPI；特别是使用 xcb_randr_screen_change_notify_event_t 结构中的mwidth 和mheight 字段。DPI 值将四舍五入为整数。

配置 Windows

Qt 会自动使用 Windows 的显示比例设置；无需进行特定设置。例如，如果显示器配置为 175% 的缩放比例，那么 Qt 应用程序将在该屏幕上看到 1.75 的设备像素比。

Windows 定义了多个 DPI感知级别，应用程序可对其进行设置，以便选择使用高 DPI 功能。Qt 6 默认为每显示器 DPI 感知 V2。如果您的代码假设全局只有一个 DPI，那么您可能需要设置不同的感知级别。这可以通过在 qt.conf 中添加一个条目来实现：

[Platforms]
WindowsArguments = dpiawareness=0,1,2

测试

qt_scale_factor

设置 QT_SCALE_FACTOR 环境变量，为应用程序提供全局缩放因子。

QT_SCALE_FACTOR=2 ./myapp

这将按给定的系数缩放所有应用程序几何图形（包括设备像素比），从而使测试高 DPI 支持不受可用硬件的影响。设置的缩放因子将由 Qt 按原样使用，不会受到rounding policy 的影响。

QWindow::devicePixelRatio() 返回的有效设备像素比将是设定的缩放系数与原生设备像素比的乘积。例如，在 2x Wayland 显示器上设置 QT_SCALE_FACTOR=2，应用程序将看到 4 的设备像素比。

DprGadget

DprGadget 测试程序可用于检查本地配置以及 Qt 对其的反应：

DprGadget 显示QWindow::devicePixelRatio() 报告的窗口设备像素比。此外，它还会显示寡妇所在屏幕的本地 DPI 和设备像素比，如 QPlatformScreen::logicalDpi() 和 QPlatformScreen::devicePixelRatio() 所报告的那样。

屏幕和 DPI 变化时，显示的值应自动更新，对话框应保持相同大小。否则，可能是 Qt 的错误。

DprGradget 是 Qt 手动测试套件的一部分，可在qtbase/tests/manual/highdpi/dprgadget 上找到。

环境变量参考

本节列出了 Qt 可识别的高 DPI 相关环境变量。按字母顺序排列：

• QT_ENABLE_HIGHDPI_SCALING 设为 0 则禁用高分辨率缩放；实际上恢复到 Qt 5 默认行为。请注意，这对 Wayland 或 macOS 等平台没有影响--它不会禁用任何本地高 DPI 支持。此变量仅用于测试目的，我们不建议永久设置它。
• QT_FONT_DPI 设置全局 DPI。这是一个用于向后兼容的传统环境变量。
• QT_SCALE_FACTOR 设置全局比例因子。用于调试和测试目的。
• QT_SCALE_FACTOR_ROUNDING_POLICY 设置缩放因子rounding policy ，它将应用于根据屏幕 DPI 计算出的缩放因子。支持的值包括
  • 圆形（Qt 5 默认值）
  • PassThrough （Qt 6 默认值）
• QT_SCREEN_SCALE_FACTORS 设置屏幕缩放因子列表。该列表有两种格式，一种是以分号分隔的屏幕比例因子列表（"1;1.5;2"），另一种是以分号分隔的 screen=factor 条目列表（"screenA=1;screenB=1.5;screenC=2"）。不建议设置此环境变量，因为它会阻止 Qt 使用系统 DPI 值。
• QT_USE_PHYSICAL_DPI 使 Qt 使用物理 DPI 而不是逻辑 DPI。使用逻辑 DPI 通常是最佳选择；在逻辑 DPI 不可用且已知物理 DPI 正确的情况下，可以设置此环境变量。

坐标系参考

• 设备独立像素 这是 Qt 的主要坐标系。窗口、窗口部件、Quick item、事件和屏幕几何图形都采用独立于设备的像素。通常情况下，独立于设备的像素在不同设备类型和屏幕密度下具有恒定的视觉尺寸。虽然这是一种概括，但具体尺寸取决于设备配置。
• 设备像素 该坐标系用于光栅化和底层图形任务，例如使用 OpenGL 应用程序接口时。设备像素坐标系通常等同于显示器的物理坐标系，但这并不保证。例如，macOS 和 Ubuntu 可能会根据显示设置应用额外的缩放。
• 本地像素 这是本地 API（如 Win32 或 Cocoa（macOS））使用的坐标系。根据平台和屏幕配置的不同，原生像素可能等同于独立于设备的像素或设备像素。