feat: Add a safe method for cross-crate interop to winit

CHANGELOG.md

@@ -9,6 +9,7 @@ And please only add new entries to the top of this list, right below the `# Unre
 # Unreleased
 
 - Bump MSRV from `1.60` to `1.64`.
+- Implement the borrowed handle traits from the `raw-window-handle` crate.
 
 # 0.28.3
 

Cargo.toml

@@ -42,8 +42,8 @@ wayland-dlopen = ["sctk/dlopen", "wayland-client/dlopen"]
 wayland-csd-adwaita = ["sctk-adwaita", "sctk-adwaita/ab_glyph"]
 wayland-csd-adwaita-crossfont = ["sctk-adwaita", "sctk-adwaita/crossfont"]
 wayland-csd-adwaita-notitle = ["sctk-adwaita"]
-android-native-activity = [ "android-activity/native-activity" ]
-android-game-activity = [ "android-activity/game-activity" ]
+android-native-activity = ["android-activity/native-activity"]
+android-game-activity = ["android-activity/game-activity"]
 
 [build-dependencies]
 cfg_aliases = "0.1.1"
@@ -54,7 +54,7 @@ instant = { version = "0.1", features = ["wasm-bindgen"] }
 log = "0.4"
 mint = { version = "0.5.6", optional = true }
 once_cell = "1.12"
-raw_window_handle = { package = "raw-window-handle", version = "0.5" }
+raw_window_handle = { package = "raw-window-handle", version = "0.5.2", features = ["std"] }
 serde = { version = "1", optional = true, features = ["serde_derive"] }
 
 [dev-dependencies]

examples/borrowed_window.rs

@@ -0,0 +1,47 @@
+//! Use borrowed window handles in `winit`.
+
+#![allow(clippy::single_match)]
+
+use raw_window_handle::{HasDisplayHandle, HasWindowHandle};
+use simple_logger::SimpleLogger;
+use winit::{
+    event::{Event, WindowEvent},
+    event_loop::EventLoop,
+    window::WindowBuilder,
+};
+
+fn main() {
+    SimpleLogger::new().init().unwrap();
+    let event_loop = EventLoop::new();
+
+    let window = WindowBuilder::new()
+        .with_title("A borrowed window!")
+        .with_inner_size(winit::dpi::LogicalSize::new(128.0, 128.0))
+        .build(&event_loop)
+        .unwrap();
+
+    event_loop.run(move |event, elwt, control_flow| {
+        control_flow.set_wait();
+        println!("{event:?}");
+
+        // Print the display handle.
+        println!("Display handle: {:?}", elwt.display_handle());
+
+        // Print the window handle.
+        match window.window_handle() {
+            Ok(handle) => println!("Window handle: {:?}", handle),
+            Err(_) => println!("Window handle: None"),
+        }
+
+        match event {
+            Event::WindowEvent {
+                event: WindowEvent::CloseRequested,
+                window_id,
+            } if window_id == window.id() => control_flow.set_exit(),
+            Event::MainEventsCleared => {
+                window.request_redraw();
+            }
+            _ => (),
+        }
+    });
+}

src/event_loop.rs

@@ -13,7 +13,9 @@ use std::{error, fmt};
 
 use instant::{Duration, Instant};
 use once_cell::sync::OnceCell;
-use raw_window_handle::{HasRawDisplayHandle, RawDisplayHandle};
+use raw_window_handle::{
+    DisplayHandle, HandleError, HasDisplayHandle, HasRawDisplayHandle, RawDisplayHandle,
+};
 
 use crate::{event::Event, monitor::MonitorHandle, platform_impl};
 
@@ -48,6 +50,71 @@ pub struct EventLoopWindowTarget<T: 'static> {
     pub(crate) _marker: PhantomData<*mut ()>, // Not Send nor Sync
 }
 
+/// Target that provides a handle to the display powering the event loop.
+///
+/// This type allows one to take advantage of the display's capabilities, such as
+/// querying the display's resolution or DPI, without having to create a window. It
+/// implements [`HasDisplayHandle`].
+///
+/// The main reason why this type exists is to act as a persistent display handle
+/// in cases where the [`Window`] type is not available. Let's say that your graphics
+/// framework has a type `Display<T>`, where `T` has to implement [`HasDisplayHandle`]
+/// so that the graphics framework can query it for data and be sure that the display is
+/// still alive. Also assume that `Display<T>` is somewhat expensive to construct, so
+/// you cannot just create a new `Display<T>` every time you need to render.
+/// Therefore, you need a *persistent* handle to the display to pass in as `T`. This
+/// handle cannot be invalidated by the borrow checker during the lifetime of the
+/// program; otherwise, you would have to drop the `Display<T>` and recreate it
+/// every time you need to render, which would be very expensive.
+///
+/// The [`EventLoop`] type is either owned or borrowed mutably during event
+/// handling. Therefore, neither [`EventLoop`], `&EventLoop` or a [`DisplayHandle`]
+/// referencing an [`EventLoop`] can be used to provide a [`HasDisplayHandle`]
+/// implementation. On the other hand, the [`EventLoopWindowTarget`] type disappears
+/// between events so it can't be used as a persistent handle either. In certain
+/// cases, you can use a [`Window`]; however, for certain graphics APIs (like OpenGL)
+/// you need to be able to query the display before creating a window. In this case,
+/// you end up with a "chicken and egg" problem; you need a display handle to create
+/// a window, but you need a window to access the display handle.
+///
+/// ![A chicken](https://i.imgur.com/9a5K2nz.jpg)
+///
+/// <sub>Figure 1: A chicken, representing the window in the above metaphor. Note that
+/// there are no eggs. "[Chicken February 2009-1]" by [Joaquim Alves Gaspar] is licensed
+/// under [CC BY-SA 3.0].</sub>
+///
+/// The `OwnedDisplayHandle` type breaks this cycle by providing a persistent handle
+/// to the display. It is not tied to any lifetime constraints, so it can't be
+/// invalidated during event handling. It is also cheaply clonable, so you can
+/// more easily pass it around to other parts of your program. Therefore, it can
+/// be passed in as `T` to your graphics framework's `Display<T>` type without
+/// worrying about the borrow checker.
+///
+/// To create an `OwnedDisplayHandle`, use the [`EventLoopWindowTarget::owned_display_handle`]
+/// method.
+///
+/// ## Safety
+///
+/// The [`DisplayHandle`] returned by the `OwnedDisplayHandle` type is guaranteed to
+/// remain valid as long as the `OwnedDisplayHandle` is alive. The internal display
+/// handle is not immediately closed by the [`EventLoop`] being dropped as long as
+/// the `OwnedDisplayHandle` is still alive. On all platforms, the underlying display
+/// is either ref-counted or a ZST, so this is safe.
+///
+/// [Chicken February 2009-1]: https://commons.wikimedia.org/wiki/File:Chicken_February_2009-1.jpg
+/// [Joaquim Alves Gaspar]: https://commons.wikimedia.org/wiki/User:Alvesgaspar
+/// [CC BY-SA 3.0]: https://creativecommons.org/licenses/by-sa/3.0
+/// [`EventLoop`]: EventLoop
+/// [`Window`]: crate::window::Window
+/// [`DisplayHandle`]: raw_window_handle::DisplayHandle
+/// [`EventLoopWindowTarget`]: EventLoopWindowTarget
+/// [`HasDisplayHandle`]: raw_window_handle::HasDisplayHandle
+#[derive(Clone)]
+pub struct OwnedDisplayHandle {
+    pub(crate) p: platform_impl::OwnedDisplayHandle,
+    pub(crate) _marker: PhantomData<*mut ()>, // Not Send nor Sync
+}
+
 /// Object that allows building the event loop.
 ///
 /// This is used to make specifying options that affect the whole application
@@ -320,6 +387,12 @@ unsafe impl<T> HasRawDisplayHandle for EventLoop<T> {
     }
 }
 
+impl<T> HasDisplayHandle for EventLoop<T> {
+    fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError> {
+        self.event_loop.window_target().display_handle()
+    }
+}
+
 impl<T> Deref for EventLoop<T> {
     type Target = EventLoopWindowTarget<T>;
     fn deref(&self) -> &EventLoopWindowTarget<T> {
@@ -367,6 +440,28 @@ impl<T> EventLoopWindowTarget<T> {
         #[cfg(any(x11_platform, wayland_platform, windows))]
         self.p.set_device_event_filter(_filter);
     }
+
+    /// Get an owned handle to the current display.
+    ///
+    /// This handle can be cheaply cloned and used, allowing one to fulfill the [`HasDisplayHandle`]
+    /// trait bound.
+    ///
+    /// For more information, see documentation for [`OwnedDisplayHandle`] and the
+    /// [`HasDisplayHandle`] trait.
+    ///
+    /// ## Example
+    ///
+    /// ```no_run
+    /// use winit::event_loop::EventLoop;
+    ///
+    /// let event_loop = EventLoop::new();
+    /// let display_handle = event_loop.owned_display_handle();
+    /// ```
+    ///
+    /// [`HasDisplayHandle`]: raw_window_handle::HasDisplayHandle
+    pub fn owned_display_handle(&self) -> &OwnedDisplayHandle {
+        self.p.owned_display_handle()
+    }
 }
 
 unsafe impl<T> HasRawDisplayHandle for EventLoopWindowTarget<T> {
@@ -376,6 +471,27 @@ unsafe impl<T> HasRawDisplayHandle for EventLoopWindowTarget<T> {
     }
 }
 
