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

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 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.

Example

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

at your option.