Qt Weekly #24: High-dpi QtWayland

Those of you following QtWayland development closely might have seen commit 7ef5e2e4 - Implement high-dpi support. In this blog we'll look at some examples and show how to test the support on high and normal dpi hardware.


Wayland 1.2 added support for high-dpi scaling via

  • wl_output::scale
  • wl_surface::set_buffer_scale

wl_output::scale is used by the compositor to inform the client that it will scale buffers by the given scale factor (presumably because it is compositing to a high resolution display). The client then has the option of providing high resolution buffers and bypass the compositor scaling. This is done by calling set_buffer_scale (and then actually creating larger buffers). Typical values for the scale factor is 1 and 2; Wayland supports integer factors only. From he client point of view the buffer sizes are the only thing that changes with the scale factor, other wl_surface geometry is not multiplied by it.


Creating larger buffers and rendering high-dpi content is handled internally by Qt using the existing devicePixelRatio implementation. This implementation is also in use on OS X and iOS, and - via the QT_DEVICE_PIXEL_RATIO environment variable in Qt 5.4 - in experimental form on X11 and Windows. The details of this mode have been covered elsewhere; the main thing to be aware of as an app developer is that you need to provide high-resolution raster artwork, and that raw OpenGL are in device pixels and see the full display resolution.


Recent versions of the Weston compositor (I'm using 1.6.0) supports running in scaled mode:

./bin/weston --width=640 --height=480 --scale=2

We can then launch any Qt app, as usual:

./anyqtapp -platform wayland

high-dpi and normal-dpi rendered Flat style demo high-dpi and normal-dpi rendered Flat style demo - best viewed at full size

The screenshots illustrate the benefits of the devicePixelRatio scaling mode: The application is automatically rendered at a higher resolution; no modifications to app code is needed. In cases where high-resolution content is not available there is a graceful degradation to low-resolution content, without breaking layouts or by displaying "small" user interface elements.

High-dpi support is currently implemented in the "dev" branch of QtWayland and are on track to be released with Qt 5.5.

Blog Topics: