[][src]Module glutin::dpi

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 normally being less than a quarter the size of their desktop counterparts. What's more, neither desktop nor mobile screens are 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, 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 normally 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 you're printing to a physical medium, you should work in scaled pixels rather than any DPI-dependent units.

Position and Size types

Winit's Physical(Position|Size) types correspond with the actual pixels on the device, and the Logical(Position|Size) 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 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 gives you a chance 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, then its scale factor is 1.0.

How is the scale factor calculated?

Scale factor is calculated differently on different platforms:

Structs

LogicalPosition

A position represented in logical pixels.

LogicalSize

A size represented in logical pixels.

PhysicalPosition

A position represented in physical pixels.

PhysicalSize

A size represented in physical pixels.

Enums

Position

A position that's either physical or logical.

Size

A size that's either physical or logical.

Traits

Pixel

Functions

validate_scale_factor

Checks that the scale factor is a normal positive f64.