winit/
monitor.rs

1//! Types useful for interacting with a user's monitors.
2//!
3//! If you want to get basic information about a monitor, you can use the
4//! [`MonitorHandle`] type. This is retrieved from one of the following
5//! methods, which return an iterator of [`MonitorHandle`]:
6//! - [`EventLoopWindowTarget::available_monitors`](crate::event_loop::EventLoopWindowTarget::available_monitors).
7//! - [`Window::available_monitors`](crate::window::Window::available_monitors).
8use crate::{
9    dpi::{PhysicalPosition, PhysicalSize},
10    platform_impl,
11};
12
13/// Describes a fullscreen video mode of a monitor.
14///
15/// Can be acquired with [`MonitorHandle::video_modes`].
16#[derive(Clone, PartialEq, Eq, Hash)]
17pub struct VideoMode {
18    pub(crate) video_mode: platform_impl::VideoMode,
19}
20
21impl std::fmt::Debug for VideoMode {
22    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
23        self.video_mode.fmt(f)
24    }
25}
26
27impl PartialOrd for VideoMode {
28    fn partial_cmp(&self, other: &VideoMode) -> Option<std::cmp::Ordering> {
29        Some(self.cmp(other))
30    }
31}
32
33impl Ord for VideoMode {
34    fn cmp(&self, other: &VideoMode) -> std::cmp::Ordering {
35        // TODO: we can impl `Ord` for `PhysicalSize` once we switch from `f32`
36        // to `u32` there
37        let size: (u32, u32) = self.size().into();
38        let other_size: (u32, u32) = other.size().into();
39        self.monitor().cmp(&other.monitor()).then(
40            size.cmp(&other_size)
41                .then(
42                    self.refresh_rate_millihertz()
43                        .cmp(&other.refresh_rate_millihertz())
44                        .then(self.bit_depth().cmp(&other.bit_depth())),
45                )
46                .reverse(),
47        )
48    }
49}
50
51impl VideoMode {
52    /// Returns the resolution of this video mode.
53    #[inline]
54    pub fn size(&self) -> PhysicalSize<u32> {
55        self.video_mode.size()
56    }
57
58    /// Returns the bit depth of this video mode, as in how many bits you have
59    /// available per color. This is generally 24 bits or 32 bits on modern
60    /// systems, depending on whether the alpha channel is counted or not.
61    ///
62    /// ## Platform-specific
63    ///
64    /// - **Wayland / Orbital:** Always returns 32.
65    /// - **iOS:** Always returns 32.
66    #[inline]
67    pub fn bit_depth(&self) -> u16 {
68        self.video_mode.bit_depth()
69    }
70
71    /// Returns the refresh rate of this video mode in mHz.
72    #[inline]
73    pub fn refresh_rate_millihertz(&self) -> u32 {
74        self.video_mode.refresh_rate_millihertz()
75    }
76
77    /// Returns the monitor that this video mode is valid for. Each monitor has
78    /// a separate set of valid video modes.
79    #[inline]
80    pub fn monitor(&self) -> MonitorHandle {
81        MonitorHandle {
82            inner: self.video_mode.monitor(),
83        }
84    }
85}
86
87impl std::fmt::Display for VideoMode {
88    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
89        write!(
90            f,
91            "{}x{} @ {} mHz ({} bpp)",
92            self.size().width,
93            self.size().height,
94            self.refresh_rate_millihertz(),
95            self.bit_depth()
96        )
97    }
98}
99
100/// Handle to a monitor.
101///
102/// Allows you to retrieve information about a given monitor and can be used in [`Window`] creation.
103///
104/// [`Window`]: crate::window::Window
105#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
106pub struct MonitorHandle {
107    pub(crate) inner: platform_impl::MonitorHandle,
108}
109
110impl MonitorHandle {
111    /// Returns a human-readable name of the monitor.
112    ///
113    /// Returns `None` if the monitor doesn't exist anymore.
114    ///
115    /// ## Platform-specific
116    ///
117    /// - **Web:** Always returns None
118    #[inline]
119    pub fn name(&self) -> Option<String> {
120        self.inner.name()
121    }
122
123    /// Returns the monitor's resolution.
124    ///
125    /// ## Platform-specific
126    ///
127    /// - **Web:** Always returns (0,0)
128    #[inline]
129    pub fn size(&self) -> PhysicalSize<u32> {
130        self.inner.size()
131    }
132
133    /// Returns the top-left corner position of the monitor relative to the larger full
134    /// screen area.
135    ///
136    /// ## Platform-specific
137    ///
138    /// - **Web:** Always returns (0,0)
139    #[inline]
140    pub fn position(&self) -> PhysicalPosition<i32> {
141        self.inner.position()
142    }
143
144    /// The monitor refresh rate used by the system.
145    ///
146    /// Return `Some` if succeed, or `None` if failed, which usually happens when the monitor
147    /// the window is on is removed.
148    ///
149    /// When using exclusive fullscreen, the refresh rate of the [`VideoMode`] that was used to
150    /// enter fullscreen should be used instead.
151    #[inline]
152    pub fn refresh_rate_millihertz(&self) -> Option<u32> {
153        self.inner.refresh_rate_millihertz()
154    }
155
156    /// Returns the scale factor that can be used to map logical pixels to physical pixels, and vice versa.
157    ///
158    /// See the [`dpi`](crate::dpi) module for more information.
159    ///
160    /// ## Platform-specific
161    ///
162    /// - **X11:** Can be overridden using the `WINIT_X11_SCALE_FACTOR` environment variable.
163    /// - **Android:** Always returns 1.0.
164    /// - **Web:** Always returns 1.0
165    #[inline]
166    pub fn scale_factor(&self) -> f64 {
167        self.inner.scale_factor()
168    }
169
170    /// Returns all fullscreen video modes supported by this monitor.
171    ///
172    /// ## Platform-specific
173    ///
174    /// - **Web:** Always returns an empty iterator
175    #[inline]
176    pub fn video_modes(&self) -> impl Iterator<Item = VideoMode> {
177        self.inner
178            .video_modes()
179            .map(|video_mode| VideoMode { video_mode })
180    }
181}
winit/monitor.rs

winit/
monitor.rs
