1 //! Interoperability library for Rust Windowing applications. 2 //! 3 //! This library provides standard types for accessing a window's platform-specific raw window 4 //! handle. This does not provide any utilities for creating and managing windows; instead, it 5 //! provides a common interface that window creation libraries (e.g. Winit, SDL) can use to easily 6 //! talk with graphics libraries (e.g. gfx-hal). 7 //! 8 //! ## Platform handle initialization 9 //! 10 //! Each platform handle struct is purposefully non-exhaustive, so that additional fields may be 11 //! added without breaking backwards compatibility. Each struct provides an `empty` method that may 12 //! be used along with the struct update syntax to construct it. See each specific struct for 13 //! examples. 14 //! 15 #![cfg_attr(feature = "nightly-docs", feature(doc_cfg))] 16 #![no_std] 17 18 #[cfg_attr(feature = "nightly-docs", doc(cfg(target_os = "android")))] 19 #[cfg_attr(not(feature = "nightly-docs"), cfg(target_os = "android"))] 20 pub mod android; 21 #[cfg_attr(feature = "nightly-docs", doc(cfg(target_os = "ios")))] 22 #[cfg_attr(not(feature = "nightly-docs"), cfg(target_os = "ios"))] 23 pub mod ios; 24 #[cfg_attr(feature = "nightly-docs", doc(cfg(target_os = "macos")))] 25 #[cfg_attr(not(feature = "nightly-docs"), cfg(target_os = "macos"))] 26 pub mod macos; 27 #[cfg_attr( 28 feature = "nightly-docs", 29 doc(cfg(any( 30 target_os = "linux", 31 target_os = "dragonfly", 32 target_os = "freebsd", 33 target_os = "netbsd", 34 target_os = "openbsd" 35 ))) 36 )] 37 #[cfg_attr( 38 not(feature = "nightly-docs"), 39 cfg(any( 40 target_os = "linux", 41 target_os = "dragonfly", 42 target_os = "freebsd", 43 target_os = "netbsd", 44 target_os = "openbsd" 45 )) 46 )] 47 pub mod unix; 48 #[cfg_attr(feature = "nightly-docs", doc(cfg(target_arch = "wasm32")))] 49 #[cfg_attr(not(feature = "nightly-docs"), cfg(target_arch = "wasm32"))] 50 pub mod web; 51 #[cfg_attr(feature = "nightly-docs", doc(cfg(target_os = "windows")))] 52 #[cfg_attr(not(feature = "nightly-docs"), cfg(target_os = "windows"))] 53 pub mod windows; 54 55 mod platform { 56 #[cfg(target_os = "android")] 57 pub use crate::android::*; 58 #[cfg(target_os = "macos")] 59 pub use crate::macos::*; 60 #[cfg(any( 61 target_os = "linux", 62 target_os = "dragonfly", 63 target_os = "freebsd", 64 target_os = "netbsd", 65 target_os = "openbsd" 66 ))] 67 pub use crate::unix::*; 68 #[cfg(target_os = "windows")] 69 pub use crate::windows::*; 70 // mod platform; 71 #[cfg(target_os = "ios")] 72 pub use crate::ios::*; 73 #[cfg(target_arch = "wasm32")] 74 pub use crate::web::*; 75 } 76 77 /// Window that wraps around a raw window handle. 78 /// 79 /// # Safety guarantees 80 /// 81 /// Users can safely assume that non-`null`/`0` fields are valid handles, and it is up to the 82 /// implementer of this trait to ensure that condition is upheld. However, It is entirely valid 83 /// behavior for fields within each platform-specific `RawWindowHandle` variant to be `null` or 84 /// `0`, and appropriate checking should be done before the handle is used. 85 /// 86 /// Despite that qualification, implementers should still make a best-effort attempt to fill in all 87 /// available fields. If an implementation doesn't, and a downstream user needs the field, it should 88 /// try to derive the field from other fields the implementer *does* provide via whatever methods the 89 /// platform provides. 90 /// 91 /// The exact handles returned by `raw_window_handle` must remain consistent between multiple calls 92 /// to `raw_window_handle`, and must be valid for at least the lifetime of the `HasRawWindowHandle` 93 /// implementer. 94 pub unsafe trait HasRawWindowHandle { raw_window_handle(&self) -> RawWindowHandle95 fn raw_window_handle(&self) -> RawWindowHandle; 96 } 97 98 #[derive(Debug, Clone, Copy, PartialEq, Eq)] 99 pub enum RawWindowHandle { 100 #[cfg_attr(feature = "nightly-docs", doc(cfg(target_os = "ios")))] 101 #[cfg_attr(not(feature = "nightly-docs"), cfg(target_os = "ios"))] 102 IOS(ios::IOSHandle), 103 104 #[cfg_attr(feature = "nightly-docs", doc(cfg(target_os = "macos")))] 105 #[cfg_attr(not(feature = "nightly-docs"), cfg(target_os = "macos"))] 106 MacOS(macos::MacOSHandle), 107 108 #[cfg_attr( 109 feature = "nightly-docs", 110 doc(cfg(any( 111 target_os = "linux", 112 target_os = "dragonfly", 113 target_os = "freebsd", 114 target_os = "netbsd", 115 target_os = "openbsd" 116 ))) 117 )] 118 #[cfg_attr( 119 not(feature = "nightly-docs"), 120 cfg(any( 121 target_os = "linux", 122 target_os = "dragonfly", 123 target_os = "freebsd", 124 target_os = "netbsd", 125 target_os = "openbsd" 126 )) 127 )] 128 Xlib(unix::XlibHandle), 129 130 #[cfg_attr( 131 feature = "nightly-docs", 132 doc(cfg(any( 133 target_os = "linux", 134 target_os = "dragonfly", 135 target_os = "freebsd", 136 target_os = "netbsd", 137 target_os = "openbsd" 138 ))) 139 )] 140 #[cfg_attr( 141 not(feature = "nightly-docs"), 142 cfg(any( 143 target_os = "linux", 144 target_os = "dragonfly", 145 target_os = "freebsd", 146 target_os = "netbsd", 147 target_os = "openbsd" 148 )) 149 )] 150 Xcb(unix::XcbHandle), 151 152 #[cfg_attr( 153 feature = "nightly-docs", 154 doc(cfg(any( 155 target_os = "linux", 156 target_os = "dragonfly", 157 target_os = "freebsd", 158 target_os = "netbsd", 159 target_os = "openbsd" 160 ))) 161 )] 162 #[cfg_attr( 163 not(feature = "nightly-docs"), 164 cfg(any( 165 target_os = "linux", 166 target_os = "dragonfly", 167 target_os = "freebsd", 168 target_os = "netbsd", 169 target_os = "openbsd" 170 )) 171 )] 172 Wayland(unix::WaylandHandle), 173 174 #[cfg_attr(feature = "nightly-docs", doc(cfg(target_os = "windows")))] 175 #[cfg_attr(not(feature = "nightly-docs"), cfg(target_os = "windows"))] 176 Windows(windows::WindowsHandle), 177 178 #[cfg_attr(feature = "nightly-docs", doc(cfg(target_arch = "wasm32")))] 179 #[cfg_attr(not(feature = "nightly-docs"), cfg(target_arch = "wasm32"))] 180 Web(web::WebHandle), 181 182 #[cfg_attr(feature = "nightly-docs", doc(cfg(target_os = "android")))] 183 #[cfg_attr(not(feature = "nightly-docs"), cfg(target_os = "android"))] 184 Android(android::AndroidHandle), 185 186 #[doc(hidden)] 187 #[deprecated = "This field is used to ensure that this struct is non-exhaustive, so that it may be extended in the future. Do not refer to this field."] 188 __NonExhaustiveDoNotUse(seal::Seal), 189 } 190 191 mod seal { 192 #[derive(Debug, Clone, Copy, PartialEq, Eq)] 193 pub struct Seal; 194 } 195