gpu-handle-types 0.1.0

Typed, owned native GPU resource handles (Vulkan, D3D11/12, Metal, OpenGL, CUDA, OpenCL, DMA-BUF, IOSurface, AHardwareBuffer, WebGPU, ...), cross-API sync points and video pixel formats, for passing GPU resources between libraries.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

// SPDX-License-Identifier: MIT OR Apache-2.0

//! Typed, owned native GPU resource handles, cross-API sync points and video
//! pixel formats — the vocabulary for passing GPU resources between
//! libraries: a decoder handing frames to a renderer, a renderer handing
//! textures to an encoder, one graphics API importing another's memory.
//!
//! - [`GpuResource`] — one validated newtype per native handle kind (Vulkan,
//!   D3D11 / D3D12, Metal / IOSurface / CoreVideo, OpenGL, CUDA, OpenCL,
//!   DMA-BUF / VA-API, `AHardwareBuffer` / MediaCodec, `wgpu`, the browser,
//!   CPU memory). OS handles and refcounted foreign objects are owned behind
//!   an `Arc`; borrowed API handles can carry a [`ResourceKeepAlive`] from
//!   their producer.
//! - [`GpuContext`] / [`ExternalQueue`] — an existing context or queue a
//!   host asks a library to work inside.
//! - [`SyncPoint`] / [`SyncWaiter`] — "this work is done" across APIs, with
//!   blocking, timeout-bounded and `async` waits.
//! - [`PixelFormat`] — video and image pixel formats with their plane
//!   layouts, bit depths, alpha semantics and stable shader ordinals.
//! - [`MemoryBudget`], [`BackendKind`], [`DeviceId`], [`Error`] — the
//!   accounting and identity types around them.
//!
//! What the pixels *mean* — colour, frame metadata, geometry — lives one
//! crate down, in `video-types`, whose types this crate's API uses directly.
//!
//! No `dyn` dispatch on the per-frame hot path. One background thread, owned
//! and documented: the [`WaiterThread`] that parks on fences a caller cannot
//! poll. Async waits are offered beside the blocking ones, never instead of
//! them. No backend-library knowledge: nothing here links FFmpeg, CUDA or
//! OpenCL, and `wgpu` only behind the `wgpu` feature.
//!
//! # Features
//!
//! | Feature | Default | Enables |
//! |---|---|---|
//! | `wgpu` | on | `wgpu`-backed resource / context / sync variants, texture byte estimates, the device-creation and error-scope locks |
//! | `serde` | off | `Serialize` / `Deserialize` on [`PixelFormat`], [`PlaneFormat`], [`AlphaChannel`]; forwards `video-types/serde` |
//! | `cuda`, `opencl` | off | The CUDA / OpenCL compute backends' [`BackendKind`] variants, queue variants and budget caps (no library is linked) |
//! | `web`, `webgl`, `web-codecs` | off | Browser handles on `wasm32` (WebGPU, WebGL, DOM image sources, WebCodecs `VideoFrame`) |
//! | `ash` | off | `VkImage::as_ash_image` / `VkBufferHandle::as_ash_buffer` |

#![cfg_attr(docsrs, feature(doc_cfg))]

mod backend;
mod budget;
mod device;
#[cfg(feature = "wgpu")]
mod device_create_lock;
mod device_handles;
mod error;
#[cfg(feature = "wgpu")]
mod error_scope;
mod exec_path;
mod external_queue;
mod gpu_context;
mod gpu_resource;
mod pixel_format;
#[cfg(test)]
mod pixel_format_tests;
mod sync;
#[cfg(feature = "wgpu")]
mod texture_bytes;
mod thread_marker;
mod wait_thread;
// Browser-platform resource handles. wasm-only + gated on the `web`
// Cargo feature (which pulls in `web-sys` / `wasm-bindgen`); native
// builds do not resolve those crates.
#[cfg(all(target_family = "wasm", feature = "web"))]
mod web;

pub use backend::*;
pub use budget::*;
pub use device::*;
#[cfg(feature = "wgpu")]
pub use device_create_lock::*;
pub use device_handles::*;
pub use error::*;
#[cfg(feature = "wgpu")]
pub use error_scope::*;
pub use exec_path::*;
pub use external_queue::*;
pub use gpu_context::*;
pub use gpu_resource::*;
pub use pixel_format::*;
pub use sync::*;
#[cfg(feature = "wgpu")]
pub use texture_bytes::*;
pub use thread_marker::*;
pub use wait_thread::*;
#[cfg(all(target_family = "wasm", feature = "web"))]
pub use web::*;

// Compiles and runs the README's examples as doctests, so the page crates.io
// shows cannot drift from the API.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct ReadmeDoctests;