Crate gpu_handle_types

Expand description

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`

Structs§

BackendWaitFuture: Future returned by WaiterThread::enqueue. Resolves when the waiter thread reports Signaled / Failed / Err(Timeout) on the deadline.
BudgetCaps: Per-backend budget caps. None disables that side (e.g. soft_cap only, hard_cap only, or unbounded).
BudgetCapsSet: Named-field set of per-backend caps. Deliberately a struct with cfg-gated fields rather than a [BudgetCaps; N] — no BackendKind::COUNT to mislead under --no-default-features, and partial configs compose via ..Default::default().
BudgetPressureEvent
BudgetReservation: RAII token. Dropping the token releases the reservation back to the pool.
ClContext: OpenCL cl_context borrowed for an OpenCL sync-target dispatch. The platform/device parentage is rederived inside the bridge via clGetContextInfo.
ClQueueRef: OpenCL cl_command_queue borrowed by ExternalQueue::OpenClQueue.
CpuBytes: Flat CPU byte buffer. The raw ptr is non-owning; keep_alive pins whatever owns the backing allocation (an SDK decoder’s frame anchor, an aligned-buffer pool slot, a boxed expand buffer, …) so the bytes outlive every clone the caller hands off. Pass None only when the caller guarantees the allocation’s lifetime by other means (e.g. a test stack buffer that outlives the handle).
CpuPlane
CpuPlaneSet: Up-to-four-plane CPU buffer set. count ∈ 1..=4; unused slots are None. Zero heap allocation — the [Option<CpuPlane>; 4] is inline.
CpuSharedSlot: Producer-allocated CPU staging slot. Caller cannot dereference; reads land via the producer’s readback API.
CudaBufferHandle: 1D (flat) CUDA device pointer with byte size.
CudaContext: CUDA CUcontext borrowed for the duration of a CUDA sync-target dispatch.
CudaPtr2D: 2D (pitched) CUDA device pointer (CUdeviceptr aliased as u64).
CudaStreamRef: CUDA CUstream borrowed by ExternalQueue::CudaStream. The stream’s lifetime is anchored by the caller’s CUDA context.
CudaSurfacewgpu: Opaque CUDA CUsurfObject bound to a CUarray, used as a surf2Dwrite kernel write target.
D3D11Device: ID3D11Device* borrowed for a D3D11 sync-target dispatch. Caller has set D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX or the multithread-protect flag — that’s the cross-thread contract.
D3D11Texture: ID3D11Texture2D* keyed-mutex / shared-handle resource.
D3D12BufferHandle: Buffer-dimension ID3D12Resource* (committed with Dimension = D3D12_RESOURCE_DIMENSION_BUFFER).
D3D12Device: ID3D12Device* borrowed for a D3D12 sync-target dispatch. LUID-matched against the source VkDevice / Vulkan instance by the bridge dispatcher.
D3D12Resource: ID3D12Resource* keyed-mutex / shared-handle resource (Texture2D dimension).
DeferredWgpuSlotwgpu: Shared, mutate-once slot the producer fills in after the caller submits the encoded work. Used by SyncPoint::DeferredWgpu.
DeviceInfo
DmaBufHandleAndroid or Linux: Linux / Android DMA-BUF descriptor — the direct analogue of libva’s VADRMPRIMESurfaceDescriptor (va_drmcommon.h).
DmaBufImportDescAndroid or Linux: Everything about a DMA-BUF surface except the object fds themselves — the layout half of DmaBufHandle.
GlBufferHandle: GL buffer object (GLuint) + binding metadata.
GlContextRef: Platform-native OpenGL context handle (EGLContext / HGLRC / CGLContextObj). The GlBackend flavour travels alongside it in an OpenGL sync target so the bridge dispatcher resolves the matching proc-address loader without re-probing.
GlTextureHandle: GL texture name (GLuint) + binding metadata.
MemoryBudget
MetalBufferHandle: MTLBuffer*.
MetalTextureHandle: MTLTexture* (Objective-C-bridged Metal texture).
MtlCommandBufferRef: id<MTLCommandBuffer> borrowed by ExternalQueue::MetalCommandBuffer. Recording into the same command buffer from multiple threads is undefined, and nothing here prevents it — the borrow is shared and the newtype is Copy, so confining recording to one thread is the caller’s obligation.
MtlDevice: id<MTLDevice> borrowed for a Metal sync-target dispatch.
OpenClGlSharing: Caller-asserted GL-sharing handles for an OpenCl context.
OpenClMem: cl_mem handle paired with its producing cl_command_queue.
PlaneInfo: Storage description of a single plane in a PlaneLayout.
PlaneLayout: How a pixel format lays out its planes in memory.
PoolHandle
PressureCallbackHandle
RawFenceCarrierWaiter: A SyncWaiter for a SyncPoint reconstructed from a raw foreign fence handle that has not yet been imported onto a waiting device.
VaapiSurfaceLinux: VAAPI surface (VASurfaceID + VADisplay), as a newtype so the GpuResource enum carries it uniformly with the rest.
VkAcquireBinaryHermit or Unix or WASI or Windows: Per-frame fresh BINARY semaphore carrier — the NVIDIA-Windows fallback path when VkAcquireTimeline cannot be GPU-waited by the consumer (no exportable D3D12_FENCE timeline flavour AND no GL_NV_timeline_semaphore + OPAQUE_WIN32 import support).
VkAcquireTimelineHermit or Unix or WASI or Windows: Optional GPU-side acquire-sync attached to a VkOpaqueFd / VkOpaqueWin32 carrier.
VkBufferHandle: Vulkan VkBuffer on a specific VkDevice.
VkDevice: VkDevice borrowed for a Vulkan sync-target dispatch.
VkImage: Vulkan VkImage on a specific VkDevice, with optional cross-vendor identity (deviceUUID).
VkInstance: VkInstance borrowed for a Vulkan sync-target dispatch. Required even for device-level work because ash resolves device fn pointers through vkGetDeviceProcAddr, which is itself an instance-level command (vkGetInstanceProcAddr(NULL, ...) returns NULL).
VkOpaqueExportDescHermit or Unix or WASI or Windows: The producer-side export descriptor both native opaque-handle carriers carry — VkOpaqueFd on POSIX, VkOpaqueWin32 on Windows. (Those two are mutually-exclusive #[cfg]s, so they are named as plain code spans here rather than intra-doc links: no single rustdoc target can resolve both.)
VkOpaqueFdHermit or Unix or WASI: Vulkan opaque-fd export via VK_KHR_external_memory_fd.
VkSlotRelease: Consumer→producer slot-release back-pressure carrier.
WaiterThread: Permanently-attached waiter thread + request channel.
WgpuTexturewgpu: A native wgpu::Texture that already lives on the consumer’s own wgpu device — the zero-interop passthrough.

Enums§

AlphaChannel: What a PixelFormat’s fourth component means — the contract a consumer must honour before it reads lane 3 of a packed layout (or the fourth plane of a planar one).
AngleBackend: Underlying implementation of an ANGLE “GL” context. Probed via glGetString(GL_RENDERER) + the matching EGL_ANGLE_* extension when GlBackend::Angle(_) is selected.
BackendKind: Identity of a compute backend. Used as a discriminant on error variants, budget accounting, GpuContext, SyncPoint, etc.
BudgetPressure
DeviceId: Stable identity of a physical GPU / CPU / accelerator. Used as cache key in multi-GPU setups and as an equality test for Error::DeviceMismatch.
Error: Domain error for every leaf operation in gpu-handle-types.
ErrorKind: Classification of an Error. Callers branch on .kind() for retry / abort / reconfigure decisions without pattern-matching every variant.
ExecutionPath: Which path a frame went down. Carried on per-call result types (an interop layer’s import / export results) rather than process-global cells.
ExternalQueue: Borrowed handle into an external command queue. The 'a lifetime ties the queue to the caller’s scope so the borrow-checker prevents reentrant use across the call it is lent to.
GlBackend: Which GL context flavour GpuContext::OpenGL::context points at.
GlBufferTarget: GL buffer bind target. Non-exhaustive — covers the targets a video / VFX caller realistically allocates exportable buffers under.
GlInternalFormat: GL sized internal-format enum the texture was created with — only the subset that a video pipeline ever surfaces.
GlTextureTarget: GL bind target the texture was allocated with. Maps 1:1 onto the matching GL_TEXTURE_* enum value.
GpuContext
GpuContextError: Failure modes for the typed GpuContext unpackers above.
GpuResource: Zero-copy GPU resource handle.
InvalidHandleError: Returned from try_from_raw constructors when the caller-supplied payload violates an invariant the newtype enforces (e.g. a null VkImage, a zero-sized D3D12 buffer).
PixelFormat: Every pixel layout this crate understands.
PlaneFormat: Per-plane storage primitive. A plane’s PlaneFormat names the smallest texture format a GPU upload would use for it; the shader reinterprets the channels when needed (e.g. AYUV64LE uses RGBA16 storage with AYUV channel semantics).
SliceOutcome: Result of one slice-bounded native wait. Returned by the SliceFn closure each per-backend wait_async override supplies.
SyncPoint: GPU sync primitive. Produced by every submit-side path; consumed by anything that needs to serialise on a prior GPU submission.
VulkanSemaphoreKind: Discriminator for SyncPoint::Vulkan’s VkSemaphore flavour.

Constants§

DEFAULT_WAIT_TIMEOUT: Default wait budget for SyncPoint::wait() and SyncPoint::wait_blocking() — 10 seconds.
WAITER_SLICE: Per-slice native blocking-with-timeout budget. Sized to:

Traits§

CudaEventWaiter: CUDA-event-specific extension trait for the SyncPoint::CudaEvent variant. Supertrait of SyncWaiter so a CudaEventWaiter always satisfies the generic SyncPoint::wait dispatch path; adds the CUDA-only wait_on_foreign_stream extension method that cross-API bridges downcast to via SyncWaiter::as_any.
EvictablePool: Pool trait — drop unused resources on request. This is the single dyn exception in this crate; see the module doc-comment. The MaybeSendSync supertrait is Send + Sync off wasm and empty on wasm.
GlContextExecutor: Host-supplied scheduler that posts a closure onto the thread that owns a particular OpenGL context.
MaybeSendNon-target_family=wasm: Send off wasm; empty on wasm.
MaybeSendSyncNon-target_family=wasm: Send + Sync off wasm; empty on wasm. See module docs.
ResourceKeepAlive: Marker trait for per-variant lifetime anchors carried on GpuResource newtypes.
SyncWaiter: Backend-specific wait dispatch + lifetime anchor for a SyncPoint.

Functions§

duration_to_ms_u32: Helper: convert a Duration to milliseconds, saturating at u32::MAX for the Win32 INFINITE sentinel (WaitForSingleObject, WaitForMultipleObjects).
duration_to_ns: Helper: convert a Duration to nanoseconds, saturating at u64::MAX for “wait forever”. Matches vkWaitSemaphores’ UINT64_MAX infinite-wait sentinel.
estimate_descriptor_byteswgpu: Convenience wrapper around estimate_texture_bytes for callers that already hold a wgpu::TextureDescriptor.
estimate_texture_byteswgpu: Estimate the on-device byte footprint of a 2D / 3D texture.
lock_device_creationwgpu: Acquire the process-global wgpu device-creation lock. Hold the returned guard across the whole Instance::new → request_adapter → request_device sequence (and drop it once the device exists). Reentrant on the holding thread, so a library call made inside the sequence that takes the lock itself proceeds instead of deadlocking.
make_deferred_wgpu_sync_pointwgpu: Construct a SyncPoint::DeferredWgpu complete with its waiter.
run_hybrid_wait: Compose the fast-path yield-spin (bounded) + the waiter-thread fallback (thread handoff) into the canonical hybrid wait_async body.
wait_deadline: The absolute deadline a wait(timeout) poll loop should honour, or None for the SyncWaiter::wait contract’s Duration::MAX “wait forever” sentinel.
with_device_creation_lockwgpu: Run f (a wgpu device-creation sequence) under the process-global device-creation lock. See the module docs for why this exists.
with_error_scopewgpu: Run f (an allocation already bracketed by push_error_scope / pop_error_scope on device) while holding device’s process-global error-scope lock, so the push/pop triple cannot interleave with a concurrent triple on the same device.
yield_once: Runtime-agnostic single-yield future. Returns Pending once then resolves to Ready(()) on the next poll, with wake_by_ref driving the re-poll. Works under any executor (pollster, tokio, smol, futures::executor).

Type Aliases§

BoxFutureNon-target_family=wasm: Boxed dyn-future return shape used by SyncWaiter::wait_async so the trait stays object-safe through Arc<dyn SyncWaiter>. Native async fn on the trait would be RPITIT and dyn-incompatible by default; callers dispatch through Arc<dyn SyncWaiter>, so boxing the future is mandatory.
KeepAlive: Convenience alias for the boxed-trait-object form most call sites use.
PressureCallbackNon-target_family=wasm
SliceFnNon-target_family=wasm: Boxed closure each per-backend wait_async override builds at handoff time. The waiter thread calls it on its own thread with the current slice budget; the closure must: