3 unstable releases

0.1.1 Mar 15, 2024
0.1.0 Mar 13, 2024
0.0.0 Feb 20, 2024

#336 in GUI

Download history 11/week @ 2024-02-27 5/week @ 2024-03-05 248/week @ 2024-03-12 22/week @ 2024-03-19 887/week @ 2024-03-26 4737/week @ 2024-04-02 6260/week @ 2024-04-09 7648/week @ 2024-04-16 8696/week @ 2024-04-23 12128/week @ 2024-04-30 13482/week @ 2024-05-07 13992/week @ 2024-05-14 14149/week @ 2024-05-21 16833/week @ 2024-05-28 18439/week @ 2024-06-04 13922/week @ 2024-06-11

65,475 downloads per month
Used in 116 crates (6 directly)

Apache-2.0

40KB
1K SLoC

DPI

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

The PhysicalPosition / PhysicalSize / PhysicalUnit types correspond with the actual pixels on the device, and the LogicalPosition / LogicalSize / LogicalUnit types correspond to the physical pixels divided by the scale factor.

The 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.

Cargo Features

This crate provides the following Cargo features:

  • serde: Enables serialization/deserialization of certain types with Serde.
  • mint: Enables mint (math interoperability standard types) conversions.

Dependencies

~180KB