Skip to main content

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};