[−][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:
-
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: "retina displays" have a scale factor of 2.0. Otherwise, the scale factor is 1.0. Intermediate scale factors are never used. It's possible for any display to use that 2.0 scale factor, given the use of the command line.
-
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_FACTORenvironment variable, if present. - If not present, use the value set in
Xft.dpiin Xresources. - Otherwise, calcuate the scale factor based on the millimeter monitor dimensions provided by XRandR.
If
WINIT_X11_SCALE_FACTORis set torandr, it'll ignore theXft.dpifield and use the XRandR scaling method. Generally speaking, you should try to configure the standard system variables to do what you want before resorting toWINIT_X11_SCALE_FACTOR. - Use the value in the
-
Wayland: On Wayland, scale factors are set per-screen by the server, and are always integers (most often 1 or 2).
-
iOS: Scale factors are set by Apple to the value that best suits the device, and range from
1.0to3.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.0to4.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 below1.0.
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 |