From 075dfcea1943e36e98d7910619121559a6e8bbee Mon Sep 17 00:00:00 2001
From: Kirill Chibisov <contact@kchibisov.com>
Date: Sat, 28 Oct 2023 14:23:20 +0400
Subject: [PATCH] Clarify `scale_factor` docs

Wayland scales each window individually, thus make it clear. Also
recommend against using the `MonitorHandle::scale_factor`.

Fixes #3183.
---
 src/dpi.rs     | 3 ++-
 src/monitor.rs | 6 +++++-
 src/window.rs  | 9 ++++++---
 3 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/src/dpi.rs b/src/dpi.rs
index 6d1bc388..2f027b18 100644
--- a/src/dpi.rs
+++ b/src/dpi.rs
@@ -82,7 +82,8 @@
 //!   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:** Scale factor is suggested by the the compositor.
+//! - **Wayland:** 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][apple_1] and [this article][apple_2] for more
 //!   information.
diff --git a/src/monitor.rs b/src/monitor.rs
index 47d32809..45c355e5 100644
--- a/src/monitor.rs
+++ b/src/monitor.rs
@@ -138,14 +138,18 @@ impl MonitorHandle {
         self.inner.refresh_rate_millihertz()
     }
 
-    /// Returns the scale factor that can be used to map logical pixels to physical pixels, and vice versa.
+    /// Returns the scale factor of the underlying monitor. To map logical pixels to physical
+    /// pixels and vice versa, use [`Window::scale_factor`].
     ///
     /// See the [`dpi`](crate::dpi) module for more information.
     ///
     /// ## Platform-specific
     ///
     /// - **X11:** Can be overridden using the `WINIT_X11_SCALE_FACTOR` environment variable.
+    /// - **Wayland:** May differ from [`Window::scale_factor`].
     /// - **Android:** Always returns 1.0.
+    ///
+    /// [`Window::scale_factor`]: crate::window::Window::scale_factor
     #[inline]
     pub fn scale_factor(&self) -> f64 {
         self.inner.scale_factor()
diff --git a/src/window.rs b/src/window.rs
index e3950c34..8251e927 100644
--- a/src/window.rs
+++ b/src/window.rs
@@ -543,14 +543,17 @@ impl Window {
         self.window.maybe_wait_on_main(|w| WindowId(w.id()))
     }
 
-    /// Returns the scale factor that can be used to map logical pixels to physical pixels, and vice versa.
-    ///
-    /// See the [`dpi`](crate::dpi) module for more information.
+    /// Returns the scale factor that can be used to map logical pixels to physical pixels, and
+    /// vice versa.
     ///
     /// Note that this value can change depending on user action (for example if the window is
     /// moved to another screen); as such, tracking [`WindowEvent::ScaleFactorChanged`] events is
     /// the most robust way to track the DPI you need to use to draw.
     ///
+    /// This value may differ from [`MonitorHandle::scale_factor`].
+    ///
+    /// See the [`dpi`](crate::dpi) module for more information.
+    ///
     /// ## Platform-specific
     ///
     /// - **X11:** This respects Xft.dpi, and can be overridden using the `WINIT_X11_SCALE_FACTOR` environment variable.