高DPI

高 DPI 显示屏（也称为视网膜显示屏）是指相对于其物理尺寸（毫米）而言具有高分辨率（像素）的显示屏，从而具有高像素密度，即每英寸点数（DPI）较高。 提高分辨率是为了在屏幕上提供更详细的内容（更平滑的文本、更精细的图标），而不是提供更多内容（更多窗口、更大的窗口尺寸）。

Qt 在所有平台上都支持高 DPI 显示屏，并提供了一个统一的 API 来抽象处理任何平台差异。当使用诸如 Qt Widgets 和 Qt Quick等更高层次的API时，会自动考虑显示分辨率，应用程序只需提供高分辨率资源（如图像和图标）。平台用户偏好设置的变更会被自动检测到。

低级图形绘制（如 OpenGL 代码）需要支持高 DPI，但可以使用跨平台的 Qt API 来获取平台的显示分辨率信息。

概念模型

Qt 采用一种应用程序坐标系与显示设备分辨率相互独立的模型。应用程序以设备独立像素为单位运行，这些像素随后通过一个称为“设备像素比”的缩放因子映射到显示器的物理像素上。该缩放因子以浮点数形式表示，例如1.0 或2.0 ，或非正式地表示为1x 和2x 。

例如，创建一个QWindow 或QWidget ，并将尺寸设置为 200x200，在标准密度显示屏（设备像素比为 1.0）上将覆盖 200x200 个显示像素， 但在高密度显示屏（设备像素比为 2.0）上则会覆盖 400x400 像素。

该模型适用于更高层次的Qt GUI 、Widgets 和 Quick API 中的大多数单元，包括小部件和项的几何属性、事件几何属性、桌面、窗口和屏幕几何属性，以及动画速度。

绘制

在使用QPainter 等绘制API时，或者在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 。

图像资源

为了充分利用高DPI显示屏更高的像素密度，应用程序还应包含静态图像资源的高DPI版本。 实现方法是：为高密度资源采用特殊的命名约定（例如logo@2x.png ），并将标准密度图像与高密度图像同时加载到QIcon 中。Qt 会在运行时自动为目标显示屏选择最佳的显示方式。更多详细信息请参见High DPI Icons 。

与设备无关的屏幕几何信息

Qt 应用程序通常以设备独立像素为单位运行。这包括报告给应用程序的窗口和屏幕几何信息。

这意味着QScreen::geometry() 返回的值可能并非屏幕的物理像素数，也可能与操作系统报告的像素尺寸不一致。这对虚拟桌面几何参数有影响：

现代桌面操作系统通常会为所有连接的屏幕创建一个共享坐标系，并允许用户（通常通过配置对话框）调整屏幕位置以匹配其物理屏幕布局。如果这种定位是在与 Qt 的设备独立像素等效的坐标系中进行的（例如在 macOS 上），那么QScreen 的几何信息将与原生屏幕布局一致。 如果定位是在屏幕物理像素中进行的（如在 Windows 上），那么 Qt 对屏幕几何的处理可能会在虚拟桌面几何中引入未被任何屏幕使用的空白区域。

具体来说，Qt 会缩放屏幕尺寸（正缩放因子会导致屏幕“变小”），但不会改变屏幕位置。这会产生“屏幕孤岛”式的虚拟桌面几何布局。

应用程序代码不应假设紧邻某屏幕且位于其外部的位置是相邻屏幕上的有效位置。相反，应通过 `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 和 Kubuntu 等桌面环境针对逻辑 DPI 的缺失实现了变通方案，并提供了易于配置的高 DPI 支持。如果您希望手动配置 X11 的 DPI 设置，本节将说明 Qt 会读取哪些 X11 设置。

某些 X11 配置流程涉及覆盖报告的屏幕物理尺寸，以使 DPI 计算得出特定的 DPI 值。Qt 支持此配置流程，但需要按下文所述进行启用。

确切的配置优先级如下，其中 Qt 会使用首个可用的选项。

在 X11 上使用物理 DPI

要强制 Qt 无条件地使用 RandR 物理 DPI 而不是逻辑 DPI，请设置QT_USE_PHYSICAL_DPI=1 。随后，Qt 将读取xcb_randr_screen_change_notify_event_t 结构中的mwidth 和mheight 字段，并将得到的 DPI 值四舍五入为整数。

当逻辑 DPI 不可用且已知显示器的物理 DPI 正确时，此方法非常有用。另请参阅《环境变量参考》。

配置 Windows

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

Windows 定义了多种DPI 感知级别，应用程序可通过设置这些级别来启用高 DPI 功能。Qt 6 默认采用“按显示器 DPI 感知 V2”模式。如果您正在集成假设存在单一全局 DPI 的代码，则可能需要设置不同的感知级别。为此，请在qt.conf 中添加以下内容：

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

测试

在开发或调试高DPI支持时，仅依赖特定硬件往往不切实际。Qt提供了一个环境变量来模拟不同的缩放因子，并提供了一个测试应用程序，用于检查Qt如何解释当前的显示配置。

QT_SCALE_FACTOR

将环境变量QT_SCALE_FACTOR 设置为应用程序的全局缩放因子。

例如：

QT_SCALE_FACTOR=2 ./myapp

这会将所有应用程序几何图形（包括设备像素比）按给定的因子进行缩放，从而能够独立于现有硬件测试高DPI支持功能。

Qt会直接使用设定的缩放因子，且不受rounding policy 的影响。

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

DprGadget 测试应用程序

您可以使用 DprGadget 测试应用程序来检查原生配置，以及 Qt 对此的响应：

DprGadget 会显示窗口的设备像素比，该值由QWindow::devicePixelRatio() 返回。此外，它还会显示窗口所在屏幕的原生 DPI 和设备像素比，这些值分别由 QPlatformScreen::logicalDpi() 和 QPlatformScreen::devicePixelRatio() 返回。

当屏幕分辨率和 DPI 发生变化时，显示的数值应自动更新，且对话框应保持相同大小。若未达到此效果，则可能是 Qt 的错误。

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

环境变量参考

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

坐标系参考

Qt 的 API 中使用了以下坐标系。大多数应用程序代码以设备独立像素为单位运行；其他坐标系主要与低级图形处理和平台集成相关：