High-DPI displays – also known as retina displays – are displays with high resolution (pixels) in relation to their physical size (mm), resulting in a high pixel density, or high number of dots per inch (DPI). The increased resolution is used to provide more detailed content on screen (smoother text, more detailed icons), rather than more content (more windows, larger window sizes).

Qt supports high-DPI displays on all platforms, and provides a unified API that abstracts over any platform differences. Qt will automatically account for the display resolution when using higher level APIs such as Qt Widgets and Qt Quick, and applications only need to provide high-resolution assets, such as images and icons. Changes in the platform's user preferences are automatically picked up.

Lower-level graphics drawing (such as OpenGL code) need to be high-DPI aware, but can use cross platform Qt APIs to learn about the platform's display resolutions.

Conceptual Model

Qt uses a model where the application coordinate system is independent of the display device resolution. The application operates in device-independent pixels, which are then mapped to the physical pixels of the display via a scale factor, known as the device pixel ratio. The scale factor is expressed as a floating point number, for example 1.0 or 2.0, or informally as 1x and 2x.

For example, creating a QWindow or QWidget, and setting its size to 200x200 will result in a corresponding window of 200x200 pixels on a normal density display (with a device pixel ratio of 1.0), but will result in a window of 400x400 pixel on a high density display (with a device pixel ratio of 2.0).

This model applies to most units in higher level Qt Gui, Widgets, and Quick APIs, including widget and item geometry, event geometry, desktop, window and screen geometry, as well as animation velocities.

Note: The model does not handle differences between UI classes, such as the size of touch targets vs mouse targets.

Drawing

Qt will automatically take advantage of the increased density of a high-DPI display when using drawing APIs such as QPainter, or when rendering graphic primitives or text in Qt Quick.

As a result the application can operate in a single unified coordinate system, without needing to account for the possible display densities the application will run on.

However, when using lower level drawing APIs, for example OpenGL, the application needs to take the device pixel ratio of the display into account. This is available both per window, as QWindow::devicePixelRatio() (tracking the device pixel ratio of the window when moved between displays), or per display, as QScreen::devicePixelRatio().

Image buffers such as QImage and QPixmap represent the raw pixels, and as a result do not operate in the device independent coordinate system described earlier. A QImage of size 400x400, with a device pixel ratio of 2.0, will fit a 200x200 QWindow on a high density (2x) display, or will be automatically downscaled to 200x200 during drawing if targeting a normal density (1x) display. See Drawing High Resolution Versions of Pixmaps and Images for more details.

Image Assets

To take advantage of the increased pixel density of high-DPI displays, the application should also include high-DPI versions of static image assets. This is achieved by using a special naming convention for the high density assets, for example logo@2x.png, and loading both the normal density image and the high-density image into a QIcon. Qt will automatically choose the best representation for the target display at runtime. See High DPI Icons for more details.

Configuring

As an end user you may want to adjust the DPI or scale settings to match display hardware, or to account for viewing distance and personal preferences. These adjustments should be done using the native display settings of the platform, so that all applications will agree on the same DPI or scale factor values. Qt does not provide end user facilities to configure the behavior of Qt's high-DPI support.

The operating system may represent the scale factor either as a factor (1.5), as a percentage (150%), or as dots per inch (144 DPI). Qt translates these to the device pixel ratio seen by the application. In the latter case Qt assumes a "base" DPI – e.g 96 on X11 – and calculates the resulting device pixel ratio accordingly.

Integer scale factors (e.g. 1.0 or 2.0) are preferred for best results. "Rounding" the scale factor to 25% increments can also give good results. Setting the scale factor or DPI to the exact physical display DPI may not give good visual results due to the fractional scaling involved. If the application suffers from visual artifacts in this scenario, it can use QGuiApplication::setHighDpiScaleFactorRoundingPolicy() to limit the scale factors it will see.

Platform Details

The following table describes how to configure high-DPI on various platforms.

Note: Some windowing systems may have limitations that are then reflected in Qt. Qt does not provide workarounds for these limitations. Instead, consider workarounds on the windowing system level.

Testing

The DprGadget test application can be used to inspect the native configuration, and how Qt reacts to it:

DprGadget displays the device pixel ratio of the window, as reported by QWindow::devicePixelRatio(). In addition is displays the native DPI and device pixel ratio of the screen the widow is on, as reported by QPlatformScreen::logicalDpi() and QPlatformScreen::devicePixelRatio().

The displayed values should be updated automatically on screen and DPI changes, and the dialog should maintain the same size. If this does happen then that indicate there might be a bug in Qt.

DprGradget is a part Qt's manual test suite, and can be found at qtbase/tests/manual/highdpi/pixelgadget.