Decouple display and window from RawWindowHandle

On free platforms there're usually multiple displays, so APIs like
EGL have a concept of native display when creating EGLDisplay.

Sometimes creating EGLDisplay must be done before creating the window
on that particular display, to supply e.g. X11 visual information to
the window that will be created on that display later on.

Co-authored-by: Lokathor <[email protected]>
Co-authored-by: Markus Røyset <[email protected]>

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## Unreleased
+
+* **Breaking:** The `RawWindowHandle` variants were split into `RawDisplayHandle` and `RawWindowHandle`.
+* The X11 screen is now present in new `XlibDisplayHandle` and `XcbDisplayHandle`.
+
 ## 0.4.3 (2022-03-29)
 
 * [Add visual IDs to X11 handles](https://github.com/rust-windowing/raw-window-handle/pull/83)

README.md

@@ -2,4 +2,8 @@
 [![Crates.io](https://img.shields.io/crates/v/raw-window-handle.svg?maxAge=2592000)](https://crates.io/crates/raw-window-handle)
 [![Docs](https://docs.rs/raw-window-handle/badge.svg)](https://docs.rs/raw-window-handle)
 
-This library provides standard types for accessing a window's platform-specific raw window handle. This does not provide any utilities for creating and managing windows; instead, it provides a common interface that window creation libraries (e.g. Winit, SDL) can use to easily talk with graphics libraries (e.g. gfx-hal).
+This library provides standard types for accessing a window's platform-specific
+raw window handle and display's platform-specific raw display handle. This does
+not provide any utilities for creating and managing windows; instead, it
+provides a common interface that window creation libraries (e.g. Winit, SDL)
+can use to easily talk with graphics libraries (e.g. gfx-hal).

src/android.rs

@@ -1,22 +1,40 @@
 use core::ffi::c_void;
 use core::ptr;
 
+/// Raw display handle for Android.
+///
+/// ## Construction
+/// ```
+/// # use raw_window_handle::AndroidDisplayHandle;
+/// let mut display_handle = AndroidDisplayHandle::empty();
+/// /* set fields */
+/// ```
+#[non_exhaustive]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct AndroidDisplayHandle;
+
+impl AndroidDisplayHandle {
+    pub fn empty() -> Self {
+        Self {}
+    }
+}
+
 /// Raw window handle for Android NDK.
 ///
 /// ## Construction
 /// ```
-/// # use raw_window_handle::AndroidNdkHandle;
-/// let mut handle = AndroidNdkHandle::empty();
+/// # use raw_window_handle::AndroidNdkWindowHandle;
+/// let mut window_handle = AndroidNdkWindowHandle::empty();
 /// /* set fields */
 /// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct AndroidNdkHandle {
+pub struct AndroidNdkWindowHandle {
     /// A pointer to an `ANativeWindow`.
     pub a_native_window: *mut c_void,
 }
 
-impl AndroidNdkHandle {
+impl AndroidNdkWindowHandle {
     pub fn empty() -> Self {
         Self {
             a_native_window: ptr::null_mut(),

src/appkit.rs

@@ -1,25 +1,43 @@
 use core::ffi::c_void;
 use core::ptr;
 
+/// Raw display handle for AppKit.
+///
+/// ## Construction
+/// ```
+/// # use raw_window_handle::AppKitDisplayHandle;
+/// let mut display_handle = AppKitDisplayHandle::empty();
+/// /* set fields */
+/// ```
+#[non_exhaustive]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct AppKitDisplayHandle;
+
+impl AppKitDisplayHandle {
+    pub fn empty() -> Self {
+        Self {}
+    }
+}
+
 /// Raw window handle for AppKit.
 ///
 /// ## Construction
 /// ```
-/// # use raw_window_handle::AppKitHandle;
-/// let mut handle = AppKitHandle::empty();
+/// # use raw_window_handle::AppKitWindowHandle;
+/// let mut window_handle = AppKitWindowHandle::empty();
 /// /* set fields */
 /// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct AppKitHandle {
+pub struct AppKitWindowHandle {
     /// A pointer to an `NSWindow` object.
     pub ns_window: *mut c_void,
     /// A pointer to an `NSView` object.
     pub ns_view: *mut c_void,
     // TODO: WHAT ABOUT ns_window_controller and ns_view_controller?
 }
 
-impl AppKitHandle {
+impl AppKitWindowHandle {
     pub fn empty() -> Self {
         Self {
             ns_window: ptr::null_mut(),

src/haiku.rs

@@ -1,24 +1,42 @@
 use core::ffi::c_void;
 use core::ptr;
 
+/// Raw display handle for Haiku.
+///
+/// ## Construction
+/// ```
+/// # use raw_window_handle::HaikuDisplayHandle;
+/// let mut display_handle = HaikuDisplayHandle::empty();
+/// /* set fields */
+/// ```
+#[non_exhaustive]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct HaikuDisplayHandle;
+
+impl HaikuDisplayHandle {
+    pub fn empty() -> Self {
+        Self {}
+    }
+}
+
 /// Raw window handle for Haiku.
 ///
 /// ## Construction
 /// ```
-/// # use raw_window_handle::HaikuHandle;
-/// let mut handle = HaikuHandle::empty();
+/// # use raw_window_handle::HaikuWindowHandle;
+/// let mut window_handle = HaikuWindowHandle::empty();
 /// /* set fields */
 /// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct HaikuHandle {
+pub struct HaikuWindowHandle {
     /// A pointer to a BWindow object
     pub b_window: *mut c_void,
     /// A pointer to a BDirectWindow object that might be null
     pub b_direct_window: *mut c_void,
 }
 
-impl HaikuHandle {
+impl HaikuWindowHandle {
     pub fn empty() -> Self {
         Self {
             b_window: ptr::null_mut(),