diff --git a/CHANGELOG.md b/CHANGELOG.md index e426ae0..9a22aa1 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/README.md b/README.md index a406ee5..d26c4db 100644 --- a/README.md +++ b/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). diff --git a/src/android.rs b/src/android.rs index 48f69e9..e4504ce 100644 --- a/src/android.rs +++ b/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(), diff --git a/src/appkit.rs b/src/appkit.rs index 27793be..1023aa0 100644 --- a/src/appkit.rs +++ b/src/appkit.rs @@ -1,17 +1,35 @@ 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. @@ -19,7 +37,7 @@ pub struct AppKitHandle { // TODO: WHAT ABOUT ns_window_controller and ns_view_controller? } -impl AppKitHandle { +impl AppKitWindowHandle { pub fn empty() -> Self { Self { ns_window: ptr::null_mut(), diff --git a/src/haiku.rs b/src/haiku.rs index 38432fd..d44e8c2 100644 --- a/src/haiku.rs +++ b/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(), diff --git a/src/lib.rs b/src/lib.rs index 2896d8e..79ad228 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -4,13 +4,13 @@ //! Interoperability library for Rust Windowing applications. //! //! 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). +//! handle and platforms 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). //! //! ## Safety guarantees //! -//! Please see the docs of [`HasRawWindowHandle`]. +//! Please see the docs of [`HasRawWindowHandle`] and [`HasRawDisplayHandle`]. //! //! ## Platform handle initialization //! @@ -31,18 +31,21 @@ mod unix; mod web; mod windows; -pub use android::AndroidNdkHandle; -pub use appkit::AppKitHandle; -pub use haiku::HaikuHandle; -pub use redox::OrbitalHandle; -pub use uikit::UiKitHandle; -pub use unix::{DrmHandle, WaylandHandle, XcbHandle, XlibHandle}; -pub use web::WebHandle; -pub use windows::{Win32Handle, WinRtHandle}; +pub use android::{AndroidDisplayHandle, AndroidNdkWindowHandle}; +pub use appkit::{AppKitDisplayHandle, AppKitWindowHandle}; +pub use haiku::{HaikuDisplayHandle, HaikuWindowHandle}; +pub use redox::{OrbitalDisplayHandle, OrbitalWindowHandle}; +pub use uikit::{UiKitDisplayHandle, UiKitWindowHandle}; +pub use unix::{ + DrmDisplayHandle, DrmWindowHandle, WaylandDisplayHandle, WaylandWindowHandle, XcbDisplayHandle, + XcbWindowHandle, XlibDisplayHandle, XlibWindowHandle, +}; +pub use web::{WebDisplayHandle, WebWindowHandle}; +pub use windows::{Win32WindowHandle, WinRtWindowHandle, WindowsDisplayHandle}; /// Window that wraps around a raw window handle. /// -/// # Safety guarantees +/// # Safety /// /// Users can safely assume that non-`null`/`0` fields are valid handles, and it is up to the /// implementer of this trait to ensure that condition is upheld. @@ -101,68 +104,192 @@ pub enum RawWindowHandle { /// Mac Catalyst (`$arch-apple-ios-macabi` targets, which can notably use /// UIKit *or* AppKit), as these are the targets that (currently) support /// UIKit. - UiKit(UiKitHandle), + UiKit(UiKitWindowHandle), /// A raw window handle for AppKit. /// /// ## Availability Hints /// This variant is likely to be used on macOS, although Mac Catalyst /// (`$arch-apple-ios-macabi` targets, which can notably use UIKit *or* /// AppKit) can also use it despite being `target_os = "ios"`. - AppKit(AppKitHandle), + AppKit(AppKitWindowHandle), /// A raw window handle for the Redox operating system. /// /// ## Availability Hints /// This variant is used by the Orbital Windowing System in the Redox /// operating system. - Orbital(OrbitalHandle), + Orbital(OrbitalWindowHandle), /// A raw window handle for Xlib. /// /// ## Availability Hints /// This variant is likely to show up anywhere someone manages to get X11 /// working that Xlib can be built for, which is to say, most (but not all) /// Unix systems. - Xlib(XlibHandle), + Xlib(XlibWindowHandle), /// A raw window handle for Xcb. /// /// ## Availability Hints /// This variant is likely to show up anywhere someone manages to get X11 /// working that XCB can be built for, which is to say, most (but not all) /// Unix systems. - Xcb(XcbHandle), + Xcb(XcbWindowHandle), /// A raw window handle for Wayland. /// /// ## Availability Hints /// This variant should be expected anywhere Wayland works, which is /// currently some subset of unix systems. - Wayland(WaylandHandle), + Wayland(WaylandWindowHandle), /// A raw window handle for the Linux Kernel Mode Set/Direct Rendering Manager /// /// ## Availability Hints /// This variant is used on Linux when neither X nor Wayland are available - Drm(DrmHandle), + Drm(DrmWindowHandle), /// A raw window handle for Win32. /// /// ## Availability Hints /// This variant is used on Windows systems. - Win32(Win32Handle), + Win32(Win32WindowHandle), /// A raw window handle for WinRT. /// /// ## Availability Hints /// This variant is used on Windows systems. - WinRt(WinRtHandle), + WinRt(WinRtWindowHandle), /// A raw window handle for the Web. /// /// ## Availability Hints /// This variant is used on Wasm or asm.js targets when targeting the Web/HTML5. - Web(WebHandle), + Web(WebWindowHandle), /// A raw window handle for Android NDK. /// /// ## Availability Hints /// This variant is used on Android targets. - AndroidNdk(AndroidNdkHandle), + AndroidNdk(AndroidNdkWindowHandle), /// A raw window handle for Haiku. /// /// ## Availability Hints /// This variant is used on HaikuOS. - Haiku(HaikuHandle), + Haiku(HaikuWindowHandle), +} + +/// Display that wraps around a raw display handle. +/// +/// # Safety +/// +/// Users can safely assume that non-`null`/`0` fields are valid handles, and it is up to the +/// implementer of this trait to ensure that condition is upheld. +/// +/// Despite that qualification, implementers should still make a best-effort attempt to fill in all +/// available fields. If an implementation doesn't, and a downstream user needs the field, it should +/// try to derive the field from other fields the implementer *does* provide via whatever methods the +/// platform provides. +/// +/// The exact handles returned by `raw_display_handle` must remain consistent between multiple calls +/// to `raw_display_handle` as long as not indicated otherwise by platform specific events. +pub unsafe trait HasRawDisplayHandle { + fn raw_display_handle(&self) -> RawDisplayHandle; +} + +unsafe impl<'a, T: HasRawDisplayHandle + ?Sized> HasRawDisplayHandle for &'a T { + fn raw_display_handle(&self) -> RawDisplayHandle { + (*self).raw_display_handle() + } +} + +#[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] +unsafe impl HasRawDisplayHandle for alloc::rc::Rc { + fn raw_display_handle(&self) -> RawDisplayHandle { + (**self).raw_display_handle() + } +} + +#[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] +unsafe impl HasRawDisplayHandle for alloc::sync::Arc { + fn raw_display_handle(&self) -> RawDisplayHandle { + (**self).raw_display_handle() + } +} + +/// An enum to simply combine the different possible raw display handle variants. +/// +/// # Variant Availability +/// +/// Note that all variants are present on all targets (none are disabled behind +/// `#[cfg]`s), but see the "Availability Hints" section on each variant for +/// some hints on where this variant might be expected. +/// +/// Note that these "Availability Hints" are not normative. That is to say, a +/// [`HasRawDisplayHandle`] implementor is completely allowed to return something +/// unexpected. (For example, it's legal for someone to return a +/// [`RawDisplayHandle::Xlib`] on macOS, it would just be weird, and probably +/// requires something like XQuartz be used). +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum RawDisplayHandle { + /// A raw display handle for UIKit (Apple's non-macOS windowing library). + /// + /// ## Availability Hints + /// This variant is likely to be used on iOS, tvOS, (in theory) watchOS, and + /// Mac Catalyst (`$arch-apple-ios-macabi` targets, which can notably use + /// UIKit *or* AppKit), as these are the targets that (currently) support + /// UIKit. + UiKit(UiKitDisplayHandle), + /// A raw display handle for AppKit. + /// + /// ## Availability Hints + /// This variant is likely to be used on macOS, although Mac Catalyst + /// (`$arch-apple-ios-macabi` targets, which can notably use UIKit *or* + /// AppKit) can also use it despite being `target_os = "ios"`. + AppKit(AppKitDisplayHandle), + /// A raw display handle for the Redox operating system. + /// + /// ## Availability Hints + /// This variant is used by the Orbital Windowing System in the Redox + /// operating system. + Orbital(OrbitalDisplayHandle), + /// A raw display handle for Xlib. + /// + /// ## Availability Hints + /// This variant is likely to show up anywhere someone manages to get X11 + /// working that Xlib can be built for, which is to say, most (but not all) + /// Unix systems. + Xlib(XlibDisplayHandle), + /// A raw display handle for Xcb. + /// + /// ## Availability Hints + /// This variant is likely to show up anywhere someone manages to get X11 + /// working that XCB can be built for, which is to say, most (but not all) + /// Unix systems. + Xcb(XcbDisplayHandle), + /// A raw display handle for Wayland. + /// + /// ## Availability Hints + /// This variant should be expected anywhere Wayland works, which is + /// currently some subset of unix systems. + Wayland(WaylandDisplayHandle), + /// A raw display handle for the Linux Kernel Mode Set/Direct Rendering Manager + /// + /// ## Availability Hints + /// This variant is used on Linux when neither X nor Wayland are available + Drm(DrmDisplayHandle), + /// A raw display handle for Win32. + /// + /// ## Availability Hints + /// This variant is used on Windows systems. + Windows(WindowsDisplayHandle), + /// A raw display handle for the Web. + /// + /// ## Availability Hints + /// This variant is used on Wasm or asm.js targets when targeting the Web/HTML5. + Web(WebDisplayHandle), + /// A raw display handle for Android NDK. + /// + /// ## Availability Hints + /// This variant is used on Android targets. + Android(AndroidDisplayHandle), + /// A raw display handle for Haiku. + /// + /// ## Availability Hints + /// This variant is used on HaikuOS. + Haiku(HaikuDisplayHandle), } diff --git a/src/redox.rs b/src/redox.rs index da7880c..5faa985 100644 --- a/src/redox.rs +++ b/src/redox.rs @@ -1,22 +1,40 @@ use core::ffi::c_void; use core::ptr; +/// Raw display handle for the Redox operating system. +/// +/// ## Construction +/// ``` +/// # use raw_window_handle::OrbitalDisplayHandle; +/// let mut display_handle = OrbitalDisplayHandle::empty(); +/// /* set fields */ +/// ``` +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub struct OrbitalDisplayHandle; + +impl OrbitalDisplayHandle { + pub fn empty() -> Self { + Self {} + } +} + /// Raw window handle for the Redox operating system. /// /// ## Construction /// ``` -/// # use raw_window_handle::OrbitalHandle; -/// let mut handle = OrbitalHandle::empty(); +/// # use raw_window_handle::OrbitalWindowHandle; +/// let mut window_handle = OrbitalWindowHandle::empty(); /// /* set fields */ /// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub struct OrbitalHandle { +pub struct OrbitalWindowHandle { /// A pointer to an orbclient window. pub window: *mut c_void, } -impl OrbitalHandle { +impl OrbitalWindowHandle { pub fn empty() -> Self { Self { window: ptr::null_mut(), diff --git a/src/uikit.rs b/src/uikit.rs index 412d107..bee3a9a 100644 --- a/src/uikit.rs +++ b/src/uikit.rs @@ -1,17 +1,35 @@ use core::ffi::c_void; use core::ptr; +/// Raw display handle for UIKit. +/// +/// ## Construction +/// ``` +/// # use raw_window_handle::UiKitDisplayHandle; +/// let mut display_handle = UiKitDisplayHandle::empty(); +/// /* set fields */ +/// ``` +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub struct UiKitDisplayHandle; + +impl UiKitDisplayHandle { + pub fn empty() -> Self { + Self {} + } +} + /// Raw window handle for UIKit. /// /// ## Construction /// ``` -/// # use raw_window_handle::UiKitHandle; -/// let mut handle = UiKitHandle::empty(); +/// # use raw_window_handle::UiKitWindowHandle; +/// let mut window_handle = UiKitWindowHandle::empty(); /// /* set fields */ /// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub struct UiKitHandle { +pub struct UiKitWindowHandle { /// A pointer to an `UIWindow` object. pub ui_window: *mut c_void, /// A pointer to an `UIView` object. @@ -20,7 +38,7 @@ pub struct UiKitHandle { pub ui_view_controller: *mut c_void, } -impl UiKitHandle { +impl UiKitWindowHandle { pub fn empty() -> Self { Self { ui_window: ptr::null_mut(), diff --git a/src/unix.rs b/src/unix.rs index 793139b..bd95ccd 100644 --- a/src/unix.rs +++ b/src/unix.rs @@ -1,111 +1,206 @@ use core::ffi::c_void; use core::ptr; -use cty::c_ulong; +use cty::{c_int, c_ulong}; + +/// Raw display handle for Xlib. +/// +/// ## Construction +/// ``` +/// # use raw_window_handle::XlibDisplayHandle; +/// let display_handle = XlibDisplayHandle::empty(); +/// /* set fields */ +/// ``` +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub struct XlibDisplayHandle { + /// A pointer to an Xlib `Display`. + pub display: *mut c_void, + + /// An X11 screen to use with this display handle. + /// + /// Note, that X11 could have multiple screens, however + /// graphics APIs could work only with one screen at the time, + /// given that multiple screens usually reside on different GPUs. + pub screen: c_int, +} /// Raw window handle for Xlib. /// /// ## Construction /// ``` -/// # use raw_window_handle::XlibHandle; -/// let handle = XlibHandle::empty(); +/// # use raw_window_handle::XlibWindowHandle; +/// let window_handle = XlibWindowHandle::empty(); /// /* set fields */ /// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub struct XlibHandle { +pub struct XlibWindowHandle { /// An Xlib `Window`. pub window: c_ulong, - /// A pointer to an Xlib `Display`. - pub display: *mut c_void, /// An Xlib visual ID, or 0 if unknown. pub visual_id: c_ulong, } +/// Raw display handle for Xcb. +/// +/// ## Construction +/// ``` +/// # use raw_window_handle::XcbDisplayHandle; +/// let display_handle = XcbDisplayHandle::empty(); +/// /* set fields */ +/// ``` +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub struct XcbDisplayHandle { + /// A pointer to an X server `xcb_connection_t`. + pub connection: *mut c_void, + + /// An X11 screen to use with this display handle. + /// + /// Note, that X11 could have multiple screens, however + /// graphics APIs could work only with one screen at the time, + /// given that multiple screens usually reside on different GPUs. + pub screen: c_int, +} + /// Raw window handle for Xcb. /// /// ## Construction /// ``` -/// # use raw_window_handle::XcbHandle; -/// let handle = XcbHandle::empty(); +/// # use raw_window_handle::XcbWindowHandle; +/// let window_handle = XcbWindowHandle::empty(); /// /* set fields */ /// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub struct XcbHandle { +pub struct XcbWindowHandle { /// An X11 `xcb_window_t`. pub window: u32, // Based on xproto.h - /// A pointer to an X server `xcb_connection_t`. - pub connection: *mut c_void, /// An X11 `xcb_visualid_t`, or 0 if unknown. pub visual_id: u32, } +/// Raw display handle for Wayland. +/// +/// ## Construction +/// ``` +/// # use raw_window_handle::WaylandDisplayHandle; +/// let display_handle = WaylandDisplayHandle::empty(); +/// /* set fields */ +/// ``` +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub struct WaylandDisplayHandle { + /// A pointer to a `wl_display`. + pub display: *mut c_void, +} + /// Raw window handle for Wayland. /// /// ## Construction /// ``` -/// # use raw_window_handle::WaylandHandle; -/// let handle = WaylandHandle::empty(); +/// # use raw_window_handle::WaylandWindowHandle; +/// let window_handle = WaylandWindowHandle::empty(); /// /* set fields */ /// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub struct WaylandHandle { +pub struct WaylandWindowHandle { /// A pointer to a `wl_surface`. pub surface: *mut c_void, - /// A pointer to a `wl_display`. - pub display: *mut c_void, } -/// Raw window handle for the Linux Kernel Mode Set/Direct Rendering Manager. +/// Raw display handle for the Linux Kernel Mode Set/Direct Rendering Manager. /// /// ## Construction /// ``` -/// # use raw_window_handle::DrmHandle; -/// let handle = DrmHandle::empty(); +/// # use raw_window_handle::DrmDisplayHandle; +/// let display_handle = DrmDisplayHandle::empty(); /// /* set fields */ /// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub struct DrmHandle { - /// The drm file descriptor +pub struct DrmDisplayHandle { + /// The drm file descriptor. pub fd: i32, - /// The primary drm plane handle +} + +/// Raw window handle for the Linux Kernel Mode Set/Direct Rendering Manager. +/// +/// ## Construction +/// ``` +/// # use raw_window_handle::DrmWindowHandle; +/// let handle = DrmWindowHandle::empty(); +/// /* set fields */ +/// ``` +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub struct DrmWindowHandle { + /// The primary drm plane handle. pub plane: u32, } -impl XlibHandle { +impl XlibDisplayHandle { pub fn empty() -> Self { Self { - window: 0, display: ptr::null_mut(), - visual_id: 0, + screen: 0, } } } -impl XcbHandle { +impl XlibWindowHandle { pub fn empty() -> Self { Self { window: 0, + visual_id: 0, + } + } +} + +impl XcbDisplayHandle { + pub fn empty() -> Self { + Self { connection: ptr::null_mut(), + screen: 0, + } + } +} + +impl XcbWindowHandle { + pub fn empty() -> Self { + Self { + window: 0, visual_id: 0, } } } -impl WaylandHandle { +impl WaylandDisplayHandle { pub fn empty() -> Self { Self { - surface: ptr::null_mut(), display: ptr::null_mut(), } } } -impl DrmHandle { +impl WaylandWindowHandle { + pub fn empty() -> Self { + Self { + surface: ptr::null_mut(), + } + } +} + +impl DrmDisplayHandle { + pub fn empty() -> Self { + Self { fd: 0 } + } +} + +impl DrmWindowHandle { pub fn empty() -> Self { - Self { fd: 0, plane: 0 } + Self { plane: 0 } } } diff --git a/src/web.rs b/src/web.rs index 632be63..1e6908f 100644 --- a/src/web.rs +++ b/src/web.rs @@ -1,14 +1,32 @@ +/// Raw display handle for the Web. +/// +/// ## Construction +/// ``` +/// # use raw_window_handle::WebDisplayHandle; +/// let mut display_handle = WebDisplayHandle::empty(); +/// /* set fields */ +/// ``` +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub struct WebDisplayHandle; + +impl WebDisplayHandle { + pub fn empty() -> Self { + Self {} + } +} + /// Raw window handle for the Web. /// /// ## Construction /// ``` -/// # use raw_window_handle::WebHandle; -/// let mut handle = WebHandle::empty(); +/// # use raw_window_handle::WebWindowHandle; +/// let mut window_handle = WebWindowHandle::empty(); /// /* set fields */ /// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub struct WebHandle { +pub struct WebWindowHandle { /// An ID value inserted into the [data attributes] of the canvas element as '`raw-handle`'. /// /// When accessing from JS, the attribute will automatically be called `rawHandle`. @@ -20,7 +38,7 @@ pub struct WebHandle { pub id: u32, } -impl WebHandle { +impl WebWindowHandle { pub fn empty() -> Self { Self { id: 0 } } diff --git a/src/windows.rs b/src/windows.rs index ab75635..32b1a88 100644 --- a/src/windows.rs +++ b/src/windows.rs @@ -1,24 +1,44 @@ use core::ffi::c_void; use core::ptr; +/// Raw display handle for Windows. +/// +/// It could be used regardless of Windows window backend. +/// +/// ## Construction +/// ``` +/// # use raw_window_handle::WindowsDisplayHandle; +/// let mut display_handle = WindowsDisplayHandle::empty(); +/// /* set fields */ +/// ``` +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub struct WindowsDisplayHandle; + +impl WindowsDisplayHandle { + pub fn empty() -> Self { + Self + } +} + /// Raw window handle for Win32. /// /// ## Construction /// ``` -/// # use raw_window_handle::Win32Handle; -/// let mut handle = Win32Handle::empty(); +/// # use raw_window_handle::Win32WindowHandle; +/// let mut window_handle = Win32WindowHandle::empty(); /// /* set fields */ /// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub struct Win32Handle { +pub struct Win32WindowHandle { /// A Win32 `HWND` handle. pub hwnd: *mut c_void, /// The `HINSTANCE` associated with this type's `HWND`. pub hinstance: *mut c_void, } -impl Win32Handle { +impl Win32WindowHandle { pub fn empty() -> Self { Self { hwnd: ptr::null_mut(), @@ -31,18 +51,18 @@ impl Win32Handle { /// /// ## Construction /// ``` -/// # use raw_window_handle::WinRtHandle; -/// let mut handle = WinRtHandle::empty(); +/// # use raw_window_handle::WinRtWindowHandle; +/// let mut window_handle = WinRtWindowHandle::empty(); /// /* set fields */ /// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub struct WinRtHandle { +pub struct WinRtWindowHandle { /// A WinRT `CoreWindow` handle. pub core_window: *mut c_void, } -impl WinRtHandle { +impl WinRtWindowHandle { pub fn empty() -> Self { Self { core_window: ptr::null_mut(),