winit/
monitor.rs

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

winit/
monitor.rs
