feat: Add ability to get underlying window handle

Adds the `get_ref` and `get_mut` functions, which can be used to get
references (mutable or otherwise) to the underlying window handle.

cc https://github.com/rust-windowing/raw-window-handle/issues/158#issuecomment-1881376603

Signed-off-by: John Nunley <dev@notgull.net>

src/cg.rs

@@ -30,7 +30,7 @@ pub struct CGImpl<D, W> {
     window: id,
     color_space: CGColorSpace,
     size: Option<(NonZeroU32, NonZeroU32)>,
-    _window_source: W,
+    window_handle: W,
     _display: PhantomData<D>,
 }
 
@@ -62,10 +62,16 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> CGImpl<D, W> {
             color_space,
             size: None,
             _display: PhantomData,
-            _window_source: window_src,
+            window_handle: window_src,
         })
     }
 
+    /// Get the inner window handle.
+    #[inline]
+    pub fn window(&self) -> &W {
+        &self.window_handle
+    }
+
     pub fn resize(&mut self, width: NonZeroU32, height: NonZeroU32) -> Result<(), SoftBufferError> {
         self.size = Some((width, height));
         Ok(())

src/kms.rs

@@ -73,7 +73,7 @@ pub(crate) struct KmsImpl<D: ?Sized, W: ?Sized> {
     buffer: Option<Buffers>,
 
     /// Window handle that we are keeping around.
-    _window: W,
+    window_handle: W,
 }
 
 #[derive(Debug)]
@@ -200,10 +200,16 @@ impl<D: ?Sized, W: HasWindowHandle> KmsImpl<D, W> {
             connectors,
             display,
             buffer: None,
-            _window: window,
+            window_handle: window,
         })
     }
 
+    /// Get the inner window handle.
+    #[inline]
+    pub fn window(&self) -> &W {
+        &self.window_handle
+    }
+
     /// Resize the internal buffer to the given size.
     pub(crate) fn resize(
         &mut self,

src/lib.rs

@@ -86,6 +86,15 @@ macro_rules! make_dispatch {
         }
 
         impl<D: HasDisplayHandle, W: HasWindowHandle> SurfaceDispatch<D, W> {
+            fn window(&self) -> &W {
+                match self {
+                    $(
+                        $(#[$attr])*
+                        Self::$name(inner) => inner.window(),
+                    )*
+                }
+            }
+
             pub fn resize(&mut self, width: NonZeroU32, height: NonZeroU32) -> Result<(), SoftBufferError> {
                 match self {
                     $(
@@ -311,6 +320,11 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> Surface<D, W> {
         })
     }
 
+    /// Get a reference to the underlying window handle.
+    pub fn window(&self) -> &W {
+        self.surface_impl.window()
+    }
+
     /// Set the size of the buffer that will be returned by [`Surface::buffer_mut`].
     ///
     /// If the size of the buffer does not match the size of the window, the buffer is drawn
@@ -350,6 +364,22 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> Surface<D, W> {
     }
 }
 
+impl<D: HasDisplayHandle, W: HasWindowHandle> AsRef<W> for Surface<D, W> {
+    #[inline]
+    fn as_ref(&self) -> &W {
+        self.window()
+    }
+}
+
+impl<D: HasDisplayHandle, W: HasWindowHandle> HasWindowHandle for Surface<D, W> {
+    #[inline]
+    fn window_handle(
+        &self,
+    ) -> Result<raw_window_handle::WindowHandle<'_>, raw_window_handle::HandleError> {
+        self.window().window_handle()
+    }
+}
+
 /// A buffer that can be written to by the CPU and presented to the window.
 ///
 /// This derefs to a `[u32]`, which depending on the backend may be a mapping into shared memory

src/orbital.rs

@@ -59,7 +59,7 @@ pub struct OrbitalImpl<D, W> {
     width: u32,
     height: u32,
     presented: bool,
-    _window_source: W,
+    window_handle: W,
     _display: PhantomData<D>,
 }
 
@@ -76,11 +76,17 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> OrbitalImpl<D, W> {
             width: 0,
             height: 0,
             presented: false,
-            _window_source: window,
+            window_handle: window,
             _display: PhantomData,
         })
     }
 
