Module winit::dpi

source ·
Expand description

UI scaling is important, so read the docs for this module if you don’t want to be confused.

§Why should I care about UI scaling?

Modern computer screens don’t have a consistent relationship between resolution and size. 1920x1080 is a common resolution for both desktop and mobile screens, despite mobile screens typically being less than a quarter the size of their desktop counterparts. Moreover, neither desktop nor mobile screens have consistent resolutions within their own size classes - common mobile screens range from below 720p to above 1440p, and desktop screens range from 720p to 5K and beyond.

Given that, it’s a mistake to assume that 2D content will only be displayed on screens with a consistent pixel density. If you were to render a 96-pixel-square image on a 1080p screen and then render the same image on a similarly-sized 4K screen, the 4K rendition would only take up about a quarter of the physical space as it did on the 1080p screen. That issue is especially problematic with text rendering, where quarter-sized text becomes a significant legibility problem.

Failure to account for the scale factor can create a significantly degraded user experience. Most notably, it can make users feel like they have bad eyesight, which will potentially cause them to think about growing elderly, resulting in them having an existential crisis. Once users enter that state, they will no longer be focused on your application.

§How should I handle it?

The solution to this problem is to account for the device’s scale factor. The scale factor is the factor UI elements should be scaled by to be consistent with the rest of the user’s system - for example, a button that’s usually 50 pixels across would be 100 pixels across on a device with a scale factor of 2.0, or 75 pixels across with a scale factor of 1.5.

Many UI systems, such as CSS, expose DPI-dependent units like points or picas. That’s usually a mistake since there’s no consistent mapping between the scale factor and the screen’s actual DPI. Unless printing to a physical medium, you should work in scaled pixels rather than any DPI-dependent units.

§Position and Size types

Winit’s PhysicalPosition / PhysicalSize types correspond with the actual pixels on the device, and the LogicalPosition / LogicalSize types correspond to the physical pixels divided by the scale factor. All of Winit’s functions return physical types, but can take either logical or physical coordinates as input, allowing you to use the most convenient coordinate system for your particular application.

Winit’s position and size types are generic over their exact pixel type, P, to allow the API to have integer precision where appropriate (e.g. most window manipulation functions) and floating precision when necessary (e.g. logical sizes for fractional scale factors and touch input). If P is a floating-point type, please do not cast the values with as {int}. Doing so will truncate the fractional part of the float rather than properly round to the nearest integer. Use the provided cast function or From/Into conversions, which handle the rounding properly. Note that precision loss will still occur when rounding from a float to an int, although rounding lessens the problem.

§Events

Winit will dispatch a ScaleFactorChanged event whenever a window’s scale factor has changed. This can happen if the user drags their window from a standard-resolution monitor to a high-DPI monitor or if the user changes their DPI settings. This allows you to rescale your application’s UI elements and adjust how the platform changes the window’s size to reflect the new scale factor. If a window hasn’t received a ScaleFactorChanged event, its scale factor can be found by calling window.scale_factor().

§How is the scale factor calculated?

The scale factor is calculated differently on different platforms:

  • Windows: On Windows 8 and 10, per-monitor scaling is readily configured by users from the display settings. While users are free to select any option they want, they’re only given a selection of “nice” scale factors, i.e. 1.0, 1.25, 1.5… on Windows 7. The scale factor is global and changing it requires logging out. See this article for technical details.

  • macOS: Recent macOS versions allow the user to change the scaling factor for specific displays. When available, the user may pick a per-monitor scaling factor from a set of pre-defined settings. All “retina displays” have a scaling factor above 1.0 by default, but the specific value varies across devices.

  • X11: Many man-hours have been spent trying to figure out how to handle DPI in X11. Winit currently uses a three-pronged approach:

    • Use the value in the WINIT_X11_SCALE_FACTOR environment variable if present.
    • If not present, use the value set in Xft.dpi in Xresources.
    • Otherwise, calculate the scale factor based on the millimeter monitor dimensions provided by XRandR.

    If WINIT_X11_SCALE_FACTOR is set to randr, it’ll ignore the Xft.dpi field and use the XRandR scaling method. Generally speaking, you should try to configure the standard system variables to do what you want before resorting to WINIT_X11_SCALE_FACTOR.

  • Wayland: The scale factor is suggested by the compositor for each window individually. The monitor scale factor may differ from the window scale factor.

  • iOS: Scale factors are set by Apple to the value that best suits the device, and range from 1.0 to 3.0. See this article and this article for more information.

  • Android: Scale factors are set by the manufacturer to the value that best suits the device, and range from 1.0 to 4.0. See this article for more information.

  • Web: The scale factor is the ratio between CSS pixels and the physical device pixels. In other words, it is the value of window.devicePixelRatio. It is affected by both the screen scaling and the browser zoom level and can go below 1.0.

Structs§

Enums§

  • Position
    A position that’s either physical or logical.
  • Size
    A size that’s either physical or logical.

Traits§

Functions§