gpu_handle_types/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Typed, owned native GPU resource handles, cross-API sync points and video
4//! pixel formats — the vocabulary for passing GPU resources between
5//! libraries: a decoder handing frames to a renderer, a renderer handing
6//! textures to an encoder, one graphics API importing another's memory.
7//!
8//! - [`GpuResource`] — one validated newtype per native handle kind (Vulkan,
9//!   D3D11 / D3D12, Metal / IOSurface / CoreVideo, OpenGL, CUDA, OpenCL,
10//!   DMA-BUF / VA-API, `AHardwareBuffer` / MediaCodec, `wgpu`, the browser,
11//!   CPU memory). OS handles and refcounted foreign objects are owned behind
12//!   an `Arc`; borrowed API handles can carry a [`ResourceKeepAlive`] from
13//!   their producer.
14//! - [`GpuContext`] / [`ExternalQueue`] — an existing context or queue a
15//!   host asks a library to work inside.
16//! - [`SyncPoint`] / [`SyncWaiter`] — "this work is done" across APIs, with
17//!   blocking, timeout-bounded and `async` waits.
18//! - [`PixelFormat`] — video and image pixel formats with their plane
19//!   layouts, bit depths, alpha semantics and stable shader ordinals.
20//! - [`MemoryBudget`], [`BackendKind`], [`DeviceId`], [`Error`] — the
21//!   accounting and identity types around them.
22//!
23//! What the pixels *mean* — colour, frame metadata, geometry — lives one
24//! crate down, in `video-types`, whose types this crate's API uses directly.
25//!
26//! No `dyn` dispatch on the per-frame hot path. One background thread, owned
27//! and documented: the [`WaiterThread`] that parks on fences a caller cannot
28//! poll. Async waits are offered beside the blocking ones, never instead of
29//! them. No backend-library knowledge: nothing here links FFmpeg, CUDA or
30//! OpenCL, and `wgpu` only behind the `wgpu` feature.
31//!
32//! # Features
33//!
34//! | Feature | Default | Enables |
35//! |---|---|---|
36//! | `wgpu` | on | `wgpu`-backed resource / context / sync variants, texture byte estimates, the device-creation and error-scope locks |
37//! | `serde` | off | `Serialize` / `Deserialize` on [`PixelFormat`], [`PlaneFormat`], [`AlphaChannel`]; forwards `video-types/serde` |
38//! | `cuda`, `opencl` | off | The CUDA / OpenCL compute backends' [`BackendKind`] variants, queue variants and budget caps (no library is linked) |
39//! | `web`, `webgl`, `web-codecs` | off | Browser handles on `wasm32` (WebGPU, WebGL, DOM image sources, WebCodecs `VideoFrame`) |
40//! | `ash` | off | `VkImage::as_ash_image` / `VkBufferHandle::as_ash_buffer` |
41
42#![cfg_attr(docsrs, feature(doc_cfg))]
43
44mod backend;
45mod budget;
46mod device;
47#[cfg(feature = "wgpu")]
48mod device_create_lock;
49mod device_handles;
50mod error;
51#[cfg(feature = "wgpu")]
52mod error_scope;
53mod exec_path;
54mod external_queue;
55mod gpu_context;
56mod gpu_resource;
57mod pixel_format;
58#[cfg(test)]
59mod pixel_format_tests;
60mod sync;
61#[cfg(feature = "wgpu")]
62mod texture_bytes;
63mod thread_marker;
64mod wait_thread;
65// Browser-platform resource handles. wasm-only + gated on the `web`
66// Cargo feature (which pulls in `web-sys` / `wasm-bindgen`); native
67// builds do not resolve those crates.
68#[cfg(all(target_family = "wasm", feature = "web"))]
69mod web;
70
71pub use backend::*;
72pub use budget::*;
73pub use device::*;
74#[cfg(feature = "wgpu")]
75pub use device_create_lock::*;
76pub use device_handles::*;
77pub use error::*;
78#[cfg(feature = "wgpu")]
79pub use error_scope::*;
80pub use exec_path::*;
81pub use external_queue::*;
82pub use gpu_context::*;
83pub use gpu_resource::*;
84pub use pixel_format::*;
85pub use sync::*;
86#[cfg(feature = "wgpu")]
87pub use texture_bytes::*;
88pub use thread_marker::*;
89pub use wait_thread::*;
90#[cfg(all(target_family = "wasm", feature = "web"))]
91pub use web::*;
92
93// Compiles and runs the README's examples as doctests, so the page crates.io
94// shows cannot drift from the API.
95#[cfg(doctest)]
96#[doc = include_str!("../README.md")]
97struct ReadmeDoctests;
gpu_handle_types/lib.rs

gpu_handle_types/
lib.rs
