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