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 `AHardwareBuffer` on Android, an
6//! `IOSurface` on Apple platforms, a shared `ID3D12Resource` handle on
7//! Windows. This crate turns each of those into a [`wgpu::Texture`] on a
8//! device the caller already owns, without ever routing a pixel through the
9//! CPU.
10//!
11//! Each platform gets its own module, because the handles genuinely have
12//! nothing in common: one is a file descriptor with a DRM format modifier and
13//! an explicit fence, one is a reference-counted NDK object, one is a
14//! `CoreFoundation` object, one is a `Win32` `HANDLE`. There is no unifying
15//! trait, and inventing one would only hide the differences a caller has to
16//! know about anyway. A module exists only on its own platform, so these docs
17//! link the one built for the target they were generated for and name the
18//! others.
19//!
20// Each bullet's first line is written twice, linked under the module's own
21// `cfg` and plain otherwise: rustdoc cannot resolve a link to a module the
22// target compiles out, and the modules cannot be compiled elsewhere because
23// their dependencies are target-specific.
24#![cfg_attr(
25 target_os = "linux",
26 doc = "- [`dma_buf`] — Linux DMA-BUF, imported through Vulkan external memory"
27)]
28#![cfg_attr(
29 not(target_os = "linux"),
30 doc = "- `dma_buf` — Linux DMA-BUF, imported through Vulkan external memory"
31)]
32//! (`VK_EXT_external_memory_dma_buf`) or EGL
33//! (`EGL_LINUX_DMA_BUF_EXT` plus `glEGLImageTargetTexture2DOES`), whichever
34//! backend the `wgpu` device runs on.
35#![cfg_attr(
36 target_os = "android",
37 doc = "- [`ahardware_buffer`] — Android `AHardwareBuffer`, imported through Vulkan"
38)]
39#![cfg_attr(
40 not(target_os = "android"),
41 doc = "- `ahardware_buffer` — Android `AHardwareBuffer`, imported through Vulkan"
42)]
43//! (`VK_ANDROID_external_memory_android_hardware_buffer`) and adopted by
44//! `wgpu` without a copy, except for YCbCr buffers the driver describes only
45//! through an external format, which a GPU pass converts into planes `wgpu`
46//! owns.
47#![cfg_attr(
48 any(target_os = "macos", target_os = "ios"),
49 doc = "- [`io_surface`] — macOS and iOS `IOSurface`, packed RGBA/BGRA or"
50)]
51#![cfg_attr(
52 not(any(target_os = "macos", target_os = "ios")),
53 doc = "- `io_surface` — macOS and iOS `IOSurface`, packed RGBA/BGRA or"
54)]
55//! biplanar 4:2:0 YCbCr one plane per texture, imported through
56//! `MTLDevice::newTextureWithDescriptor:iosurface:plane:`.
57#![cfg_attr(
58 target_os = "windows",
59 doc = "- [`shared_handle`] — Windows shared texture handles, imported through"
60)]
61#![cfg_attr(
62 not(target_os = "windows"),
63 doc = "- `shared_handle` — Windows shared texture handles, imported through"
64)]
65//! `ID3D12Device::OpenSharedHandle`.
66//!
67//! Every import reaches under `wgpu` to its `hal` layer, so the caller must
68//! run on the backend that platform's import requires; each entry point says
69//! which, and asserts it rather than guessing.
70
71#[cfg(target_os = "android")]
72pub mod ahardware_buffer;
73#[cfg(target_os = "linux")]
74pub mod dma_buf;
75#[cfg(any(target_os = "macos", target_os = "ios"))]
76pub mod io_surface;
77#[cfg(target_os = "windows")]
78pub mod shared_handle;
79#[cfg(any(target_os = "linux", target_os = "android"))]
80mod vulkan_memory;
81mod ycbcr;
82
83pub use ycbcr::{YcbcrEncoding, YcbcrMatrix, YcbcrRange};