+impl<T> HasDisplayHandle for EventLoopWindowTarget<T> {
+    fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError> {
+        // SAFETY: The display handle is valid for as long as the window target is.
+        Ok(unsafe { DisplayHandle::borrow_raw(self.raw_display_handle()) })
+    }
+}
+
+unsafe impl HasRawDisplayHandle for OwnedDisplayHandle {
+    /// Returns a [`raw_window_handle::RawDisplayHandle`] for the event loop.
+    fn raw_display_handle(&self) -> RawDisplayHandle {
+        self.p.raw_display_handle()
+    }
+}
+
+impl HasDisplayHandle for OwnedDisplayHandle {
+    fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError> {
+        // SAFETY: The display handle is valid for as long as the window target is.
+        Ok(unsafe { DisplayHandle::borrow_raw(self.raw_display_handle()) })
+    }
+}
+
 /// Used to send custom events to [`EventLoop`].
 pub struct EventLoopProxy<T: 'static> {
     event_loop_proxy: platform_impl::EventLoopProxy<T>,

src/platform_impl/android/mod.rs

@@ -16,7 +16,7 @@ use android_activity::{
 };
 use once_cell::sync::Lazy;
 use raw_window_handle::{
-    AndroidDisplayHandle, HasRawWindowHandle, RawDisplayHandle, RawWindowHandle,
+    Active, AndroidDisplayHandle, HasRawWindowHandle, RawDisplayHandle, RawWindowHandle,
 };
 
 use crate::platform_impl::Fullscreen;
