From 9b122c380485b061f0583f8650b1d93bf61f33df Mon Sep 17 00:00:00 2001 From: Osspial Date: Sat, 4 Jan 2020 19:19:17 -0500 Subject: [PATCH] Update the DPI module docs (#1349) * Update the DPI module docs * Fix HiDpiFactorChanged doc link * Incorporate lokathor and icefox feedback * Adjust documented desktop resolution range * X11 is one of the reasons I use Windows * Address DPI generics and float->int rounding * Revise DPI value statement to better reflect best practices * Address some of freya's feedback * phrasing * Rephrase X11 DPI stuff --- src/dpi.rs | 170 ++++++++++++++++++++++++++++----------------------- src/event.rs | 2 +- 2 files changed, 96 insertions(+), 76 deletions(-) diff --git a/src/dpi.rs b/src/dpi.rs index 66467f08..798a6783 100644 --- a/src/dpi.rs +++ b/src/dpi.rs @@ -1,80 +1,106 @@ -//! DPI is important, so read the docs for this module if you don't want to be confused. +//! UI scaling is important, so read the docs for this module if you don't want to be confused. //! -//! Originally, `winit` dealt entirely in physical pixels (excluding unintentional inconsistencies), but now all -//! window-related functions both produce and consume logical pixels. Monitor-related functions still use physical -//! pixels, as do any context-related functions in `glutin`. +//! ## Why should I care about UI scaling? //! -//! If you've never heard of these terms before, then you're not alone, and this documentation will explain the -//! concepts. +//! 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. //! -//! Modern screens have a defined physical resolution, most commonly 1920x1080. Indepedent of that is the amount of -//! space the screen occupies, which is to say, the height and width in millimeters. The relationship between these two -//! measurements is the *pixel density*. Mobile screens require a high pixel density, as they're held close to the -//! eyes. Larger displays also require a higher pixel density, hence the growing presence of 1440p and 4K displays. +//! 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. //! -//! So, this presents a problem. Let's say we want to render a square 100px button. It will occupy 100x100 of the -//! screen's pixels, which in many cases, seems perfectly fine. However, because this size doesn't account for the -//! screen's dimensions or pixel density, the button's size can vary quite a bit. On a 4K display, it would be unusably -//! small. +//! 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. //! -//! That's a description of what happens when the button is 100x100 *physical* pixels. Instead, let's try using 100x100 -//! *logical* pixels. To map logical pixels to physical pixels, we simply multiply by the DPI (dots per inch) factor. -//! On a "typical" desktop display, the scale factor will be 1.0, so 100x100 logical pixels equates to 100x100 physical -//! pixels. However, a 1440p display may have a scale factor of 1.25, so the button is rendered as 125x125 physical pixels. -//! Ideally, the button now has approximately the same perceived size across varying displays. +//! ## How should I handle it? //! -//! Failure to account for the scale factor can create a badly 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 entering an existential panic. Once users enter that state, they will no longer be focused on your application. +//! 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`. //! -//! There are two ways to get the scale factor: -//! - You can track the [`DpiChanged`](crate::event::WindowEvent::DpiChanged) event of your -//! windows. This event is sent any time the scale factor changes, either because the window moved to another monitor, -//! or because the user changed the configuration of their screen. -//! - You can also retrieve the scale factor of a monitor by calling -//! [`MonitorHandle::scale_factor`](crate::monitor::MonitorHandle::scale_factor), or the -//! current scale factor applied to a window by calling -//! [`Window::scale_factor`](crate::window::Window::scale_factor), which is roughly equivalent -//! to `window.current_monitor().scale_factor()`. +//! The scale factor correlates with, but no has direct relationship to, the screen's actual DPI +//! (dots per inch). Operating systems used to define the scale factor in terms of the screen's +//! approximate DPI (at the time, 72 pixels per inch), but [Microsoft decided to report that the DPI +//! was roughly 1/3 bigger than the screen's actual DPI (so, 96 pixels per inch) in order to make +//! text more legible][microsoft_dpi]. As a result, the exact DPI as defined by the OS doesn't carry +//! a whole lot of weight when designing cross-platform UIs. Scaled pixels should generally be used +//! as the base unit for on-screen UI measurement, instead of DPI-dependent units such as +//! [points][points] or [picas][picas]. //! -//! Depending on the platform, the window's actual scale factor may only be known after -//! the event loop has started and your window has been drawn once. To properly handle these cases, -//! the most robust way is to monitor the [`DpiChanged`](crate::event::WindowEvent::DpiChanged) -//! event and dynamically adapt your drawing logic to follow the scale factor. +//! ### Position and Size types //! -//! Here's an overview of what sort of scale factors you can expect, and where they come from: -//! - **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. -//! - **macOS:** The buzzword is "retina displays", which have a scale factor of 2.0. Otherwise, the scale factor is 1.0. -//! Intermediate scale factors are never used, thus 1440p displays/etc. aren't properly supported. It's possible for any -//! display to use that 2.0 scale factor, given the use of the command line. -//! - **X11:** On X11, we calcuate the scale factor based on the millimeter dimensions provided by XRandR. This can -//! result in a wide range of possible values, including some interesting ones like 1.0833333333333333. This can be -//! overridden using the `WINIT_X11_SCALE_FACTOR` environment variable, though that's not recommended. -//! - **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 both constant and device-specific on iOS. -//! - **Android:** This feature isn't yet implemented on Android, so the scale factor will always be returned as 1.0. -//! - **Web:** scale factors are handled by the browser and will always be 1.0 for your application. +//! 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. //! -//! The window's logical size is conserved across DPI changes, resulting in the physical size changing instead. This -//! may be surprising on X11, but is quite standard elsewhere. Physical size changes always produce a -//! [`Resized`](crate::event::WindowEvent::Resized) event, even on platforms where no resize actually occurs, -//! such as macOS and Wayland. As a result, it's not necessary to separately handle -//! [`DpiChanged`](crate::event::WindowEvent::DpiChanged) if you're only listening for size. +//! 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. //! -//! Your GPU has no awareness of the concept of logical pixels, and unless you like wasting pixel density, your -//! framebuffer's size should be in physical pixels. +//! ### Events //! -//! `winit` will send [`Resized`](crate::event::WindowEvent::Resized) events whenever a window's logical size -//! changes, and [`DpiChanged`](crate::event::WindowEvent::DpiChanged) events -//! whenever the scale factor changes. Receiving either of these events means that the physical size of your window has -//! changed, and you should recompute it using the latest values you received for each. If the logical size and the -//! scale factor change simultaneously, `winit` will send both events together; thus, it's recommended to buffer -//! these events and process them at the end of the queue. +//! Winit will dispatch a [`DpiChanged`](crate::event::WindowEvent::DpiChanged) +//! 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 [`DpiChanged`](crate::event::WindowEvent::DpiChanged) event, +//! then its scale factor is `1.0`. //! -//! If you never received any [`DpiChanged`](crate::event::WindowEvent::DpiChanged) events, -//! then your window's scale factor is 1. +//! ## 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][windows_1] 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_FACTOR` environment variable, if present. +//! + If not present, use the value set in `Xft.dpi` in Xresources. +//! + Otherwise, calcuate 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:** 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.0` to `3.0`. See [this article][apple_1] and [this article][apple_2] 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][android_1] for more information. +//! - **Web:** The scale factor is the ratio between CSS pixels and the physical device pixels. +//! +//! [microsoft_dpi]: https://blogs.msdn.microsoft.com/fontblog/2005/11/08/where-does-96-dpi-come-from-in-windows/ +//! [points]: https://en.wikipedia.org/wiki/Point_(typography) +//! [picas]: https://en.wikipedia.org/wiki/Pica_(typography) +//! [windows_1]: https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows +//! [apple_1]: https://developer.apple.com/library/archive/documentation/DeviceInformation/Reference/iOSDeviceCompatibility/Displays/Displays.html +//! [apple_2]: https://developer.apple.com/design/human-interface-guidelines/macos/icons-and-images/image-size-and-resolution/ +//! [android_1]: https://developer.android.com/training/multiscreen/screendensities pub trait Pixel: Copy + Into { fn from_f64(f: f64) -> Self; @@ -136,9 +162,9 @@ pub fn validate_scale_factor(dpi_factor: f64) -> bool { /// A position represented in logical pixels. /// -/// The position is stored as floats, so please be careful. Casting floats to integers truncates the fractional part, -/// which can cause noticable issues. To help with that, an `Into<(i32, i32)>` implementation is provided which -/// does the rounding for you. +/// The position is stored as floats, so please be careful. Casting floats to integers truncates the +/// fractional part, which can cause noticable issues. To help with that, an `Into<(i32, i32)>` +/// implementation is provided which does the rounding for you. #[derive(Debug, Copy, Clone, PartialEq)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub struct LogicalPosition

{ @@ -204,10 +230,6 @@ impl Into<[X; 2]> for LogicalPosition

{ } /// A position represented in physical pixels. -/// -/// The position is stored as floats, so please be careful. Casting floats to integers truncates the fractional part, -/// which can cause noticable issues. To help with that, an `Into<(i32, i32)>` implementation is provided which -/// does the rounding for you. #[derive(Debug, Copy, Clone, PartialEq)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub struct PhysicalPosition

{ @@ -273,10 +295,6 @@ impl Into<[X; 2]> for PhysicalPosition

{ } /// A size represented in logical pixels. -/// -/// The size is stored as floats, so please be careful. Casting floats to integers truncates the fractional part, -/// which can cause noticable issues. To help with that, an `Into<(u32, u32)>` implementation is provided which -/// does the rounding for you. #[derive(Debug, Copy, Clone, PartialEq)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub struct LogicalSize

{ @@ -400,6 +418,7 @@ impl Into<[X; 2]> for PhysicalSize

{ } } +/// A size that's either physical or logical. #[derive(Debug, Copy, Clone, PartialEq)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub enum Size { @@ -441,6 +460,7 @@ impl From> for Size { } } +/// A position that's either physical or logical. #[derive(Debug, Copy, Clone, PartialEq)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub enum Position { diff --git a/src/event.rs b/src/event.rs index 117a4c72..4a61f319 100644 --- a/src/event.rs +++ b/src/event.rs @@ -304,7 +304,7 @@ pub enum WindowEvent<'a> { /// is pointed to by the `new_inner_size` reference. By default, this will contain the size suggested /// by the OS, but it can be changed to any value. /// - /// For more information about DPI in general, see the [`dpi`](dpi/index.html) module. + /// For more information about DPI in general, see the [`dpi`](crate::dpi) module. DpiChanged { scale_factor: f64, new_inner_size: &'a mut PhysicalSize,