raw-window-handle-0.6.2/.cargo_vcs_info.json0000644000000001360000000000100143700ustar { "git": { "sha1": "5fda8e8420b069368e9450e70c2869e32dcdffc1" }, "path_in_vcs": "" }raw-window-handle-0.6.2/.github/workflows/ci.yml000064400000000000000000000030371046102023000176760ustar 00000000000000name: CI on: pull_request: push: branches: [master] env: RUST_BACKTRACE: 1 CARGO_INCREMENTAL: 0 RUSTFLAGS: "-Cdebuginfo=0 --deny=warnings" RUSTDOCFLAGS: "--deny=warnings" jobs: fmt: name: Tidy Code runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: hecrj/setup-rust-action@v1 with: rust-version: stable components: rustfmt - uses: taiki-e/install-action@v2 with: tool: typos-cli - name: Check Formatting run: cargo fmt --all -- --check - name: Run Typos run: typos tests: name: Tests needs: fmt # `raw-window-handle` only has `cfg` guards for Android, so we just run Ubuntu # and manually test Android runs-on: ubuntu-latest strategy: matrix: rust_version: ["1.64", stable, nightly] steps: - uses: actions/checkout@v2 - uses: hecrj/setup-rust-action@v1 with: rust-version: ${{ matrix.rust_version }} - run: rustup target add wasm32-unknown-unknown - name: Pin deps that break MSRV if: matrix.rust_version == '1.64' run: | cargo update -p bumpalo --precise 3.14.0 - name: Check documentation run: cargo doc --no-deps --document-private-items - uses: taiki-e/install-action@cargo-hack - name: Run tests run: cargo hack test --feature-powerset - name: Run tests for wasm32-unknown-unknown run: cargo hack check --target wasm32-unknown-unknown --feature-powerset raw-window-handle-0.6.2/.gitignore000064400000000000000000000000361046102023000151470ustar 00000000000000/target **/*.rs.bk Cargo.lock raw-window-handle-0.6.2/CHANGELOG.md000064400000000000000000000111101046102023000147630ustar 00000000000000# Changelog ## 0.6.2 (2024-05-17) * Add OpenHarmony OS support (#164) * Minor Documentation updates ## 0.6.1 (2024-04-20) - Add safe constructors for window handles. This may be useful for implementing windowing systems with zero unsafe code. (#159) - Improve documentation for Apple window handles. (#160) - Add a clarification as to what circumstances Windows handles are considered "valid" under. (#163) ## 0.6.0 (2023-09-30) * **Breaking:** Raw pointer handles now use `NonNull` where appropriate, to avoid null pointer dereferences. * **Breaking:** Renamed `empty` methods to `new`, and take parameters in most of those, to better match normal Rust semantics. * **Breaking:** `HasRaw(Display/Window)Handle::raw_(display/window)_handle` returns a result indicating if fetching the window handle failed (#122). * **Breaking:** Remove the `Active/ActiveHandle` types from the public API (#126). * **Breaking:** Remove `AppKitWindowHandle::ns_window` and `UiKitWindowHandle::ui_window` since they can be retrieved from the view (#129). * **Breaking:** Remove `Copy` derive from `RawWindowHandle` and `WindowHandle` (#140). * Implement `PartialEq`, `Eq` and `Hash` for `WindowHandle` too. (#128) * Implement the relevant traits for `&mut T where T: `. (#130) * Add web handles for `wasm-bindgen` v0.2. They are locked behind the `wasm-bindgen-0-2` feature. (#134) * Deprecate the raw window/display handle traits. They will be removed at the next stable release. (#139) ## 0.5.2 (2023-03-31) * Add several types for using raw window handles safely, including `HasWindowHandle`, `WindowHandle`, `HasDisplayHandle`, `DisplayHandle` and `Active` (#110). ## 0.5.1 (2023-03-07) * Add the `rust-version` field (`1.64`). * Implemented `From` for `RawWindowHandle` and `RawDisplayHandle` ## 0.5.0 (2022-07-14) * **Breaking:** The `RawWindowHandle` variants were split into `RawDisplayHandle` and `RawWindowHandle`. * The X11 screen is now present in new `XlibDisplayHandle` and `XcbDisplayHandle`. - Add GBM support. ## 0.4.3 (2022-03-29) * [Add visual IDs to X11 handles](https://github.com/rust-windowing/raw-window-handle/pull/83) * [Add a link to the MDN page for data attributes in the documentation for WebHandle](https://github.com/rust-windowing/raw-window-handle/pull/86) * [add haiku support](https://github.com/rust-windowing/raw-window-handle/pull/88) ## 0.4.2 (2021-11-24) * Also implement `HasRawWindowHandle` for `Rc`, and `Arc` where `T: ?Sized`. ## 0.4.1 (2021-11-19) * Added an impl of `HasRawWindowHandle` for `&T`, `Rc`, and `Arc`. The impls for `Rc` and `Arc` require the `alloc` feature. ## 0.4.0 (2021-11-15) * **Breaking:** Remove `_do_not_use` tags to use `#[non_exhaustive]` macro * **Breaking:** `RawWindowHandle` variants are no longer cfg-guarded by platform. * **Breaking:** Rename `IOS` to `UiKit`. * **Breaking:** Rename `MacOS` to `AppKit`. * **Breaking:** Rename `Windows` to `Win32`. * **Breaking:** Rename `Redox` to `Orbital`. * **Breaking:** Rename `Android` to `AndroidNdk`. * **Breaking:** Inner window handle structs are now exported at crate root. * Added Windows `WinRt` handle. # 0.3.4 (2021-11-27) * Add `HasRawWindowHandle` implementation for `HasRawWindowHandle` in the newer `v0.4`. This allows "provider" crates that implement `HasRawWindowHandle` (like `winit`, `sdl2`, `glfw`, `fltk`, ...) to upgrade to `v0.4` without a breaking change. Afterwards "consumer" crates (like `gfx`, `wgpu`, `rfd`, ...) can start upgrading with minimal breakage for their users. ## 0.3.3 (2019-12-1) * Add missing `Hash` implementation for `AndroidHandle`. ## 0.3.2 (2019-11-29) * Add `Hash` implementation for `RawWindowHandle`. ## 0.3.1 (2019-10-27) * Remove `RawWindowHandle`'s `HasRawWindowHandle` implementation, as it was unsound (see [#35](https://github.com/rust-windowing/raw-window-handle/issues/35)) * Explicitly require that handles within `RawWindowHandle` be valid for the lifetime of the `HasRawWindowHandle` implementation that provided them. ## 0.3.0 (2019-10-5) * **Breaking:** Rename `XLib.surface` to `XLib.window`, as that more accurately represents the underlying type. * Implement `HasRawWindowHandle` for `RawWindowHandle` * Add `HINSTANCE` field to `WindowsHandle`. ## 0.2.0 (2019-09-26) * **Breaking:** Rename `X11` to `XLib`. * Add XCB support. * Add Web support. * Add Android support. ## 0.1.2 (2019-08-13) * Fix use of private `_non_exhaustive` field in platform handle structs preventing structs from getting initialized. ## 0.1.1 (2019-08-13) * Flesh out Cargo.toml, adding crates.io info rendering tags. ## 0.1.0 (2019-08-13) * Initial release. raw-window-handle-0.6.2/Cargo.toml0000644000000026060000000000100123720ustar # THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g., crates.io) dependencies. # # If you are reading this file be aware that the original Cargo.toml # will likely look very different (and much more reasonable). # See Cargo.toml.orig for the original contents. [package] edition = "2021" rust-version = "1.64" name = "raw-window-handle" version = "0.6.2" authors = ["Osspial "] build = false autobins = false autoexamples = false autotests = false autobenches = false description = "Interoperability library for Rust Windowing applications." documentation = "https://docs.rs/raw-window-handle" readme = "README.md" keywords = ["windowing"] license = "MIT OR Apache-2.0 OR Zlib" repository = "https://github.com/rust-windowing/raw-window-handle" [package.metadata.docs.rs] all-features = true rustdoc-args = [ "--cfg", "docsrs", ] [lib] name = "raw_window_handle" path = "src/lib.rs" [dev-dependencies.static_assertions] version = "1.1.0" [features] alloc = [] std = ["alloc"] wasm-bindgen-0-2 = [ "wasm-bindgen", "std", ] [target."cfg(target_family = \"wasm\")".dependencies.wasm-bindgen] version = "0.2.87" features = ["std"] optional = true default-features = false raw-window-handle-0.6.2/Cargo.toml.orig000064400000000000000000000015151046102023000160510ustar 00000000000000[package] name = "raw-window-handle" version = "0.6.2" authors = ["Osspial "] edition = "2021" description = "Interoperability library for Rust Windowing applications." license = "MIT OR Apache-2.0 OR Zlib" repository = "https://github.com/rust-windowing/raw-window-handle" keywords = ["windowing"] readme = "README.md" documentation = "https://docs.rs/raw-window-handle" rust-version = "1.64" [features] alloc = [] std = ["alloc"] # Allow conversion methods to/from WASM types using `wasm-bindgen` v0.2. wasm-bindgen-0-2 = ["wasm-bindgen", "std"] [target.'cfg(target_family = "wasm")'.dependencies.wasm-bindgen] version = "0.2.87" default-features = false features = ["std"] optional = true [dev-dependencies] static_assertions = "1.1.0" [package.metadata.docs.rs] all-features = true rustdoc-args = ["--cfg", "docsrs"] raw-window-handle-0.6.2/LICENSE-APACHE.md000064400000000000000000000236761046102023000155210ustar 00000000000000 Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS raw-window-handle-0.6.2/LICENSE-MIT.md000064400000000000000000000020501046102023000152100ustar 00000000000000MIT License Copyright (c) 2019 Osspial Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. raw-window-handle-0.6.2/LICENSE-ZLIB.md000064400000000000000000000015041046102023000153220ustar 00000000000000Copyright (c) 2020 Osspial This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: 1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required. 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution. raw-window-handle-0.6.2/README.md000064400000000000000000000024311046102023000144370ustar 00000000000000# `raw-window-handle`: A common windowing interoperability library for Rust [![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) [![CI Status](https://github.com/rust-windowing/raw-window-handle/workflows/CI/badge.svg)](https://github.com/rust-windowing/raw-window-handle/actions) 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). ## MSRV Policy The Minimum Safe Rust Version (MSRV) of this crate as of the time of writing is **1.64.0**. For pre-`1.0` releases of `raw-window-handle`, this version will not be changed without a patch bump to the version of `raw-window-handle`. After version `1.0.0` is released, changes to the MSRV will necessitate a minor version bump. When the `wasm-bindgen-0-2` feature is enabled, the MSRV of this crate will be raised to the MSRV of the latest version of `wasm-bindgen`. raw-window-handle-0.6.2/rustfmt.toml000064400000000000000000000000361046102023000155600ustar 00000000000000use_field_init_shorthand=true raw-window-handle-0.6.2/src/android.rs000064400000000000000000000036511046102023000157420ustar 00000000000000use core::ffi::c_void; use core::ptr::NonNull; use super::DisplayHandle; /// Raw display handle for Android. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct AndroidDisplayHandle {} impl AndroidDisplayHandle { /// Create a new empty display handle. /// /// /// # Example /// /// ``` /// # use raw_window_handle::AndroidDisplayHandle; /// let handle = AndroidDisplayHandle::new(); /// ``` pub fn new() -> Self { Self {} } } impl DisplayHandle<'static> { /// Create an Android-based display handle. /// /// As no data is borrowed by this handle, it is completely safe to create. This function /// may be useful to windowing framework implementations that want to avoid unsafe code. /// /// # Example /// /// ``` /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle}; /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; } /// let handle = DisplayHandle::android(); /// do_something(handle); /// ``` pub fn android() -> Self { // SAFETY: No data is borrowed. unsafe { Self::borrow_raw(AndroidDisplayHandle::new().into()) } } } /// Raw window handle for Android NDK. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct AndroidNdkWindowHandle { /// A pointer to an `ANativeWindow`. pub a_native_window: NonNull, } impl AndroidNdkWindowHandle { /// Create a new handle to an `ANativeWindow`. /// /// /// # Example /// /// ``` /// # use core::ptr::NonNull; /// # use raw_window_handle::AndroidNdkWindowHandle; /// # type ANativeWindow = (); /// # /// let ptr: NonNull; /// # ptr = NonNull::from(&()); /// let handle = AndroidNdkWindowHandle::new(ptr.cast()); /// ``` pub fn new(a_native_window: NonNull) -> Self { Self { a_native_window } } } raw-window-handle-0.6.2/src/appkit.rs000064400000000000000000000065221046102023000156120ustar 00000000000000use core::ffi::c_void; use core::ptr::NonNull; use super::DisplayHandle; /// Raw display handle for AppKit. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct AppKitDisplayHandle {} impl AppKitDisplayHandle { /// Create a new empty display handle. /// /// /// # Example /// /// ``` /// # use raw_window_handle::AppKitDisplayHandle; /// let handle = AppKitDisplayHandle::new(); /// ``` pub fn new() -> Self { Self {} } } impl DisplayHandle<'static> { /// Create an AppKit-based display handle. /// /// As no data is borrowed by this handle, it is completely safe to create. This function /// may be useful to windowing framework implementations that want to avoid unsafe code. /// /// # Example /// /// ``` /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle}; /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; } /// let handle = DisplayHandle::appkit(); /// do_something(handle); /// ``` pub fn appkit() -> Self { // SAFETY: No data is borrowed. unsafe { Self::borrow_raw(AppKitDisplayHandle::new().into()) } } } /// Raw window handle for AppKit. /// /// Note that `NSView` can only be accessed from the main thread of the /// application. This struct is `!Send` and `!Sync` to help with ensuring /// that. /// /// # Example /// /// Getting the view from a [`WindowHandle`][crate::WindowHandle]. /// /// ```no_run /// # fn inner() { /// #![cfg(target_os = "macos")] /// # #[cfg(requires_objc2)] /// use objc2_app_kit::NSView; /// # #[cfg(requires_objc2)] /// use objc2_foundation::is_main_thread; /// # #[cfg(requires_objc2)] /// use objc2::rc::Id; /// use raw_window_handle::{WindowHandle, RawWindowHandle}; /// /// let handle: WindowHandle<'_>; // Get the window handle from somewhere else /// # handle = unimplemented!(); /// match handle.as_raw() { /// # #[cfg(requires_objc2)] /// RawWindowHandle::AppKit(handle) => { /// assert!(is_main_thread(), "can only access AppKit handles on the main thread"); /// let ns_view = handle.ns_view.as_ptr(); /// // SAFETY: The pointer came from `WindowHandle`, which ensures /// // that the `AppKitWindowHandle` contains a valid pointer to an /// // `NSView`. /// // Unwrap is fine, since the pointer came from `NonNull`. /// let ns_view: Id = unsafe { Id::retain(ns_view.cast()) }.unwrap(); /// // Do something with the NSView here, like getting the `NSWindow` /// let ns_window = ns_view.window().expect("view was not installed in a window"); /// } /// handle => unreachable!("unknown handle {handle:?} for platform"), /// } /// # } /// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct AppKitWindowHandle { /// A pointer to an `NSView` object. pub ns_view: NonNull, } impl AppKitWindowHandle { /// Create a new handle to a view. /// /// /// # Example /// /// ``` /// # use core::ptr::NonNull; /// # use raw_window_handle::AppKitWindowHandle; /// # type NSView = (); /// # /// let view: &NSView; /// # view = &(); /// let handle = AppKitWindowHandle::new(NonNull::from(view).cast()); /// ``` pub fn new(ns_view: NonNull) -> Self { Self { ns_view } } } raw-window-handle-0.6.2/src/borrowed.rs000064400000000000000000000242541046102023000161470ustar 00000000000000//! Borrowable window handles based on the ones in this crate. //! //! These should be 100% safe to pass around and use, no possibility of dangling or invalidity. use core::borrow::Borrow; use core::fmt; use core::marker::PhantomData; use crate::{HandleError, RawDisplayHandle, RawWindowHandle}; /// A display that acts as a wrapper around a display handle. /// /// Objects that implement this trait should be able to return a [`DisplayHandle`] for the display /// that they are associated with. This handle should last for the lifetime of the object, and should /// return an error if the application is inactive. /// /// Implementors of this trait will be windowing systems, like [`winit`] and [`sdl2`]. These windowing /// systems should implement this trait on types that represent the top-level display server. It /// should be implemented by tying the lifetime of the [`DisplayHandle`] to the lifetime of the /// display object. /// /// Users of this trait will include graphics libraries, like [`wgpu`] and [`glutin`]. These APIs /// should be generic over a type that implements `HasDisplayHandle`, and should use the /// [`DisplayHandle`] type to access the display handle. /// /// Note that these requirements are not enforced on `HasDisplayHandle`, rather, they are enforced on the /// constructors of [`DisplayHandle`]. This is because the `HasDisplayHandle` trait is safe to implement. /// /// [`winit`]: https://crates.io/crates/winit /// [`sdl2`]: https://crates.io/crates/sdl2 /// [`wgpu`]: https://crates.io/crates/wgpu /// [`glutin`]: https://crates.io/crates/glutin pub trait HasDisplayHandle { /// Get a handle to the display controller of the windowing system. fn display_handle(&self) -> Result, HandleError>; } impl HasDisplayHandle for &H { fn display_handle(&self) -> Result, HandleError> { (**self).display_handle() } } impl HasDisplayHandle for &mut H { fn display_handle(&self) -> Result, HandleError> { (**self).display_handle() } } #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] impl HasDisplayHandle for alloc::boxed::Box { fn display_handle(&self) -> Result, HandleError> { (**self).display_handle() } } #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] impl HasDisplayHandle for alloc::rc::Rc { fn display_handle(&self) -> Result, HandleError> { (**self).display_handle() } } #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] impl HasDisplayHandle for alloc::sync::Arc { fn display_handle(&self) -> Result, HandleError> { (**self).display_handle() } } /// The handle to the display controller of the windowing system. /// /// This is the primary return type of the [`HasDisplayHandle`] trait. It is guaranteed to contain /// a valid platform-specific display handle for its lifetime. #[repr(transparent)] #[derive(PartialEq, Eq, Hash, Copy, Clone)] pub struct DisplayHandle<'a> { raw: RawDisplayHandle, _marker: PhantomData<&'a ()>, } impl fmt::Debug for DisplayHandle<'_> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_tuple("DisplayHandle").field(&self.raw).finish() } } impl<'a> DisplayHandle<'a> { /// Create a `DisplayHandle` from a [`RawDisplayHandle`]. /// /// # 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, implementors 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. /// /// It is not possible to invalidate a [`DisplayHandle`] on any platform without additional unsafe code. pub unsafe fn borrow_raw(raw: RawDisplayHandle) -> Self { Self { raw, _marker: PhantomData, } } /// Get the underlying raw display handle. pub fn as_raw(&self) -> RawDisplayHandle { self.raw } } impl AsRef for DisplayHandle<'_> { fn as_ref(&self) -> &RawDisplayHandle { &self.raw } } impl Borrow for DisplayHandle<'_> { fn borrow(&self) -> &RawDisplayHandle { &self.raw } } impl From> for RawDisplayHandle { fn from(handle: DisplayHandle<'_>) -> Self { handle.raw } } impl<'a> HasDisplayHandle for DisplayHandle<'a> { fn display_handle(&self) -> Result, HandleError> { Ok(*self) } } /// A handle to a window. /// /// Objects that implement this trait should be able to return a [`WindowHandle`] for the window /// that they are associated with. This handle should last for the lifetime of the object, and should /// return an error if the application is inactive. /// /// Implementors of this trait will be windowing systems, like [`winit`] and [`sdl2`]. These windowing /// systems should implement this trait on types that represent windows. /// /// Users of this trait will include graphics libraries, like [`wgpu`] and [`glutin`]. These APIs /// should be generic over a type that implements `HasWindowHandle`, and should use the /// [`WindowHandle`] type to access the window handle. The window handle should be acquired and held /// while the window is being used, in order to ensure that the window is not deleted while it is in /// use. /// /// [`winit`]: https://crates.io/crates/winit /// [`sdl2`]: https://crates.io/crates/sdl2 /// [`wgpu`]: https://crates.io/crates/wgpu /// [`glutin`]: https://crates.io/crates/glutin pub trait HasWindowHandle { /// Get a handle to the window. fn window_handle(&self) -> Result, HandleError>; } impl HasWindowHandle for &H { fn window_handle(&self) -> Result, HandleError> { (**self).window_handle() } } impl HasWindowHandle for &mut H { fn window_handle(&self) -> Result, HandleError> { (**self).window_handle() } } #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] impl HasWindowHandle for alloc::boxed::Box { fn window_handle(&self) -> Result, HandleError> { (**self).window_handle() } } #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] impl HasWindowHandle for alloc::rc::Rc { fn window_handle(&self) -> Result, HandleError> { (**self).window_handle() } } #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] impl HasWindowHandle for alloc::sync::Arc { fn window_handle(&self) -> Result, HandleError> { (**self).window_handle() } } /// The handle to a window. /// /// This is the primary return type of the [`HasWindowHandle`] trait. All *pointers* within this type /// are guaranteed to be valid and not dangling for the lifetime of the handle. This excludes window IDs /// like XIDs and the window ID for web platforms. See the documentation on the [`HasWindowHandle`] /// trait for more information about these safety requirements. /// /// This handle is guaranteed to be safe and valid. #[derive(PartialEq, Eq, Hash, Copy, Clone)] pub struct WindowHandle<'a> { raw: RawWindowHandle, _marker: PhantomData<&'a ()>, } impl fmt::Debug for WindowHandle<'_> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_tuple("WindowHandle").field(&self.raw).finish() } } impl<'a> WindowHandle<'a> { /// Borrow a `WindowHandle` from a [`RawWindowHandle`]. /// /// # 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. /// /// Note that this guarantee only applies to *pointers*, and not any window ID types in the handle. /// This includes Window IDs (XIDs) from X11 and the window ID for web platforms. There is no way for /// Rust to enforce any kind of invariant on these types, since: /// /// - For all three listed platforms, it is possible for safe code in the same process to delete /// the window. /// - For X11, it is possible for code in a different process to delete the window. In fact, it is /// possible for code on a different *machine* to delete the window. /// /// It is *also* possible for the window to be replaced with another, valid-but-different window. User /// code should be aware of this possibility, and should be ready to soundly handle the possible error /// conditions that can arise from this. pub unsafe fn borrow_raw(raw: RawWindowHandle) -> Self { Self { raw, _marker: PhantomData, } } /// Get the underlying raw window handle. pub fn as_raw(&self) -> RawWindowHandle { self.raw.clone() } } impl AsRef for WindowHandle<'_> { fn as_ref(&self) -> &RawWindowHandle { &self.raw } } impl Borrow for WindowHandle<'_> { fn borrow(&self) -> &RawWindowHandle { &self.raw } } impl From> for RawWindowHandle { fn from(handle: WindowHandle<'_>) -> Self { handle.raw } } impl HasWindowHandle for WindowHandle<'_> { fn window_handle(&self) -> Result { Ok(*self) } } raw-window-handle-0.6.2/src/haiku.rs000064400000000000000000000041371046102023000154230ustar 00000000000000use core::ffi::c_void; use core::ptr::NonNull; use super::DisplayHandle; /// Raw display handle for Haiku. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct HaikuDisplayHandle {} impl HaikuDisplayHandle { /// Create a new empty display handle. /// /// /// # Example /// /// ``` /// # use raw_window_handle::HaikuDisplayHandle; /// let handle = HaikuDisplayHandle::new(); /// ``` pub fn new() -> Self { Self {} } } impl DisplayHandle<'static> { /// Create an Haiku-based display handle. /// /// As no data is borrowed by this handle, it is completely safe to create. This function /// may be useful to windowing framework implementations that want to avoid unsafe code. /// /// # Example /// /// ``` /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle}; /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; } /// let handle = DisplayHandle::haiku(); /// do_something(handle); /// ``` pub fn haiku() -> Self { // SAFETY: No data is borrowed. unsafe { Self::borrow_raw(HaikuDisplayHandle::new().into()) } } } /// Raw window handle for Haiku. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct HaikuWindowHandle { /// A pointer to a BWindow object pub b_window: NonNull, /// A pointer to a BDirectWindow object that might be null pub b_direct_window: Option>, } impl HaikuWindowHandle { /// Create a new handle to a window. /// /// /// # Example /// /// ``` /// # use core::ptr::NonNull; /// # use raw_window_handle::HaikuWindowHandle; /// # type BWindow = (); /// # /// let b_window: NonNull; /// # b_window = NonNull::from(&()); /// let mut handle = HaikuWindowHandle::new(b_window.cast()); /// // Optionally set `b_direct_window`. /// handle.b_direct_window = None; /// ``` pub fn new(b_window: NonNull) -> Self { Self { b_window, b_direct_window: None, } } } raw-window-handle-0.6.2/src/lib.rs000064400000000000000000000514271046102023000150740ustar 00000000000000#![no_std] #![cfg_attr(docsrs, feature(doc_cfg))] #![allow(clippy::new_without_default)] #![deny(unsafe_op_in_unsafe_fn)] //! Interoperability library for Rust Windowing applications. //! //! This library provides standard types for accessing a window's platform-specific raw window //! 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 [`HasWindowHandle`] and [`HasDisplayHandle`]. //! //! ## Platform handle initialization //! //! Each platform handle struct is purposefully non-exhaustive, so that additional fields may be //! added without breaking backwards compatibility. Each struct provides an `empty` method that may //! be used along with the struct update syntax to construct it. See each specific struct for //! examples. //! //! ## Display Handles //! //! Some windowing systems use a separate display handle for some operations. The display usually //! represents a connection to some display server, but it is not necessarily tied to a particular //! window. See [`RawDisplayHandle`] for more details. #[cfg(feature = "alloc")] extern crate alloc; #[cfg(feature = "std")] extern crate std; mod android; mod appkit; mod borrowed; mod haiku; mod ohos; mod redox; mod uikit; mod unix; mod web; mod windows; pub use android::{AndroidDisplayHandle, AndroidNdkWindowHandle}; pub use appkit::{AppKitDisplayHandle, AppKitWindowHandle}; pub use borrowed::{DisplayHandle, HasDisplayHandle, HasWindowHandle, WindowHandle}; pub use haiku::{HaikuDisplayHandle, HaikuWindowHandle}; pub use ohos::{OhosDisplayHandle, OhosNdkWindowHandle}; pub use redox::{OrbitalDisplayHandle, OrbitalWindowHandle}; pub use uikit::{UiKitDisplayHandle, UiKitWindowHandle}; pub use unix::{ DrmDisplayHandle, DrmWindowHandle, GbmDisplayHandle, GbmWindowHandle, WaylandDisplayHandle, WaylandWindowHandle, XcbDisplayHandle, XcbWindowHandle, XlibDisplayHandle, XlibWindowHandle, }; pub use web::{ WebCanvasWindowHandle, WebDisplayHandle, WebOffscreenCanvasWindowHandle, WebWindowHandle, }; pub use windows::{Win32WindowHandle, WinRtWindowHandle, WindowsDisplayHandle}; use core::fmt; /// Window that wraps around a raw window handle. /// /// # Safety /// /// Users can safely assume that pointers and non-zero fields are valid, 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_window_handle` must remain consistent between multiple calls /// to `raw_window_handle` as long as not indicated otherwise by platform specific events. #[deprecated = "Use `HasWindowHandle` instead"] pub unsafe trait HasRawWindowHandle { fn raw_window_handle(&self) -> Result; } #[allow(deprecated)] unsafe impl HasRawWindowHandle for T { fn raw_window_handle(&self) -> Result { self.window_handle().map(Into::into) } } /// A window handle for a particular windowing system. /// /// Each variant contains a struct with fields specific to that windowing system /// (e.g. [`Win32WindowHandle`] will include a [HWND], [`WaylandWindowHandle`] uses [wl_surface], /// etc.) /// /// [HWND]: https://learn.microsoft.com/en-us/windows/win32/winmsg/about-windows#window-handle /// [wl_surface]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_surface /// /// # 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 /// [`HasWindowHandle`] implementor is completely allowed to return something /// unexpected. (For example, it's legal for someone to return a /// [`RawWindowHandle::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 RawWindowHandle { /// A raw window 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(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(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(OrbitalWindowHandle), /// A raw window handle for the OpenHarmony OS NDK /// /// ## Availability Hints /// This variant is used on OpenHarmony OS (`target_env = "ohos"`). OhosNdk(OhosNdkWindowHandle), /// 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(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(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(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(DrmWindowHandle), /// A raw window handle for the Linux Generic Buffer Manager. /// /// ## Availability Hints /// This variant is present regardless of windowing backend and likely to be used with /// EGL_MESA_platform_gbm or EGL_KHR_platform_gbm. Gbm(GbmWindowHandle), /// A raw window handle for Win32. /// /// ## Availability Hints /// This variant is used on Windows systems. Win32(Win32WindowHandle), /// A raw window handle for WinRT. /// /// ## Availability Hints /// This variant is used on Windows systems. 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(WebWindowHandle), /// A raw window handle for a Web canvas registered via [`wasm-bindgen`]. /// /// ## Availability Hints /// This variant is used on Wasm or asm.js targets when targeting the Web/HTML5. /// /// [`wasm-bindgen`]: https://crates.io/crates/wasm-bindgen WebCanvas(WebCanvasWindowHandle), /// A raw window handle for a Web offscreen canvas registered via [`wasm-bindgen`]. /// /// ## Availability Hints /// This variant is used on Wasm or asm.js targets when targeting the Web/HTML5. /// /// [`wasm-bindgen`]: https://crates.io/crates/wasm-bindgen WebOffscreenCanvas(WebOffscreenCanvasWindowHandle), /// A raw window handle for Android NDK. /// /// ## Availability Hints /// This variant is used on Android targets. AndroidNdk(AndroidNdkWindowHandle), /// A raw window handle for Haiku. /// /// ## Availability Hints /// This variant is used on HaikuOS. Haiku(HaikuWindowHandle), } /// Display that wraps around a raw display handle. /// /// # Safety /// /// Users can safely assume that pointers and non-zero fields are valid, 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. #[deprecated = "Use `HasDisplayHandle` instead"] pub unsafe trait HasRawDisplayHandle { fn raw_display_handle(&self) -> Result; } #[allow(deprecated)] unsafe impl HasRawDisplayHandle for T { fn raw_display_handle(&self) -> Result { self.display_handle().map(Into::into) } } /// A display server handle for a particular windowing system. /// /// The display usually represents a connection to some display server, but it is not necessarily /// tied to a particular window. Some APIs can use the display handle without ever creating a window /// handle (e.g. offscreen rendering, headless event handling). /// /// Each variant contains a struct with fields specific to that windowing system /// (e.g. [`XlibDisplayHandle`] contains a [Display] connection to an X Server, /// [`WaylandDisplayHandle`] uses [wl_display] to connect to a compositor). Not all windowing /// systems have a separate display handle (or they haven't been implemented yet) and their variants /// contain empty structs. /// /// [Display]: https://www.x.org/releases/current/doc/libX11/libX11/libX11.html#Display_Functions /// [wl_display]: https://wayland.freedesktop.org/docs/html/apb.html#Client-classwl__display /// /// # 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 /// [`HasDisplayHandle`] 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 OpenHarmony OS NDK /// /// ## Availability Hints /// This variant is used on OpenHarmony OS (`target_env = "ohos"`). Ohos(OhosDisplayHandle), /// 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 the Linux Generic Buffer Manager. /// /// ## Availability Hints /// This variant is present regardless of windowing backend and likely to be used with /// EGL_MESA_platform_gbm or EGL_KHR_platform_gbm. Gbm(GbmDisplayHandle), /// 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), } /// An error that can occur while fetching a display or window handle. #[derive(Debug, Clone)] #[non_exhaustive] pub enum HandleError { /// The underlying handle cannot be represented using the types in this crate. /// /// This may be returned if the underlying window system does not support any of the /// representative C window handles in this crate. For instance, if you were using a pure Rust /// library to set up X11 (like [`x11rb`]), you would not be able to use any of the /// [`RawWindowHandle`] variants, as they all represent C types. /// /// Another example would be a system that isn't supported by `raw-window-handle` yet, /// like some game consoles. /// /// In the event that this error is returned, you should try to use the underlying window /// system's native API to get the handle you need. /// /// [`x11rb`]: https://crates.io/crates/x11rb NotSupported, /// The underlying handle is not available. /// /// In some cases the underlying window handle may become temporarily unusable. For example, on /// Android, the native window pointer can arbitrarily be replaced or removed by the system. In /// this case, returning a window handle would be disingenuous, as it would not be usable. A /// similar situation can occur on Wayland for the layer shell windows. /// /// In the event that this error is returned, you should wait until the handle becomes available /// again. Unavailable, } impl fmt::Display for HandleError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { Self::NotSupported => write!( f, "the underlying handle cannot be represented using the types in this crate" ), Self::Unavailable => write!(f, "the underlying handle is not available"), } } } #[cfg(feature = "std")] impl std::error::Error for HandleError {} macro_rules! from_impl { ($($to:ident, $enum:ident, $from:ty)*) => ($( impl From<$from> for $to { fn from(value: $from) -> Self { $to::$enum(value) } } )*) } from_impl!(RawDisplayHandle, UiKit, UiKitDisplayHandle); from_impl!(RawDisplayHandle, AppKit, AppKitDisplayHandle); from_impl!(RawDisplayHandle, Orbital, OrbitalDisplayHandle); from_impl!(RawDisplayHandle, Ohos, OhosDisplayHandle); from_impl!(RawDisplayHandle, Xlib, XlibDisplayHandle); from_impl!(RawDisplayHandle, Xcb, XcbDisplayHandle); from_impl!(RawDisplayHandle, Wayland, WaylandDisplayHandle); from_impl!(RawDisplayHandle, Drm, DrmDisplayHandle); from_impl!(RawDisplayHandle, Gbm, GbmDisplayHandle); from_impl!(RawDisplayHandle, Windows, WindowsDisplayHandle); from_impl!(RawDisplayHandle, Web, WebDisplayHandle); from_impl!(RawDisplayHandle, Android, AndroidDisplayHandle); from_impl!(RawDisplayHandle, Haiku, HaikuDisplayHandle); from_impl!(RawWindowHandle, UiKit, UiKitWindowHandle); from_impl!(RawWindowHandle, AppKit, AppKitWindowHandle); from_impl!(RawWindowHandle, Orbital, OrbitalWindowHandle); from_impl!(RawWindowHandle, OhosNdk, OhosNdkWindowHandle); from_impl!(RawWindowHandle, Xlib, XlibWindowHandle); from_impl!(RawWindowHandle, Xcb, XcbWindowHandle); from_impl!(RawWindowHandle, Wayland, WaylandWindowHandle); from_impl!(RawWindowHandle, Drm, DrmWindowHandle); from_impl!(RawWindowHandle, Gbm, GbmWindowHandle); from_impl!(RawWindowHandle, Win32, Win32WindowHandle); from_impl!(RawWindowHandle, WinRt, WinRtWindowHandle); from_impl!(RawWindowHandle, Web, WebWindowHandle); from_impl!(RawWindowHandle, WebCanvas, WebCanvasWindowHandle); from_impl!( RawWindowHandle, WebOffscreenCanvas, WebOffscreenCanvasWindowHandle ); from_impl!(RawWindowHandle, AndroidNdk, AndroidNdkWindowHandle); from_impl!(RawWindowHandle, Haiku, HaikuWindowHandle); #[cfg(test)] mod tests { use core::panic::{RefUnwindSafe, UnwindSafe}; use static_assertions::{assert_impl_all, assert_not_impl_any}; use super::*; #[test] fn auto_traits() { assert_impl_all!(RawDisplayHandle: UnwindSafe, RefUnwindSafe, Unpin); assert_not_impl_any!(RawDisplayHandle: Send, Sync); assert_impl_all!(DisplayHandle<'_>: UnwindSafe, RefUnwindSafe, Unpin); assert_not_impl_any!(DisplayHandle<'_>: Send, Sync); assert_impl_all!(RawWindowHandle: UnwindSafe, RefUnwindSafe, Unpin); assert_not_impl_any!(RawWindowHandle: Send, Sync); assert_impl_all!(WindowHandle<'_>: UnwindSafe, RefUnwindSafe, Unpin); assert_not_impl_any!(WindowHandle<'_>: Send, Sync); assert_impl_all!(HandleError: Send, Sync, UnwindSafe, RefUnwindSafe, Unpin); // TODO: Unsure if some of these should not actually be Send + Sync assert_impl_all!(UiKitDisplayHandle: Send, Sync); assert_impl_all!(AppKitDisplayHandle: Send, Sync); assert_impl_all!(OrbitalDisplayHandle: Send, Sync); assert_impl_all!(OhosDisplayHandle: Send, Sync); assert_not_impl_any!(XlibDisplayHandle: Send, Sync); assert_not_impl_any!(XcbDisplayHandle: Send, Sync); assert_not_impl_any!(WaylandDisplayHandle: Send, Sync); assert_impl_all!(DrmDisplayHandle: Send, Sync); assert_not_impl_any!(GbmDisplayHandle: Send, Sync); assert_impl_all!(WindowsDisplayHandle: Send, Sync); assert_impl_all!(WebDisplayHandle: Send, Sync); assert_impl_all!(AndroidDisplayHandle: Send, Sync); assert_impl_all!(HaikuDisplayHandle: Send, Sync); // TODO: Unsure if some of these should not actually be Send + Sync assert_not_impl_any!(UiKitWindowHandle: Send, Sync); assert_not_impl_any!(AppKitWindowHandle: Send, Sync); assert_not_impl_any!(OrbitalWindowHandle: Send, Sync); assert_not_impl_any!(OhosNdkWindowHandle: Send, Sync); assert_impl_all!(XlibWindowHandle: Send, Sync); assert_impl_all!(XcbWindowHandle: Send, Sync); assert_not_impl_any!(WaylandWindowHandle: Send, Sync); assert_impl_all!(DrmWindowHandle: Send, Sync); assert_not_impl_any!(GbmWindowHandle: Send, Sync); assert_impl_all!(Win32WindowHandle: Send, Sync); assert_not_impl_any!(WinRtWindowHandle: Send, Sync); assert_impl_all!(WebWindowHandle: Send, Sync); assert_not_impl_any!(WebCanvasWindowHandle: Send, Sync); assert_not_impl_any!(WebOffscreenCanvasWindowHandle: Send, Sync); assert_not_impl_any!(AndroidNdkWindowHandle: Send, Sync); assert_not_impl_any!(HaikuWindowHandle: Send, Sync); } #[allow(deprecated, unused)] fn assert_object_safe( _: &dyn HasRawWindowHandle, _: &dyn HasRawDisplayHandle, _: &dyn HasWindowHandle, _: &dyn HasDisplayHandle, ) { } } raw-window-handle-0.6.2/src/ohos.rs000064400000000000000000000074671046102023000153030ustar 00000000000000//! [OpenHarmony] OS Window Handles //! //! ## Background //! //! Applications on [OpenHarmony] use [ArkUI] for defining their UI. Applications can use an //! [XComponent] to render using native Code (e.g. Rust) via EGL. //! Native code will receive a callback `OnSurfaceCreatedCB(OH_NativeXComponent *component, void *window)` //! when the `XComponent` is created. The window argument has the type [`OHNativeWindow`] / `EGLNativeWindowType`. //! The window can then be used to create a surface with //! `eglCreateWindowSurface(eglDisplay_, eglConfig_, window, NULL)` //! //! [OpenHarmony]: https://gitee.com/openharmony/docs/blob/master/en/OpenHarmony-Overview.md //! [ArkUI]: https://gitee.com/openharmony/docs/blob/master/en/application-dev/ui/arkui-overview.md //! [XComponent]: https://gitee.com/openharmony/docs/blob/master/en/application-dev/ui/arkts-common-components-xcomponent.md //! [`OHNativeWindow`]: https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis-arkgraphics2d/_native_window.md use core::ffi::c_void; use core::ptr::NonNull; use super::DisplayHandle; /// Raw display handle for OpenHarmony. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct OhosDisplayHandle {} impl OhosDisplayHandle { /// Create a new empty display handle. /// /// /// # Example /// /// ``` /// # use raw_window_handle::OhosDisplayHandle; /// let handle = OhosDisplayHandle::new(); /// ``` pub fn new() -> Self { Self {} } } impl DisplayHandle<'static> { /// Create an OpenHarmony-based display handle. /// /// As no data is borrowed by this handle, it is completely safe to create. This function /// may be useful to windowing framework implementations that want to avoid unsafe code. /// /// # Example /// /// ``` /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle}; /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; } /// let handle = DisplayHandle::ohos(); /// do_something(handle); /// ``` pub fn ohos() -> Self { // SAFETY: No data is borrowed. unsafe { Self::borrow_raw(OhosDisplayHandle::new().into()) } } } /// Raw window handle for Ohos NDK. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct OhosNdkWindowHandle { pub native_window: NonNull, } impl OhosNdkWindowHandle { /// Create a new handle to an [`OHNativeWindow`] on OpenHarmony. /// /// The handle will typically be created from an [`XComponent`], consult the /// [native `XComponent` Guidelines] for more details. /// /// [`XComponent`]: https://gitee.com/openharmony/docs/blob/master/en/application-dev/ui/arkts-common-components-xcomponent.md /// [native `XComponent` Guidelines]: https://gitee.com/openharmony/docs/blob/OpenHarmony-4.0-Release/en/application-dev/napi/xcomponent-guidelines.md /// [`OHNativeWindow`]: https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis-arkgraphics2d/_native_window.md /// # Example /// /// ``` /// # use core::ptr::NonNull; /// # use core::ffi::c_void; /// # use raw_window_handle::OhosNdkWindowHandle; /// # #[allow(non_camel_case_types)] /// # type OH_NativeXComponent = (); /// /// /// Called When the `XComponent` is created. /// /// /// /// See the [XComponent Guidelines](https://gitee.com/openharmony/docs/blob/OpenHarmony-4.0-Release/en/application-dev/napi/xcomponent-guidelines.md) /// /// for more details /// extern "C" fn on_surface_created_callback(component: *mut OH_NativeXComponent, window: *mut c_void) { /// let handle = OhosNdkWindowHandle::new(NonNull::new(window).unwrap()); /// } /// ``` pub fn new(native_window: NonNull) -> Self { Self { native_window } } } raw-window-handle-0.6.2/src/redox.rs000064400000000000000000000040631046102023000154410ustar 00000000000000use core::ffi::c_void; use core::ptr::NonNull; use super::DisplayHandle; /// Raw display handle for the Redox operating system. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct OrbitalDisplayHandle {} impl OrbitalDisplayHandle { /// Create a new empty display handle. /// /// /// # Example /// /// ``` /// # use raw_window_handle::OrbitalDisplayHandle; /// let handle = OrbitalDisplayHandle::new(); /// ``` pub fn new() -> Self { Self {} } } impl DisplayHandle<'static> { /// Create an Orbital-based display handle. /// /// As no data is borrowed by this handle, it is completely safe to create. This function /// may be useful to windowing framework implementations that want to avoid unsafe code. /// /// # Example /// /// ``` /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle}; /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; } /// let handle = DisplayHandle::orbital(); /// do_something(handle); /// ``` pub fn orbital() -> Self { // SAFETY: No data is borrowed. unsafe { Self::borrow_raw(OrbitalDisplayHandle::new().into()) } } } /// Raw window handle for the Redox operating system. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct OrbitalWindowHandle { /// A pointer to an orbclient window. // TODO(madsmtm): I think this is a file descriptor, so perhaps it should // actually use `std::os::fd::RawFd`, or some sort of integer instead? pub window: NonNull, } impl OrbitalWindowHandle { /// Create a new handle to a window. /// /// /// # Example /// /// ``` /// # use core::ptr::NonNull; /// # use raw_window_handle::OrbitalWindowHandle; /// # type Window = (); /// # /// let window: NonNull; /// # window = NonNull::from(&()); /// let mut handle = OrbitalWindowHandle::new(window.cast()); /// ``` pub fn new(window: NonNull) -> Self { Self { window } } } raw-window-handle-0.6.2/src/uikit.rs000064400000000000000000000070371046102023000154510ustar 00000000000000use core::ffi::c_void; use core::ptr::NonNull; use super::DisplayHandle; /// Raw display handle for UIKit. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct UiKitDisplayHandle {} impl UiKitDisplayHandle { /// Create a new empty display handle. /// /// /// # Example /// /// ``` /// # use raw_window_handle::UiKitDisplayHandle; /// let handle = UiKitDisplayHandle::new(); /// ``` pub fn new() -> Self { Self {} } } impl DisplayHandle<'static> { /// Create a UiKit-based display handle. /// /// As no data is borrowed by this handle, it is completely safe to create. This function /// may be useful to windowing framework implementations that want to avoid unsafe code. /// /// # Example /// /// ``` /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle}; /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; } /// let handle = DisplayHandle::uikit(); /// do_something(handle); /// ``` pub fn uikit() -> Self { // SAFETY: No data is borrowed. unsafe { Self::borrow_raw(UiKitDisplayHandle::new().into()) } } } /// Raw window handle for UIKit. /// /// Note that `UIView` can only be accessed from the main thread of the /// application. This struct is `!Send` and `!Sync` to help with ensuring /// that. /// /// # Example /// /// Getting the view from a [`WindowHandle`][crate::WindowHandle]. /// /// ```no_run /// # fn inner() { /// #![cfg(any(target_os = "ios", target_os = "tvos", target_os = "watchos", target_os = "xros"))] /// # #[cfg(requires_objc2)] /// use objc2_foundation::is_main_thread; /// # #[cfg(requires_objc2)] /// use objc2::rc::Id; /// # #[cfg(requires_objc2)] /// use objc2_ui_kit::UIView; /// use raw_window_handle::{WindowHandle, RawWindowHandle}; /// /// let handle: WindowHandle<'_>; // Get the window handle from somewhere else /// # handle = unimplemented!(); /// match handle.as_raw() { /// # #[cfg(requires_objc2)] /// RawWindowHandle::UIKit(handle) => { /// assert!(is_main_thread(), "can only access UIKit handles on the main thread"); /// let ui_view = handle.ui_view.as_ptr(); /// // SAFETY: The pointer came from `WindowHandle`, which ensures /// // that the `UiKitWindowHandle` contains a valid pointer to an /// // `UIView`. /// // Unwrap is fine, since the pointer came from `NonNull`. /// let ui_view: Id = unsafe { Id::retain(ui_view.cast()) }.unwrap(); /// // Do something with the UIView here. /// } /// handle => unreachable!("unknown handle {handle:?} for platform"), /// } /// # } /// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct UiKitWindowHandle { /// A pointer to an `UIView` object. pub ui_view: NonNull, /// A pointer to an `UIViewController` object, if the view has one. pub ui_view_controller: Option>, } impl UiKitWindowHandle { /// Create a new handle to a view. /// /// /// # Example /// /// ``` /// # use core::ptr::NonNull; /// # use raw_window_handle::UiKitWindowHandle; /// # type UIView = (); /// # /// let view: &UIView; /// # view = &(); /// let mut handle = UiKitWindowHandle::new(NonNull::from(view).cast()); /// // Optionally set the view controller. /// handle.ui_view_controller = None; /// ``` pub fn new(ui_view: NonNull) -> Self { Self { ui_view, ui_view_controller: None, } } } raw-window-handle-0.6.2/src/unix.rs000064400000000000000000000200441046102023000153000ustar 00000000000000use core::ffi::{c_int, c_ulong, c_void}; use core::num::NonZeroU32; use core::ptr::NonNull; /// Raw display handle for Xlib. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct XlibDisplayHandle { /// A pointer to an Xlib `Display`. /// /// It is strongly recommended to set this value, however it may be set to /// `None` to request the default display when using EGL. pub display: Option>, /// 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, } impl XlibDisplayHandle { /// Create a new handle to a display. /// /// /// # Example /// /// ``` /// # use core::ffi::c_void; /// # use core::ptr::NonNull; /// # use raw_window_handle::XlibDisplayHandle; /// # /// let display: NonNull; /// let screen; /// # display = NonNull::from(&()).cast(); /// # screen = 0; /// let handle = XlibDisplayHandle::new(Some(display), screen); /// ``` pub fn new(display: Option>, screen: c_int) -> Self { Self { display, screen } } } /// Raw window handle for Xlib. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct XlibWindowHandle { /// An Xlib `Window`. pub window: c_ulong, /// An Xlib visual ID, or 0 if unknown. pub visual_id: c_ulong, } impl XlibWindowHandle { /// Create a new handle to a window. /// /// /// # Example /// /// ``` /// # use core::ffi::c_ulong; /// # use raw_window_handle::XlibWindowHandle; /// # /// let window: c_ulong; /// # window = 0; /// let mut handle = XlibWindowHandle::new(window); /// // Optionally set the visual ID. /// handle.visual_id = 0; /// ``` pub fn new(window: c_ulong) -> Self { Self { window, visual_id: 0, } } } /// Raw display handle for Xcb. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct XcbDisplayHandle { /// A pointer to an X server `xcb_connection_t`. /// /// It is strongly recommended to set this value, however it may be set to /// `None` to request the default display when using EGL. pub connection: Option>, /// 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, } impl XcbDisplayHandle { /// Create a new handle to a connection and screen. /// /// /// # Example /// /// ``` /// # use core::ffi::c_void; /// # use core::ptr::NonNull; /// # use raw_window_handle::XcbDisplayHandle; /// # /// let connection: NonNull; /// let screen; /// # connection = NonNull::from(&()).cast(); /// # screen = 0; /// let handle = XcbDisplayHandle::new(Some(connection), screen); /// ``` pub fn new(connection: Option>, screen: c_int) -> Self { Self { connection, screen } } } /// Raw window handle for Xcb. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct XcbWindowHandle { /// An X11 `xcb_window_t`. pub window: NonZeroU32, // Based on xproto.h /// An X11 `xcb_visualid_t`. pub visual_id: Option, } impl XcbWindowHandle { /// Create a new handle to a window. /// /// /// # Example /// /// ``` /// # use core::num::NonZeroU32; /// # use raw_window_handle::XcbWindowHandle; /// # /// let window: NonZeroU32; /// # window = NonZeroU32::new(1).unwrap(); /// let mut handle = XcbWindowHandle::new(window); /// // Optionally set the visual ID. /// handle.visual_id = None; /// ``` pub fn new(window: NonZeroU32) -> Self { Self { window, visual_id: None, } } } /// Raw display handle for Wayland. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct WaylandDisplayHandle { /// A pointer to a `wl_display`. pub display: NonNull, } impl WaylandDisplayHandle { /// Create a new display handle. /// /// /// # Example /// /// ``` /// # use core::ffi::c_void; /// # use core::ptr::NonNull; /// # use raw_window_handle::WaylandDisplayHandle; /// # /// let display: NonNull; /// # display = NonNull::from(&()).cast(); /// let handle = WaylandDisplayHandle::new(display); /// ``` pub fn new(display: NonNull) -> Self { Self { display } } } /// Raw window handle for Wayland. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct WaylandWindowHandle { /// A pointer to a `wl_surface`. pub surface: NonNull, } impl WaylandWindowHandle { /// Create a new handle to a surface. /// /// /// # Example /// /// ``` /// # use core::ffi::c_void; /// # use core::ptr::NonNull; /// # use raw_window_handle::WaylandWindowHandle; /// # /// let surface: NonNull; /// # surface = NonNull::from(&()).cast(); /// let handle = WaylandWindowHandle::new(surface); /// ``` pub fn new(surface: NonNull) -> Self { Self { surface } } } /// Raw display handle for the Linux Kernel Mode Set/Direct Rendering Manager. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct DrmDisplayHandle { /// The drm file descriptor. // TODO: Use `std::os::fd::RawFd`? pub fd: i32, } impl DrmDisplayHandle { /// Create a new handle to a file descriptor. /// /// /// # Example /// /// ``` /// # use raw_window_handle::DrmDisplayHandle; /// # /// let fd: i32; /// # fd = 0; /// let handle = DrmDisplayHandle::new(fd); /// ``` pub fn new(fd: i32) -> Self { Self { fd } } } /// Raw window handle for the Linux Kernel Mode Set/Direct Rendering Manager. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct DrmWindowHandle { /// The primary drm plane handle. pub plane: u32, } impl DrmWindowHandle { /// Create a new handle to a plane. /// /// /// # Example /// /// ``` /// # use raw_window_handle::DrmWindowHandle; /// # /// let plane: u32; /// # plane = 0; /// let handle = DrmWindowHandle::new(plane); /// ``` pub fn new(plane: u32) -> Self { Self { plane } } } /// Raw display handle for the Linux Generic Buffer Manager. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct GbmDisplayHandle { /// The gbm device. pub gbm_device: NonNull, } impl GbmDisplayHandle { /// Create a new handle to a device. /// /// /// # Example /// /// ``` /// # use core::ffi::c_void; /// # use core::ptr::NonNull; /// # use raw_window_handle::GbmDisplayHandle; /// # /// let ptr: NonNull; /// # ptr = NonNull::from(&()).cast(); /// let handle = GbmDisplayHandle::new(ptr); /// ``` pub fn new(gbm_device: NonNull) -> Self { Self { gbm_device } } } /// Raw window handle for the Linux Generic Buffer Manager. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct GbmWindowHandle { /// The gbm surface. pub gbm_surface: NonNull, } impl GbmWindowHandle { /// Create a new handle to a surface. /// /// /// # Example /// /// ``` /// # use core::ffi::c_void; /// # use core::ptr::NonNull; /// # use raw_window_handle::GbmWindowHandle; /// # /// let ptr: NonNull; /// # ptr = NonNull::from(&()).cast(); /// let handle = GbmWindowHandle::new(ptr); /// ``` pub fn new(gbm_surface: NonNull) -> Self { Self { gbm_surface } } } raw-window-handle-0.6.2/src/web.rs000064400000000000000000000164031046102023000150760ustar 00000000000000use core::ffi::c_void; use core::ptr::NonNull; use super::DisplayHandle; /// Raw display handle for the Web. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct WebDisplayHandle {} impl WebDisplayHandle { /// Create a new empty display handle. /// /// /// # Example /// /// ``` /// # use raw_window_handle::WebDisplayHandle; /// let handle = WebDisplayHandle::new(); /// ``` pub fn new() -> Self { Self {} } } impl DisplayHandle<'static> { /// Create a Web-based display handle. /// /// As no data is borrowed by this handle, it is completely safe to create. This function /// may be useful to windowing framework implementations that want to avoid unsafe code. /// /// # Example /// /// ``` /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle}; /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; } /// let handle = DisplayHandle::web(); /// do_something(handle); /// ``` pub fn web() -> Self { // SAFETY: No data is borrowed. unsafe { Self::borrow_raw(WebDisplayHandle::new().into()) } } } /// Raw window handle for the Web. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] 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`. /// /// Each canvas created by the windowing system should be assigned their own unique ID. /// /// [data attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-* pub id: u32, } impl WebWindowHandle { /// Create a new handle to a canvas element. /// /// /// # Example /// /// ``` /// # use raw_window_handle::WebWindowHandle; /// # /// let id: u32 = 0; // canvas.rawHandle; /// let handle = WebWindowHandle::new(id); /// ``` pub fn new(id: u32) -> Self { Self { id } } } /// Raw window handle for a Web canvas registered via [`wasm-bindgen`]. /// /// [`wasm-bindgen`]: https://crates.io/crates/wasm-bindgen #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct WebCanvasWindowHandle { /// A pointer to the [`JsValue`] of an [`HtmlCanvasElement`]. /// /// Note: This uses [`c_void`] to avoid depending on `wasm-bindgen` /// directly. /// /// [`JsValue`]: https://docs.rs/wasm-bindgen/latest/wasm_bindgen/struct.JsValue.html /// [`HtmlCanvasElement`]: https://docs.rs/web-sys/latest/web_sys/struct.HtmlCanvasElement.html // // SAFETY: Not using `JsValue` is sound because `wasm-bindgen` guarantees // that there's only one version of itself in any given binary, and hence // we can't have a type-confusion where e.g. one library used `JsValue` // from `v0.2` of `wasm-bindgen`, and another used `JsValue` from `v1.0`; // the binary will simply fail to compile! // // Reference: TODO pub obj: NonNull, } impl WebCanvasWindowHandle { /// Create a new handle from a pointer to [`HtmlCanvasElement`]. /// /// [`HtmlCanvasElement`]: https://docs.rs/web-sys/latest/web_sys/struct.HtmlCanvasElement.html /// /// # Example /// /// ``` /// # use core::ffi::c_void; /// # use core::ptr::NonNull; /// # use raw_window_handle::WebCanvasWindowHandle; /// # type HtmlCanvasElement = (); /// # type JsValue = (); /// let canvas: &HtmlCanvasElement; /// # canvas = &(); /// let value: &JsValue = &canvas; // Deref to `JsValue` /// let obj: NonNull = NonNull::from(value).cast(); /// let mut handle = WebCanvasWindowHandle::new(obj); /// ``` pub fn new(obj: NonNull) -> Self { Self { obj } } } #[cfg(all(target_family = "wasm", feature = "wasm-bindgen-0-2"))] #[cfg_attr( docsrs, doc(cfg(all(target_family = "wasm", feature = "wasm-bindgen-0-2"))) )] /// These implementations are only available when `wasm-bindgen-0-2` is enabled. impl WebCanvasWindowHandle { /// Create a new `WebCanvasWindowHandle` from a [`wasm_bindgen::JsValue`]. /// /// The `JsValue` should refer to a `HtmlCanvasElement`, and the lifetime /// of the value should be at least as long as the lifetime of this. pub fn from_wasm_bindgen_0_2(js_value: &wasm_bindgen::JsValue) -> Self { Self::new(NonNull::from(js_value).cast()) } /// Convert to the underlying [`wasm_bindgen::JsValue`]. /// /// # Safety /// /// The inner pointer must be valid. This is ensured if this handle was /// borrowed from [`WindowHandle`][crate::WindowHandle]. pub unsafe fn as_wasm_bindgen_0_2(&self) -> &wasm_bindgen::JsValue { unsafe { self.obj.cast().as_ref() } } } /// Raw window handle for a Web offscreen canvas registered via /// [`wasm-bindgen`]. /// /// [`wasm-bindgen`]: https://crates.io/crates/wasm-bindgen #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct WebOffscreenCanvasWindowHandle { /// A pointer to the [`JsValue`] of an [`OffscreenCanvas`]. /// /// Note: This uses [`c_void`] to avoid depending on `wasm-bindgen` /// directly. /// /// [`JsValue`]: https://docs.rs/wasm-bindgen/latest/wasm_bindgen/struct.JsValue.html /// [`OffscreenCanvas`]: https://docs.rs/web-sys/latest/web_sys/struct.OffscreenCanvas.html // // SAFETY: See WebCanvasWindowHandle. pub obj: NonNull, } impl WebOffscreenCanvasWindowHandle { /// Create a new handle from a pointer to an [`OffscreenCanvas`]. /// /// [`OffscreenCanvas`]: https://docs.rs/web-sys/latest/web_sys/struct.OffscreenCanvas.html /// /// # Example /// /// ``` /// # use core::ffi::c_void; /// # use core::ptr::NonNull; /// # use raw_window_handle::WebOffscreenCanvasWindowHandle; /// # type OffscreenCanvas = (); /// # type JsValue = (); /// let canvas: &OffscreenCanvas; /// # canvas = &(); /// let value: &JsValue = &canvas; // Deref to `JsValue` /// let obj: NonNull = NonNull::from(value).cast(); /// let mut handle = WebOffscreenCanvasWindowHandle::new(obj); /// ``` pub fn new(obj: NonNull) -> Self { Self { obj } } } #[cfg(all(target_family = "wasm", feature = "wasm-bindgen-0-2"))] #[cfg_attr( docsrs, doc(cfg(all(target_family = "wasm", feature = "wasm-bindgen-0-2"))) )] /// These implementations are only available when `wasm-bindgen-0-2` is enabled. impl WebOffscreenCanvasWindowHandle { /// Create a new `WebOffscreenCanvasWindowHandle` from a /// [`wasm_bindgen::JsValue`]. /// /// The `JsValue` should refer to a `HtmlCanvasElement`, and the lifetime /// of the value should be at least as long as the lifetime of this. pub fn from_wasm_bindgen_0_2(js_value: &wasm_bindgen::JsValue) -> Self { Self::new(NonNull::from(js_value).cast()) } /// Convert to the underlying [`wasm_bindgen::JsValue`]. /// /// # Safety /// /// The inner pointer must be valid. This is ensured if this handle was /// borrowed from [`WindowHandle`][crate::WindowHandle]. pub unsafe fn as_wasm_bindgen_0_2(&self) -> &wasm_bindgen::JsValue { unsafe { self.obj.cast().as_ref() } } } raw-window-handle-0.6.2/src/windows.rs000064400000000000000000000063061046102023000160140ustar 00000000000000use core::ffi::c_void; use core::num::NonZeroIsize; use core::ptr::NonNull; use super::DisplayHandle; /// Raw display handle for Windows. /// /// It can be used regardless of Windows window backend. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct WindowsDisplayHandle {} impl WindowsDisplayHandle { /// Create a new empty display handle. /// /// /// # Example /// /// ``` /// # use raw_window_handle::WindowsDisplayHandle; /// let handle = WindowsDisplayHandle::new(); /// ``` pub fn new() -> Self { Self {} } } impl DisplayHandle<'static> { /// Create a Windows-based display handle. /// /// As no data is borrowed by this handle, it is completely safe to create. This function /// may be useful to windowing framework implementations that want to avoid unsafe code. /// /// # Example /// /// ``` /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle}; /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; } /// let handle = DisplayHandle::windows(); /// do_something(handle); /// ``` pub fn windows() -> Self { // SAFETY: No data is borrowed. unsafe { Self::borrow_raw(WindowsDisplayHandle::new().into()) } } } /// Raw window handle for Win32. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct Win32WindowHandle { /// A Win32 `HWND` handle. pub hwnd: NonZeroIsize, /// The `GWLP_HINSTANCE` associated with this type's `HWND`. pub hinstance: Option, } impl Win32WindowHandle { /// Create a new handle to a window. /// /// # Safety /// /// It is assumed that the Win32 handle belongs to the current thread. This /// is necessary for the handle to be considered "valid" in all cases. /// /// # Example /// /// ``` /// # use core::num::NonZeroIsize; /// # use raw_window_handle::Win32WindowHandle; /// # struct HWND(isize); /// # /// let window: HWND; /// # window = HWND(1); /// let mut handle = Win32WindowHandle::new(NonZeroIsize::new(window.0).unwrap()); /// // Optionally set the GWLP_HINSTANCE. /// # #[cfg(only_for_showcase)] /// let hinstance = NonZeroIsize::new(unsafe { GetWindowLongPtrW(window, GWLP_HINSTANCE) }).unwrap(); /// # let hinstance = None; /// handle.hinstance = hinstance; /// ``` pub fn new(hwnd: NonZeroIsize) -> Self { Self { hwnd, hinstance: None, } } } /// Raw window handle for WinRT. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct WinRtWindowHandle { /// A WinRT `CoreWindow` handle. pub core_window: NonNull, } impl WinRtWindowHandle { /// Create a new handle to a window. /// /// /// # Example /// /// ``` /// # use core::ptr::NonNull; /// # use raw_window_handle::WinRtWindowHandle; /// # type CoreWindow = (); /// # /// let window: NonNull; /// # window = NonNull::from(&()); /// let handle = WinRtWindowHandle::new(window.cast()); /// ``` pub fn new(core_window: NonNull) -> Self { Self { core_window } } }