@@ -340,6 +340,7 @@ impl<T: 'static> EventLoop<T> {
                         &redraw_flag,
                         android_app.create_waker(),
                     ),
+                    active: Arc::new(Active::new()),
                     _marker: std::marker::PhantomData,
                 },
                 _marker: std::marker::PhantomData,
@@ -378,6 +379,11 @@ impl<T: 'static> EventLoop<T> {
 
             match event {
                 MainEvent::InitWindow { .. } => {
+                    // SAFETY: The window is now active.
+                    unsafe {
+                        self.window_target.p.active.set_active();
+                    }
+
                     sticky_exit_callback(
                         event::Event::Resumed,
                         self.window_target(),
@@ -392,6 +398,8 @@ impl<T: 'static> EventLoop<T> {
                         control_flow,
                         callback,
                     );
+
+                    self.window_target.p.active.set_inactive();
                 }
                 MainEvent::WindowResized { .. } => resized = true,
                 MainEvent::RedrawNeeded { .. } => *pending_redraw = true,
@@ -821,6 +829,7 @@ impl<T> EventLoopProxy<T> {
 pub struct EventLoopWindowTarget<T: 'static> {
     app: AndroidApp,
     redraw_requester: RedrawRequester,
+    active: Arc<Active>,
     _marker: std::marker::PhantomData<T>,
 }
 
@@ -838,6 +847,22 @@ impl<T: 'static> EventLoopWindowTarget<T> {
     pub fn raw_display_handle(&self) -> RawDisplayHandle {
         RawDisplayHandle::Android(AndroidDisplayHandle::empty())
     }
+
+    pub fn owned_display_handle(&self) -> &event_loop::OwnedDisplayHandle {
+        &event_loop::OwnedDisplayHandle {
+            p: OwnedDisplayHandle,
+            _marker: std::marker::PhantomData,
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct OwnedDisplayHandle;
+
+impl OwnedDisplayHandle {
+    pub fn raw_display_handle(&self) -> RawDisplayHandle {
+        RawDisplayHandle::Android(AndroidDisplayHandle::empty())
+    }
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
@@ -876,6 +901,7 @@ pub struct PlatformSpecificWindowBuilderAttributes;
 pub(crate) struct Window {
     app: AndroidApp,
     redraw_requester: RedrawRequester,
+    active: Arc<Active>,
 }
 
 impl Window {
@@ -889,6 +915,7 @@ impl Window {
         Ok(Self {
             app: el.app.clone(),
             redraw_requester: el.redraw_requester.clone(),
+            active: el.active.clone(),
         })
     }
 
@@ -1084,6 +1111,10 @@ impl Window {
     pub fn title(&self) -> String {
         String::new()
     }
+
+    pub(crate) fn active(&self) -> &Active {
+        &self.active
+    }
 }
 
 #[derive(Default, Clone, Debug)]

src/platform_impl/ios/event_loop.rs

@@ -65,6 +65,22 @@ impl<T: 'static> EventLoopWindowTarget<T> {
     pub fn raw_display_handle(&self) -> RawDisplayHandle {
         RawDisplayHandle::UiKit(UiKitDisplayHandle::empty())
     }
+
+    pub fn owned_display_handle(&self) -> &crate::event_loop::OwnedDisplayHandle {
+        &crate::event_loop::OwnedDisplayHandle {
+            p: OwnedDisplayHandle,
+            _marker: PhantomData,
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct OwnedDisplayHandle;
+
+impl OwnedDisplayHandle {
+    pub fn raw_display_handle(&self) -> RawDisplayHandle {
+        RawDisplayHandle::UiKit(UiKitDisplayHandle::empty())
+    }
 }
 
 pub struct EventLoop<T: 'static> {

src/platform_impl/ios/mod.rs

@@ -81,7 +81,8 @@ use std::fmt;
 
 pub(crate) use self::{
     event_loop::{
-        EventLoop, EventLoopProxy, EventLoopWindowTarget, PlatformSpecificEventLoopAttributes,
+        EventLoop, EventLoopProxy, EventLoopWindowTarget, OwnedDisplayHandle,
+        PlatformSpecificEventLoopAttributes,
     },
     monitor::{MonitorHandle, VideoMode},
     window::{PlatformSpecificWindowBuilderAttributes, Window, WindowId},

src/platform_impl/linux/mod.rs

@@ -685,6 +685,14 @@ pub enum EventLoopProxy<T: 'static> {
     Wayland(wayland::EventLoopProxy<T>),
 }
 
+#[derive(Clone)]
+pub enum OwnedDisplayHandle {
+    #[cfg(x11_platform)]
+    X(x11::OwnedDisplayHandle),
+    #[cfg(wayland_platform)]
+    Wayland(wayland::OwnedDisplayHandle),
+}
+
 impl<T: 'static> Clone for EventLoopProxy<T> {
     fn clone(&self) -> Self {
         x11_or_wayland!(match self; EventLoopProxy(proxy) => proxy.clone(); as EventLoopProxy)
@@ -866,6 +874,21 @@ impl<T> EventLoopWindowTarget<T> {
     pub fn raw_display_handle(&self) -> raw_window_handle::RawDisplayHandle {
         x11_or_wayland!(match self; Self(evlp) => evlp.raw_display_handle())
     }
+
+    pub fn owned_display_handle(&self) -> &crate::event_loop::OwnedDisplayHandle {
+        match self {
+            #[cfg(wayland_platform)]
+            EventLoopWindowTarget::Wayland(evlp) => evlp.owned_display_handle(),
+            #[cfg(x11_platform)]
+            EventLoopWindowTarget::X(evlp) => evlp.owned_display_handle(),
+        }
+    }
+}
+
+impl OwnedDisplayHandle {
+    pub fn raw_display_handle(&self) -> raw_window_handle::RawDisplayHandle {
+        x11_or_wayland!(match self; Self(evlp) => evlp.raw_display_handle())
+    }
 }
 
 fn sticky_exit_callback<T, F>(