wgpu_external_frame/lib.rs
1//! Zero-copy import of externally produced GPU frames into [`wgpu`] textures.
2//!
3//! Browser engines, media decoders, capture pipelines, and compositors all hand
4//! their output over as a platform handle to memory the GPU already holds:
5//! a DMA-BUF file descriptor on Linux, an `IOSurface` on Apple platforms, a
6//! shared `ID3D12Resource` handle on Windows. This crate turns each of those
7//! into a [`wgpu::Texture`] on a device the caller already owns, without ever
8//! routing a pixel through the CPU.
9//!
10//! Each platform gets its own module, because the handles genuinely have
11//! nothing in common: one is a file descriptor with a DRM format modifier and
12//! an explicit fence, one is a `CoreFoundation` object, one is a `Win32`
13//! `HANDLE`. There is no unifying trait, and inventing one would only hide the
14//! differences a caller has to know about anyway.
15//!
16//! - [`dma_buf`] — Linux DMA-BUF, imported through Vulkan external memory
17//! (`VK_EXT_external_memory_dma_buf`) or EGL
18//! (`EGL_LINUX_DMA_BUF_EXT` plus `glEGLImageTargetTexture2DOES`), whichever
19//! backend the `wgpu` device runs on.
20//! - [`io_surface`] — macOS `IOSurface`, imported through
21//! `MTLDevice::newTextureWithDescriptor:iosurface:plane:`.
22//! - [`shared_handle`] — Windows shared texture handles, imported through
23//! `ID3D12Device::OpenSharedHandle`.
24//!
25//! Every import reaches under `wgpu` to its `hal` layer, so the caller must
26//! run on the backend that platform's import requires; each entry point says
27//! which, and asserts it rather than guessing.
28
29#[cfg(target_os = "linux")]
30pub mod dma_buf;
31#[cfg(target_os = "macos")]
32pub mod io_surface;
33#[cfg(target_os = "windows")]
34pub mod shared_handle;