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/window.rs

@@ -1,5 +1,6 @@
 #![allow(clippy::single_match)]
 
+use raw_window_handle::{HasDisplayHandle, HasWindowHandle};
 use simple_logger::SimpleLogger;
 use winit::{
     event::{Event, WindowEvent},
@@ -17,10 +18,19 @@ fn main() {
         .build(&event_loop)
         .unwrap();
 
-    event_loop.run(move |event, _, control_flow| {
+    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,

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,73 @@ 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 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`] is not created yet. 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.
+///
+/// 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.
+///
+/// [`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,
+
+    /// Make sure that the display handle is !Send and !Sync.
+    ///
+    /// ```compile_fail
+    /// fn foo<T: Send>() {}
+    /// foo::<winit::event_loop::OwnedDisplayHandle>();
+    /// ```
+    ///
+    /// ```compile_fail
+    /// fn foo<T: Sync>() {}
+    /// foo::<winit::event_loop::OwnedDisplayHandle>();
+    /// ```
+    pub(crate) _marker: PhantomData<*mut ()>,
+}
+
 /// Object that allows building the event loop.
 ///
 /// This is used to make specifying options that affect the whole application
@@ -320,6 +389,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 +442,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 +473,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>,
 }
 
@@ -836,7 +845,23 @@ impl<T: 'static> EventLoopWindowTarget<T> {
     }
 
     pub fn raw_display_handle(&self) -> RawDisplayHandle {
-        RawDisplayHandle::Android(AndroidDisplayHandle::empty())
+        AndroidDisplayHandle::empty().into()
+    }
+
+    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 {
+        AndroidDisplayHandle::empty().into()
     }
 }
 
@@ -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(),
         })
     }
 
@@ -1060,7 +1087,7 @@ impl Window {
     }
 
     pub fn raw_display_handle(&self) -> RawDisplayHandle {
-        RawDisplayHandle::Android(AndroidDisplayHandle::empty())
+        AndroidDisplayHandle::empty().into()
     }
 
     pub fn config(&self) -> ConfigurationRef {
@@ -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

@@ -63,7 +63,23 @@ impl<T: 'static> EventLoopWindowTarget<T> {
     }
 
     pub fn raw_display_handle(&self) -> RawDisplayHandle {
-        RawDisplayHandle::UiKit(UiKitDisplayHandle::empty())
+        UiKitDisplayHandle::empty().into()
+    }
+
+    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 {
+        UiKitDisplayHandle::empty().into()
     }
 }
 

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/ios/window.rs

@@ -343,11 +343,11 @@ impl Inner {
         window_handle.ui_window = Id::as_ptr(&self.window) as _;
         window_handle.ui_view = Id::as_ptr(&self.view) as _;
         window_handle.ui_view_controller = Id::as_ptr(&self.view_controller) as _;
-        RawWindowHandle::UiKit(window_handle)
+        window_handle.into()
     }
 
     pub fn raw_display_handle(&self) -> RawDisplayHandle {
-        RawDisplayHandle::UiKit(UiKitDisplayHandle::empty())
+        UiKitDisplayHandle::empty().into()
     }
 
     pub fn theme(&self) -> Option<Theme> {