Skip to main content

alpha2_ffmpeg_bridge/
lib.rs

1//! The `FFmpeg` calls rsmpeg's safe surface lacks, for the native binding: frame and packet
2//! copies, codec and side-data helpers, container I/O and hardware-frame shims.
3
4use std::{error::Error, ffi::CStr, fmt, ptr, slice};
5
6#[cfg(all(target_os = "linux", feature = "hwdevice"))]
7use std::ffi::CString;
8
9#[cfg(all(
10    any(target_os = "linux", target_os = "macos", target_os = "windows"),
11    feature = "hwdevice"
12))]
13use std::sync::Mutex;
14#[cfg(all(target_os = "linux", feature = "hwdevice"))]
15use std::sync::MutexGuard;
16
17pub use alpha2_media::GpuFault;
18use rsmpeg::{
19    avcodec::{AVCodecContext, AVCodecParameters},
20    avutil::AVFrame,
21    error::RsmpegError,
22    ffi,
23    swscale::SwsContext,
24};
25
26#[cfg(all(any(target_os = "linux", target_os = "windows"), feature = "hwdevice"))]
27use rsmpeg::avutil::AVHWDeviceContext;
28
29mod container;
30mod log;
31
32pub use container::{
33    CreateOutputError, DemuxInput, OpenInputError, OutputFile, PathError, file_url, open_input,
34};
35pub use log::{LogLine, LogMark, install_log_capture, log_detail, log_mark, log_since};
36
37/// The C shims' ABI, generated from `include/` by the build script.
38#[allow(
39    dead_code,
40    non_camel_case_types,
41    unreachable_pub,
42    clippy::all,
43    clippy::pedantic,
44    clippy::undocumented_unsafe_blocks
45)]
46mod interop {
47    include!(concat!(env!("OUT_DIR"), "/interop.rs"));
48}
49
50// Pins the layouts of the D3D12 and VideoToolbox interop structs so a header edit fails on every
51// target, not only where those shims compile.
52const _: () = {
53    use interop::{Alpha2D3D12FrameInfo as D3D12, Alpha2VideoToolboxFrameInfo as VideoToolbox};
54    use std::mem::{align_of, offset_of, size_of};
55    assert!(size_of::<D3D12>() == 64 && align_of::<D3D12>() == 8);
56    assert!(offset_of!(D3D12, resource) == 0);
57    assert!(offset_of!(D3D12, fence) == 8);
58    assert!(offset_of!(D3D12, fence_value) == 16);
59    assert!(offset_of!(D3D12, device) == 24);
60    assert!(offset_of!(D3D12, dxgi_format) == 32);
61    assert!(offset_of!(D3D12, width) == 36);
62    assert!(offset_of!(D3D12, height) == 40);
63    assert!(offset_of!(D3D12, hardware_format) == 44);
64    assert!(offset_of!(D3D12, software_format) == 48);
65    assert!(offset_of!(D3D12, surface_width) == 52);
66    assert!(offset_of!(D3D12, surface_height) == 56);
67    assert!(size_of::<VideoToolbox>() == 24 && align_of::<VideoToolbox>() == 8);
68    assert!(offset_of!(VideoToolbox, pixel_buffer) == 0);
69    assert!(offset_of!(VideoToolbox, width) == 8);
70    assert!(offset_of!(VideoToolbox, height) == 12);
71    assert!(offset_of!(VideoToolbox, hardware_format) == 16);
72    assert!(offset_of!(VideoToolbox, software_format) == 20);
73};
74
75/// Copies a hardware frame into a software frame in its `sw_format`, keeping timestamps, crop and
76/// color properties. Used for surfaces the renderer could not import.
77#[cfg(all(
78    any(target_os = "linux", target_os = "macos", target_os = "windows"),
79    feature = "hwdevice"
80))]
81// A frames context's buffer data is the `AVHWFramesContext` FFmpeg allocated, aligned for it.
82#[allow(clippy::cast_ptr_alignment)]
83fn download_hardware_frame(frame: &AVFrame) -> Result<AVFrame, BridgeError> {
84    if frame.hw_frames_ctx.is_null() {
85        return Err(BridgeError::InvalidInput(
86            "hardware frame has no frames context",
87        ));
88    }
89    // SAFETY: a non-null `hw_frames_ctx` is a reference the frame holds to its live
90    // `AVHWFramesContext`; only its size is read.
91    let written = unsafe {
92        let frames = (*frame.hw_frames_ctx).data.cast::<ffi::AVHWFramesContext>();
93        ((*frames).width, (*frames).height)
94    };
95    let mut software = AVFrame::new();
96    software
97        .hwframe_transfer_data(frame)
98        .map_err(BridgeError::Ffmpeg)?;
99    // The copy's row padding is not zeroed and some transfers write only the frames context's
100    // width, but `DecodedFrame::yuv_planes` shares whole rows.
101    zero_row_padding(&mut software, written.0, written.1)?;
102    // SAFETY: both frames are live; `av_frame_copy_props` only reads `frame` and writes metadata
103    // into `software`.
104    let copied = unsafe { ffi::av_frame_copy_props(software.as_mut_ptr(), frame.as_ptr()) };
105    if copied < 0 {
106        return Err(BridgeError::FfmpegCode(copied));
107    }
108    Ok(software)
109}
110
111/// Zeroes each row of the first `height` rows past `width` pixels, up to the linesize.
112///
113/// `frame` must be the only owner of its buffers.
114///
115/// # Errors
116/// Returns an error for a format without a descriptor, a negative size, or rows outside the
117/// frame's buffers.
118#[cfg_attr(not(feature = "hwdevice"), allow(dead_code))]
119fn zero_row_padding(frame: &mut AVFrame, width: i32, height: i32) -> Result<(), BridgeError> {
120    let format = frame.format;
121    // SAFETY: av_pix_fmt_desc_get only reads the static descriptor table; null for unknown formats.
122    let descriptor = unsafe { ffi::av_pix_fmt_desc_get(format).as_ref() }
123        .ok_or(BridgeError::InvalidInput("pixel format has no descriptor"))?;
124    if width < 0 || height < 0 {
125        return Err(BridgeError::InvalidInput("negative frame size"));
126    }
127    // SAFETY: as above.
128    let planes = unsafe { ffi::av_pix_fmt_count_planes(format) };
129    for plane in 0..usize::try_from(planes).unwrap_or(0).min(4) {
130        let plane_index = i32::try_from(plane).unwrap_or(0);
131        // SAFETY: av_image_get_linesize only reads the descriptor table.
132        let written = unsafe { ffi::av_image_get_linesize(format, width, plane_index) };
133        let (Ok(written), Ok(stride)) = (
134            usize::try_from(written),
135            usize::try_from(frame.linesize[plane]),
136        ) else {
137            continue;
138        };
139        let data = frame.data[plane];
140        if data.is_null() || stride <= written {
141            continue;
142        }
143        let shift = if plane == 1 || plane == 2 {
144            descriptor.log2_chroma_h
145        } else {
146            0
147        };
148        let rows = usize::try_from(-((-height) >> shift)).unwrap_or(0);
149        let start = data as usize;
150        let end = stride
151            .checked_mul(rows)
152            .and_then(|len| start.checked_add(len))
153            .ok_or(BridgeError::InvalidInput("frame plane size overflow"))?;
154        let inside = frame.buf.iter().any(|buffer| {
155            // SAFETY: a non-null `AVFrame::buf` entry is a live `AVBufferRef` the frame holds.
156            unsafe { buffer.as_ref() }.is_some_and(|buffer| {
157                let buffer_start = buffer.data as usize;
158                buffer_start <= start && buffer_start.saturating_add(buffer.size) >= end
159            })
160        });
161        if !inside {
162            return Err(BridgeError::InvalidInput(
163                "frame plane lies outside its buffers",
164            ));
165        }
166        for row in 0..rows {
167            // SAFETY: the check above puts every row inside a frame buffer the caller solely owns.
168            unsafe { ptr::write_bytes(data.add(row * stride + written), 0, stride - written) };
169        }
170    }
171    Ok(())
172}
173
174#[cfg(all(target_os = "windows", feature = "hwdevice"))]
175use interop::Alpha2D3D12FrameInfo as D3D12FrameDescriptor;
176
177#[cfg(all(target_os = "windows", feature = "hwdevice"))]
178unsafe extern "C" {
179    fn alpha2_d3d12_device_init(
180        context: *mut ffi::AVHWDeviceContext,
181        device: *mut std::ffi::c_void,
182    ) -> i32;
183    fn alpha2_d3d12_get_format(
184        context: *mut ffi::AVCodecContext,
185        formats: *const ffi::AVPixelFormat,
186    ) -> ffi::AVPixelFormat;
187    fn alpha2_d3d12_frame_info(
188        frame: *const ffi::AVFrame,
189        output: *mut D3D12FrameDescriptor,
190    ) -> i32;
191    fn alpha2_d3d12_frame_set_fence_value(frame: *mut ffi::AVFrame, value: u64) -> i32;
192    fn alpha2_d3d12_frame_fence_value(frame: *const ffi::AVFrame, output: *mut u64) -> i32;
193    fn alpha2_d3d12_frames_configure(
194        frames: *mut ffi::AVBufferRef,
195        dxgi_format: u32,
196        resource_flags: u32,
197    ) -> i32;
198}
199
200/// `DXGI_FORMAT_NV12`, the D3D12VA encoder-input texture format.
201#[cfg(all(target_os = "windows", feature = "hwdevice"))]
202pub const DXGI_FORMAT_NV12: u32 = 103;
203
204/// Sets a D3D12VA frames context's `dxgi_format` and `resource_flags`, with one texture per frame.
205///
206/// Encoder input needs one texture per frame because each frame has its own fence and a copy
207/// addresses its planes as subresources 0 and 1. Call between `av_hwframe_ctx_alloc` and
208/// `av_hwframe_ctx_init`.
209///
210/// # Errors
211/// Returns an error when the context is not a D3D12VA one.
212#[cfg(all(target_os = "windows", feature = "hwdevice"))]
213pub fn d3d12_frames_configure(
214    frames: &mut rsmpeg::avutil::AVHWFramesContext,
215    dxgi_format: u32,
216    resource_flags: u32,
217) -> Result<(), BridgeError> {
218    // SAFETY: `frames` is live; the shim checks the device type before writing D3D12VA fields.
219    let status =
220        unsafe { alpha2_d3d12_frames_configure(frames.as_mut_ptr(), dxgi_format, resource_flags) };
221    if status < 0 {
222        return Err(BridgeError::FfmpegCode(status));
223    }
224    Ok(())
225}
226
227/// D3D12 resource and decode fence retained by one hardware frame.
228///
229/// Defined on every target so a change to the shim's record fails to compile everywhere.
230#[derive(Clone, Copy, Debug, Eq, PartialEq)]
231pub struct D3D12FrameInfo {
232    /// Borrowed `ID3D12Resource` pointer.
233    pub resource: u64,
234    /// Borrowed decode `ID3D12Fence` pointer.
235    pub fence: u64,
236    /// Fence value signaled after decode completes.
237    pub fence_value: u64,
238    /// `ID3D12Device` identity that allocated the resource.
239    pub device: u64,
240    /// Native `DXGI_FORMAT` value.
241    pub dxgi_format: u32,
242    /// Width with the right crop applied but not the left.
243    pub width: i32,
244    /// Height with the bottom crop applied but not the top.
245    pub height: i32,
246    /// Software pixel format represented by the hardware frame.
247    pub software_format: i32,
248    /// Width of the texture the frame was decoded into.
249    pub surface_width: u32,
250    /// Height of the texture the frame was decoded into.
251    pub surface_height: u32,
252}
253
254impl D3D12FrameInfo {
255    #[cfg_attr(
256        not(all(target_os = "windows", feature = "hwdevice")),
257        allow(dead_code)
258    )]
259    const fn from_descriptor(descriptor: &interop::Alpha2D3D12FrameInfo) -> Self {
260        Self {
261            resource: descriptor.resource,
262            fence: descriptor.fence,
263            fence_value: descriptor.fence_value,
264            device: descriptor.device,
265            dxgi_format: descriptor.dxgi_format,
266            width: descriptor.width,
267            height: descriptor.height,
268            software_format: descriptor.software_format,
269            surface_width: descriptor.surface_width,
270            surface_height: descriptor.surface_height,
271        }
272    }
273}
274
275/// Ref-counted ownership of one opaque D3D12 `AVFrame`.
276#[cfg(all(target_os = "windows", feature = "hwdevice"))]
277pub struct D3D12FrameLease {
278    frame: Mutex<AVFrame>,
279}
280
281#[cfg(all(target_os = "windows", feature = "hwdevice"))]
282impl fmt::Debug for D3D12FrameLease {
283    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
284        formatter
285            .debug_struct("D3D12FrameLease")
286            .finish_non_exhaustive()
287    }
288}
289
290#[cfg(all(target_os = "windows", feature = "hwdevice"))]
291impl D3D12FrameLease {
292    /// Takes ownership of one decoded `AV_PIX_FMT_D3D12` frame.
293    #[must_use]
294    pub fn new(frame: AVFrame) -> Self {
295        Self {
296            frame: Mutex::new(frame),
297        }
298    }
299
300    /// Copies this frame's pixels to the CPU. Row padding is zeroed, so the planes can be shared.
301    ///
302    /// # Errors
303    /// Returns [`BridgeError`] when `FFmpeg` cannot transfer the frame.
304    pub fn download(&self) -> Result<DecodedFrame, BridgeError> {
305        let frame = self
306            .frame
307            .lock()
308            .unwrap_or_else(std::sync::PoisonError::into_inner);
309        download_hardware_frame(&frame).map(|frame| DecodedFrame {
310            frame,
311            written: true,
312        })
313    }
314
315    /// Returns the retained frame's resource and synchronization descriptor.
316    ///
317    /// # Errors
318    /// Returns an error when this is not a valid D3D12 hardware frame.
319    pub fn info(&self) -> Result<D3D12FrameInfo, BridgeError> {
320        let frame = self
321            .frame
322            .lock()
323            .unwrap_or_else(std::sync::PoisonError::into_inner);
324        d3d12_frame_info(&frame)
325    }
326}
327
328/// Initializes an `FFmpeg` D3D12VA device context over the renderer's device.
329///
330/// # Safety
331/// `device` must be the address of a live `ID3D12Device`. The context takes its own COM reference.
332///
333/// # Errors
334/// Returns an error if the pointer is null or `FFmpeg` rejects the device.
335#[cfg(all(target_os = "windows", feature = "hwdevice"))]
336#[allow(clippy::cast_ptr_alignment)]
337pub unsafe fn create_d3d12_device_context(device: u64) -> Result<AVHWDeviceContext, BridgeError> {
338    let device = usize::try_from(device)
339        .map_err(|_| BridgeError::InvalidInput("invalid D3D12 device pointer"))?
340        as *mut std::ffi::c_void;
341    if device.is_null() {
342        return Err(BridgeError::InvalidInput("D3D12 device is null"));
343    }
344    let mut context = alloc_hwdevice(ffi::AV_HWDEVICE_TYPE_D3D12VA, "D3D12")?;
345    let device_context = context.data.cast::<ffi::AVHWDeviceContext>();
346    // SAFETY: the allocated context is writable, the caller guarantees `device` is a live
347    // `ID3D12Device`, and the shim takes its own COM reference.
348    let result = unsafe { alpha2_d3d12_device_init(device_context, device) };
349    if result < 0 {
350        return Err(BridgeError::FfmpegCode(result));
351    }
352    context.init().map_err(BridgeError::Ffmpeg)?;
353    Ok(context)
354}
355
356/// Returns the pixel-format selector used by D3D12VA decoders.
357#[cfg(all(target_os = "windows", feature = "hwdevice"))]
358#[must_use]
359pub fn d3d12_get_format_callback()
360-> unsafe extern "C" fn(*mut ffi::AVCodecContext, *const ffi::AVPixelFormat) -> ffi::AVPixelFormat {
361    alpha2_d3d12_get_format
362}
363
364/// Reads one retained D3D12 frame descriptor.
365///
366/// # Errors
367/// Returns an error if the frame is not a valid D3D12VA frame.
368#[cfg(all(target_os = "windows", feature = "hwdevice"))]
369pub fn d3d12_frame_info(frame: &AVFrame) -> Result<D3D12FrameInfo, BridgeError> {
370    let mut descriptor = D3D12FrameDescriptor::default();
371    // SAFETY: the frame remains live for the duration of the descriptor copy.
372    let result = unsafe { alpha2_d3d12_frame_info(frame.as_ptr(), &raw mut descriptor) };
373    if result != 0 {
374        return Err(BridgeError::FfmpegCode(result));
375    }
376    Ok(D3D12FrameInfo::from_descriptor(&descriptor))
377}
378
379/// The fence value `FFmpeg` waits for before next using the frame (`sync_ctx.fence_value`).
380///
381/// # Errors
382/// Returns an error if the frame is not a valid D3D12VA frame.
383#[cfg(all(target_os = "windows", feature = "hwdevice"))]
384pub fn d3d12_frame_fence_value(frame: &AVFrame) -> Result<u64, BridgeError> {
385    let mut value = 0;
386    // SAFETY: the frame is live for the call and the output is a writable local.
387    let result = unsafe { alpha2_d3d12_frame_fence_value(frame.as_ptr(), &raw mut value) };
388    if result != 0 {
389        return Err(BridgeError::FfmpegCode(result));
390    }
391    Ok(value)
392}
393
394/// One encoder-pool D3D12VA frame held open for a native GPU write.
395///
396/// The encoder waits on the frame's fence for `sync_ctx.fence_value` before reading it, so after a
397/// fenced copy is submitted, [`Self::commit`] records the value it signals. A guard dropped without
398/// a commit leaves the frame unchanged.
399#[cfg(all(target_os = "windows", feature = "hwdevice"))]
400pub struct D3D12EncodeFrameAccess<'a> {
401    frame: &'a mut AVFrame,
402    info: D3D12FrameInfo,
403}
404
405#[cfg(all(target_os = "windows", feature = "hwdevice"))]
406impl fmt::Debug for D3D12EncodeFrameAccess<'_> {
407    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
408        formatter
409            .debug_struct("D3D12EncodeFrameAccess")
410            .field("info", &self.info)
411            .finish_non_exhaustive()
412    }
413}
414
415#[cfg(all(target_os = "windows", feature = "hwdevice"))]
416impl<'a> D3D12EncodeFrameAccess<'a> {
417    /// Opens one handoff on an encoder-pool frame.
418    ///
419    /// # Errors
420    /// Returns an error when the frame is not a usable D3D12VA frame.
421    pub fn begin(frame: &'a mut AVFrame) -> Result<Self, BridgeError> {
422        let info = d3d12_frame_info(frame)?;
423        Ok(Self { frame, info })
424    }
425
426    /// The frame's texture, fence and fence value as `begin` read them.
427    #[must_use]
428    pub const fn info(&self) -> &D3D12FrameInfo {
429        &self.info
430    }
431
432    /// Retains the frame's buffers and hardware pool beyond this access guard.
433    ///
434    /// # Errors
435    /// Returns an allocation error if `FFmpeg` cannot create the reference.
436    pub fn retain_frame(&self) -> Result<AVFrame, BridgeError> {
437        // SAFETY: the frame is live; av_frame_clone makes an independent AVFrame with buffer refs.
438        let raw = unsafe { ffi::av_frame_clone(self.frame.as_ptr()) };
439        let raw = std::ptr::NonNull::new(raw)
440            .ok_or(BridgeError::InvalidInput("cannot retain encode frame"))?;
441        // SAFETY: the newly allocated frame is uniquely owned by this value.
442        Ok(unsafe { AVFrame::from_raw(raw) })
443    }
444
445    /// Records the fence value a submitted write into the frame signals.
446    ///
447    /// # Errors
448    /// Returns an error if the frame is not a valid D3D12VA frame (`begin` already checked).
449    pub fn commit(&mut self, fence_value: u64) -> Result<(), BridgeError> {
450        // SAFETY: the guard borrows the frame exclusively; the shim checks its type before writing.
451        let result =
452            unsafe { alpha2_d3d12_frame_set_fence_value(self.frame.as_mut_ptr(), fence_value) };
453        if result != 0 {
454            return Err(BridgeError::FfmpegCode(result));
455        }
456        self.info.fence_value = fence_value;
457        Ok(())
458    }
459}
460
461#[cfg(all(any(target_os = "linux", target_os = "macos"), feature = "hwdevice"))]
462use interop::Alpha2VideoToolboxFrameInfo as VideoToolboxFrameDescriptor;
463
464// The VideoToolbox shim reads only FFmpeg structures, so Linux builds and tests it too.
465#[cfg(all(any(target_os = "linux", target_os = "macos"), feature = "hwdevice"))]
466#[cfg_attr(target_os = "linux", allow(dead_code))]
467unsafe extern "C" {
468    fn alpha2_videotoolbox_get_format(
469        context: *mut ffi::AVCodecContext,
470        formats: *const ffi::AVPixelFormat,
471    ) -> ffi::AVPixelFormat;
472    fn alpha2_videotoolbox_frame_info(
473        frame: *const ffi::AVFrame,
474        output: *mut VideoToolboxFrameDescriptor,
475    ) -> i32;
476}
477
478/// `CoreVideo` pixel-buffer identity retained by one `VideoToolbox` frame.
479///
480/// Defined on every target, like [`D3D12FrameInfo`].
481#[derive(Clone, Copy, Debug, Eq, PartialEq)]
482pub struct VideoToolboxFrameInfo {
483    /// Borrowed `CVPixelBufferRef`, valid while the frame lease is retained.
484    pub pixel_buffer: u64,
485    /// Coded width reported by `FFmpeg`.
486    pub width: i32,
487    /// Coded height reported by `FFmpeg`.
488    pub height: i32,
489    /// Sample layout the frames context allocated, such as NV12 or P010.
490    pub software_format: i32,
491}
492
493impl VideoToolboxFrameInfo {
494    #[cfg_attr(
495        not(all(any(target_os = "linux", target_os = "macos"), feature = "hwdevice")),
496        allow(dead_code)
497    )]
498    const fn from_descriptor(descriptor: &interop::Alpha2VideoToolboxFrameInfo) -> Self {
499        Self {
500            pixel_buffer: descriptor.pixel_buffer,
501            width: descriptor.width,
502            height: descriptor.height,
503            software_format: descriptor.software_format,
504        }
505    }
506}
507
508/// Reads a `VideoToolbox` frame's descriptor, refusing other frames.
509#[cfg(all(any(target_os = "linux", target_os = "macos"), feature = "hwdevice"))]
510#[cfg_attr(target_os = "linux", allow(dead_code))]
511fn read_videotoolbox_frame_info(frame: &AVFrame) -> Result<VideoToolboxFrameInfo, BridgeError> {
512    let mut descriptor = VideoToolboxFrameDescriptor::default();
513    // SAFETY: `frame` is live for the copy; the shim checks each pointer before reading through it.
514    let result = unsafe { alpha2_videotoolbox_frame_info(frame.as_ptr(), &raw mut descriptor) };
515    if result != 0 {
516        return Err(BridgeError::InvalidInput(
517            "frame is not a VideoToolbox frame with a pixel buffer",
518        ));
519    }
520    Ok(VideoToolboxFrameInfo::from_descriptor(&descriptor))
521}
522
523/// Ref-counted ownership of one opaque `VideoToolbox` `AVFrame`.
524#[cfg(all(target_os = "macos", feature = "hwdevice"))]
525pub struct VideoToolboxFrameLease {
526    frame: Mutex<AVFrame>,
527}
528
529#[cfg(all(target_os = "macos", feature = "hwdevice"))]
530impl fmt::Debug for VideoToolboxFrameLease {
531    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
532        formatter
533            .debug_struct("VideoToolboxFrameLease")
534            .finish_non_exhaustive()
535    }
536}
537
538#[cfg(all(target_os = "macos", feature = "hwdevice"))]
539impl VideoToolboxFrameLease {
540    /// Takes ownership of one decoded `AV_PIX_FMT_VIDEOTOOLBOX` frame.
541    #[must_use]
542    pub fn new(frame: AVFrame) -> Self {
543        Self {
544            frame: Mutex::new(frame),
545        }
546    }
547
548    /// Copies this frame's pixels to the CPU. Row padding is zeroed, so the planes can be shared.
549    ///
550    /// # Errors
551    /// Returns [`BridgeError`] when `FFmpeg` cannot transfer the frame.
552    pub fn download(&self) -> Result<DecodedFrame, BridgeError> {
553        let frame = self
554            .frame
555            .lock()
556            .unwrap_or_else(std::sync::PoisonError::into_inner);
557        download_hardware_frame(&frame).map(|frame| DecodedFrame {
558            frame,
559            written: true,
560        })
561    }
562
563    /// Returns the retained frame's `CoreVideo` surface identity.
564    ///
565    /// # Errors
566    /// Returns an error when the frame is not a `VideoToolbox` hardware frame.
567    pub fn info(&self) -> Result<VideoToolboxFrameInfo, BridgeError> {
568        let frame = self
569            .frame
570            .lock()
571            .unwrap_or_else(std::sync::PoisonError::into_inner);
572        read_videotoolbox_frame_info(&frame)
573    }
574}
575
576/// Returns the pixel-format selector used by `VideoToolbox` decoders.
577#[cfg(all(target_os = "macos", feature = "hwdevice"))]
578#[must_use]
579pub fn videotoolbox_get_format_callback()
580-> unsafe extern "C" fn(*mut ffi::AVCodecContext, *const ffi::AVPixelFormat) -> ffi::AVPixelFormat {
581    alpha2_videotoolbox_get_format
582}
583
584/// Reads the `CoreVideo` surface identity without taking ownership of the frame.
585///
586/// # Errors
587/// Returns an error when the frame is not a `VideoToolbox` hardware frame.
588#[cfg(all(target_os = "macos", feature = "hwdevice"))]
589pub fn videotoolbox_frame_info(frame: &AVFrame) -> Result<VideoToolboxFrameInfo, BridgeError> {
590    read_videotoolbox_frame_info(frame)
591}
592
593/// Maximum number of Vulkan images described by an `FFmpeg` hardware frame.
594#[cfg(all(target_os = "linux", feature = "hwdevice"))]
595pub const MAX_VULKAN_PLANES: usize = interop::ALPHA2_MAX_VULKAN_PLANES as usize;
596
597/// Raw shared-device description used to initialize `FFmpeg`'s Vulkan context.
598#[cfg(all(target_os = "linux", feature = "hwdevice"))]
599#[derive(Clone, Debug)]
600pub struct VulkanDeviceInfo {
601    /// Raw `VkInstance`.
602    pub instance: u64,
603    /// Raw `VkPhysicalDevice`.
604    pub physical_device: u64,
605    /// Raw `VkDevice`.
606    pub device: u64,
607    /// Queue family used by wgpu and native barriers.
608    pub graphics_queue_family: u32,
609    /// Enabled graphics queues in that family.
610    pub graphics_queue_count: u32,
611    /// Dedicated video decode queue family.
612    pub decode_queue_family: u32,
613    /// Enabled decode queues in that family.
614    pub decode_queue_count: u32,
615    /// Vulkan video codec-operation flags.
616    pub decode_video_caps: u32,
617    /// Dedicated video encode queue family. Ignored when the count is zero.
618    pub encode_queue_family: u32,
619    /// Enabled encode queues in that family, or zero when this device has none.
620    pub encode_queue_count: u32,
621    /// Vulkan video encode codec-operation flags.
622    pub encode_video_caps: u32,
623    /// Enabled core feature bits required by `FFmpeg`'s context contract.
624    pub core_features: [u32; 4],
625    /// Whether `timelineSemaphore` is enabled on the device; the context is refused without it.
626    pub timeline_semaphore: u32,
627    /// Whether `synchronization2` is enabled on the device.
628    pub synchronization2: u32,
629    /// Whether `samplerYcbcrConversion` is enabled on the device.
630    pub sampler_ycbcr_conversion: u32,
631    /// Whether `videoMaintenance1` is enabled on the device.
632    pub video_maintenance1: u32,
633    /// Whether `videoDecodeVP9` (`VK_KHR_video_decode_vp9`) is enabled on the device.
634    pub video_decode_vp9: u32,
635    /// Enabled instance extension names.
636    pub instance_extensions: Vec<String>,
637    /// Enabled device extension names.
638    pub device_extensions: Vec<String>,
639}
640
641#[cfg(all(target_os = "linux", feature = "hwdevice"))]
642use interop::Alpha2VulkanDeviceInfo as VulkanDeviceDescriptor;
643
644/// Serializes one shared Vulkan queue family across `FFmpeg` and the renderer.
645///
646/// Takes the same recursive lock `FFmpeg` takes around its submissions. Only contexts made by
647/// [`create_vulkan_device_context`] have it.
648#[cfg(all(target_os = "linux", feature = "hwdevice"))]
649pub struct VulkanQueueLock {
650    device: AVHWDeviceContext,
651    queue_family: u32,
652}
653
654// SAFETY: after construction the context is only read to pass its pointer to the shim's lock and
655// unlock, which synchronize on their own mutex. The single owner drops the reference once.
656#[cfg(all(target_os = "linux", feature = "hwdevice"))]
657unsafe impl Sync for VulkanQueueLock {}
658
659#[cfg(all(target_os = "linux", feature = "hwdevice"))]
660impl fmt::Debug for VulkanQueueLock {
661    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
662        formatter
663            .debug_struct("VulkanQueueLock")
664            .field("queue_family", &self.queue_family)
665            .finish_non_exhaustive()
666    }
667}
668
669#[cfg(all(target_os = "linux", feature = "hwdevice"))]
670impl VulkanQueueLock {
671    /// Locks submissions to `queue_family` on `device`.
672    ///
673    /// # Errors
674    /// Returns an input error unless `device` came from [`create_vulkan_device_context`] and has a
675    /// lock for `queue_family`.
676    #[allow(clippy::cast_ptr_alignment)]
677    pub fn new(device: AVHWDeviceContext, queue_family: u32) -> Result<Self, BridgeError> {
678        // SAFETY: `device` keeps the context live; the shim reads only its type, free callback and
679        // its own state.
680        let lockable = unsafe {
681            alpha2_vulkan_queue_lockable(
682                device.data.cast::<ffi::AVHWDeviceContext>().cast_const(),
683                queue_family,
684            )
685        };
686        if lockable == 0 {
687            return Err(BridgeError::InvalidInput(
688                "Vulkan queue lock needs a family of a device the bridge initialized",
689            ));
690        }
691        Ok(Self {
692            device,
693            queue_family,
694        })
695    }
696
697    /// Holds the queue lock until the guard drops; the guard stays on this thread.
698    #[must_use]
699    pub fn lock(&self) -> VulkanQueueGuard<'_> {
700        // SAFETY: the guard is neither Send nor Sync and releases this exactly once.
701        unsafe { self.raw_lock() };
702        VulkanQueueGuard {
703            lock: self,
704            _owning_thread: std::marker::PhantomData,
705        }
706    }
707
708    /// Acquires the queue lock without a guard, for adapters with their own lock/unlock protocol.
709    ///
710    /// # Safety
711    /// The calling thread must release it with exactly one [`Self::raw_unlock`], in reverse order
712    /// of its other holds on this lock.
713    #[allow(clippy::cast_ptr_alignment)]
714    pub unsafe fn raw_lock(&self) {
715        // SAFETY: `new` checked the shim set up this context with a lock for this family, and the
716        // retained context keeps it alive.
717        unsafe {
718            alpha2_vulkan_queue_lock(
719                self.device.data.cast::<ffi::AVHWDeviceContext>(),
720                self.queue_family,
721            );
722        }
723    }
724
725    /// Releases a hold taken by [`Self::raw_lock`].
726    ///
727    /// # Safety
728    /// The calling thread must hold the lock from an unreleased [`Self::raw_lock`], and this must
729    /// be its most recent hold. An unbalanced release lets two submissions reach the queue at once.
730    #[allow(clippy::cast_ptr_alignment)]
731    pub unsafe fn raw_unlock(&self) {
732        // SAFETY: the caller holds this lock on this thread, per the contract above.
733        unsafe {
734            alpha2_vulkan_queue_unlock(
735                self.device.data.cast::<ffi::AVHWDeviceContext>(),
736                self.queue_family,
737            );
738        }
739    }
740}
741
742/// One hold of a [`VulkanQueueLock`], released on drop on the thread that took it.
743#[cfg(all(target_os = "linux", feature = "hwdevice"))]
744#[derive(Debug)]
745pub struct VulkanQueueGuard<'a> {
746    lock: &'a VulkanQueueLock,
747    _owning_thread: std::marker::PhantomData<*const ()>,
748}
749
750#[cfg(all(target_os = "linux", feature = "hwdevice"))]
751impl Drop for VulkanQueueGuard<'_> {
752    fn drop(&mut self) {
753        // SAFETY: `lock` took this hold on this thread (the guard is not Send), and guards drop in
754        // reverse order of creation.
755        unsafe { self.lock.raw_unlock() };
756    }
757}
758
759#[cfg(all(target_os = "linux", feature = "hwdevice"))]
760unsafe extern "C" {
761    fn alpha2_vulkan_queue_lockable(
762        context: *const ffi::AVHWDeviceContext,
763        queue_family: u32,
764    ) -> i32;
765    fn alpha2_vulkan_queue_lock(context: *mut ffi::AVHWDeviceContext, queue_family: u32);
766    fn alpha2_vulkan_queue_unlock(context: *mut ffi::AVHWDeviceContext, queue_family: u32);
767    fn alpha2_vulkan_device_init(
768        context: *mut ffi::AVHWDeviceContext,
769        info: *const VulkanDeviceDescriptor,
770    ) -> i32;
771}
772
773/// Initializes an `FFmpeg` Vulkan device context over an application-owned device.
774///
775/// # Safety
776/// The handles in `info` must be live, belong together, have been created with the queues,
777/// features and extensions `info` names, and outlive the returned context.
778///
779/// # Errors
780/// Returns an input error for invalid extension names or an `FFmpeg` error when the context cannot
781/// be initialized.
782#[cfg(all(target_os = "linux", feature = "hwdevice"))]
783#[allow(clippy::cast_ptr_alignment)]
784pub unsafe fn create_vulkan_device_context(
785    info: &VulkanDeviceInfo,
786) -> Result<AVHWDeviceContext, BridgeError> {
787    let instance = info
788        .instance_extensions
789        .iter()
790        .map(|s| CString::new(s.as_str()))
791        .collect::<Result<Vec<_>, _>>()
792        .map_err(|_| BridgeError::InvalidInput("Vulkan extension contains NUL"))?;
793    let device = info
794        .device_extensions
795        .iter()
796        .map(|s| CString::new(s.as_str()))
797        .collect::<Result<Vec<_>, _>>()
798        .map_err(|_| BridgeError::InvalidInput("Vulkan extension contains NUL"))?;
799    let instance_ptrs = instance.iter().map(|s| s.as_ptr()).collect::<Vec<_>>();
800    let device_ptrs = device.iter().map(|s| s.as_ptr()).collect::<Vec<_>>();
801    let raw = VulkanDeviceDescriptor {
802        instance: info.instance,
803        physical_device: info.physical_device,
804        device: info.device,
805        graphics_queue_family: info.graphics_queue_family,
806        graphics_queue_count: info.graphics_queue_count,
807        decode_queue_family: info.decode_queue_family,
808        decode_queue_count: info.decode_queue_count,
809        decode_video_caps: info.decode_video_caps,
810        encode_queue_family: info.encode_queue_family,
811        encode_queue_count: info.encode_queue_count,
812        encode_video_caps: info.encode_video_caps,
813        shader_image_gather_extended: info.core_features[0],
814        fragment_stores_and_atomics: info.core_features[1],
815        shader_int64: info.core_features[2],
816        vertex_pipeline_stores_and_atomics: info.core_features[3],
817        timeline_semaphore: info.timeline_semaphore,
818        synchronization2: info.synchronization2,
819        sampler_ycbcr_conversion: info.sampler_ycbcr_conversion,
820        video_maintenance1: info.video_maintenance1,
821        video_decode_vp9: info.video_decode_vp9,
822        instance_extensions: instance_ptrs.as_ptr(),
823        instance_extension_count: u32::try_from(instance_ptrs.len())
824            .map_err(|_| BridgeError::InvalidInput("too many Vulkan extensions"))?,
825        device_extensions: device_ptrs.as_ptr(),
826        device_extension_count: u32::try_from(device_ptrs.len())
827            .map_err(|_| BridgeError::InvalidInput("too many Vulkan extensions"))?,
828    };
829    let mut context = alloc_hwdevice(ffi::AV_HWDEVICE_TYPE_VULKAN, "Vulkan")?;
830    let device_context = context.data.cast::<ffi::AVHWDeviceContext>();
831    // SAFETY: the context is freshly allocated and writable, the shim copies the extension names,
832    // and the caller guarantees the handles.
833    let result = unsafe { alpha2_vulkan_device_init(device_context, &raw const raw) };
834    if result < 0 {
835        return Err(BridgeError::FfmpegCode(result));
836    }
837    context.init().map_err(BridgeError::Ffmpeg)?;
838    Ok(context)
839}
840
841/// Opaque Vulkan handles and synchronization state for one `FFmpeg` hardware frame.
842///
843/// The caller must not destroy the handles and must retain the source `AVFrame` while using them.
844#[cfg(all(target_os = "linux", feature = "hwdevice"))]
845#[derive(Clone, Debug, Eq, PartialEq)]
846pub struct VulkanFrameInfo {
847    /// `FFmpeg` hardware pixel format.
848    pub hardware_format: i32,
849    /// Software layout represented by the hardware frames context.
850    pub software_format: i32,
851    /// Visible frame width.
852    pub width: i32,
853    /// Visible frame height.
854    pub height: i32,
855    /// Allocated image width, padded to whole macroblocks.
856    pub coded_width: i32,
857    /// Allocated image height, padded to whole macroblocks.
858    pub coded_height: i32,
859    /// Number of non-null Vulkan images.
860    pub plane_count: u32,
861    /// Whether `FFmpeg` allocated the image with sampled-image usage.
862    pub sampled: bool,
863    /// `VkInstance` identity.
864    pub instance: u64,
865    /// `VkPhysicalDevice` identity.
866    pub physical_device: u64,
867    /// `VkDevice` identity.
868    pub device: u64,
869    /// Per-plane `VkImage` identities.
870    pub images: [u64; MAX_VULKAN_PLANES],
871    /// Per-plane Vulkan formats.
872    pub formats: [u32; MAX_VULKAN_PLANES],
873    /// Current per-plane image layouts.
874    pub layouts: [u32; MAX_VULKAN_PLANES],
875    /// Current per-plane access masks.
876    pub access: [u32; MAX_VULKAN_PLANES],
877    /// Per-plane timeline semaphore identities.
878    pub semaphores: [u64; MAX_VULKAN_PLANES],
879    /// Values that an importing submission must wait for.
880    pub semaphore_values: [u64; MAX_VULKAN_PLANES],
881    /// Current image queue-family ownership.
882    pub queue_families: [u32; MAX_VULKAN_PLANES],
883}
884
885/// Vulkan image and synchronization state of one hardware frame, read under the frame lock.
886#[cfg(all(target_os = "linux", feature = "hwdevice"))]
887pub type VulkanFrameDescriptor = interop::Alpha2VulkanFrameInfo;
888
889/// Locked `FFmpeg` Vulkan surface state passed to the native GPU boundary.
890///
891/// Editing a record changes no frame by itself. The record a guard writes back is reachable only
892/// through the `unsafe` `access_mut`, since its values must describe work actually submitted.
893#[cfg(all(target_os = "linux", feature = "hwdevice"))]
894#[repr(transparent)]
895#[derive(Default)]
896pub struct VulkanFrameAccess(interop::Alpha2VulkanFrameAccess);
897
898#[cfg(all(target_os = "linux", feature = "hwdevice"))]
899impl VulkanFrameAccess {
900    /// The frame's images and their synchronization state.
901    #[must_use]
902    pub const fn frame(&self) -> &VulkanFrameDescriptor {
903        &self.0.frame
904    }
905
906    /// Mutable frame state; see [`VulkanFrameAccessGuard::access_mut`] for what it must hold.
907    pub const fn frame_mut(&mut self) -> &mut VulkanFrameDescriptor {
908        &mut self.0.frame
909    }
910
911    /// The frames context's `VkAllocationCallbacks`, or zero.
912    #[must_use]
913    pub const fn allocator(&self) -> u64 {
914        self.0.allocator
915    }
916
917    /// The queue family the frame's images are owned by.
918    #[must_use]
919    pub const fn queue_family(&self) -> u32 {
920        self.0.queue_family
921    }
922
923    /// Array layers of each image.
924    #[must_use]
925    pub const fn layer_count(&self) -> u32 {
926        self.0.layer_count
927    }
928}
929
930#[cfg(all(target_os = "linux", feature = "hwdevice"))]
931unsafe extern "C" {
932    fn alpha2_vulkan_get_format(
933        context: *mut ffi::AVCodecContext,
934        formats: *const ffi::AVPixelFormat,
935    ) -> ffi::AVPixelFormat;
936    fn alpha2_vulkan_frame_info(
937        frame: *const ffi::AVFrame,
938        output: *mut VulkanFrameDescriptor,
939    ) -> i32;
940    fn alpha2_vulkan_frames_add_usage(frames: *mut ffi::AVBufferRef, usage: u32) -> i32;
941    fn alpha2_vulkan_frames_usage(frames: *const ffi::AVBufferRef) -> u32;
942    fn alpha2_vulkan_frame_access_begin(
943        frame: *mut ffi::AVFrame,
944        output: *mut VulkanFrameAccess,
945    ) -> i32;
946    fn alpha2_vulkan_frame_access_end(
947        begun: *const interop::Alpha2VulkanFrameAccess,
948        updated: *const VulkanFrameAccess,
949    );
950}
951
952/// Why the Vulkan shim refused a frame (its own codes, not `FFmpeg`'s).
953#[cfg(all(target_os = "linux", feature = "hwdevice"))]
954const fn vulkan_frame_refusal(status: i32) -> BridgeError {
955    BridgeError::InvalidInput(match status {
956        -1 => "frame is not a Vulkan hardware frame",
957        -2 => "Vulkan frame has no hardware frames or device context",
958        -3 => "Vulkan frame has no images",
959        -4 => "Vulkan frames context has no frame or queue locks, or no layers",
960        -5 => "Vulkan device has no graphics or compute queue",
961        _ => "Vulkan frame could not be read",
962    })
963}
964
965/// Ref-counted ownership of an opaque `FFmpeg` Vulkan frame.
966#[cfg(all(target_os = "linux", feature = "hwdevice"))]
967pub struct VulkanFrameLease {
968    frame: Mutex<AVFrame>,
969}
970
971#[cfg(all(target_os = "linux", feature = "hwdevice"))]
972impl fmt::Debug for VulkanFrameLease {
973    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
974        formatter
975            .debug_struct("VulkanFrameLease")
976            .finish_non_exhaustive()
977    }
978}
979
980#[cfg(all(target_os = "linux", feature = "hwdevice"))]
981impl VulkanFrameLease {
982    /// Takes ownership of one decoded `AV_PIX_FMT_VULKAN` frame.
983    #[must_use]
984    pub fn new(frame: AVFrame) -> Self {
985        Self {
986            frame: Mutex::new(frame),
987        }
988    }
989
990    /// Copies this frame's pixels to the CPU. Row padding is zeroed, so the planes can be shared.
991    ///
992    /// # Errors
993    /// Returns [`BridgeError`] when `FFmpeg` cannot transfer the frame.
994    pub fn download(&self) -> Result<DecodedFrame, BridgeError> {
995        let frame = self
996            .frame
997            .lock()
998            .unwrap_or_else(std::sync::PoisonError::into_inner);
999        download_hardware_frame(&frame).map(|frame| DecodedFrame {
1000            frame,
1001            written: true,
1002        })
1003    }
1004
1005    /// Returns a locked snapshot of the frame's native image state.
1006    ///
1007    /// # Errors
1008    /// Returns [`BridgeError`] when the frame or its hardware context is invalid.
1009    pub fn info(&self) -> Result<VulkanFrameInfo, BridgeError> {
1010        let frame = self
1011            .frame
1012            .lock()
1013            .unwrap_or_else(std::sync::PoisonError::into_inner);
1014        vulkan_frame_info(&frame)
1015    }
1016
1017    /// Locks the `FFmpeg` frame and queue for one native GPU handoff.
1018    ///
1019    /// # Errors
1020    /// Returns [`BridgeError`] if the frame has no usable sampled images or queue.
1021    pub fn lock_access(&self) -> Result<VulkanFrameAccessGuard<'_>, BridgeError> {
1022        let mut frame = self
1023            .frame
1024            .lock()
1025            .unwrap_or_else(std::sync::PoisonError::into_inner);
1026        let mut access = VulkanFrameAccess::default();
1027        // SAFETY: the mutex guard borrows the frame exclusively until the end call in Drop.
1028        let result =
1029            unsafe { alpha2_vulkan_frame_access_begin(frame.as_mut_ptr(), &raw mut access) };
1030        if result != 0 {
1031            return Err(vulkan_frame_refusal(result));
1032        }
1033        Ok(VulkanFrameAccessGuard {
1034            _frame: frame,
1035            begun: access.0,
1036            access,
1037            committed: false,
1038        })
1039    }
1040}
1041
1042/// Guard for one locked `FFmpeg` frame and queue handoff.
1043///
1044/// Safe code cannot change what is written back: an unsignaled timeline value hangs later users and
1045/// a wrong layout makes the contents undefined.
1046///
1047/// ```compile_fail,E0133
1048/// # fn forge(lease: &alpha2_ffmpeg_bridge::VulkanFrameLease) {
1049/// let mut guard = lease.lock_access().unwrap();
1050/// guard.access_mut().frame_mut().semaphore_values[0] += 1000;
1051/// guard.commit();
1052/// # }
1053/// ```
1054#[cfg(all(target_os = "linux", feature = "hwdevice"))]
1055pub struct VulkanFrameAccessGuard<'a> {
1056    _frame: MutexGuard<'a, AVFrame>,
1057    // What `begin` locked, which the end call releases and checks the write-back against.
1058    begun: interop::Alpha2VulkanFrameAccess,
1059    access: VulkanFrameAccess,
1060    committed: bool,
1061}
1062
1063#[cfg(all(target_os = "linux", feature = "hwdevice"))]
1064impl VulkanFrameAccessGuard<'_> {
1065    /// The frame's state while its `FFmpeg` locks are held.
1066    #[must_use]
1067    pub const fn access(&self) -> &VulkanFrameAccess {
1068        &self.access
1069    }
1070
1071    /// The record written back on [`Self::commit`]. Planes whose image or semaphore changed and
1072    /// timeline values below the frame's are ignored.
1073    ///
1074    /// # Safety
1075    /// On commit, each layout and access mask must be what the submitted work leaves the image in,
1076    /// and each timeline value one that work submitted before the guard drops signals.
1077    #[must_use]
1078    pub const unsafe fn access_mut(&mut self) -> &mut VulkanFrameAccess {
1079        &mut self.access
1080    }
1081
1082    /// Commits updated synchronization values when the guard is released.
1083    pub fn commit(&mut self) {
1084        self.committed = true;
1085    }
1086}
1087
1088#[cfg(all(target_os = "linux", feature = "hwdevice"))]
1089impl Drop for VulkanFrameAccessGuard<'_> {
1090    fn drop(&mut self) {
1091        let updated = if self.committed {
1092            &raw const self.access
1093        } else {
1094            ptr::null()
1095        };
1096        // SAFETY: `begun` is this frame's begin record on this thread (the guard is not Send), and
1097        // this is the unique end call. `access_mut`'s caller vouched for `access`.
1098        unsafe { alpha2_vulkan_frame_access_end(&raw const self.begun, updated) };
1099    }
1100}
1101
1102/// One encoder-pool frame held open for a native GPU write.
1103///
1104/// Unlike a [`VulkanFrameLease`], an encoder-input frame has one owner, so it is borrowed directly.
1105/// The guard stays on the thread that began it, which holds the frame and queue mutexes.
1106#[cfg(all(target_os = "linux", feature = "hwdevice"))]
1107pub struct VulkanEncodeFrameAccess<'a> {
1108    frame: &'a mut AVFrame,
1109    // What `begin` locked, which the end call releases and checks the write-back against.
1110    begun: interop::Alpha2VulkanFrameAccess,
1111    access: VulkanFrameAccess,
1112    committed: bool,
1113    _owning_thread: std::marker::PhantomData<*const ()>,
1114}
1115
1116#[cfg(all(target_os = "linux", feature = "hwdevice"))]
1117impl<'a> VulkanEncodeFrameAccess<'a> {
1118    /// Retains the frame's buffers and hardware pool beyond this access guard.
1119    ///
1120    /// # Errors
1121    /// Returns an allocation error if `FFmpeg` cannot create the reference.
1122    pub fn retain_frame(&self) -> Result<AVFrame, BridgeError> {
1123        // SAFETY: the frame is live and locked; av_frame_clone makes an independent AVFrame.
1124        let raw = unsafe { ffi::av_frame_clone(self.frame.as_ptr()) };
1125        let raw = std::ptr::NonNull::new(raw)
1126            .ok_or(BridgeError::InvalidInput("cannot retain encode frame"))?;
1127        // SAFETY: the newly allocated frame is uniquely owned by this value.
1128        Ok(unsafe { AVFrame::from_raw(raw) })
1129    }
1130
1131    /// Opens one handoff on an encoder-pool frame.
1132    ///
1133    /// # Errors
1134    /// Returns an error when the frame is not a usable Vulkan frame.
1135    pub fn begin(frame: &'a mut AVFrame) -> Result<Self, BridgeError> {
1136        let mut access = VulkanFrameAccess::default();
1137        // SAFETY: `frame` is borrowed until the guard drops, and Drop is the unique end call.
1138        let result =
1139            unsafe { alpha2_vulkan_frame_access_begin(frame.as_mut_ptr(), &raw mut access) };
1140        if result != 0 {
1141            return Err(vulkan_frame_refusal(result));
1142        }
1143        Ok(Self {
1144            frame,
1145            begun: access.0,
1146            access,
1147            committed: false,
1148            _owning_thread: std::marker::PhantomData,
1149        })
1150    }
1151
1152    /// The frame's state while its `FFmpeg` locks are held.
1153    #[must_use]
1154    pub const fn access(&self) -> &VulkanFrameAccess {
1155        &self.access
1156    }
1157
1158    /// The record written back on [`Self::commit`], checked as in
1159    /// [`VulkanFrameAccessGuard::access_mut`].
1160    ///
1161    /// # Safety
1162    /// As for [`VulkanFrameAccessGuard::access_mut`].
1163    #[must_use]
1164    pub const unsafe fn access_mut(&mut self) -> &mut VulkanFrameAccess {
1165        &mut self.access
1166    }
1167
1168    /// Writes the updated layout and timeline values back when released.
1169    pub fn commit(&mut self) {
1170        self.committed = true;
1171    }
1172}
1173
1174#[cfg(all(target_os = "linux", feature = "hwdevice"))]
1175impl Drop for VulkanEncodeFrameAccess<'_> {
1176    fn drop(&mut self) {
1177        let updated = if self.committed {
1178            &raw const self.access
1179        } else {
1180            ptr::null()
1181        };
1182        // SAFETY: `begun` is this frame's begin record on this thread (the guard is not Send), and
1183        // this is the unique end call. `access_mut`'s caller vouched for `access`.
1184        unsafe { alpha2_vulkan_frame_access_end(&raw const self.begun, updated) };
1185    }
1186}
1187
1188/// Returns the callback used by a Vulkan hardware decoder to select its opaque format.
1189#[cfg(all(target_os = "linux", feature = "hwdevice"))]
1190#[must_use]
1191pub fn vulkan_get_format_callback()
1192-> unsafe extern "C" fn(*mut ffi::AVCodecContext, *const ffi::AVPixelFormat) -> ffi::AVPixelFormat {
1193    alpha2_vulkan_get_format
1194}
1195
1196/// Reads Vulkan image and synchronization metadata from an opaque hardware frame.
1197///
1198/// The shim takes the frame lock while copying layouts and semaphore values.
1199///
1200/// # Errors
1201/// Returns an error if the frame is not a valid Vulkan hardware frame.
1202#[cfg(all(target_os = "linux", feature = "hwdevice"))]
1203pub fn vulkan_frame_info(frame: &AVFrame) -> Result<VulkanFrameInfo, BridgeError> {
1204    let mut raw = VulkanFrameDescriptor::default();
1205    // SAFETY: `frame` is live and `raw` is a writable result; the shim checks FFmpeg's pointers
1206    // before dereferencing them.
1207    let result = unsafe { alpha2_vulkan_frame_info(frame.as_ptr(), &raw mut raw) };
1208    if result != 0 {
1209        return Err(vulkan_frame_refusal(result));
1210    }
1211    Ok(VulkanFrameInfo {
1212        hardware_format: raw.hardware_format,
1213        software_format: raw.software_format,
1214        width: raw.width,
1215        height: raw.height,
1216        coded_width: raw.coded_width,
1217        coded_height: raw.coded_height,
1218        plane_count: raw.plane_count,
1219        sampled: raw.sampled != 0,
1220        instance: raw.instance,
1221        physical_device: raw.physical_device,
1222        device: raw.device,
1223        images: raw.images,
1224        formats: raw.formats,
1225        layouts: raw.layouts,
1226        access: raw.access,
1227        semaphores: raw.semaphores,
1228        semaphore_values: raw.semaphore_values,
1229        queue_families: raw.queue_families,
1230    })
1231}
1232
1233/// Whether the loaded libavutil was built with hardware device type `kind`.
1234#[cfg(all(any(target_os = "linux", target_os = "windows"), feature = "hwdevice"))]
1235fn hwdevice_available(kind: ffi::AVHWDeviceType) -> bool {
1236    let mut each = ffi::AV_HWDEVICE_TYPE_NONE;
1237    loop {
1238        // SAFETY: av_hwdevice_iterate_types only reads FFmpeg's static table of compiled-in types.
1239        each = unsafe { ffi::av_hwdevice_iterate_types(each) };
1240        if each == ffi::AV_HWDEVICE_TYPE_NONE {
1241            return false;
1242        }
1243        if each == kind {
1244            return true;
1245        }
1246    }
1247}
1248
1249/// rsmpeg's `alloc` unwraps the null context returned for a missing type, so check the type first.
1250#[cfg(all(any(target_os = "linux", target_os = "windows"), feature = "hwdevice"))]
1251fn alloc_hwdevice(
1252    kind: ffi::AVHWDeviceType,
1253    name: &'static str,
1254) -> Result<AVHWDeviceContext, BridgeError> {
1255    check_hardware_interop()?;
1256    if !hwdevice_available(kind) {
1257        return Err(BridgeError::MissingHwDevice(name));
1258    }
1259    Ok(AVHWDeviceContext::alloc(kind))
1260}
1261
1262/// Failure returned by an operation of this crate.
1263#[derive(Debug)]
1264#[non_exhaustive]
1265pub enum BridgeError {
1266    /// The caller supplied invalid dimensions or a mismatched byte count.
1267    InvalidInput(&'static str),
1268    /// `FFmpeg` could not allocate or prepare its destination frame.
1269    Ffmpeg(RsmpegError),
1270    /// An `FFmpeg` operation returned a negative `AVERROR` code (platform GPU statuses are
1271    /// [`Self::NativeGpu`]).
1272    FfmpegCode(i32),
1273    /// A platform GPU call in a native interop helper failed.
1274    NativeGpu(NativeGpuFailure),
1275    /// The loaded `FFmpeg` runtime was built without this hardware device type.
1276    MissingHwDevice(&'static str),
1277    /// The loaded libavutil is not the release the shims were compiled for, so hardware interop
1278    /// is off; the text names both versions.
1279    RuntimeMismatch(&'static str),
1280    /// A decoded surface the GPU interop does not take, with its description and the reason.
1281    UnsupportedSurface(String),
1282}
1283
1284/// How a planar or semi-planar YCbCr pixel format stores its samples.
1285#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1286pub struct YuvPlaneLayout {
1287    /// Log2 of the horizontal chroma subsampling.
1288    pub chroma_shift_x: u8,
1289    /// Log2 of the vertical chroma subsampling.
1290    pub chroma_shift_y: u8,
1291    /// Significant bits per sample; above eight, samples are `u16`s.
1292    pub bit_depth: u8,
1293    /// Whether U and V interleave in the second plane.
1294    pub interleaved_chroma: bool,
1295    /// Whether samples sit in the high bits of their `u16`.
1296    pub msb_aligned: bool,
1297}
1298
1299impl YuvPlaneLayout {
1300    /// Bytes per stored sample.
1301    #[must_use]
1302    pub const fn bytes_per_sample(self) -> u32 {
1303        if self.bit_depth > 8 { 2 } else { 1 }
1304    }
1305}
1306
1307/// One plane of a decoded frame.
1308#[derive(Clone, Debug, Eq, PartialEq)]
1309pub struct FramePlane {
1310    /// `stride * height` fully written bytes, either a view of the frame's buffer or a packed copy.
1311    pub bytes: bytes::Bytes,
1312    /// Bytes between rows, at least the row's samples.
1313    pub stride: u32,
1314    /// Sample positions per row (a U, V pair each for interleaved chroma).
1315    pub width: u32,
1316    /// Rows.
1317    pub height: u32,
1318}
1319
1320/// The planes of a YCbCr `AVFrame`: luma first, then chroma.
1321#[derive(Clone, Debug, Eq, PartialEq)]
1322pub struct YuvPlanes {
1323    /// How the planes store their samples.
1324    pub layout: YuvPlaneLayout,
1325    /// Coded luma width.
1326    pub width: u32,
1327    /// Coded luma height.
1328    pub height: u32,
1329    /// Luma, then U and V, or one interleaved chroma plane.
1330    pub planes: Vec<FramePlane>,
1331}
1332
1333impl fmt::Display for BridgeError {
1334    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1335        match self {
1336            Self::InvalidInput(context) => {
1337                write!(formatter, "invalid media buffer input: {context}")
1338            }
1339            Self::Ffmpeg(error) => write!(formatter, "{error}"),
1340            Self::FfmpegCode(code) => write!(formatter, "{}", RsmpegError::AVError(*code)),
1341            Self::NativeGpu(failure) => write!(formatter, "{failure}"),
1342            Self::MissingHwDevice(kind) => {
1343                write!(formatter, "the loaded FFmpeg has no {kind} hardware device")
1344            }
1345            Self::UnsupportedSurface(description) => formatter.write_str(description),
1346            Self::RuntimeMismatch(reason) => formatter.write_str(reason),
1347        }
1348    }
1349}
1350
1351/// Applies explicit matrix and range coefficients to a scaling context.
1352///
1353/// Coefficient arguments are `SWS_CS_*` constants. RGB endpoints still need
1354/// an explicit full-range flag.
1355fn configure_colorspace(
1356    context: &mut SwsContext,
1357    source_coefficients: i32,
1358    source_full_range: bool,
1359    destination_coefficients: i32,
1360    destination_full_range: bool,
1361) -> Result<(), BridgeError> {
1362    // SAFETY: the context is live and exclusively borrowed; both coefficient pointers refer to
1363    // static arrays owned by `libswscale`.
1364    let result = unsafe {
1365        ffi::sws_setColorspaceDetails(
1366            context.as_mut_ptr(),
1367            ffi::sws_getCoefficients(source_coefficients),
1368            i32::from(source_full_range),
1369            ffi::sws_getCoefficients(destination_coefficients),
1370            i32::from(destination_full_range),
1371            0,
1372            1 << 16,
1373            1 << 16,
1374        )
1375    };
1376    if result < 0 {
1377        Err(BridgeError::FfmpegCode(result))
1378    } else {
1379        Ok(())
1380    }
1381}
1382
1383/// Row alignment in bytes of every `sws_scale` destination, the widest SIMD store (16 RGBA pixels).
1384const SCALER_DESTINATION_ALIGN: i32 = 64;
1385
1386/// Converts frames of one size and pixel format into another pixel format at the same size.
1387///
1388/// `sws_scale` writes only into this type's own frame, with rows padded to 64 bytes and zero
1389/// filled, because some converters write whole blocks past a row's last pixel or skip the last
1390/// columns.
1391pub struct PackedScaler {
1392    context: SwsContext,
1393    width: i32,
1394    height: i32,
1395    source: ffi::AVPixelFormat,
1396    target: ffi::AVPixelFormat,
1397    destination: AVFrame,
1398}
1399
1400impl PackedScaler {
1401    /// A scaler from `source` to `target` at `width`x`height`, with bilinear filtering.
1402    ///
1403    /// # Errors
1404    /// Returns an error when `libswscale` has no conversion between the formats or a frame of that
1405    /// size cannot be allocated.
1406    pub fn new(
1407        width: i32,
1408        height: i32,
1409        source: ffi::AVPixelFormat,
1410        target: ffi::AVPixelFormat,
1411    ) -> Result<Self, BridgeError> {
1412        if width <= 0 || height <= 0 {
1413            return Err(BridgeError::InvalidInput("scaler size is not positive"));
1414        }
1415        let context = SwsContext::get_context(
1416            width,
1417            height,
1418            source,
1419            width,
1420            height,
1421            target,
1422            scaler_flags(width, height, source, target),
1423            None,
1424            None,
1425            None,
1426        )
1427        .ok_or(BridgeError::InvalidInput(
1428            "libswscale has no conversion between these pixel formats",
1429        ))?;
1430        let destination = padded_zeroed_frame(width, height, target)?;
1431        Ok(Self {
1432            context,
1433            width,
1434            height,
1435            source,
1436            target,
1437            destination,
1438        })
1439    }
1440
1441    /// Applies explicit matrix and range coefficients (`SWS_CS_*` constants) to the conversion.
1442    /// RGB endpoints still need an explicit full-range flag.
1443    ///
1444    /// # Errors
1445    /// Returns an error when `libswscale` rejects the configuration.
1446    pub fn configure_colorspace(
1447        &mut self,
1448        source_coefficients: i32,
1449        source_full_range: bool,
1450        destination_coefficients: i32,
1451        destination_full_range: bool,
1452    ) -> Result<(), BridgeError> {
1453        configure_colorspace(
1454            &mut self.context,
1455            source_coefficients,
1456            source_full_range,
1457            destination_coefficients,
1458            destination_full_range,
1459        )
1460    }
1461
1462    /// Converts `frame` and returns the target's planes packed without row padding, in plane
1463    /// order (the `av_image_copy_to_buffer` layout at alignment 1).
1464    ///
1465    /// # Errors
1466    /// Returns `InvalidInput` for a frame of another size or format than the scaler's, and an
1467    /// error when `libswscale` fails.
1468    pub fn convert(&mut self, frame: &AVFrame) -> Result<Vec<u8>, BridgeError> {
1469        self.check_source(frame)?;
1470        scale_into(&mut self.context, frame, &mut self.destination, self.height)?;
1471        // SAFETY: a pure size computation over plain values.
1472        let size =
1473            unsafe { ffi::av_image_get_buffer_size(self.target, self.width, self.height, 1) };
1474        let len = usize::try_from(size).map_err(|_| BridgeError::FfmpegCode(size))?;
1475        let mut packed = vec![0_u8; len];
1476        // SAFETY: `packed` holds exactly `size` bytes, and the destination frame's planes hold
1477        // `height` rows of the target format at their linesizes.
1478        let copied = unsafe {
1479            ffi::av_image_copy_to_buffer(
1480                packed.as_mut_ptr(),
1481                size,
1482                self.destination.data.as_ptr().cast(),
1483                self.destination.linesize.as_ptr(),
1484                self.target,
1485                self.width,
1486                self.height,
1487                1,
1488            )
1489        };
1490        if copied < 0 {
1491            return Err(BridgeError::FfmpegCode(copied));
1492        }
1493        Ok(packed)
1494    }
1495
1496    /// Converts `frame` into a new frame of the target format with padded rows, for an encoder
1497    /// that keeps references to its input.
1498    ///
1499    /// # Errors
1500    /// As [`Self::convert`], and when the new frame cannot be allocated.
1501    pub fn convert_to_frame(&mut self, frame: &AVFrame) -> Result<AVFrame, BridgeError> {
1502        self.check_source(frame)?;
1503        let mut output = padded_zeroed_frame(self.width, self.height, self.target)?;
1504        scale_into(&mut self.context, frame, &mut output, self.height)?;
1505        Ok(output)
1506    }
1507
1508    fn check_source(&self, frame: &AVFrame) -> Result<(), BridgeError> {
1509        if frame.width != self.width || frame.height != self.height || frame.format != self.source {
1510            return Err(BridgeError::InvalidInput(
1511                "frame size or format differs from the scaler's",
1512            ));
1513        }
1514        Ok(())
1515    }
1516}
1517
1518impl fmt::Debug for PackedScaler {
1519    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1520        formatter
1521            .debug_struct("PackedScaler")
1522            .field("width", &self.width)
1523            .field("height", &self.height)
1524            .field("source", &self.source)
1525            .field("target", &self.target)
1526            .finish_non_exhaustive()
1527    }
1528}
1529
1530/// Bilinear, plus accurate rounding where `libswscale` would otherwise pick its unscaled
1531/// 4:2:0/4:2:2-to-RGB converter for an odd width: its C version never writes the last column.
1532fn scaler_flags(
1533    width: i32,
1534    height: i32,
1535    source: ffi::AVPixelFormat,
1536    target: ffi::AVPixelFormat,
1537) -> ffi::SwsFlags {
1538    let unscaled_rgb_source = matches!(
1539        source,
1540        ffi::AV_PIX_FMT_YUV420P | ffi::AV_PIX_FMT_YUV422P | ffi::AV_PIX_FMT_YUVA420P
1541    );
1542    // SAFETY: `av_pix_fmt_desc_get` accepts any value and returns null or a static descriptor.
1543    let rgb_target = unsafe { ffi::av_pix_fmt_desc_get(target).as_ref() }
1544        .is_some_and(|descriptor| descriptor.flags & u64::from(ffi::AV_PIX_FMT_FLAG_RGB) != 0);
1545    if unscaled_rgb_source && rgb_target && height % 2 == 0 && width % 2 == 1 {
1546        ffi::SWS_BILINEAR | ffi::SWS_ACCURATE_RND
1547    } else {
1548        ffi::SWS_BILINEAR
1549    }
1550}
1551
1552/// A frame of `format` with rows aligned to [`SCALER_DESTINATION_ALIGN`], every byte zero.
1553fn padded_zeroed_frame(
1554    width: i32,
1555    height: i32,
1556    format: ffi::AVPixelFormat,
1557) -> Result<AVFrame, BridgeError> {
1558    let mut frame = AVFrame::new();
1559    frame.set_format(format);
1560    frame.set_width(width);
1561    frame.set_height(height);
1562    frame.get_buffer(SCALER_DESTINATION_ALIGN)?;
1563    for buffer in frame.buf {
1564        // SAFETY: a non-null `AVFrame::buf` entry is live, and this new frame is its only owner.
1565        if let Some(buffer) = unsafe { buffer.as_ref() } {
1566            // SAFETY: as above.
1567            unsafe { ptr::write_bytes(buffer.data, 0, buffer.size) };
1568        }
1569    }
1570    Ok(frame)
1571}
1572
1573/// The workspace's only `sws_scale` call. `destination` is a frame from [`padded_zeroed_frame`]
1574/// of the context's target format and size.
1575fn scale_into(
1576    context: &mut SwsContext,
1577    source: &AVFrame,
1578    destination: &mut AVFrame,
1579    height: i32,
1580) -> Result<(), BridgeError> {
1581    // SAFETY: the context is exclusively borrowed and was made for this size and both formats,
1582    // the source planes belong to the live `source`, and the destination planes belong to a frame
1583    // this crate allocated for the target format and size with padded rows.
1584    let rows = unsafe {
1585        ffi::sws_scale(
1586            context.as_mut_ptr(),
1587            source.data.as_ptr().cast(),
1588            source.linesize.as_ptr(),
1589            0,
1590            height,
1591            destination.data.as_ptr().cast(),
1592            destination.linesize.as_ptr(),
1593        )
1594    };
1595    if rows < 0 {
1596        return Err(BridgeError::FfmpegCode(rows));
1597    }
1598    if rows != height {
1599        return Err(BridgeError::InvalidInput(
1600            "libswscale wrote fewer rows than the frame has",
1601        ));
1602    }
1603    Ok(())
1604}
1605
1606impl Error for BridgeError {}
1607
1608impl BridgeError {
1609    /// The device fault a failed platform GPU call's status names, if any.
1610    #[must_use]
1611    pub const fn gpu_fault(&self) -> Option<GpuFault> {
1612        match self {
1613            Self::NativeGpu(failure) => failure.fault,
1614            _ => None,
1615        }
1616    }
1617}
1618
1619/// The graphics API a native interop helper called.
1620#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1621pub enum NativeGpuBackend {
1622    /// Vulkan; the status is a `VkResult`.
1623    Vulkan,
1624    /// Direct3D 12; the status is an `HRESULT`.
1625    D3D12,
1626    /// Metal through `CoreVideo`; the status is a `CVReturn`.
1627    Metal,
1628}
1629
1630impl NativeGpuBackend {
1631    /// The API's name.
1632    #[must_use]
1633    pub const fn as_str(self) -> &'static str {
1634        match self {
1635            Self::Vulkan => "Vulkan",
1636            Self::D3D12 => "D3D12",
1637            Self::Metal => "Metal",
1638        }
1639    }
1640}
1641
1642/// A platform GPU call that failed inside a native interop helper.
1643///
1644/// Classify by `fault`, which the backend reads from `status`, not by the message.
1645#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1646pub struct NativeGpuFailure {
1647    /// The API the call belongs to.
1648    pub backend: NativeGpuBackend,
1649    /// What the helper was doing, such as `encode copy`.
1650    pub operation: &'static str,
1651    /// The step of it that failed, such as `queue submit`.
1652    pub step: &'static str,
1653    /// A `VkResult`, `HRESULT` bits, or `CVReturn`; zero when the helper's own check failed.
1654    pub status: i32,
1655    /// What the status is evidence of, when it names a fault.
1656    pub fault: Option<GpuFault>,
1657}
1658
1659impl fmt::Display for NativeGpuFailure {
1660    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1661        let Self {
1662            backend,
1663            operation,
1664            step,
1665            status,
1666            ..
1667        } = *self;
1668        let backend = backend.as_str();
1669        // Use the renderer's timeout sentence so a hung GPU reads the same everywhere.
1670        if self.fault == Some(GpuFault::Timeout) {
1671            write!(
1672                formatter,
1673                "{backend} {operation} ({step}): {}",
1674                alpha2_media::GPU_TIMEOUT_MESSAGE
1675            )?;
1676        } else {
1677            write!(formatter, "{backend} {operation} failed at {step}")?;
1678        }
1679        if status == 0 {
1680            return Ok(());
1681        }
1682        match self.backend {
1683            NativeGpuBackend::Vulkan => write!(formatter, " (VkResult {status})"),
1684            NativeGpuBackend::D3D12 => write!(formatter, " (HRESULT {status:#010X})"),
1685            NativeGpuBackend::Metal => write!(formatter, " (CVReturn {status})"),
1686        }
1687    }
1688}
1689
1690impl From<RsmpegError> for BridgeError {
1691    fn from(error: RsmpegError) -> Self {
1692        Self::Ffmpeg(error)
1693    }
1694}
1695
1696unsafe extern "C" {
1697    fn alpha2_ffmpeg_shim_avutil_version() -> std::ffi::c_uint;
1698}
1699
1700/// Why hardware interop is off in this process, or `None` when the loaded libavutil has the
1701/// major and minor version the shims were compiled against.
1702///
1703/// The shims read `FFmpeg` structures at offsets of one minor release, so every hardware device
1704/// constructor of this crate refuses with [`BridgeError::RuntimeMismatch`] while this is `Some`.
1705#[must_use]
1706pub fn hardware_interop_refusal() -> Option<&'static str> {
1707    static REFUSAL: std::sync::OnceLock<Option<String>> = std::sync::OnceLock::new();
1708    REFUSAL
1709        .get_or_init(|| {
1710            // SAFETY: returns a constant compiled into the shim.
1711            let compiled = unsafe { alpha2_ffmpeg_shim_avutil_version() };
1712            // SAFETY: a pure query of the loaded library.
1713            let loaded = unsafe { ffi::avutil_version() };
1714            interop_version_refusal(compiled, loaded)
1715        })
1716        .as_deref()
1717}
1718
1719/// Refuses interop across a major or minor `AV_VERSION_INT` difference; micro versions may differ.
1720fn interop_version_refusal(compiled: u32, loaded: u32) -> Option<String> {
1721    let version = |value: u32| format!("{}.{}.{}", value >> 16, (value >> 8) & 0xff, value & 0xff);
1722    (compiled >> 8 != loaded >> 8).then(|| {
1723        format!(
1724            "hardware interop is off: the FFmpeg shims were compiled for libavutil {} and the \
1725             loaded libavutil is {}",
1726            version(compiled),
1727            version(loaded)
1728        )
1729    })
1730}
1731
1732/// The refusal of [`hardware_interop_refusal`] as an error.
1733///
1734/// # Errors
1735/// Returns [`BridgeError::RuntimeMismatch`] when the loaded libavutil is another minor release.
1736pub fn check_hardware_interop() -> Result<(), BridgeError> {
1737    hardware_interop_refusal().map_or(Ok(()), |reason| Err(BridgeError::RuntimeMismatch(reason)))
1738}
1739
1740/// Returns the linked `FFmpeg` runtime version string.
1741#[must_use]
1742pub fn runtime_version() -> String {
1743    // SAFETY: FFmpeg returns a process-lifetime, NUL-terminated string.
1744    unsafe { CStr::from_ptr(ffi::av_version_info()) }
1745        .to_string_lossy()
1746        .into_owned()
1747}
1748
1749/// Returns the linked libavcodec configure string.
1750#[must_use]
1751pub fn runtime_configuration() -> String {
1752    // SAFETY: FFmpeg returns a process-lifetime, NUL-terminated string.
1753    unsafe { CStr::from_ptr(ffi::avcodec_configuration()) }
1754        .to_string_lossy()
1755        .into_owned()
1756}
1757
1758/// Whether muxer `format` can store `codec` at normal compliance; `None` when it is not linked.
1759#[must_use]
1760pub fn muxer_accepts_codec(format: &CStr, codec: ffi::AVCodecID) -> Option<bool> {
1761    // SAFETY: `format` is NUL-terminated; FFmpeg returns a registered, process-lifetime muxer
1762    // or null.
1763    let muxer = unsafe { ffi::av_guess_format(format.as_ptr(), ptr::null(), ptr::null()) };
1764    if muxer.is_null() {
1765        return None;
1766    }
1767    // SAFETY: `muxer` is the live registered muxer found above.
1768    let accepted = unsafe {
1769        ffi::avformat_query_codec(
1770            muxer,
1771            codec,
1772            i32::try_from(ffi::FF_COMPLIANCE_NORMAL).unwrap_or(0),
1773        )
1774    };
1775    Some(accepted == 1)
1776}
1777
1778/// Chroma layout, component depth, and alpha of one pixel format.
1779#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1780pub struct SampleProfile {
1781    /// Whether the format is planar/semi-planar YCbCr with 4:2:0 subsampling.
1782    pub is_yuv_420: bool,
1783    /// Largest component depth in bits.
1784    pub bit_depth: u8,
1785    /// Whether the format carries an alpha component.
1786    pub has_alpha: bool,
1787    /// Whether the components are RGB (palettes included) rather than luma and chroma or gray.
1788    pub is_rgb: bool,
1789}
1790
1791/// Describes a pixel format, or `None` when the value has no descriptor.
1792///
1793/// A stream's format may be unset until the first frame decodes, so `None` means "not yet known".
1794#[must_use]
1795pub fn sample_profile(format: ffi::AVPixelFormat) -> Option<SampleProfile> {
1796    if format == ffi::AV_PIX_FMT_NONE {
1797        return None;
1798    }
1799    // SAFETY: `av_pix_fmt_desc_get` accepts any value and returns null or a static descriptor.
1800    let descriptor = unsafe { ffi::av_pix_fmt_desc_get(format).as_ref() }?;
1801    let components = usize::from(descriptor.nb_components.min(4));
1802    Some(SampleProfile {
1803        is_yuv_420: descriptor.log2_chroma_w == 1
1804            && descriptor.log2_chroma_h == 1
1805            && descriptor.nb_components >= 3
1806            && descriptor.flags & u64::from(ffi::AV_PIX_FMT_FLAG_RGB) == 0,
1807        bit_depth: descriptor.comp[..components]
1808            .iter()
1809            .map(|component| u8::try_from(component.depth).unwrap_or(u8::MAX))
1810            .max()
1811            .unwrap_or(8),
1812        has_alpha: descriptor.flags & u64::from(ffi::AV_PIX_FMT_FLAG_ALPHA) != 0,
1813        is_rgb: descriptor.flags & u64::from(ffi::AV_PIX_FMT_FLAG_RGB | ffi::AV_PIX_FMT_FLAG_PAL)
1814            != 0,
1815    })
1816}
1817
1818/// Returns `FFmpeg`'s stable name for a pixel-format value.
1819#[must_use]
1820pub fn pixel_format_name(format: ffi::AVPixelFormat) -> Option<String> {
1821    // SAFETY: `av_get_pix_fmt_name` accepts any value and returns null or a static C string.
1822    let name = unsafe { ffi::av_get_pix_fmt_name(format) };
1823    if name.is_null() {
1824        None
1825    } else {
1826        // SAFETY: non-null return values obey the FFmpeg string contract above.
1827        Some(
1828            unsafe { CStr::from_ptr(name) }
1829                .to_string_lossy()
1830                .into_owned(),
1831        )
1832    }
1833}
1834
1835/// Opens `context` with `options`, returning what `FFmpeg` did not consume.
1836///
1837/// `avcodec_open2` frees the dictionary and writes the remainder back on failure as well as
1838/// success. rsmpeg's `AVCodecContext::open` double-frees it on failure, which would abort an
1839/// encoder fallback.
1840///
1841/// # Errors
1842/// Returns the `FFmpeg` status when the encoder or decoder cannot be opened.
1843pub fn open_codec_context(
1844    context: &mut rsmpeg::avcodec::AVCodecContext,
1845    options: rsmpeg::avutil::AVDictionary,
1846) -> Result<Option<rsmpeg::avutil::AVDictionary>, RsmpegError> {
1847    let _media_foundation = media_foundation_lock(context);
1848    let mut dictionary = options.into_raw().as_ptr();
1849    // SAFETY: `context` is live and FFmpeg owns `dictionary`, replacing it with a null or owned
1850    // remainder.
1851    let status = unsafe {
1852        ffi::avcodec_open2(
1853            context.as_mut_ptr(),
1854            ptr::null_mut(),
1855            std::ptr::addr_of_mut!(dictionary),
1856        )
1857    };
1858    // SAFETY: a non-null remainder is a dictionary FFmpeg handed back; this is its only owner.
1859    let unused = ptr::NonNull::new(dictionary)
1860        .map(|dictionary| unsafe { rsmpeg::avutil::AVDictionary::from_raw(dictionary) });
1861    if status < 0 {
1862        return Err(RsmpegError::from(status));
1863    }
1864    Ok(unused)
1865}
1866
1867/// Serializes opening and closing `MediaFoundation` (`_mf`) encoders; `None` for other codecs.
1868///
1869/// `MFTEnumEx` (on open) and `MFShutdown` (on close) take mfplat's critical section and the
1870/// work-queue lock in opposite orders and deadlock across threads, whatever the `MFStartup` count.
1871fn media_foundation_lock(
1872    context: &rsmpeg::avcodec::AVCodecContext,
1873) -> Option<std::sync::MutexGuard<'static, ()>> {
1874    static LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
1875    if !cfg!(target_os = "windows") || context.codec.is_null() {
1876        return None;
1877    }
1878    // SAFETY: a non-null `codec` is a static codec descriptor with a static C-string `name`.
1879    let name = unsafe { CStr::from_ptr((*context.codec).name) };
1880    name.to_bytes().ends_with(b"_mf").then(|| {
1881        LOCK.lock()
1882            .unwrap_or_else(std::sync::PoisonError::into_inner)
1883    })
1884}
1885
1886/// An [`AVCodecContext`] closed under the `MediaFoundation` lock when it is an `_mf` encoder.
1887///
1888/// [`AVCodecContext`]: rsmpeg::avcodec::AVCodecContext
1889pub struct EncoderContext(Option<rsmpeg::avcodec::AVCodecContext>);
1890
1891impl From<rsmpeg::avcodec::AVCodecContext> for EncoderContext {
1892    fn from(context: rsmpeg::avcodec::AVCodecContext) -> Self {
1893        Self(Some(context))
1894    }
1895}
1896
1897impl std::ops::Deref for EncoderContext {
1898    type Target = rsmpeg::avcodec::AVCodecContext;
1899
1900    fn deref(&self) -> &Self::Target {
1901        self.0.as_ref().expect("taken only when dropped")
1902    }
1903}
1904
1905impl std::ops::DerefMut for EncoderContext {
1906    fn deref_mut(&mut self) -> &mut Self::Target {
1907        self.0.as_mut().expect("taken only when dropped")
1908    }
1909}
1910
1911impl Drop for EncoderContext {
1912    fn drop(&mut self) {
1913        if let Some(context) = self.0.take() {
1914            let _media_foundation = media_foundation_lock(&context);
1915            drop(context);
1916        }
1917    }
1918}
1919
1920/// `VkImageUsageFlags` an encoder-input pool needs beyond `FFmpeg`'s own.
1921///
1922/// `TRANSFER_DST` for the renderer's copy, `SAMPLED` for wgpu import, `TRANSFER_SRC` for readback
1923/// checks, `VIDEO_ENCODE_SRC` for the encoder.
1924#[cfg(all(target_os = "linux", feature = "hwdevice"))]
1925pub const VULKAN_ENCODE_INPUT_USAGE: u32 = 0x0000_0001 | 0x0000_0002 | 0x0000_0004 | 0x0000_4000;
1926
1927/// Adds `usage` to a Vulkan frames context before it allocates its pool.
1928///
1929/// Left at zero, `hwcontext_vulkan` picks a default that requires `STORAGE` support. A nonzero
1930/// usage is used exactly as given, so every flag must be supported by the format; encoder-input
1931/// pools ask for [`VULKAN_ENCODE_INPUT_USAGE`]. Call between `av_hwframe_ctx_alloc` and
1932/// `av_hwframe_ctx_init`.
1933///
1934/// # Errors
1935/// Returns an error when the context is not a Vulkan one.
1936#[cfg(all(target_os = "linux", feature = "hwdevice"))]
1937pub fn vulkan_frames_add_usage(
1938    frames: &mut rsmpeg::avutil::AVHWFramesContext,
1939    usage: u32,
1940) -> Result<(), BridgeError> {
1941    // SAFETY: `frames` is live; the shim checks the device type and only ORs into `usage`.
1942    let status = unsafe { alpha2_vulkan_frames_add_usage(frames.as_mut_ptr(), usage) };
1943    if status < 0 {
1944        return Err(BridgeError::FfmpegCode(status));
1945    }
1946    Ok(())
1947}
1948
1949/// Usage the pool was created with, including the default `FFmpeg` picks for zero.
1950#[cfg(all(target_os = "linux", feature = "hwdevice"))]
1951#[must_use]
1952pub fn vulkan_frames_usage(frames: &rsmpeg::avutil::AVHWFramesContext) -> u32 {
1953    // SAFETY: `frames` is live; the shim checks the device type before reading `hwctx`.
1954    unsafe { alpha2_vulkan_frames_usage(frames.as_ptr()) }
1955}
1956
1957/// Copies one packet's payload out of `FFmpeg`'s buffer.
1958#[must_use]
1959pub fn packet_bytes(packet: &rsmpeg::avcodec::AVPacket) -> Vec<u8> {
1960    let size = usize::try_from(packet.size).unwrap_or(0);
1961    if packet.data.is_null() || size == 0 {
1962        return Vec::new();
1963    }
1964    // SAFETY: the borrowed packet owns `size` readable bytes at `data`.
1965    unsafe { slice::from_raw_parts(packet.data.cast_const(), size) }.to_vec()
1966}
1967
1968/// A copy of a stream's codec extradata (parameter sets for H.264 and HEVC).
1969///
1970/// Takes rsmpeg's wrapper because a bare `AVCodecParameters` can carry a forged pointer:
1971///
1972/// ```compile_fail,E0308
1973/// let mut forged: rsmpeg::ffi::AVCodecParameters = *rsmpeg::avcodec::AVCodecParameters::new();
1974/// forged.extradata = 0x10 as *mut u8;
1975/// forged.extradata_size = 64;
1976/// alpha2_ffmpeg_bridge::codec_parameters_extradata(&forged);
1977/// ```
1978#[must_use]
1979pub fn codec_parameters_extradata(parameters: &rsmpeg::avcodec::AVCodecParameters) -> Vec<u8> {
1980    let size = usize::try_from(parameters.extradata_size).unwrap_or(0);
1981    if parameters.extradata.is_null() || size == 0 {
1982        return Vec::new();
1983    }
1984    // SAFETY: the borrowed parameters own `extradata_size` readable bytes at `extradata`.
1985    unsafe { slice::from_raw_parts(parameters.extradata.cast_const(), size) }.to_vec()
1986}
1987
1988/// Whether `packet` carries side data of `kind`.
1989#[must_use]
1990pub fn packet_has_side_data(
1991    packet: &rsmpeg::avcodec::AVPacket,
1992    kind: ffi::AVPacketSideDataType,
1993) -> bool {
1994    let mut size = 0_usize;
1995    // SAFETY: `packet` is live; the result is only compared with null.
1996    !unsafe { ffi::av_packet_get_side_data(packet.as_ptr(), kind, &raw mut size) }.is_null()
1997}
1998
1999/// Removes and returns `packet`'s side data of `kind`.
2000///
2001/// Encoder parameter sets must be taken off, not copied, or the MP4 muxer reads them as a sample
2002/// description change.
2003#[must_use]
2004pub fn take_packet_side_data(
2005    packet: &mut rsmpeg::avcodec::AVPacket,
2006    kind: ffi::AVPacketSideDataType,
2007) -> Option<Vec<u8>> {
2008    let mut size = 0_usize;
2009    // SAFETY: `packet` is live; a non-null result points at `size` bytes the packet owns.
2010    let data = unsafe { ffi::av_packet_get_side_data(packet.as_ptr(), kind, &raw mut size) };
2011    if data.is_null() {
2012        return None;
2013    }
2014    // SAFETY: as above; the bytes are copied before the entry is freed below.
2015    let bytes = unsafe { slice::from_raw_parts(data, size) }.to_vec();
2016    let packet = packet.as_mut_ptr();
2017    // SAFETY: `side_data` and `side_data_elems` are the packet's own array and count, which
2018    // `av_packet_side_data_remove` keeps consistent while freeing the `av_malloc`ed entry.
2019    unsafe {
2020        ffi::av_packet_side_data_remove(
2021            (*packet).side_data,
2022            &raw mut (*packet).side_data_elems,
2023            kind,
2024        );
2025    }
2026    Some(bytes)
2027}
2028
2029/// Gives `packet` side data of `kind` holding `data`, replacing any it had.
2030///
2031/// # Errors
2032/// When the side data cannot be allocated or `data` is too large.
2033pub fn set_packet_side_data(
2034    packet: &mut rsmpeg::avcodec::AVPacket,
2035    kind: ffi::AVPacketSideDataType,
2036    data: &[u8],
2037) -> Result<(), BridgeError> {
2038    let _ = take_packet_side_data(packet, kind);
2039    // SAFETY: `packet` is mutably borrowed; `av_packet_new_side_data` returns null or a padded
2040    // entry of `data.len()` bytes.
2041    let entry = unsafe { ffi::av_packet_new_side_data(packet.as_mut_ptr(), kind, data.len()) };
2042    if entry.is_null() {
2043        return Err(BridgeError::FfmpegCode(ffi::AVERROR(ffi::ENOMEM)));
2044    }
2045    // SAFETY: the entry just made holds `data.len()` writable bytes.
2046    unsafe { ptr::copy_nonoverlapping(data.as_ptr(), entry, data.len()) };
2047    Ok(())
2048}
2049
2050/// Replaces the extradata of `output`'s stream `index` before the header is written.
2051///
2052/// rsmpeg exposes an output's streams read-only. `FFmpeg` needs padded `av_malloc` memory here, not
2053/// a Rust buffer.
2054///
2055/// # Errors
2056/// When there is no stream `index`, or `data` is too large or cannot be allocated.
2057pub fn set_output_stream_extradata(
2058    output: &mut rsmpeg::avformat::AVFormatContextOutput,
2059    index: usize,
2060    data: &[u8],
2061) -> Result<(), BridgeError> {
2062    let parameters = output
2063        .streams()
2064        .get(index)
2065        .ok_or(BridgeError::InvalidInput("the output has no such stream"))?
2066        .codecpar;
2067    let size = i32::try_from(data.len())
2068        .map_err(|_| BridgeError::InvalidInput("extradata is larger than FFmpeg holds"))?;
2069    let padding = usize::try_from(ffi::AV_INPUT_BUFFER_PADDING_SIZE).unwrap_or(64);
2070    // SAFETY: `av_mallocz` returns null or a zeroed buffer of the size asked for.
2071    let buffer = unsafe { ffi::av_mallocz(data.len() + padding) }.cast::<u8>();
2072    if buffer.is_null() {
2073        return Err(BridgeError::FfmpegCode(ffi::AVERROR(ffi::ENOMEM)));
2074    }
2075    // SAFETY: `buffer` holds `data.len()` writable bytes and does not overlap `data`.
2076    unsafe { ptr::copy_nonoverlapping(data.as_ptr(), buffer, data.len()) };
2077    // SAFETY: the stream owns its codec parameters and the output is mutably borrowed. The old
2078    // extradata is null or `av_malloc`ed and is freed; the parameters now own `buffer`.
2079    unsafe {
2080        ffi::av_freep((&raw mut (*parameters).extradata).cast());
2081        (*parameters).extradata = buffer;
2082        (*parameters).extradata_size = size;
2083    }
2084    Ok(())
2085}
2086
2087/// A packet holding a copy of `data`, every other field at its default.
2088///
2089/// # Errors
2090/// When `data` is too large or the packet cannot be allocated.
2091pub fn packet_from_bytes(data: &[u8]) -> Result<rsmpeg::avcodec::AVPacket, BridgeError> {
2092    let size = i32::try_from(data.len())
2093        .map_err(|_| BridgeError::InvalidInput("a packet is larger than FFmpeg holds"))?;
2094    let mut packet = rsmpeg::avcodec::AVPacket::new();
2095    // SAFETY: `packet` is fresh and empty; `av_new_packet` gives it a padded buffer or fails.
2096    let status = unsafe { ffi::av_new_packet(packet.as_mut_ptr(), size) };
2097    if status < 0 {
2098        return Err(BridgeError::FfmpegCode(status));
2099    }
2100    if !data.is_empty() {
2101        // SAFETY: the packet's buffer holds `size` writable bytes and does not overlap `data`.
2102        unsafe { ptr::copy_nonoverlapping(data.as_ptr(), packet.data, data.len()) };
2103    }
2104    Ok(packet)
2105}
2106
2107/// Replaces `packet`'s payload with `data`, no longer than it, keeping timestamps and side data.
2108///
2109/// # Errors
2110/// When `data` is longer than the payload or the buffer cannot be made writable.
2111pub fn shrink_packet_to(
2112    packet: &mut rsmpeg::avcodec::AVPacket,
2113    data: &[u8],
2114) -> Result<(), BridgeError> {
2115    let size = i32::try_from(data.len())
2116        .ok()
2117        .filter(|size| *size <= packet.size)
2118        .ok_or(BridgeError::InvalidInput("a packet cannot grow in place"))?;
2119    // SAFETY: `packet` is live; `av_packet_make_writable` gives it an unshared buffer of its size.
2120    let status = unsafe { ffi::av_packet_make_writable(packet.as_mut_ptr()) };
2121    if status < 0 {
2122        return Err(BridgeError::FfmpegCode(status));
2123    }
2124    if !data.is_empty() {
2125        // SAFETY: the writable buffer holds at least `data.len()` bytes and cannot overlap `data`.
2126        unsafe { ptr::copy_nonoverlapping(data.as_ptr(), packet.data, data.len()) };
2127    }
2128    // SAFETY: `size` is not above the packet's size; FFmpeg zeroes the padding after it.
2129    unsafe { ffi::av_shrink_packet(packet.as_mut_ptr(), size) };
2130    Ok(())
2131}
2132
2133/// Codec parameters for a video stream not produced by an `FFmpeg` encoder.
2134#[derive(Clone, Copy, Debug)]
2135pub struct VideoStreamDescription<'a> {
2136    /// The codec.
2137    pub codec_id: ffi::AVCodecID,
2138    /// Coded width.
2139    pub width: i32,
2140    /// Coded height.
2141    pub height: i32,
2142    /// The pixel format the stream decodes to.
2143    pub pixel_format: ffi::AVPixelFormat,
2144    /// `AV_PROFILE_*` for the codec.
2145    pub profile: i32,
2146    /// The codec's level number.
2147    pub level: i32,
2148    /// Colour primaries tag.
2149    pub color_primaries: ffi::AVColorPrimaries,
2150    /// Transfer characteristics tag.
2151    pub color_trc: ffi::AVColorTransferCharacteristic,
2152    /// Matrix coefficients tag.
2153    pub color_space: ffi::AVColorSpace,
2154    /// Sample range.
2155    pub color_range: ffi::AVColorRange,
2156    /// Pixel aspect ratio; `0/1` when undeclared.
2157    pub sample_aspect_ratio: ffi::AVRational,
2158    /// Frames per second.
2159    pub frame_rate: ffi::AVRational,
2160    /// Average bitrate, `0` when unknown.
2161    pub bit_rate: i64,
2162    /// The sample description (`avcC` for H.264).
2163    pub extradata: &'a [u8],
2164}
2165
2166/// Codec parameters for a video stream `description` describes.
2167///
2168/// # Errors
2169/// When the extradata is larger than `FFmpeg` holds or cannot be allocated.
2170pub fn video_codec_parameters(
2171    description: &VideoStreamDescription<'_>,
2172) -> Result<rsmpeg::avcodec::AVCodecParameters, BridgeError> {
2173    let extradata_size = i32::try_from(description.extradata.len())
2174        .map_err(|_| BridgeError::InvalidInput("extradata is larger than FFmpeg holds"))?;
2175    let mut parameters = rsmpeg::avcodec::AVCodecParameters::new();
2176    let raw = parameters.as_mut_ptr();
2177    // SAFETY: `raw` is freshly allocated and uniquely owned; the fields are plain values.
2178    unsafe {
2179        (*raw).codec_type = ffi::AVMEDIA_TYPE_VIDEO;
2180        (*raw).codec_id = description.codec_id;
2181        (*raw).width = description.width;
2182        (*raw).height = description.height;
2183        (*raw).format = description.pixel_format;
2184        (*raw).profile = description.profile;
2185        (*raw).level = description.level;
2186        (*raw).color_primaries = description.color_primaries;
2187        (*raw).color_trc = description.color_trc;
2188        (*raw).color_space = description.color_space;
2189        (*raw).color_range = description.color_range;
2190        (*raw).sample_aspect_ratio = description.sample_aspect_ratio;
2191        (*raw).framerate = description.frame_rate;
2192        (*raw).bit_rate = description.bit_rate;
2193        (*raw).field_order = ffi::AV_FIELD_PROGRESSIVE;
2194    }
2195    if !description.extradata.is_empty() {
2196        let padding = usize::try_from(ffi::AV_INPUT_BUFFER_PADDING_SIZE).unwrap_or(64);
2197        // SAFETY: `av_mallocz` returns null or a zeroed buffer of the size asked for.
2198        let buffer = unsafe { ffi::av_mallocz(description.extradata.len() + padding) }.cast::<u8>();
2199        if buffer.is_null() {
2200            return Err(BridgeError::FfmpegCode(ffi::AVERROR(ffi::ENOMEM)));
2201        }
2202        // SAFETY: `buffer` holds the extradata's length and does not overlap it. The parameters
2203        // had no extradata and now own `buffer`.
2204        unsafe {
2205            ptr::copy_nonoverlapping(
2206                description.extradata.as_ptr(),
2207                buffer,
2208                description.extradata.len(),
2209            );
2210            (*raw).extradata = buffer;
2211            (*raw).extradata_size = extradata_size;
2212        }
2213    }
2214    Ok(parameters)
2215}
2216
2217/// Opens a bitstream filter chain in `ffmpeg -bsf` list syntax for a stream described by
2218/// `parameters` with packets in `time_base`.
2219///
2220/// rsmpeg cannot parse a list or set a filter's private options.
2221///
2222/// # Errors
2223/// Returns the `FFmpeg` status when the list does not parse, names a filter or option the runtime
2224/// lacks, or a filter refuses the stream.
2225pub fn bitstream_filter_list(
2226    spec: &CStr,
2227    parameters: &AVCodecParameters,
2228    time_base: rsmpeg::avutil::AVRational,
2229) -> Result<rsmpeg::avcodec::AVBSFContext, BridgeError> {
2230    let mut raw = ptr::null_mut();
2231    // SAFETY: `spec` is NUL-terminated; on success `raw` holds a new context taken over below.
2232    let status = unsafe { ffi::av_bsf_list_parse_str(spec.as_ptr(), &raw mut raw) };
2233    if status < 0 {
2234        return Err(BridgeError::FfmpegCode(status));
2235    }
2236    let raw = ptr::NonNull::new(raw).ok_or(BridgeError::FfmpegCode(ffi::AVERROR(ffi::ENOMEM)))?;
2237    // SAFETY: `raw` was just allocated and is unshared; the wrapper frees it with `av_bsf_free`.
2238    let mut context = unsafe { rsmpeg::avcodec::AVBSFContextUninit::from_raw(raw) };
2239    // rsmpeg's `set_par_in` panics when the copy cannot allocate.
2240    // SAFETY: `par_in` is the context's own parameter set and `parameters` is live;
2241    // `avcodec_parameters_copy` deep-copies into it.
2242    let status = unsafe { ffi::avcodec_parameters_copy(context.par_in, parameters.as_ptr()) };
2243    if status < 0 {
2244        return Err(BridgeError::FfmpegCode(status));
2245    }
2246    context.set_time_base_in(time_base);
2247    context.init().map_err(BridgeError::Ffmpeg)
2248}
2249
2250/// Sets a stream's codec tag (sample entry); zero lets the muxer pick its default.
2251pub fn set_stream_codec_tag(stream: &mut rsmpeg::avformat::AVStreamMut<'_>, tag: u32) {
2252    let mut parameters = stream.codecpar_mut();
2253    // SAFETY: the mutably borrowed stream owns its codec parameters; `codec_tag` is a plain field.
2254    unsafe { (*parameters.as_mut_ptr()).codec_tag = tag };
2255}
2256
2257/// Replaces a stream's display matrix (MP4's `tkhd` matrix) with `display`'s rotation and flip, as
2258/// [`display_rotation`] reads it back.
2259///
2260/// # Errors
2261/// When the side data cannot be allocated.
2262pub fn set_stream_display_matrix(
2263    stream: &mut rsmpeg::avformat::AVStreamMut<'_>,
2264    display: DisplayRotation,
2265) -> Result<(), BridgeError> {
2266    let mut parameters = stream.codecpar_mut();
2267    let parameters = parameters.as_mut_ptr();
2268    // SAFETY: the mutably borrowed stream owns its codec parameters; `av_packet_side_data_new`
2269    // keeps the array and count consistent and returns null only on allocation failure.
2270    let entry = unsafe {
2271        ffi::av_packet_side_data_new(
2272            &raw mut (*parameters).coded_side_data,
2273            &raw mut (*parameters).nb_coded_side_data,
2274            ffi::AV_PKT_DATA_DISPLAYMATRIX,
2275            size_of::<[i32; 9]>(),
2276            0,
2277        )
2278    };
2279    if entry.is_null() {
2280        return Err(BridgeError::FfmpegCode(ffi::AVERROR(ffi::ENOMEM)));
2281    }
2282    let mut matrix = [0_i32; 9];
2283    // `av_display_rotation_set` turns clockwise, opposite to `av_display_rotation_get`.
2284    // SAFETY: `matrix` is a complete, aligned 3x3 display matrix.
2285    unsafe {
2286        ffi::av_display_rotation_set(matrix.as_mut_ptr(), -display.counter_clockwise_degrees);
2287        if display.flipped {
2288            ffi::av_display_matrix_flip(matrix.as_mut_ptr(), 1, 0);
2289        }
2290    }
2291    // SAFETY: the new entry holds `size_of::<[i32; 9]>()` writable bytes; a byte copy needs no
2292    // alignment.
2293    unsafe {
2294        ptr::copy_nonoverlapping(
2295            matrix.as_ptr().cast::<u8>(),
2296            (*entry).data,
2297            size_of::<[i32; 9]>(),
2298        );
2299    }
2300    Ok(())
2301}
2302
2303/// Returns `FFmpeg`'s stable name for a hardware device type.
2304#[must_use]
2305pub fn hardware_device_type_name(device_type: ffi::AVHWDeviceType) -> Option<String> {
2306    // SAFETY: `av_hwdevice_get_type_name` accepts any value and returns null or a static C string.
2307    let name = unsafe { ffi::av_hwdevice_get_type_name(device_type) };
2308    if name.is_null() {
2309        None
2310    } else {
2311        // SAFETY: non-null return values obey the FFmpeg string contract above.
2312        Some(
2313            unsafe { CStr::from_ptr(name) }
2314                .to_string_lossy()
2315                .into_owned(),
2316        )
2317    }
2318}
2319
2320/// The plane layout of a YCbCr format the renderer samples directly, or `None`.
2321///
2322/// Accepts three components of one depth from 8 to 16 bits, chroma subsampled by at most four per
2323/// axis, three planes or U, V interleaved in the second, native byte order, low- or (above eight
2324/// bits) high-bit aligned. Rejects RGB, alpha, gray, palette, Bayer, float, XYZ, bitstream,
2325/// hardware formats and NV21.
2326#[must_use]
2327pub fn yuv_layout(format: ffi::AVPixelFormat) -> Option<YuvPlaneLayout> {
2328    if format == ffi::AV_PIX_FMT_NONE {
2329        return None;
2330    }
2331    // SAFETY: `av_pix_fmt_desc_get` accepts any value and returns null or a static descriptor.
2332    let descriptor = unsafe { ffi::av_pix_fmt_desc_get(format).as_ref() }?;
2333    let foreign_endian = if cfg!(target_endian = "little") {
2334        ffi::AV_PIX_FMT_FLAG_BE
2335    } else {
2336        0
2337    };
2338    let rejected = foreign_endian
2339        | ffi::AV_PIX_FMT_FLAG_PAL
2340        | ffi::AV_PIX_FMT_FLAG_BITSTREAM
2341        | ffi::AV_PIX_FMT_FLAG_HWACCEL
2342        | ffi::AV_PIX_FMT_FLAG_RGB
2343        | ffi::AV_PIX_FMT_FLAG_ALPHA
2344        | ffi::AV_PIX_FMT_FLAG_BAYER
2345        | ffi::AV_PIX_FMT_FLAG_FLOAT
2346        | ffi::AV_PIX_FMT_FLAG_XYZ;
2347    if descriptor.flags & u64::from(rejected) != 0 || descriptor.nb_components != 3 {
2348        return None;
2349    }
2350    let [luma, u, v, _] = descriptor.comp;
2351    let depth = luma.depth;
2352    if !(8..=16).contains(&depth) || u.depth != depth || v.depth != depth {
2353        return None;
2354    }
2355    if descriptor.log2_chroma_w > 2 || descriptor.log2_chroma_h > 2 {
2356        return None;
2357    }
2358    let bytes = if depth > 8 { 2 } else { 1 };
2359    let shift = luma.shift;
2360    let msb_aligned = match shift {
2361        0 => false,
2362        _ if depth > 8 && shift == 16 - depth => true,
2363        _ => return None,
2364    };
2365    let planar = u.plane == 1
2366        && v.plane == 2
2367        && u.step == bytes
2368        && v.step == bytes
2369        && u.offset == 0
2370        && v.offset == 0;
2371    let interleaved = u.plane == 1
2372        && v.plane == 1
2373        && u.step == 2 * bytes
2374        && v.step == 2 * bytes
2375        && u.offset == 0
2376        && v.offset == bytes;
2377    if luma.plane != 0
2378        || luma.step != bytes
2379        || luma.offset != 0
2380        || u.shift != shift
2381        || v.shift != shift
2382        || !(planar || interleaved)
2383    {
2384        return None;
2385    }
2386    Some(YuvPlaneLayout {
2387        chroma_shift_x: descriptor.log2_chroma_w,
2388        chroma_shift_y: descriptor.log2_chroma_h,
2389        bit_depth: u8::try_from(depth).ok()?,
2390        interleaved_chroma: interleaved,
2391        msb_aligned,
2392    })
2393}
2394
2395/// Copies the samples of a frame whose format [`yuv_layout`] accepts into packed forward rows, or
2396/// returns `Ok(None)` for other formats. Odd dimensions round chroma up.
2397///
2398/// Row padding is never read since it may be uninitialized; [`DecodedFrame::yuv_planes`] can share
2399/// fully written frames instead.
2400///
2401/// # Errors
2402/// Returns an error for invalid dimensions, null planes, or linesizes shorter than the plane width.
2403pub fn yuv_planes(frame: &AVFrame) -> Result<Option<YuvPlanes>, BridgeError> {
2404    frame_yuv_planes(frame, false)
2405}
2406
2407/// A decoded frame, and whether every byte of its buffers, row padding included, is written.
2408///
2409/// Only this crate constructs one; frames from elsewhere go to [`yuv_planes`].
2410pub struct DecodedFrame {
2411    frame: AVFrame,
2412    written: bool,
2413}
2414
2415impl DecodedFrame {
2416    /// Takes the next frame `decoder` has ready.
2417    ///
2418    /// # Errors
2419    /// Returns what `avcodec_receive_frame` does for a drained decoder or a decode failure.
2420    pub fn receive(decoder: &mut AVCodecContext) -> Result<Self, RsmpegError> {
2421        let written = decoder_frames_are_initialized(decoder);
2422        let frame = decoder.receive_frame()?;
2423        Ok(Self { frame, written })
2424    }
2425
2426    /// Like [`yuv_planes`], but shares the frame's buffer when it is fully written. Planes with a
2427    /// negative linesize or outside the frame's buffers are still copied.
2428    ///
2429    /// # Errors
2430    /// Returns an error for invalid dimensions, null planes, or linesizes shorter than the plane
2431    /// width.
2432    pub fn yuv_planes(&self) -> Result<Option<YuvPlanes>, BridgeError> {
2433        frame_yuv_planes(&self.frame, self.written)
2434    }
2435
2436    /// Sets the frame's presentation timestamp.
2437    pub fn set_pts(&mut self, pts: i64) {
2438        self.frame.set_pts(pts);
2439    }
2440
2441    /// Takes ownership of the frame.
2442    #[must_use]
2443    pub fn into_frame(self) -> AVFrame {
2444        self.frame
2445    }
2446}
2447
2448impl std::ops::Deref for DecodedFrame {
2449    type Target = AVFrame;
2450
2451    fn deref(&self) -> &AVFrame {
2452        &self.frame
2453    }
2454}
2455
2456impl fmt::Debug for DecodedFrame {
2457    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2458        formatter
2459            .debug_struct("DecodedFrame")
2460            .field("format", &self.frame.format)
2461            .field("width", &self.frame.width)
2462            .field("height", &self.frame.height)
2463            .field("pts", &self.frame.pts)
2464            .field("written", &self.written)
2465            .finish_non_exhaustive()
2466    }
2467}
2468
2469/// Whether `decoder`'s frame buffers are fully initialized, so they may be shared.
2470///
2471/// The default `get_buffer2` uses zeroed pools. Wrapped external decoders (`wrapper_name`, such as
2472/// libdav1d) and replaced `get_buffer2` callbacks do not qualify.
2473fn decoder_frames_are_initialized(decoder: &AVCodecContext) -> bool {
2474    static DEFAULT_GET_BUFFER2: std::sync::OnceLock<usize> = std::sync::OnceLock::new();
2475    // Read the default from a new context; Rust's address of the function could be a linker stub.
2476    let default = *DEFAULT_GET_BUFFER2.get_or_init(|| {
2477        // SAFETY: a context allocated without a codec is only read and then freed.
2478        unsafe {
2479            let mut context = ffi::avcodec_alloc_context3(ptr::null());
2480            let get_buffer2 = context
2481                .as_ref()
2482                .and_then(|context| context.get_buffer2)
2483                .map_or(0, |function| function as usize);
2484            ffi::avcodec_free_context(&raw mut context);
2485            get_buffer2
2486        }
2487    });
2488    // SAFETY: a context's `codec` is null or a static, read-only description.
2489    let wrapped =
2490        unsafe { decoder.codec.as_ref() }.is_none_or(|codec| !codec.wrapper_name.is_null());
2491    let get_buffer2 = decoder.get_buffer2.map_or(0, |function| function as usize);
2492    !wrapped && default != 0 && get_buffer2 == default
2493}
2494
2495/// The planes of `frame`; `share` only for fully initialized frames.
2496fn frame_yuv_planes(frame: &AVFrame, share: bool) -> Result<Option<YuvPlanes>, BridgeError> {
2497    let Some(layout) = yuv_layout(frame.format) else {
2498        return Ok(None);
2499    };
2500    let width =
2501        u32::try_from(frame.width).map_err(|_| BridgeError::InvalidInput("negative YUV width"))?;
2502    let height = u32::try_from(frame.height)
2503        .map_err(|_| BridgeError::InvalidInput("negative YUV height"))?;
2504    if width == 0 || height == 0 {
2505        return Err(BridgeError::InvalidInput("empty YUV frame"));
2506    }
2507    let bytes = layout.bytes_per_sample();
2508    let chroma_width = width.div_ceil(1 << layout.chroma_shift_x);
2509    let chroma_height = height.div_ceil(1 << layout.chroma_shift_y);
2510    // Only a vouched-for, reference-counted frame is shared; `AVFrame::clone` adds buffer refs.
2511    let shared =
2512        (share && !frame.buf[0].is_null()).then(|| std::sync::Arc::new(SharedFrame(frame.clone())));
2513    let copy = |index: usize,
2514                samples: u32,
2515                pairs: u32,
2516                rows: u32,
2517                context: &'static str|
2518     -> Result<FramePlane, BridgeError> {
2519        let row_bytes = samples
2520            .checked_mul(bytes)
2521            .and_then(|row| row.checked_mul(pairs))
2522            .ok_or(BridgeError::InvalidInput(context))?;
2523        if let Some(view) = shared
2524            .as_ref()
2525            .and_then(|frame| PlaneView::new(frame, index, row_bytes, rows))
2526        {
2527            let stride =
2528                u32::try_from(view.stride).map_err(|_| BridgeError::InvalidInput(context))?;
2529            return Ok(FramePlane {
2530                bytes: bytes::Bytes::from_owner(view),
2531                stride,
2532                width: samples,
2533                height: rows,
2534            });
2535        }
2536        Ok(FramePlane {
2537            bytes: copy_video_plane(frame, index, row_bytes, rows, context)?.into(),
2538            stride: row_bytes,
2539            width: samples,
2540            height: rows,
2541        })
2542    };
2543    let mut planes = vec![copy(0, width, 1, height, "invalid Y plane")?];
2544    if layout.interleaved_chroma {
2545        planes.push(copy(1, chroma_width, 2, chroma_height, "invalid UV plane")?);
2546    } else {
2547        planes.push(copy(1, chroma_width, 1, chroma_height, "invalid U plane")?);
2548        planes.push(copy(2, chroma_width, 1, chroma_height, "invalid V plane")?);
2549    }
2550    Ok(Some(YuvPlanes {
2551        layout,
2552        width,
2553        height,
2554        planes,
2555    }))
2556}
2557
2558/// A decoded frame whose buffers several plane views share.
2559struct SharedFrame(AVFrame);
2560
2561// SAFETY: the wrapped frame is only read. FFmpeg never writes to a buffer with more than one
2562// reference, so nothing mutates it while shared.
2563unsafe impl Sync for SharedFrame {}
2564
2565/// `stride * rows` bytes of one plane of a fully written [`SharedFrame`], which it keeps alive.
2566struct PlaneView {
2567    frame: std::sync::Arc<SharedFrame>,
2568    data: *const u8,
2569    len: usize,
2570    stride: usize,
2571}
2572
2573// SAFETY: the view reads immutable memory in `frame`'s buffers, which it keeps alive;
2574// `SharedFrame` is `Send + Sync`.
2575unsafe impl Send for PlaneView {}
2576
2577impl PlaneView {
2578    /// `None` unless the linesize is positive, covers `row_bytes`, and all rows lie in one buffer.
2579    fn new(
2580        frame: &std::sync::Arc<SharedFrame>,
2581        index: usize,
2582        row_bytes: u32,
2583        rows: u32,
2584    ) -> Option<Self> {
2585        let inner = &frame.0;
2586        let data = inner.data[index].cast_const();
2587        let stride = usize::try_from(inner.linesize[index]).ok()?;
2588        let row_bytes = usize::try_from(row_bytes).ok()?;
2589        if data.is_null() || stride < row_bytes || rows == 0 {
2590            return None;
2591        }
2592        let len = stride.checked_mul(usize::try_from(rows).ok()?)?;
2593        in_frame_buffer(inner, data as usize, len).then(|| Self {
2594            frame: std::sync::Arc::clone(frame),
2595            data,
2596            len,
2597            stride,
2598        })
2599    }
2600}
2601
2602impl AsRef<[u8]> for PlaneView {
2603    fn as_ref(&self) -> &[u8] {
2604        let _ = &self.frame;
2605        // SAFETY: `new` checked `data..data + len` lies in a buffer of the frame `self` holds.
2606        unsafe { slice::from_raw_parts(self.data, self.len) }
2607    }
2608}
2609
2610/// Copies plane `index` of `frame`, refusing rows outside the frame's buffers when it has any.
2611fn copy_video_plane(
2612    frame: &AVFrame,
2613    index: usize,
2614    width: u32,
2615    height: u32,
2616    context: &'static str,
2617) -> Result<Vec<u8>, BridgeError> {
2618    let (data, linesize) = (frame.data[index].cast_const(), frame.linesize[index]);
2619    let has_buffers = frame.buf.iter().any(|buffer| !buffer.is_null());
2620    if has_buffers && !plane_rows_in_frame_buffer(frame, data, linesize, width, height) {
2621        return Err(BridgeError::InvalidInput(context));
2622    }
2623    // SAFETY: the rows lie in one of the frame's buffers, or a frame without buffers vouches for
2624    // its own planes.
2625    unsafe { copy_plane_rows(data, linesize, width, height, context) }
2626}
2627
2628/// Whether `height` rows of `width` bytes at the signed `linesize` from `data` lie in one buffer.
2629fn plane_rows_in_frame_buffer(
2630    frame: &AVFrame,
2631    data: *const u8,
2632    linesize: i32,
2633    width: u32,
2634    height: u32,
2635) -> bool {
2636    let (Ok(row_bytes), Ok(rows)) = (usize::try_from(width), usize::try_from(height)) else {
2637        return false;
2638    };
2639    let Ok(stride) = usize::try_from(linesize.unsigned_abs()) else {
2640        return false;
2641    };
2642    let Some(span) = stride
2643        .checked_mul(rows.saturating_sub(1))
2644        .and_then(|before| before.checked_add(row_bytes))
2645    else {
2646        return false;
2647    };
2648    // A negative linesize walks back from the first row, so the lowest address is the last row.
2649    let start = if linesize < 0 {
2650        (data as usize).checked_sub(span - row_bytes)
2651    } else {
2652        Some(data as usize)
2653    };
2654    !data.is_null() && rows > 0 && start.is_some_and(|start| in_frame_buffer(frame, start, span))
2655}
2656
2657/// # Safety
2658/// A non-null `data` must have `height` rows at the signed `linesize`, each `width` bytes long.
2659unsafe fn copy_plane_rows(
2660    data: *const u8,
2661    linesize: i32,
2662    width: u32,
2663    height: u32,
2664    context: &'static str,
2665) -> Result<Vec<u8>, BridgeError> {
2666    let row_bytes = usize::try_from(width).map_err(|_| BridgeError::InvalidInput(context))?;
2667    let rows = usize::try_from(height).map_err(|_| BridgeError::InvalidInput(context))?;
2668    let stride =
2669        usize::try_from(linesize.unsigned_abs()).map_err(|_| BridgeError::InvalidInput(context))?;
2670    if data.is_null() || linesize == 0 || stride < row_bytes {
2671        return Err(BridgeError::InvalidInput(context));
2672    }
2673    let byte_len = row_bytes
2674        .checked_mul(rows)
2675        .ok_or(BridgeError::InvalidInput(context))?;
2676    // Append row by row to avoid an extra zeroing pass over the buffer.
2677    let mut output = Vec::with_capacity(byte_len);
2678    let signed_stride =
2679        isize::try_from(linesize).map_err(|_| BridgeError::InvalidInput(context))?;
2680    for row in 0..rows {
2681        let row = isize::try_from(row).map_err(|_| BridgeError::InvalidInput(context))?;
2682        let offset = row
2683            .checked_mul(signed_stride)
2684            .ok_or(BridgeError::InvalidInput(context))?;
2685        // SAFETY: delegated to this function's contract; the linesize covers `row_bytes`.
2686        let source = unsafe { slice::from_raw_parts(data.offset(offset), row_bytes) };
2687        output.extend_from_slice(source);
2688    }
2689    debug_assert_eq!(output.len(), byte_len);
2690    Ok(output)
2691}
2692
2693/// Copies tightly packed RGBA bytes into an owned `FFmpeg` frame.
2694///
2695/// # Errors
2696/// Returns an `FFmpeg` error when its frame buffer cannot be allocated.
2697pub fn rgba_frame(bytes: &[u8], width: i32, height: i32) -> Result<AVFrame, BridgeError> {
2698    let row_bytes = usize::try_from(width)
2699        .ok()
2700        .and_then(|value| value.checked_mul(4))
2701        .ok_or(BridgeError::InvalidInput("RGBA row width overflow"))?;
2702    let rows =
2703        usize::try_from(height).map_err(|_| BridgeError::InvalidInput("negative RGBA height"))?;
2704    let expected = row_bytes
2705        .checked_mul(rows)
2706        .ok_or(BridgeError::InvalidInput("RGBA frame size overflow"))?;
2707    if bytes.len() != expected {
2708        return Err(BridgeError::InvalidInput("RGBA byte length mismatch"));
2709    }
2710
2711    let mut frame = AVFrame::new();
2712    frame.set_format(ffi::AV_PIX_FMT_RGBA);
2713    frame.set_width(width);
2714    frame.set_height(height);
2715    frame.get_buffer(1)?;
2716    frame.make_writable()?;
2717    let linesize = usize::try_from(frame.linesize[0])
2718        .map_err(|_| BridgeError::InvalidInput("negative RGBA linesize"))?;
2719    if frame.data[0].is_null() || linesize < row_bytes {
2720        return Err(BridgeError::InvalidInput(
2721            "RGBA destination plane is too small",
2722        ));
2723    }
2724
2725    // SAFETY: av_frame_get_buffer allocated `height` writable rows of `linesize` bytes; both slices
2726    // span one validated RGBA row.
2727    unsafe {
2728        for row in 0..rows {
2729            let destination_offset = row.checked_mul(linesize).ok_or(BridgeError::InvalidInput(
2730                "RGBA destination offset overflow",
2731            ))?;
2732            let source_offset = row
2733                .checked_mul(row_bytes)
2734                .ok_or(BridgeError::InvalidInput("RGBA source offset overflow"))?;
2735            let destination =
2736                slice::from_raw_parts_mut(frame.data[0].add(destination_offset), row_bytes);
2737            destination.copy_from_slice(&bytes[source_offset..source_offset + row_bytes]);
2738        }
2739    }
2740    Ok(frame)
2741}
2742
2743/// Copies owned planar 8-bit 4:2:0 samples into an `FFmpeg` video frame.
2744///
2745/// # Errors
2746/// Returns an error for invalid dimensions, short source planes, or an allocation failure.
2747#[allow(clippy::too_many_arguments)]
2748pub fn yuv420p_frame(
2749    y: &[u8],
2750    y_stride: u32,
2751    u: &[u8],
2752    u_stride: u32,
2753    v: &[u8],
2754    v_stride: u32,
2755    width: i32,
2756    height: i32,
2757) -> Result<AVFrame, BridgeError> {
2758    let width =
2759        u32::try_from(width).map_err(|_| BridgeError::InvalidInput("negative YUV width"))?;
2760    let height =
2761        u32::try_from(height).map_err(|_| BridgeError::InvalidInput("negative YUV height"))?;
2762    if width == 0 || height == 0 {
2763        return Err(BridgeError::InvalidInput("empty YUV frame"));
2764    }
2765    let chroma_width = width.div_ceil(2);
2766    let chroma_height = height.div_ceil(2);
2767    validate_source_plane(y, y_stride, width, height, "invalid Y source plane")?;
2768    validate_source_plane(
2769        u,
2770        u_stride,
2771        chroma_width,
2772        chroma_height,
2773        "invalid U source plane",
2774    )?;
2775    validate_source_plane(
2776        v,
2777        v_stride,
2778        chroma_width,
2779        chroma_height,
2780        "invalid V source plane",
2781    )?;
2782
2783    let mut frame = AVFrame::new();
2784    frame.set_format(ffi::AV_PIX_FMT_YUV420P);
2785    frame.set_width(i32::try_from(width).map_err(|_| BridgeError::InvalidInput("YUV width"))?);
2786    frame.set_height(i32::try_from(height).map_err(|_| BridgeError::InvalidInput("YUV height"))?);
2787    frame.get_buffer(1)?;
2788    frame.make_writable()?;
2789    copy_plane_to_frame(y, y_stride, width, height, frame.data[0], frame.linesize[0])?;
2790    copy_plane_to_frame(
2791        u,
2792        u_stride,
2793        chroma_width,
2794        chroma_height,
2795        frame.data[1],
2796        frame.linesize[1],
2797    )?;
2798    copy_plane_to_frame(
2799        v,
2800        v_stride,
2801        chroma_width,
2802        chroma_height,
2803        frame.data[2],
2804        frame.linesize[2],
2805    )?;
2806    Ok(frame)
2807}
2808
2809/// The first pixel format in `FFmpeg`'s table laid out as `layout` (`yuv420p`, not the deprecated
2810/// `yuvj420p`).
2811#[must_use]
2812pub fn yuv_pixel_format(layout: YuvPlaneLayout) -> Option<ffi::AVPixelFormat> {
2813    let mut descriptor = ptr::null();
2814    loop {
2815        // SAFETY: null starts the walk; other values are static descriptors from the previous call.
2816        descriptor = unsafe { ffi::av_pix_fmt_desc_next(descriptor) };
2817        if descriptor.is_null() {
2818            return None;
2819        }
2820        // SAFETY: a descriptor from the table names its own format.
2821        let format = unsafe { ffi::av_pix_fmt_desc_get_id(descriptor) };
2822        if yuv_layout(format) == Some(layout) {
2823            return Some(format);
2824        }
2825    }
2826}
2827
2828/// A `width` by `height` frame of `format` holding a copy of `planes` (bytes and stride each).
2829///
2830/// # Errors
2831/// For a format without a descriptor, the wrong plane count, or a plane smaller than the picture.
2832pub fn planar_frame(
2833    format: ffi::AVPixelFormat,
2834    planes: &[(&[u8], u32)],
2835    width: u32,
2836    height: u32,
2837) -> Result<AVFrame, BridgeError> {
2838    // SAFETY: `av_pix_fmt_desc_get` accepts any value and returns null or a static descriptor.
2839    let descriptor = unsafe { ffi::av_pix_fmt_desc_get(format).as_ref() }
2840        .ok_or(BridgeError::InvalidInput("pixel format has no descriptor"))?;
2841    // SAFETY: a pure computation over plain values.
2842    let count = unsafe { ffi::av_pix_fmt_count_planes(format) };
2843    if usize::try_from(count).ok() != Some(planes.len()) || width == 0 || height == 0 {
2844        return Err(BridgeError::InvalidInput(
2845            "planes do not match the pixel format",
2846        ));
2847    }
2848    let signed = |value: u32| {
2849        i32::try_from(value).map_err(|_| BridgeError::InvalidInput("frame size overflow"))
2850    };
2851    let mut frame = AVFrame::new();
2852    frame.set_format(format);
2853    frame.set_width(signed(width)?);
2854    frame.set_height(signed(height)?);
2855    frame.get_buffer(1)?;
2856    frame.make_writable()?;
2857    for (index, (bytes, stride)) in planes.iter().enumerate() {
2858        let plane = i32::try_from(index).unwrap_or(i32::MAX);
2859        // SAFETY: a pure computation over plain values.
2860        let row_bytes = unsafe { ffi::av_image_get_linesize(format, signed(width)?, plane) };
2861        let row_bytes = u32::try_from(row_bytes).map_err(|_| BridgeError::FfmpegCode(row_bytes))?;
2862        let rows = if index == 0 || index == 3 {
2863            height
2864        } else {
2865            height.div_ceil(1 << descriptor.log2_chroma_h)
2866        };
2867        validate_source_plane(bytes, *stride, row_bytes, rows, "invalid source plane")?;
2868        copy_plane_to_frame(
2869            bytes,
2870            *stride,
2871            row_bytes,
2872            rows,
2873            frame.data[index],
2874            frame.linesize[index],
2875        )?;
2876    }
2877    Ok(frame)
2878}
2879
2880fn validate_source_plane(
2881    bytes: &[u8],
2882    stride: u32,
2883    width: u32,
2884    height: u32,
2885    context: &'static str,
2886) -> Result<(), BridgeError> {
2887    let required = usize::try_from(stride).ok().and_then(|stride| {
2888        usize::try_from(height)
2889            .ok()
2890            .and_then(|height| stride.checked_mul(height))
2891    });
2892    if stride < width || required != Some(bytes.len()) {
2893        Err(BridgeError::InvalidInput(context))
2894    } else {
2895        Ok(())
2896    }
2897}
2898
2899fn copy_plane_to_frame(
2900    source: &[u8],
2901    source_stride: u32,
2902    width: u32,
2903    height: u32,
2904    destination: *mut u8,
2905    destination_stride: i32,
2906) -> Result<(), BridgeError> {
2907    let row_bytes =
2908        usize::try_from(width).map_err(|_| BridgeError::InvalidInput("YUV row width overflow"))?;
2909    let rows =
2910        usize::try_from(height).map_err(|_| BridgeError::InvalidInput("YUV row count overflow"))?;
2911    let source_stride = usize::try_from(source_stride)
2912        .map_err(|_| BridgeError::InvalidInput("YUV source stride overflow"))?;
2913    let destination_stride = usize::try_from(destination_stride)
2914        .map_err(|_| BridgeError::InvalidInput("negative YUV destination stride"))?;
2915    if destination.is_null() || destination_stride < row_bytes {
2916        return Err(BridgeError::InvalidInput(
2917            "YUV destination plane is too small",
2918        ));
2919    }
2920    for row in 0..rows {
2921        let source_offset = row
2922            .checked_mul(source_stride)
2923            .ok_or(BridgeError::InvalidInput("YUV source offset overflow"))?;
2924        let destination_offset = row
2925            .checked_mul(destination_stride)
2926            .ok_or(BridgeError::InvalidInput("YUV destination offset overflow"))?;
2927        // SAFETY: the destination has `height` writable rows covering `width` bytes, and the source
2928        // length was checked against its stride and row count.
2929        unsafe {
2930            ptr::copy_nonoverlapping(
2931                source.as_ptr().add(source_offset),
2932                destination.add(destination_offset),
2933                row_bytes,
2934            );
2935        }
2936    }
2937    Ok(())
2938}
2939
2940/// Copies planar `f32` samples into an audio frame of `format` (`FLTP`, `FLT` or `S16`). 16-bit
2941/// samples are clamped to [-1, 1] and rounded.
2942///
2943/// # Errors
2944/// Returns an error for mismatched channels, invalid dimensions, another sample format, or an
2945/// allocation failure.
2946pub fn audio_frame(
2947    channels: &[Vec<f32>],
2948    format: ffi::AVSampleFormat,
2949    sample_rate: i32,
2950    pts: i64,
2951) -> Result<AVFrame, BridgeError> {
2952    let Some(samples) = channels.first().map(Vec::len) else {
2953        return Err(BridgeError::InvalidInput("invalid planar audio shape"));
2954    };
2955    if sample_rate <= 0
2956        || samples == 0
2957        || channels.len() > ffi::AV_NUM_DATA_POINTERS as usize
2958        || channels.iter().any(|channel| channel.len() != samples)
2959    {
2960        return Err(BridgeError::InvalidInput(
2961            "planar audio channel lengths differ",
2962        ));
2963    }
2964    let sample_bytes = match format {
2965        ffi::AV_SAMPLE_FMT_FLTP | ffi::AV_SAMPLE_FMT_FLT => size_of::<f32>(),
2966        ffi::AV_SAMPLE_FMT_S16 => size_of::<i16>(),
2967        _ => return Err(BridgeError::InvalidInput("unsupported audio sample format")),
2968    };
2969    let planar = format == ffi::AV_SAMPLE_FMT_FLTP;
2970    let channel_count = i32::try_from(channels.len())
2971        .map_err(|_| BridgeError::InvalidInput("audio channel count overflow"))?;
2972    let sample_count = i32::try_from(samples)
2973        .map_err(|_| BridgeError::InvalidInput("audio sample count overflow"))?;
2974    let mut frame = AVFrame::new();
2975    frame.set_format(format);
2976    frame.set_ch_layout(
2977        rsmpeg::avutil::AVChannelLayout::from_nb_channels(channel_count).into_inner(),
2978    );
2979    frame.set_sample_rate(sample_rate);
2980    frame.set_nb_samples(sample_count);
2981    frame.set_pts(pts);
2982    frame.set_time_base(ffi::AVRational {
2983        num: 1,
2984        den: sample_rate,
2985    });
2986    frame.get_buffer(0)?;
2987    frame.make_writable()?;
2988    let plane_bytes = samples
2989        .checked_mul(sample_bytes)
2990        .and_then(|bytes| bytes.checked_mul(if planar { 1 } else { channels.len() }))
2991        .ok_or(BridgeError::InvalidInput("audio plane byte count overflow"))?;
2992    let plane_capacity = usize::try_from(frame.linesize[0]).unwrap_or(0);
2993    if plane_capacity < plane_bytes {
2994        return Err(BridgeError::InvalidInput(
2995            "audio plane capacity is too small",
2996        ));
2997    }
2998    let planes = if planar { channels.len() } else { 1 };
2999    if frame.data[..planes].iter().any(|plane| plane.is_null()) {
3000        return Err(BridgeError::InvalidInput("audio plane pointer is null"));
3001    }
3002    if planar {
3003        for (index, source) in channels.iter().enumerate() {
3004            // SAFETY: av_frame_get_buffer allocated one writable plane per channel of `linesize[0]`
3005            // bytes, checked above to hold the channel.
3006            unsafe {
3007                ptr::copy_nonoverlapping(
3008                    source.as_ptr().cast::<u8>(),
3009                    frame.data[index],
3010                    plane_bytes,
3011                );
3012            }
3013        }
3014        return Ok(frame);
3015    }
3016    // SAFETY: the single interleaved plane was checked to hold every sample and is unshared.
3017    let plane = unsafe { std::slice::from_raw_parts_mut(frame.data[0], plane_bytes) };
3018    let interleaved = (0..samples).flat_map(|sample| channels.iter().map(move |c| c[sample]));
3019    if format == ffi::AV_SAMPLE_FMT_FLT {
3020        for (bytes, value) in plane.as_chunks_mut::<4>().0.iter_mut().zip(interleaved) {
3021            *bytes = value.to_ne_bytes();
3022        }
3023    } else {
3024        for (bytes, value) in plane.as_chunks_mut::<2>().0.iter_mut().zip(interleaved) {
3025            // In range after the clamp, so the cast cannot truncate.
3026            #[allow(clippy::cast_possible_truncation)]
3027            let value = (value.clamp(-1.0, 1.0) * 32_767.0).round() as i16;
3028            *bytes = value.to_ne_bytes();
3029        }
3030    }
3031    Ok(frame)
3032}
3033
3034/// The `AVChannel` of each channel of `layout`, in order; empty for `AV_CHANNEL_ORDER_UNSPEC`.
3035///
3036/// Takes rsmpeg's wrapper because a bare `AVChannelLayout` can carry a forged channel map:
3037///
3038/// ```compile_fail,E0308
3039/// use rsmpeg::ffi;
3040/// let forged = ffi::AVChannelLayout {
3041///     order: ffi::AV_CHANNEL_ORDER_CUSTOM,
3042///     nb_channels: 4,
3043///     u: ffi::AVChannelLayout__bindgen_ty_1 { map: 0x10 as *mut _ },
3044///     opaque: std::ptr::null_mut(),
3045/// };
3046/// alpha2_ffmpeg_bridge::channel_layout_channels(&forged);
3047/// ```
3048#[must_use]
3049pub fn channel_layout_channels(layout: &rsmpeg::avutil::AVChannelLayout) -> Vec<ffi::AVChannel> {
3050    if layout.order == ffi::AV_CHANNEL_ORDER_UNSPEC {
3051        return Vec::new();
3052    }
3053    let channels = u32::try_from(layout.nb_channels).unwrap_or(0);
3054    (0..channels)
3055        .map(|index| {
3056            layout
3057                .channel_from_index(index)
3058                .unwrap_or(ffi::AV_CHAN_NONE)
3059        })
3060        .collect()
3061}
3062
3063/// A channel layout of `channels` in order, native when possible, else custom.
3064///
3065/// # Errors
3066/// Returns an error for no channels or when `FFmpeg` cannot allocate or retype the layout.
3067pub fn channel_layout_of(
3068    channels: &[ffi::AVChannel],
3069) -> Result<rsmpeg::avutil::AVChannelLayout, BridgeError> {
3070    let count = i32::try_from(channels.len())
3071        .ok()
3072        .filter(|count| *count > 0)
3073        .ok_or(BridgeError::InvalidInput("a channel layout needs channels"))?;
3074    let mut raw = std::mem::MaybeUninit::<ffi::AVChannelLayout>::zeroed();
3075    // SAFETY: `custom_init` gives the zeroed layout a map of `count` entries, all written below.
3076    let initialized = unsafe { ffi::av_channel_layout_custom_init(raw.as_mut_ptr(), count) };
3077    if initialized < 0 {
3078        return Err(BridgeError::FfmpegCode(initialized));
3079    }
3080    // SAFETY: initialized above; from here `layout` owns it and uninitializes it on drop.
3081    let mut layout = unsafe { rsmpeg::avutil::AVChannelLayout::new(raw.assume_init()) };
3082    for (index, channel) in channels.iter().enumerate() {
3083        // SAFETY: a custom layout's map holds `count` entries, and `index` is below it.
3084        unsafe { (*layout.u.map.add(index)).id = *channel };
3085    }
3086    let flags = i32::try_from(ffi::AV_CHANNEL_LAYOUT_RETYPE_FLAG_CANONICAL).unwrap_or(0);
3087    // SAFETY: `layout` is a valid custom layout that `retype` may rewrite in place.
3088    let retyped = unsafe {
3089        ffi::av_channel_layout_retype(layout.as_mut_ptr(), ffi::AV_CHANNEL_ORDER_UNSPEC, flags)
3090    };
3091    if retyped < 0 {
3092        return Err(BridgeError::FfmpegCode(retyped));
3093    }
3094    Ok(layout)
3095}
3096
3097/// Copies a packed `AV_SAMPLE_FMT_FLT` frame into an owned interleaved vector.
3098///
3099/// # Errors
3100/// Returns an error if the frame format, dimensions, or buffer is invalid.
3101pub fn audio_f32_interleaved(frame: &AVFrame) -> Result<Vec<f32>, BridgeError> {
3102    if frame.format != ffi::AV_SAMPLE_FMT_FLT || frame.nb_samples < 0 {
3103        return Err(BridgeError::InvalidInput(
3104            "packed audio format or sample count is invalid",
3105        ));
3106    }
3107    let channels = usize::try_from(frame.ch_layout().nb_channels)
3108        .map_err(|_| BridgeError::InvalidInput("packed audio channel count is negative"))?;
3109    let frames = usize::try_from(frame.nb_samples)
3110        .map_err(|_| BridgeError::InvalidInput("packed audio sample count is negative"))?;
3111    let samples = frames
3112        .checked_mul(channels)
3113        .ok_or(BridgeError::InvalidInput(
3114            "packed audio sample count overflow",
3115        ))?;
3116    let bytes = samples
3117        .checked_mul(size_of::<f32>())
3118        .ok_or(BridgeError::InvalidInput(
3119            "packed audio byte count overflow",
3120        ))?;
3121    if channels == 0
3122        || frame.data[0].is_null()
3123        || usize::try_from(frame.linesize[0]).unwrap_or(0) < bytes
3124    {
3125        return Err(BridgeError::InvalidInput(
3126            "packed audio plane is missing or too small",
3127        ));
3128    }
3129    let mut output = vec![0.0_f32; samples];
3130    // SAFETY: the FLT plane was checked to hold every sample, and `output` is exactly that size.
3131    unsafe {
3132        ptr::copy_nonoverlapping(frame.data[0], output.as_mut_ptr().cast::<u8>(), bytes);
3133    }
3134    Ok(output)
3135}
3136
3137/// The rotation a display matrix asks for, in `FFmpeg`'s convention.
3138#[derive(Copy, Clone, Debug, PartialEq)]
3139pub struct DisplayRotation {
3140    /// Counter-clockwise angle in degrees, in `[-180, 180]`.
3141    pub counter_clockwise_degrees: f64,
3142    /// Whether the matrix also mirrors: this rotation followed by a horizontal flip.
3143    pub flipped: bool,
3144}
3145
3146/// Reads a stream display matrix.
3147#[must_use]
3148pub fn display_rotation(parameters: &AVCodecParameters) -> Option<DisplayRotation> {
3149    let count = usize::try_from(parameters.nb_coded_side_data).ok()?;
3150    if count == 0 || count > 64 || parameters.coded_side_data.is_null() {
3151        return None;
3152    }
3153    // SAFETY: the borrowed parameters own exactly `nb_coded_side_data` entries.
3154    let entries = unsafe { slice::from_raw_parts(parameters.coded_side_data, count) };
3155    let matrix = entries.iter().find(|entry| {
3156        entry.type_ == ffi::AV_PKT_DATA_DISPLAYMATRIX
3157            && entry.size >= 9 * size_of::<i32>()
3158            && !entry.data.is_null()
3159    })?;
3160    // SAFETY: the matching side-data entry was validated to hold a complete 3x3 display matrix.
3161    unsafe { matrix_rotation(matrix.data) }
3162}
3163
3164/// Reads a frame's display matrix, such as the JPEG decoder attaches for Exif `Orientation`.
3165#[must_use]
3166pub fn frame_display_rotation(frame: &AVFrame) -> Option<DisplayRotation> {
3167    // SAFETY: `frame` is a live frame; the returned entry, if any, is owned by it for this borrow.
3168    let entry =
3169        unsafe { ffi::av_frame_get_side_data(frame.as_ptr(), ffi::AV_FRAME_DATA_DISPLAYMATRIX) };
3170    if entry.is_null() {
3171        return None;
3172    }
3173    // SAFETY: a non-null entry returned by `av_frame_get_side_data` is a valid side-data record.
3174    let entry = unsafe { &*entry };
3175    if entry.size < 9 * size_of::<i32>() || entry.data.is_null() {
3176        return None;
3177    }
3178    // SAFETY: the entry was validated to hold a complete 3x3 display matrix.
3179    unsafe { matrix_rotation(entry.data) }
3180}
3181
3182/// # Safety
3183/// `data` must point at nine readable `i32`s, aligned or not.
3184unsafe fn matrix_rotation(data: *const u8) -> Option<DisplayRotation> {
3185    let mut aligned = [0_i32; 9];
3186    // SAFETY: the caller guarantees a complete 3x3 matrix; a byte copy needs no alignment.
3187    unsafe {
3188        ptr::copy_nonoverlapping(
3189            data,
3190            aligned.as_mut_ptr().cast::<u8>(),
3191            size_of::<[i32; 9]>(),
3192        );
3193    }
3194    // `av_display_rotation_get` is meaningless for a mirroring matrix (negative 2x2 determinant),
3195    // so remove the horizontal flip first.
3196    let determinant = i64::from(aligned[0]) * i64::from(aligned[4])
3197        - i64::from(aligned[1]) * i64::from(aligned[3]);
3198    let flipped = determinant < 0;
3199    if flipped {
3200        // SAFETY: `aligned` is a complete, correctly aligned 3x3 matrix.
3201        unsafe { ffi::av_display_matrix_flip(aligned.as_mut_ptr(), 1, 0) };
3202    }
3203    // SAFETY: `aligned` is a complete, correctly aligned 3x3 display matrix.
3204    let angle = unsafe { ffi::av_display_rotation_get(aligned.as_ptr()) };
3205    angle.is_finite().then_some(DisplayRotation {
3206        counter_clockwise_degrees: angle,
3207        flipped,
3208    })
3209}
3210
3211const fn size_of<T>() -> usize {
3212    std::mem::size_of::<T>()
3213}
3214
3215/// A reusable `FFmpeg` YUV420P frame the caller writes into directly.
3216///
3217/// Avoids [`yuv420p_frame`]'s per-frame allocation and copy. [`Yuv420pFrameBuffer::begin_write`]
3218/// returns plane memory only once `FFmpeg` no longer shares the buffer, copying it if needed.
3219pub struct Yuv420pFrameBuffer {
3220    frame: AVFrame,
3221    width: usize,
3222    height: usize,
3223    /// Each plane's visible bytes per row and rows, from the pixel format descriptor.
3224    planes: Vec<(usize, usize)>,
3225}
3226
3227/// Writable plane memory for one reusable frame.
3228pub struct Yuv420pFramePlanes<'a> {
3229    /// Luma rows, `y_stride` bytes apart.
3230    pub y: &'a mut [u8],
3231    /// Distance between luma rows.
3232    pub y_stride: usize,
3233    /// Blue-difference chroma rows, `chroma_stride` bytes apart.
3234    pub u: &'a mut [u8],
3235    /// Red-difference chroma rows, `chroma_stride` bytes apart.
3236    pub v: &'a mut [u8],
3237    /// Distance between chroma rows.
3238    pub chroma_stride: usize,
3239}
3240
3241impl Yuv420pFrameBuffer {
3242    /// Allocates one reusable frame for this exact coded size.
3243    ///
3244    /// # Errors
3245    /// Returns an error for a non-positive size or a failed allocation.
3246    pub fn new(width: i32, height: i32) -> Result<Self, BridgeError> {
3247        Self::with_format(width, height, ffi::AV_PIX_FMT_YUV420P)
3248    }
3249
3250    /// Allocates one reusable frame of `format`; each plane's row bytes and rows come from the
3251    /// format's descriptor.
3252    ///
3253    /// # Errors
3254    /// Returns an error for a non-positive size, a format without planes, or a failed allocation.
3255    pub fn with_format(
3256        width: i32,
3257        height: i32,
3258        format: ffi::AVPixelFormat,
3259    ) -> Result<Self, BridgeError> {
3260        let coded_width = usize::try_from(width)
3261            .map_err(|_| BridgeError::InvalidInput("negative frame width"))?;
3262        let coded_height = usize::try_from(height)
3263            .map_err(|_| BridgeError::InvalidInput("negative frame height"))?;
3264        if coded_width == 0 || coded_height == 0 {
3265            return Err(BridgeError::InvalidInput("empty frame"));
3266        }
3267        let planes = plane_geometry(format, width, height)?;
3268        let frame = zeroed_frame(width, height, format)?;
3269        for (index, &(row_bytes, _)) in planes.iter().enumerate() {
3270            if frame.data[index].is_null()
3271                || plane_stride(frame.linesize[index], row_bytes).is_err()
3272            {
3273                return Err(BridgeError::InvalidInput(
3274                    "the frame's planes do not match its pixel format",
3275                ));
3276            }
3277        }
3278        Ok(Self {
3279            frame,
3280            width: coded_width,
3281            height: coded_height,
3282            planes,
3283        })
3284    }
3285
3286    /// Each plane's visible bytes per row and rows, in `FFmpeg`'s plane order.
3287    #[must_use]
3288    pub fn planes(&self) -> &[(usize, usize)] {
3289        &self.planes
3290    }
3291
3292    /// Each plane's memory and stride after making the frame unshared, for any format.
3293    ///
3294    /// # Errors
3295    /// As [`Self::begin_write`].
3296    pub fn begin_write_planes(&mut self) -> Result<Vec<(&mut [u8], usize)>, BridgeError> {
3297        self.make_writable()?;
3298        let mut written = Vec::with_capacity(self.planes.len());
3299        for (index, &(row_bytes, rows)) in self.planes.iter().enumerate() {
3300            let stride = plane_stride(self.frame.linesize[index], row_bytes)?;
3301            // SAFETY: `writable_plane` checks the rows lie in one of the frame's buffers, and
3302            // `make_writable` left this frame their sole owner.
3303            let plane = unsafe { writable_plane(&self.frame, index, stride, row_bytes, rows)? };
3304            written.push((plane, stride));
3305        }
3306        Ok(written)
3307    }
3308
3309    fn make_writable(&mut self) -> Result<(), BridgeError> {
3310        // Not `av_frame_make_writable`: it leaves SIMD row padding unwritten under slices that span
3311        // it.
3312        if !self.frame.is_writable().map_err(BridgeError::Ffmpeg)? {
3313            let mut copy = zeroed_frame(self.frame.width, self.frame.height, self.frame.format)?;
3314            // SAFETY: both frames are live with one size and format; `copy` is unshared and
3315            // `self.frame` is only read.
3316            let status = unsafe {
3317                let copied = ffi::av_frame_copy(copy.as_mut_ptr(), self.frame.as_ptr());
3318                if copied < 0 {
3319                    copied
3320                } else {
3321                    ffi::av_frame_copy_props(copy.as_mut_ptr(), self.frame.as_ptr())
3322                }
3323            };
3324            if status < 0 {
3325                return Err(BridgeError::FfmpegCode(status));
3326            }
3327            self.frame = copy;
3328        }
3329        Ok(())
3330    }
3331
3332    /// Luma width and height in pixels.
3333    #[must_use]
3334    pub const fn dimensions(&self) -> (usize, usize) {
3335        (self.width, self.height)
3336    }
3337
3338    /// Returns the plane memory to overwrite, after making the frame unshared.
3339    ///
3340    /// # Errors
3341    /// Returns an error when the buffer cannot be made writable or its planes changed layout.
3342    pub fn begin_write(&mut self) -> Result<Yuv420pFramePlanes<'_>, BridgeError> {
3343        if self.frame.format != ffi::AV_PIX_FMT_YUV420P {
3344            return Err(BridgeError::InvalidInput("the frame is not YUV420P"));
3345        }
3346        let mut planes = self.begin_write_planes()?.into_iter();
3347        let (Some((y, y_stride)), Some((u, u_stride)), Some((v, v_stride))) =
3348            (planes.next(), planes.next(), planes.next())
3349        else {
3350            return Err(BridgeError::InvalidInput("the frame is not YUV420P"));
3351        };
3352        if u_stride != v_stride {
3353            return Err(BridgeError::InvalidInput("mismatched chroma strides"));
3354        }
3355        Ok(Yuv420pFramePlanes {
3356            y,
3357            y_stride,
3358            u,
3359            v,
3360            chroma_stride: u_stride,
3361        })
3362    }
3363
3364    /// Stamps the presentation timestamp this frame will be encoded with.
3365    pub fn set_presentation(&mut self, pts: i64, time_base: ffi::AVRational) {
3366        self.frame.set_pts(pts);
3367        self.frame.set_time_base(time_base);
3368    }
3369
3370    /// The frame to hand to an encoder.
3371    #[must_use]
3372    pub const fn frame(&self) -> &AVFrame {
3373        &self.frame
3374    }
3375
3376    /// Bytes of the visible planes, without row padding.
3377    #[must_use]
3378    pub fn visible_bytes(&self) -> usize {
3379        if self.planes.is_empty() {
3380            let chroma = self.width.div_ceil(2) * self.height.div_ceil(2);
3381            return self.width * self.height + 2 * chroma;
3382        }
3383        self.planes
3384            .iter()
3385            .map(|&(row_bytes, rows)| row_bytes * rows)
3386            .sum()
3387    }
3388
3389    /// Coded luma dimensions this buffer was allocated for.
3390    #[must_use]
3391    pub const fn size(&self) -> (usize, usize) {
3392        (self.width, self.height)
3393    }
3394}
3395
3396/// A frame of `format` with tightly packed rows, every byte of it zero.
3397fn zeroed_frame(
3398    width: i32,
3399    height: i32,
3400    format: ffi::AVPixelFormat,
3401) -> Result<AVFrame, BridgeError> {
3402    let mut frame = AVFrame::new();
3403    frame.set_format(format);
3404    frame.set_width(width);
3405    frame.set_height(height);
3406    frame.get_buffer(1)?;
3407    for buffer in frame.buf {
3408        // SAFETY: a non-null `AVFrame::buf` entry is live, and this new frame is its only owner.
3409        if let Some(buffer) = unsafe { buffer.as_ref() } {
3410            // SAFETY: as above.
3411            unsafe { ptr::write_bytes(buffer.data, 0, buffer.size) };
3412        }
3413    }
3414    Ok(frame)
3415}
3416
3417impl fmt::Debug for Yuv420pFrameBuffer {
3418    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
3419        formatter
3420            .debug_struct("Yuv420pFrameBuffer")
3421            .field("width", &self.width)
3422            .field("height", &self.height)
3423            .finish_non_exhaustive()
3424    }
3425}
3426
3427fn plane_stride(linesize: i32, width: usize) -> Result<usize, BridgeError> {
3428    let stride = usize::try_from(linesize)
3429        .map_err(|_| BridgeError::InvalidInput("negative frame linesize"))?;
3430    if stride < width {
3431        return Err(BridgeError::InvalidInput(
3432            "frame linesize is below its width",
3433        ));
3434    }
3435    Ok(stride)
3436}
3437
3438/// Plane `index` of `frame` as `rows` rows of `stride` bytes, the last one `row_bytes` long.
3439///
3440/// # Safety
3441/// The caller must solely own the frame's buffers for the slice's lifetime.
3442unsafe fn writable_plane<'a>(
3443    frame: &AVFrame,
3444    index: usize,
3445    stride: usize,
3446    row_bytes: usize,
3447    rows: usize,
3448) -> Result<&'a mut [u8], BridgeError> {
3449    let data = frame.data[index];
3450    if data.is_null() {
3451        return Err(BridgeError::InvalidInput("frame plane is null"));
3452    }
3453    let len = stride
3454        .checked_mul(rows.saturating_sub(1))
3455        .and_then(|before| before.checked_add(row_bytes))
3456        .ok_or(BridgeError::InvalidInput("frame plane size overflow"))?;
3457    if !in_frame_buffer(frame, data as usize, len) {
3458        return Err(BridgeError::InvalidInput(
3459            "frame plane extends past its buffer",
3460        ));
3461    }
3462    // SAFETY: the range lies in one of the frame's buffers; exclusivity is the caller's.
3463    Ok(unsafe { slice::from_raw_parts_mut(data, len) })
3464}
3465
3466/// Whether `len` bytes from address `start` lie inside one of `frame`'s buffers.
3467fn in_frame_buffer(frame: &AVFrame, start: usize, len: usize) -> bool {
3468    let Some(end) = start.checked_add(len) else {
3469        return false;
3470    };
3471    frame.buf.iter().any(|buffer| {
3472        // SAFETY: a non-null `AVFrame::buf` entry is a live `AVBufferRef` the frame holds.
3473        let Some(buffer) = (unsafe { buffer.as_ref() }) else {
3474            return false;
3475        };
3476        let buffer_start = buffer.data as usize;
3477        buffer_start
3478            .checked_add(buffer.size)
3479            .is_some_and(|buffer_end| buffer_start <= start && end <= buffer_end)
3480    })
3481}
3482
3483/// Visible bytes per row and rows of each plane of a `width` by `height` frame of `format`.
3484fn plane_geometry(
3485    format: ffi::AVPixelFormat,
3486    width: i32,
3487    height: i32,
3488) -> Result<Vec<(usize, usize)>, BridgeError> {
3489    // SAFETY: `av_pix_fmt_desc_get` accepts any value and returns null or a static descriptor.
3490    let descriptor = unsafe { ffi::av_pix_fmt_desc_get(format).as_ref() }
3491        .ok_or(BridgeError::InvalidInput("pixel format has no descriptor"))?;
3492    // SAFETY: a pure computation over plain values.
3493    let count = unsafe { ffi::av_pix_fmt_count_planes(format) };
3494    let count = usize::try_from(count)
3495        .ok()
3496        .filter(|count| (1..=4).contains(count))
3497        .ok_or(BridgeError::InvalidInput("pixel format has no planes"))?;
3498    let rows = usize::try_from(height).map_err(|_| BridgeError::InvalidInput("negative height"))?;
3499    (0..count)
3500        .map(|index| {
3501            let plane = i32::try_from(index).unwrap_or(i32::MAX);
3502            // SAFETY: a pure computation over plain values.
3503            let row_bytes = unsafe { ffi::av_image_get_linesize(format, width, plane) };
3504            let row_bytes =
3505                usize::try_from(row_bytes).map_err(|_| BridgeError::FfmpegCode(row_bytes))?;
3506            let rows = if index == 1 || index == 2 {
3507                rows.div_ceil(1 << descriptor.log2_chroma_h)
3508            } else {
3509                rows
3510            };
3511            Ok((row_bytes, rows))
3512        })
3513        .collect()
3514}
3515
3516#[cfg(all(test, target_os = "linux", feature = "hwdevice"))]
3517mod vulkan_shim_tests;
3518
3519#[cfg(all(test, target_os = "linux", feature = "hwdevice"))]
3520mod vulkan_access_tests;
3521
3522#[cfg(test)]
3523mod tests;