+    /// Get the inner window handle.
+    #[inline]
+    pub fn window(&self) -> &W {
+        &self.window_handle
+    }
+
     pub fn resize(&mut self, width: NonZeroU32, height: NonZeroU32) -> Result<(), SoftBufferError> {
         let width = width.get();
         let height = height.get();

src/wayland/mod.rs

@@ -83,7 +83,7 @@ pub struct WaylandImpl<D: ?Sized, W: ?Sized> {
     ///
     /// This has to be dropped *after* the `surface` field, because the `surface` field implicitly
     /// borrows this.
-    _window: W,
+    window_handle: W,
 }
 
 impl<D: HasDisplayHandle + ?Sized, W: HasWindowHandle> WaylandImpl<D, W> {
@@ -109,10 +109,16 @@ impl<D: HasDisplayHandle + ?Sized, W: HasWindowHandle> WaylandImpl<D, W> {
             surface: Some(surface),
             buffers: Default::default(),
             size: None,
-            _window: window,
+            window_handle: window,
         })
     }
 
+    /// Get the inner window handle.
+    #[inline]
+    pub fn window(&self) -> &W {
+        &self.window_handle
+    }
+
     pub fn resize(&mut self, width: NonZeroU32, height: NonZeroU32) -> Result<(), SoftBufferError> {
         self.size = Some(
             (|| {

src/web.rs

@@ -57,7 +57,7 @@ pub struct WebImpl<D, W> {
     size: Option<(NonZeroU32, NonZeroU32)>,
 
     /// The underlying window handle.
-    _window: W,
+    window_handle: W,
 
     /// The underlying display handle.
     _display: PhantomData<D>,
@@ -114,7 +114,7 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> WebImpl<D, W> {
             buffer: Vec::new(),
             buffer_presented: false,
             size: None,
-            _window: window,
+            window_handle: window,
             _display: PhantomData,
         })
     }
@@ -130,11 +130,17 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> WebImpl<D, W> {
             buffer: Vec::new(),
             buffer_presented: false,
             size: None,
-            _window: window,
+            window_handle: window,
             _display: PhantomData,
         })
     }
 
+    /// Get the inner window handle.
+    #[inline]
+    pub fn window(&self) -> &W {
+        &self.window_handle
+    }
+
     /// De-duplicates the error handling between `HtmlCanvasElement` and `OffscreenCanvas`.
     fn resolve_ctx<T: JsCast>(
         result: Option<Option<Object>>,

src/win32.rs

@@ -142,7 +142,7 @@ pub struct Win32Impl<D: ?Sized, W> {
     /// The handle for the window.
     ///
     /// This should be kept alive in order to keep `window` valid.
-    _window: W,
+    handle: W,
 
     /// The display handle.
     ///
@@ -184,11 +184,17 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> Win32Impl<D, W> {
             dc,
             window: hwnd,
             buffer: None,
-            _window: window,
+            handle: window,
             _display: PhantomData,
         })
     }
 
+    /// Get the inner window handle.
+    #[inline]
+    pub fn window(&self) -> &W {
+        &self.handle
+    }
+
     pub fn resize(&mut self, width: NonZeroU32, height: NonZeroU32) -> Result<(), SoftBufferError> {
         let (width, height) = (|| {
             let width = NonZeroI32::new(i32::try_from(width.get()).ok()?)?;

src/x11.rs

@@ -150,7 +150,7 @@ pub struct X11Impl<D: ?Sized, W: ?Sized> {
     size: Option<(NonZeroU16, NonZeroU16)>,
 
     /// Keep the window alive.
-    _window_handle: W,
+    window_handle: W,
 }
 
 /// The buffer that is being drawn to.
@@ -292,10 +292,16 @@ impl<D: HasDisplayHandle + ?Sized, W: HasWindowHandle> X11Impl<D, W> {
             buffer,
             buffer_presented: false,
             size: None,
-            _window_handle: window_src,
+            window_handle: window_src,
         })
     }
 
+    /// Get the inner window handle.
+    #[inline]
+    pub fn window(&self) -> &W {
+        &self.window_handle
+    }
+
     /// Resize the internal buffer to the given width and height.
     pub(crate) fn resize(
         &mut self,