Skip to main content

alpha2_native_gpu/
lib.rs

1//! Platform GPU interop for native decoded video surfaces.
2//!
3//! `FFmpeg` ownership stays in `alpha2-ffmpeg-bridge`; this crate owns raw GPU handles,
4//! barriers, synchronization, and bounded surface accounting.
5
6#[cfg(all(target_os = "android", feature = "ahb-import"))]
7mod android;
8#[cfg(all(
9    test,
10    feature = "hwdevice",
11    any(target_os = "linux", target_os = "windows", target_os = "macos")
12))]
13mod conformance;
14mod context;
15/// The fixed-width ABI shared with the C helpers, generated from their headers by the build
16/// script with bindgen's layout assertions. Structs only Windows or macOS use are also pinned by
17/// hand below.
18#[allow(
19    dead_code,
20    non_camel_case_types,
21    unreachable_pub,
22    clippy::all,
23    clippy::pedantic,
24    clippy::undocumented_unsafe_blocks
25)]
26mod interop {
27    include!(concat!(env!("OUT_DIR"), "/interop.rs"));
28}
29
30// Pins the layouts of interop structs that only Windows and macOS builds compile, so a header
31// edit to them fails on every target.
32const _: () = {
33    use interop::{
34        Alpha2D3D12CopyInfo as D3D12, Alpha2D3D12EncodeCaps as Caps,
35        Alpha2D3D12EncodeCopy as Encode, Alpha2MetalFrameInfo as Metal,
36    };
37    use std::mem::{align_of, offset_of, size_of};
38    assert!(size_of::<D3D12>() == 40 && align_of::<D3D12>() == 8);
39    assert!(offset_of!(D3D12, resource) == 0);
40    assert!(offset_of!(D3D12, fence) == 8);
41    assert!(offset_of!(D3D12, fence_value) == 16);
42    assert!(offset_of!(D3D12, width) == 24);
43    assert!(offset_of!(D3D12, height) == 28);
44    assert!(offset_of!(D3D12, dxgi_format) == 32);
45    assert!(size_of::<Encode>() == 48 && align_of::<Encode>() == 8);
46    assert!(offset_of!(Encode, luma) == 0);
47    assert!(offset_of!(Encode, chroma) == 8);
48    assert!(offset_of!(Encode, destination) == 16);
49    assert!(offset_of!(Encode, frame_fence) == 24);
50    assert!(offset_of!(Encode, frame_value) == 32);
51    assert!(offset_of!(Encode, width) == 40);
52    assert!(offset_of!(Encode, height) == 44);
53    assert!(size_of::<Caps>() == 76 && align_of::<Caps>() == 4);
54    assert!(offset_of!(Caps, supported) == 0);
55    assert!(offset_of!(Caps, refused_check) == 4);
56    assert!(offset_of!(Caps, refused_status) == 8);
57    assert!(offset_of!(Caps, validation_flags) == 12);
58    assert!(offset_of!(Caps, min_width) == 16);
59    assert!(offset_of!(Caps, min_height) == 20);
60    assert!(offset_of!(Caps, max_width) == 24);
61    assert!(offset_of!(Caps, max_height) == 28);
62    assert!(offset_of!(Caps, width_multiple) == 32);
63    assert!(offset_of!(Caps, height_multiple) == 36);
64    assert!(offset_of!(Caps, max_p_l0_references) == 40);
65    assert!(offset_of!(Caps, max_b_l0_references) == 44);
66    assert!(offset_of!(Caps, max_l1_references) == 48);
67    assert!(offset_of!(Caps, rate_control_modes) == 52);
68    assert!(offset_of!(Caps, refused_rate_control_modes) == 56);
69    assert!(offset_of!(Caps, rate_control_status) == 60);
70    assert!(size_of::<Metal>() == 56 && align_of::<Metal>() == 8);
71    assert!(offset_of!(Metal, width) == 0);
72    assert!(offset_of!(Metal, height) == 4);
73    assert!(offset_of!(Metal, plane_width) == 8);
74    assert!(offset_of!(Metal, plane_height) == 16);
75    assert!(offset_of!(Metal, clean_x) == 24);
76    assert!(offset_of!(Metal, clean_y) == 28);
77    assert!(offset_of!(Metal, clean_width) == 32);
78    assert!(offset_of!(Metal, clean_height) == 36);
79    assert!(offset_of!(Metal, pixel_format) == 40);
80    assert!(offset_of!(Metal, plane_count) == 44);
81    assert!(offset_of!(Metal, io_surface) == 48);
82};
83#[cfg(all(target_os = "windows", feature = "hwdevice"))]
84mod d3d12;
85mod import;
86mod lifetime;
87#[cfg(feature = "hwdevice")]
88mod memory_budget;
89#[cfg(all(target_os = "macos", feature = "hwdevice"))]
90mod metal;
91#[cfg(feature = "hwdevice")]
92mod status;
93mod surface_budget;
94mod sync;
95#[cfg(all(target_os = "linux", feature = "hwdevice"))]
96mod vulkan;
97
98#[cfg(all(target_os = "android", feature = "ahb-import"))]
99pub use android::{
100    AhbImportError, AhbImporter, AhbPlanes, ImportedAhbFrame, MAX_CONVERSIONS_IN_FLIGHT,
101    reopen_for_ahb_import,
102};
103pub use context::NativeGpuIdentity;
104#[cfg(all(target_os = "windows", feature = "hwdevice"))]
105pub use d3d12::{
106    D3D12AdapterIdentity, D3D12CopyLease, D3D12EncodeCodec, D3D12EncodeCopier, D3D12EncodeExtent,
107    ImportedD3D12Frame, SharedD3D12Context, SharedD3D12Error, d3d12_adapter_identity,
108    gpu_wait_timeout as d3d12_wait_timeout, hresult_text,
109};
110pub use import::{ImportedPlaneDescriptor, NativePlaneLayout};
111pub use lifetime::{NativeSurfaceLease, SurfaceIdentity};
112#[cfg(feature = "hwdevice")]
113pub use memory_budget::adapter_memory_budget;
114#[cfg(all(target_os = "macos", feature = "hwdevice"))]
115pub use metal::{
116    ImportedMetalFrame, MetalEncoderPlanes, MetalImportLease, SharedMetalContext, SharedMetalError,
117    VideoToolboxCodec, gpu_wait_timeout as metal_wait_timeout, videotoolbox_hardware_decodes,
118    videotoolbox_surface_id,
119};
120pub use surface_budget::{SurfaceBudget, SurfaceBudgetError, SurfaceReservation, SurfaceUsage};
121pub use sync::{ExternalSyncPoint, NativeImageState};
122#[cfg(all(target_os = "linux", feature = "hwdevice"))]
123pub use vulkan::{
124    ImportTicketStats, ImportedVulkanFrame, SharedVulkanChoice, SharedVulkanContext,
125    SharedVulkanError, VideoEncodeExtent, VulkanCandidate, VulkanEncodeCopier, VulkanImportLease,
126    VulkanLayerVersion, adapter_pinned, choose_shared_vulkan, probe_vulkan_submission,
127    shared_device_index, vulkan_candidates,
128};
129
130/// Sets how long the platform interop helpers wait on GPU work before failing with a timeout.
131///
132/// Defaults to 30 seconds. A helper whose work did not finish in time leaks its GPU objects
133/// rather than freeing memory the device may still use.
134pub fn set_gpu_wait_timeout(timeout: std::time::Duration) {
135    #[cfg(all(target_os = "linux", feature = "hwdevice"))]
136    vulkan::set_wait_timeout(timeout);
137    #[cfg(all(target_os = "windows", feature = "hwdevice"))]
138    d3d12::set_wait_timeout(timeout);
139    #[cfg(all(target_os = "macos", feature = "hwdevice"))]
140    metal::set_wait_timeout(timeout);
141    #[cfg(all(target_os = "android", feature = "ahb-import"))]
142    android::set_wait_timeout(timeout);
143    let _ = timeout;
144}
145
146/// `timeout` in whole milliseconds for a Win32 wait. `0xFFFFFFFF` means `INFINITE`, so longer
147/// values clamp one below it and no setting makes a wait unbounded.
148#[cfg_attr(
149    not(all(target_os = "windows", feature = "hwdevice")),
150    allow(dead_code)
151)]
152fn win32_wait_milliseconds(timeout: std::time::Duration) -> u32 {
153    const INFINITE: u32 = u32::MAX;
154    u32::try_from(timeout.as_millis())
155        .unwrap_or(INFINITE)
156        .min(INFINITE - 1)
157}
158
159#[cfg(test)]
160mod tests {
161    use std::time::Duration;
162
163    #[test]
164    fn no_wait_timeout_reaches_win32_as_infinite() {
165        let milliseconds =
166            |value: u64| super::win32_wait_milliseconds(Duration::from_millis(value));
167        assert_eq!(milliseconds(30_000), 30_000);
168        assert_eq!(milliseconds(u64::from(u32::MAX) - 1), u32::MAX - 1);
169        assert_eq!(milliseconds(u64::from(u32::MAX)), u32::MAX - 1);
170        assert_eq!(milliseconds(u64::from(u32::MAX) + 1), u32::MAX - 1);
171        assert_eq!(milliseconds(u64::MAX), u32::MAX - 1);
172        assert_eq!(super::win32_wait_milliseconds(Duration::MAX), u32::MAX - 1);
173        // Below a millisecond is no wait, as `Duration::as_millis` rounds it.
174        assert_eq!(
175            super::win32_wait_milliseconds(Duration::from_micros(999)),
176            0
177        );
178    }
179}