1 #![no_std]
2 
3 //! Interoperability library for Rust Windowing applications.
4 //!
5 //! This library provides standard types for accessing a window's platform-specific raw window
6 //! handle. This does not provide any utilities for creating and managing windows; instead, it
7 //! provides a common interface that window creation libraries (e.g. Winit, SDL) can use to easily
8 //! talk with graphics libraries (e.g. gfx-hal).
9 //!
10 //! ## Safety guarantees
11 //!
12 //! Please see the docs of [`HasRawWindowHandle`].
13 //!
14 //! ## Platform handle initialization
15 //!
16 //! Each platform handle struct is purposefully non-exhaustive, so that additional fields may be
17 //! added without breaking backwards compatibility. Each struct provides an `empty` method that may
18 //! be used along with the struct update syntax to construct it. See each specific struct for
19 //! examples.
20 
21 #[cfg(feature = "alloc")]
22 extern crate alloc;
23 
24 mod android;
25 mod appkit;
26 mod redox;
27 mod uikit;
28 mod unix;
29 mod web;
30 mod windows;
31 
32 pub use android::AndroidNdkHandle;
33 pub use appkit::AppKitHandle;
34 pub use redox::OrbitalHandle;
35 pub use uikit::UiKitHandle;
36 pub use unix::{WaylandHandle, XcbHandle, XlibHandle};
37 pub use web::WebHandle;
38 pub use windows::{Win32Handle, WinRtHandle};
39 
40 /// Window that wraps around a raw window handle.
41 ///
42 /// # Safety guarantees
43 ///
44 /// Users can safely assume that non-`null`/`0` fields are valid handles, and it is up to the
45 /// implementer of this trait to ensure that condition is upheld.
46 ///
47 /// Despite that qualification, implementers should still make a best-effort attempt to fill in all
48 /// available fields. If an implementation doesn't, and a downstream user needs the field, it should
49 /// try to derive the field from other fields the implementer *does* provide via whatever methods the
50 /// platform provides.
51 ///
52 /// The exact handles returned by `raw_window_handle` must remain consistent between multiple calls
53 /// to `raw_window_handle` as long as not indicated otherwise by platform specific events.
54 pub unsafe trait HasRawWindowHandle {
raw_window_handle(&self) -> RawWindowHandle55     fn raw_window_handle(&self) -> RawWindowHandle;
56 }
57 
58 unsafe impl<'a, T: HasRawWindowHandle + ?Sized> HasRawWindowHandle for &'a T {
raw_window_handle(&self) -> RawWindowHandle59     fn raw_window_handle(&self) -> RawWindowHandle {
60         (*self).raw_window_handle()
61     }
62 }
63 #[cfg(feature = "alloc")]
64 unsafe impl<T: HasRawWindowHandle + ?Sized> HasRawWindowHandle for alloc::rc::Rc<T> {
raw_window_handle(&self) -> RawWindowHandle65     fn raw_window_handle(&self) -> RawWindowHandle {
66         (**self).raw_window_handle()
67     }
68 }
69 #[cfg(feature = "alloc")]
70 unsafe impl<T: HasRawWindowHandle + ?Sized> HasRawWindowHandle for alloc::sync::Arc<T> {
raw_window_handle(&self) -> RawWindowHandle71     fn raw_window_handle(&self) -> RawWindowHandle {
72         (**self).raw_window_handle()
73     }
74 }
75 
76 /// An enum to simply combine the different possible raw window handle variants.
77 ///
78 /// # Variant Availability
79 ///
80 /// Note that all variants are present on all targets (none are disabled behind
81 /// `#[cfg]`s), but see the "Availability Hints" section on each variant for
82 /// some hints on where this variant might be expected.
83 ///
84 /// Note that these "Availability Hints" are not normative. That is to say, a
85 /// [`HasRawWindowHandle`] implementor is completely allowed to return something
86 /// unexpected. (For example, it's legal for someone to return a
87 /// [`RawWindowHandle::Xlib`] on macOS, it would just be weird, and probably
88 /// requires something like XQuartz be used).
89 #[non_exhaustive]
90 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
91 pub enum RawWindowHandle {
92     /// A raw window handle for UIKit (Apple's non-macOS windowing library).
93     ///
94     /// ## Availability Hints
95     /// This variant is likely to be used on iOS, tvOS, (in theory) watchOS, and
96     /// Mac Catalyst (`$arch-apple-ios-macabi` targets, which can notably use
97     /// UIKit *or* AppKit), as these are the targets that (currently) support
98     /// UIKit.
99     UiKit(UiKitHandle),
100     /// A raw window handle for AppKit.
101     ///
102     /// ## Availability Hints
103     /// This variant is likely to be used on macOS, although Mac Catalyst
104     /// (`$arch-apple-ios-macabi` targets, which can notably use UIKit *or*
105     /// AppKit) can also use it despite being `target_os = "ios"`.
106     AppKit(AppKitHandle),
107     /// A raw window handle for the Redox operating system.
108     ///
109     /// ## Availability Hints
110     /// This variant is used by the Orbital Windowing System in the Redox
111     /// operating system.
112     Orbital(OrbitalHandle),
113     /// A raw window handle for Xlib.
114     ///
115     /// ## Availability Hints
116     /// This variant is likely to show up anywhere someone manages to get X11
117     /// working that Xlib can be built for, which is to say, most (but not all)
118     /// Unix systems.
119     Xlib(XlibHandle),
120     /// A raw window handle for Xcb.
121     ///
122     /// ## Availability Hints
123     /// This variant is likely to show up anywhere someone manages to get X11
124     /// working that XCB can be built for, which is to say, most (but not all)
125     /// Unix systems.
126     Xcb(XcbHandle),
127     /// A raw window handle for Wayland.
128     ///
129     /// ## Availability Hints
130     /// This variant should be expected anywhere Wayland works, which is
131     /// currently some subset of unix systems.
132     Wayland(WaylandHandle),
133     /// A raw window handle for Win32.
134     ///
135     /// ## Availability Hints
136     /// This variant is used on Windows systems.
137     Win32(Win32Handle),
138     /// A raw window handle for WinRT.
139     ///
140     /// ## Availability Hints
141     /// This variant is used on Windows systems.
142     WinRt(WinRtHandle),
143     /// A raw window handle for the Web.
144     ///
145     /// ## Availability Hints
146     /// This variant is used on Wasm or asm.js targets when targeting the Web/HTML5.
147     Web(WebHandle),
148     /// A raw window handle for Android NDK.
149     ///
150     /// ## Availability Hints
151     /// This variant is used on Android targets.
152     AndroidNdk(AndroidNdkHandle),
153 }
154