DeCarabas/oden
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Vendor things

Browse source
This commit is contained in:
John Doty 2024-03-08 11:03:01 -08:00
parent 5deceec006
commit 977e3c17e5
19434 changed files with 10682014 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

615
third-party/vendor/raw-window-handle/src/borrowed.rs vendored Normal file
View file

@ -0,0 +1,615 @@
//! 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.
#[cfg(all(not(feature = "std"), target_os = "android"))]
compile_error!("Using borrowed handles on Android requires the `std` feature to be enabled.");
use core::fmt;
use core::hash::{Hash, Hasher};
use core::marker::PhantomData;
use crate::{HasRawDisplayHandle, HasRawWindowHandle, RawDisplayHandle, RawWindowHandle};
/// Keeps track of whether the application is currently active.
///
/// On certain platforms (e.g. Android), it is possible for the application to enter a "suspended"
/// state. While in this state, all previously valid window handles become invalid. Therefore, in
/// order for window handles to be valid, the application must be active.
///
/// On platforms where the graphical user interface is always active, this type is a ZST and all
/// of its methods are noops. On Android, this type acts as a reference counter that keeps track
/// of all currently active window handles. Before the application enters the suspended state, it
/// blocks until all of the currently active window handles are dropped.
///
/// ## Explanation
///
/// On Android, there is an [Activity]-global [`ANativeWindow`] object that is used for drawing. This
/// handle is used [within the `RawWindowHandle` type] for Android NDK, since it is necessary for GFX
/// APIs to draw to the screen.
///
/// However, the [`ANativeWindow`] type can be arbitrarily invalidated by the underlying Android runtime.
/// The reasoning for this is complicated, but this idea is exposed to native code through the
/// [`onNativeWindowCreated`] and [`onNativeWindowDestroyed`] callbacks. To save you a click, the
/// conditions associated with these callbacks are:
///
/// - [`onNativeWindowCreated`] provides a valid [`ANativeWindow`] pointer that can be used for drawing.
/// - [`onNativeWindowDestroyed`] indicates that the previous [`ANativeWindow`] pointer is no longer
/// valid. The documentation clarifies that, *once the function returns*, the [`ANativeWindow`] pointer
/// can no longer be used for drawing without resulting in undefined behavior.
///
/// In [`winit`], these are exposed via the [`Resumed`] and [`Suspended`] events, respectively. Therefore,
/// between the last [`Suspended`] event and the next [`Resumed`] event, it is undefined behavior to use
/// the raw window handle. This condition makes it tricky to define an API that safely wraps the raw
/// window handles, since an existing window handle can be made invalid at any time.
///
/// The Android docs specifies that the [`ANativeWindow`] pointer is still valid while the application
/// is still in the [`onNativeWindowDestroyed`] block, and suggests that synchronization needs to take
/// place to ensure that the pointer has been invalidated before the function returns. `Active` aims
/// to be the solution to this problem. It keeps track of all currently active window handles, and
/// blocks until all of them are dropped before allowing the application to enter the suspended state.
///
/// [Activity]: https://developer.android.com/reference/android/app/Activity
/// [`ANativeWindow`]: https://developer.android.com/ndk/reference/group/a-native-window
/// [within the `RawWindowHandle` type]: struct.AndroidNdkWindowHandle.html#structfield.a_native_window
/// [`onNativeWindowCreated`]: https://developer.android.com/ndk/reference/struct/a-native-activity-callbacks#onnativewindowcreated
/// [`onNativeWindowDestroyed`]: https://developer.android.com/ndk/reference/struct/a-native-activity-callbacks#onnativewindowdestroyed
/// [`Resumed`]: https://docs.rs/winit/latest/winit/event/enum.Event.html#variant.Resumed
/// [`Suspended`]: https://docs.rs/winit/latest/winit/event/enum.Event.html#variant.Suspended
/// [`sdl2`]: https://crates.io/crates/sdl2
/// [`RawWindowHandle`]: https://docs.rs/raw-window-handle/latest/raw_window_handle/enum.RawWindowHandle.html
/// [`HasRawWindowHandle`]: https://docs.rs/raw-window-handle/latest/raw_window_handle/trait.HasRawWindowHandle.html
/// [`winit`]: https://crates.io/crates/winit
pub struct Active(imp::Active);
impl fmt::Debug for Active {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("Active { .. }")
}
}
/// Represents a live window handle.
///
/// This is carried around by the [`Active`] type, and is used to ensure that the application doesn't
/// enter the suspended state while there are still live window handles. See documentation on the
/// [`Active`] type for more information.
///
/// On non-Android platforms, this is a ZST. On Android, this is a reference counted handle that
/// keeps the application active while it is alive.
#[derive(Clone)]
pub struct ActiveHandle<'a>(imp::ActiveHandle<'a>);
impl<'a> fmt::Debug for ActiveHandle<'a> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("ActiveHandle { .. }")
}
}
impl Active {
/// Create a new `Active` tracker.
///
/// Only one of these should exist per display connection.
///
/// # Example
///
/// ```
/// use raw_window_handle::Active;
/// let active = Active::new();
/// ```
pub const fn new() -> Self {
Self(imp::Active::new())
}
/// Get a live window handle.
///
/// This function returns an active handle if the application is active, and `None` otherwise.
///
/// # Example
///
/// ```
/// use raw_window_handle::Active;
///
/// // Set the application to be active.
/// let active = Active::new();
/// unsafe { active.set_active() };
///
/// // Get a live window handle.
/// let handle = active.handle();
///
/// // Drop it and set the application to be inactive.
/// drop(handle);
/// active.set_inactive();
/// ```
pub fn handle(&self) -> Option<ActiveHandle<'_>> {
self.0.handle().map(ActiveHandle)
}
/// Set the application to be inactive.
///
/// This function may block until there are no more active handles.
///
/// # Example
///
/// ```
/// use raw_window_handle::Active;
///
/// // Set the application to be active.
/// let active = Active::new();
/// unsafe { active.set_active() };
///
/// // Set the application to be inactive.
/// active.set_inactive();
/// ```
pub fn set_inactive(&self) {
self.0.set_inactive()
}
/// Set the application to be active.
///
/// # Safety
///
/// The application must actually be active. Setting to active when the application is not active
/// will result in undefined behavior.
///
/// # Example
///
/// ```
/// use raw_window_handle::Active;
///
/// // Set the application to be active.
/// let active = Active::new();
/// unsafe { active.set_active() };
///
/// // Set the application to be inactive.
/// active.set_inactive();
/// ```
pub unsafe fn set_active(&self) {
self.0.set_active()
}
}
impl ActiveHandle<'_> {
/// Create a new freestanding active handle.
///
/// This function acts as an "escape hatch" to allow the user to create a live window handle
/// without having to go through the [`Active`] type. This is useful if the user *knows* that the
/// application is active, and wants to create a live window handle without having to go through
/// the [`Active`] type.
///
/// # Safety
///
/// The application must actually be active.
///
/// # Example
///
/// ```
/// use raw_window_handle::ActiveHandle;
///
/// // Create a freestanding active handle.
/// // SAFETY: The application must actually be active.
/// let handle = unsafe { ActiveHandle::new_unchecked() };
/// ```
pub unsafe fn new_unchecked() -> Self {
Self(imp::ActiveHandle::new_unchecked())
}
}
/// 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 already implement [`HasRawDisplayHandle`]. 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.
///
/// # Safety
///
/// The safety requirements of [`HasRawDisplayHandle`] apply here as well. To reiterate, the
/// [`DisplayHandle`] must contain a valid window handle for its lifetime.
///
/// It is not possible to invalidate a [`DisplayHandle`] on any platform without additional unsafe code.
///
/// 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.
///
/// [`HasRawDisplayHandle`]: crate::HasRawDisplayHandle
/// [`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<DisplayHandle<'_>, HandleError>;
}
impl<H: HasDisplayHandle + ?Sized> HasDisplayHandle for &H {
fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError> {
(**self).display_handle()
}
}
#[cfg(feature = "alloc")]
impl<H: HasDisplayHandle + ?Sized> HasDisplayHandle for alloc::boxed::Box<H> {
fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError> {
(**self).display_handle()
}
}
#[cfg(feature = "alloc")]
impl<H: HasDisplayHandle + ?Sized> HasDisplayHandle for alloc::rc::Rc<H> {
fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError> {
(**self).display_handle()
}
}
#[cfg(feature = "alloc")]
impl<H: HasDisplayHandle + ?Sized> HasDisplayHandle for alloc::sync::Arc<H> {
fn display_handle(&self) -> Result<DisplayHandle<'_>, 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.
///
/// Get the underlying raw display handle with the [`HasRawDisplayHandle`] trait.
#[repr(transparent)]
#[derive(PartialEq, Eq, Hash)]
pub struct DisplayHandle<'a> {
raw: RawDisplayHandle,
_marker: PhantomData<&'a *const ()>,
}
impl fmt::Debug for DisplayHandle<'_> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_tuple("DisplayHandle").field(&self.raw).finish()
}
}
impl<'a> Clone for DisplayHandle<'a> {
fn clone(&self) -> Self {
Self {
raw: self.raw,
_marker: PhantomData,
}
}
}
impl<'a> DisplayHandle<'a> {
/// Create a `DisplayHandle` from a [`RawDisplayHandle`].
///
/// # Safety
///
/// The `RawDisplayHandle` must be valid for the lifetime.
pub unsafe fn borrow_raw(raw: RawDisplayHandle) -> Self {
Self {
raw,
_marker: PhantomData,
}
}
}
unsafe impl HasRawDisplayHandle for DisplayHandle<'_> {
fn raw_display_handle(&self) -> RawDisplayHandle {
self.raw
}
}
impl<'a> HasDisplayHandle for DisplayHandle<'a> {
fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError> {
Ok(self.clone())
}
}
/// 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 already implement [`HasRawWindowHandle`]. First,
/// it should be made sure that the display type contains a unique [`Active`] ref-counted handle.
/// To create a [`WindowHandle`], the [`Active`] should be used to create an [`ActiveHandle`] that is
/// then used to create a [`WindowHandle`]. Finally, the raw window handle should be retrieved from
/// the type and used to create a [`WindowHandle`].
///
/// 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.
///
/// # Safety
///
/// All pointers within the resulting [`WindowHandle`] must be valid and not dangling for the lifetime of
/// the handle.
///
/// 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.
///
/// In addition, the window handle must not be invalidated for the duration of the [`ActiveHandle`] token.
///
/// Note that these requirements are not enforced on `HasWindowHandle`, rather, they are enforced on the
/// constructors of [`WindowHandle`]. This is because the `HasWindowHandle` 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 HasWindowHandle {
/// Get a handle to the window.
fn window_handle(&self) -> Result<WindowHandle<'_>, HandleError>;
}
impl<H: HasWindowHandle + ?Sized> HasWindowHandle for &H {
fn window_handle(&self) -> Result<WindowHandle<'_>, HandleError> {
(**self).window_handle()
}
}
#[cfg(feature = "alloc")]
impl<H: HasWindowHandle + ?Sized> HasWindowHandle for alloc::boxed::Box<H> {
fn window_handle(&self) -> Result<WindowHandle<'_>, HandleError> {
(**self).window_handle()
}
}
#[cfg(feature = "alloc")]
impl<H: HasWindowHandle + ?Sized> HasWindowHandle for alloc::rc::Rc<H> {
fn window_handle(&self) -> Result<WindowHandle<'_>, HandleError> {
(**self).window_handle()
}
}
#[cfg(feature = "alloc")]
impl<H: HasWindowHandle + ?Sized> HasWindowHandle for alloc::sync::Arc<H> {
fn window_handle(&self) -> Result<WindowHandle<'_>, 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. Get the underlying raw window handle with the
/// [`HasRawWindowHandle`] trait.
#[derive(Clone)]
pub struct WindowHandle<'a> {
raw: RawWindowHandle,
_active: ActiveHandle<'a>,
_marker: PhantomData<&'a *const ()>,
}
impl fmt::Debug for WindowHandle<'_> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_tuple("WindowHandle").field(&self.raw).finish()
}
}
impl PartialEq for WindowHandle<'_> {
fn eq(&self, other: &Self) -> bool {
self.raw == other.raw
}
}
impl Eq for WindowHandle<'_> {}
impl Hash for WindowHandle<'_> {
fn hash<H: Hasher>(&self, state: &mut H) {
self.raw.hash(state);
}
}
impl<'a> WindowHandle<'a> {
/// Borrow a `WindowHandle` from a [`RawWindowHandle`].
///
/// # Safety
///
/// The [`RawWindowHandle`] must be valid for the lifetime and the application must not be
/// suspended. The [`Active`] object that the [`ActiveHandle`] was created from must be
/// associated directly with the display that the window handle is associated with.
pub unsafe fn borrow_raw(raw: RawWindowHandle, active: ActiveHandle<'a>) -> Self {
Self {
raw,
_active: active,
_marker: PhantomData,
}
}
}
unsafe impl HasRawWindowHandle for WindowHandle<'_> {
fn raw_window_handle(&self) -> RawWindowHandle {
self.raw
}
}
impl HasWindowHandle for WindowHandle<'_> {
fn window_handle(&self) -> Result<Self, HandleError> {
Ok(self.clone())
}
}
/// The error type returned when a handle cannot be obtained.
#[derive(Debug)]
#[non_exhaustive]
pub enum HandleError {
/// The handle is not currently active.
///
/// See documentation on [`Active`] for more information.
Inactive,
}
impl fmt::Display for HandleError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Inactive => write!(f, "the handle is not currently active"),
}
}
}
#[cfg(feature = "std")]
impl std::error::Error for HandleError {}
/// ```compile_fail
/// use raw_window_handle::{Active, DisplayHandle, WindowHandle};
/// fn _assert<T: Send + Sync>() {}
/// _assert::<Active<'static>>();
/// _assert::<DisplayHandle<'static>>();
/// _assert::<WindowHandle<'static>>();
/// ```
fn _not_send_or_sync() {}
#[cfg(not(any(target_os = "android", raw_window_handle_force_refcount)))]
#[cfg_attr(docsrs, doc(cfg(not(target_os = "android"))))]
mod imp {
//! We don't need to refcount the handles, so we can just use no-ops.
use core::cell::UnsafeCell;
use core::marker::PhantomData;
pub(super) struct Active;
#[derive(Clone)]
pub(super) struct ActiveHandle<'a> {
_marker: PhantomData<&'a UnsafeCell<()>>,
}
impl Active {
pub(super) const fn new() -> Self {
Self
}
pub(super) fn handle(&self) -> Option<ActiveHandle<'_>> {
// SAFETY: The handle is always active.
Some(unsafe { ActiveHandle::new_unchecked() })
}
pub(super) unsafe fn set_active(&self) {}
pub(super) fn set_inactive(&self) {}
}
impl ActiveHandle<'_> {
pub(super) unsafe fn new_unchecked() -> Self {
Self {
_marker: PhantomData,
}
}
}
impl Drop for ActiveHandle<'_> {
fn drop(&mut self) {
// Done for consistency with the refcounted version.
}
}
impl super::ActiveHandle<'_> {
/// Create a new `ActiveHandle`.
///
/// This is safe because the handle is always active.
///
/// # Example
///
/// ```
/// use raw_window_handle::ActiveHandle;
/// let handle = ActiveHandle::new();
/// ```
#[allow(clippy::new_without_default)]
pub fn new() -> Self {
// SAFETY: The handle is always active.
unsafe { super::ActiveHandle::new_unchecked() }
}
}
}
#[cfg(any(target_os = "android", raw_window_handle_force_refcount))]
#[cfg_attr(docsrs, doc(cfg(any(target_os = "android"))))]
mod imp {
//! We need to refcount the handles, so we use an `RwLock` to do so.
use std::sync::{RwLock, RwLockReadGuard};
pub(super) struct Active {
active: RwLock<bool>,
}
pub(super) struct ActiveHandle<'a> {
inner: Option<Inner<'a>>,
}
struct Inner<'a> {
_read_guard: RwLockReadGuard<'a, bool>,
active: &'a Active,
}
impl Clone for ActiveHandle<'_> {
fn clone(&self) -> Self {
Self {
inner: self.inner.as_ref().map(|inner| Inner {
_read_guard: inner.active.active.read().unwrap(),
active: inner.active,
}),
}
}
}
impl Active {
pub(super) const fn new() -> Self {
Self {
active: RwLock::new(false),
}
}
pub(super) fn handle(&self) -> Option<ActiveHandle<'_>> {
let active = self.active.read().ok()?;
if !*active {
return None;
}
Some(ActiveHandle {
inner: Some(Inner {
_read_guard: active,
active: self,
}),
})
}
pub(super) unsafe fn set_active(&self) {
*self.active.write().unwrap() = true;
}
pub(super) fn set_inactive(&self) {
*self.active.write().unwrap() = false;
}
}
impl ActiveHandle<'_> {
pub(super) unsafe fn new_unchecked() -> Self {
Self { inner: None }
}
}
}