gpu-handle-types 0.2.0

# gpu-handle-types

Typed, owned native GPU resource handles, cross-API sync points and video
pixel formats: the shared vocabulary for passing GPU resources between
libraries, such as a decoder handing frames to a renderer, a renderer handing
textures to an encoder, or one graphics API importing another's memory.

This crate doesn't create, import or convert resources itself. It defines the
values that cross those boundaries, and gives them ownership and lifetime
rules that can't be broken by accident.

## What's in it

| Area | Types |
|---|---|
| Resource handles | `GpuResource`, a sum type over one validated newtype per native handle: Vulkan images, buffers and opaque fds / Win32 handles; D3D11 textures, D3D12 resources, NT handles and KMT tokens; Metal textures and buffers, `IOSurface`, CoreVideo frames; OpenGL textures and buffers; CUDA pointers, buffers and surfaces; OpenCL memory; DMA-BUF and VA-API surfaces; `AHardwareBuffer`, MediaCodec / `AImage` frames; `wgpu` textures; WebGPU / WebGL / WebCodecs handles; CPU byte and plane buffers |
| Host-provided contexts | `GpuContext` (an existing Vulkan / D3D11 / D3D12 / Metal / OpenGL / CUDA / OpenCL / wgpu context to work inside), `ExternalQueue`, and borrowed device and queue handles such as `CudaContext` and `MtlCommandBufferRef` |
| Synchronisation | `SyncPoint`: Vulkan timeline semaphores, D3D12 fences, D3D11 keyed mutexes, CUDA / OpenCL events, Metal shared events, GL semaphores and fence syncs, wgpu submissions. Blocking, timeout-bounded and `async` waits through `SyncWaiter` |
| Pixel formats | `PixelFormat` (NV12, P010, 4:2:2 / 4:4:4 biplanar and planar YUV, packed RGB(A), RAW-sensor and scalar formats) with plane layouts, bit depths, MSB-alignment, alpha semantics and stable shader ordinals |
| Infrastructure | `BackendKind`, `DeviceId`, `Error` / `ErrorKind`, memory-budget accounting (`MemoryBudget` with soft and hard caps, pressure callbacks and evictable pools), the background `WaiterThread` for fences that can't be polled, and process-wide wgpu device-creation and error-scope locks |

Colour, HDR and frame metadata come from the
[`video-types`](https://crates.io/crates/video-types) crate, which this crate
builds on.

## Ownership model

Each handle newtype checks its invariants once, in an `unsafe` `try_from_raw`
constructor, and every use after that is safe code:

- **OS handles** (fds, NT handles) and **refcounted foreign objects**
  (`IOSurface`, `CVPixelBuffer`, `AHardwareBuffer`) sit behind an `Arc`.
  Cloning one costs a single atomic increment, and the last drop runs the
  platform release call.
- **Borrowed API handles**, such as a `VkImage` or an `ID3D12Resource`
  pointer, can carry a keep-alive `Arc` from the producer that owns them, so
  the resource can't be freed while a consumer still holds the handle.

Handles that exist only on one platform are `cfg`-gated to it. Every
platform's handles appear on [docs.rs](https://docs.rs/gpu-handle-types).

## Example

```rust
use gpu_handle_types::{PixelFormat, SyncPoint};

// NV12 at an odd size: the chroma plane keeps its half-covered row and
// column, exactly as FFmpeg allocates it.
assert!(PixelFormat::NV12.is_biplanar());
assert_eq!(PixelFormat::NV12.plane_size(321, 241, 0), (321, 241));
assert_eq!(PixelFormat::NV12.plane_size(321, 241, 1), (161, 121));

// A sync point for CPU-only work is already signalled.
SyncPoint::Cpu.wait_blocking().expect("nothing to wait for");
```

## Feature flags

| Feature | Default | Enables |
|---|---|---|
| `wgpu` | on | `wgpu`-backed variants (`GpuResource::WgpuTexture`, `GpuContext::Wgpu`, `SyncPoint::Wgpu`), texture byte estimates, and the device-creation / error-scope locks |
| `serde` | off | `Serialize` / `Deserialize` on `PixelFormat`, `PlaneFormat` and `AlphaChannel`, and forwards `video-types/serde` |
| `cuda` | off | The CUDA compute backend: `BackendKind::Cuda`, CUDA stream queues and CUDA budget caps. Vocabulary only; no CUDA library is linked |
| `opencl` | off | The same for OpenCL |
| `web` | off | Browser handles on `wasm32`: WebGPU devices and textures, `<video>`, `<canvas>`, `ImageBitmap` and other image sources, WebGL textures |
| `webgl` | off | `GpuContext::WebGl` (implies `web`) |
| `web-codecs` | off | WebCodecs `VideoFrame` handles (implies `web`) |
| `ash` | off | `VkImage::as_ash_image` / `VkBufferHandle::as_ash_buffer` |

## Minimum supported Rust version

1.88 (edition 2024).

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.