winit_core/
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//! - [`ActiveEventLoop::available_monitors`][crate::event_loop::ActiveEventLoop::available_monitors].
7//! - [`Window::available_monitors`][crate::window::Window::available_monitors].
8use std::any::Any;
9use std::borrow::Cow;
10use std::fmt;
11use std::num::{NonZeroU16, NonZeroU32};
12use std::ops::Deref;
13use std::sync::Arc;
14
15use dpi::{PhysicalPosition, PhysicalSize};
16
17/// Handle to a monitor.
18///
19/// Allows you to retrieve basic information and metadata about a monitor.
20///
21/// Can be used in [`Window`] creation to place the window on a specific
22/// monitor.
23///
24/// This can be retrieved from one of the following methods, which return an
25/// iterator of [`MonitorHandle`]s:
26/// - [`ActiveEventLoop::available_monitors`](crate::event_loop::ActiveEventLoop::available_monitors).
27/// - [`Window::available_monitors`](crate::window::Window::available_monitors).
28///
29/// ## Platform-specific
30///
31/// **Web:** A [`MonitorHandle`] created without `detailed monitor permissions`
32/// will always represent the current monitor the browser window is in instead of a specific
33/// monitor.
34///
35/// [`Window`]: crate::window::Window
36#[derive(Debug, Clone)]
37pub struct MonitorHandle(pub Arc<dyn MonitorHandleProvider>);
38
39impl Deref for MonitorHandle {
40    type Target = dyn MonitorHandleProvider;
41
42    fn deref(&self) -> &Self::Target {
43        self.0.as_ref()
44    }
45}
46
47impl PartialEq for MonitorHandle {
48    fn eq(&self, other: &Self) -> bool {
49        self.0.as_ref().eq(other.0.as_ref())
50    }
51}
52
53impl Eq for MonitorHandle {}
54
55/// Provider of the [`MonitorHandle`].
56pub trait MonitorHandleProvider: Any + fmt::Debug + Send + Sync {
57    /// Identifier for this monitor.
58    ///
59    /// The representation of this modifier is not guaranteed and should be used only to compare
60    /// monitors.
61    fn id(&self) -> u128;
62
63    /// Native platform identifier of this monitor.
64    ///
65    /// # Platform-specific
66    ///
67    /// - **Windows**: This is `HMONITOR`.
68    /// - **macOS**: This is `CGDirectDisplayID`.
69    /// - **iOS**: This is `UIScreen*`.
70    /// - **Wayland**: This is the ID of the `wl_output` device.
71    /// - **X11**: This is the ID of the CRTC.
72    /// - **Web**: This is an internal ID not meant for consumption.
73    fn native_id(&self) -> u64;
74
75    /// Returns a human-readable name of the monitor.
76    ///
77    /// Returns `None` if the monitor doesn't exist anymore or the name couldn't be obtained.
78    ///
79    ///
80    /// ## Platform-specific
81    ///
82    /// **Web:** Always returns [`None`] without `detailed monitor permissions`.
83    fn name(&self) -> Option<Cow<'_, str>>;
84
85    /// Returns the top-left corner position of the monitor in desktop coordinates.
86    ///
87    /// This position is in the same coordinate system as [`Window::outer_position`].
88    ///
89    /// [`Window::outer_position`]: crate::window::Window::outer_position
90    ///
91    /// ## Platform-specific
92    ///
93    /// **Web:** Always returns [`None`] without `detailed monitor permissions`.
94    fn position(&self) -> Option<PhysicalPosition<i32>>;
95
96    /// Returns the scale factor of the underlying monitor. To map logical pixels to physical
97    /// pixels and vice versa, use [`Window::scale_factor`].
98    ///
99    /// See the [`dpi`] module for more information.
100    ///
101    /// - **Wayland:** May differ from [`Window::scale_factor`].
102    /// - **Web:** Always returns `0.0` without `detailed_monitor_permissions`.
103    ///
104    /// [`Window::scale_factor`]: crate::window::Window::scale_factor
105    fn scale_factor(&self) -> f64;
106
107    fn current_video_mode(&self) -> Option<VideoMode>;
108
109    /// Returns all fullscreen video modes supported by this monitor.
110    fn video_modes(&self) -> Box<dyn Iterator<Item = VideoMode>>;
111}
112
113impl PartialEq for dyn MonitorHandleProvider + '_ {
114    fn eq(&self, other: &Self) -> bool {
115        self.id() == other.id()
116    }
117}
118
119impl Eq for dyn MonitorHandleProvider + '_ {}
120
121impl_dyn_casting!(MonitorHandleProvider);
122
123/// Describes a fullscreen video mode of a monitor.
124///
125/// Can be acquired with [`MonitorHandleProvider::video_modes`].
126#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
127pub struct VideoMode {
128    pub(crate) size: PhysicalSize<u32>,
129    pub(crate) bit_depth: Option<NonZeroU16>,
130    pub(crate) refresh_rate_millihertz: Option<NonZeroU32>,
131}
132
133impl VideoMode {
134    pub fn new(
135        size: PhysicalSize<u32>,
136        bit_depth: Option<NonZeroU16>,
137        refresh_rate_millihertz: Option<NonZeroU32>,
138    ) -> Self {
139        Self { size, bit_depth, refresh_rate_millihertz }
140    }
141
142    /// Returns the resolution of this video mode. This **must not** be used to create your
143    /// rendering surface. Use [`Window::surface_size()`] instead.
144    ///
145    /// [`Window::surface_size()`]: crate::window::Window::surface_size
146    pub fn size(&self) -> PhysicalSize<u32> {
147        self.size
148    }
149
150    /// Returns the bit depth of this video mode, as in how many bits you have
151    /// available per color. This is generally 24 bits or 32 bits on modern
152    /// systems, depending on whether the alpha channel is counted or not.
153    ///
154    /// # Platform-specific
155    ///
156    /// - **macOS**: Video modes do not control the bit depth of the monitor, so this often defaults
157    ///   to 32.
158    /// - **iOS**: Always returns `None`.
159    /// - **Wayland**: Always returns `None`.
160    pub fn bit_depth(&self) -> Option<NonZeroU16> {
161        self.bit_depth
162    }
163
164    /// Returns the refresh rate of this video mode in mHz.
165    pub fn refresh_rate_millihertz(&self) -> Option<NonZeroU32> {
166        self.refresh_rate_millihertz
167    }
168}
169
170impl fmt::Display for VideoMode {
171    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
172        write!(
173            f,
174            "{}x{} {}{}",
175            self.size.width,
176            self.size.height,
177            self.refresh_rate_millihertz.map(|rate| format!("@ {rate} mHz ")).unwrap_or_default(),
178            self.bit_depth.map(|bit_depth| format!("({bit_depth} bpp)")).unwrap_or_default(),
179        )
180    }
181}
182
183/// Fullscreen modes.
184#[derive(Clone, Debug, PartialEq, Eq)]
185#[non_exhaustive]
186pub enum Fullscreen {
187    Exclusive(MonitorHandle, VideoMode),
188
189    /// Providing `None` to `Borderless` will fullscreen on the current monitor.
190    Borderless(Option<MonitorHandle>),
191}
winit_core/monitor.rs

winit_core/
monitor.rs
