videotoolbox 0.21.0

//! [`DecompressionSession`] — hardware H.264/HEVC/ProRes decoder.
//!
//! Mirror of [`crate::compression::CompressionSession`] for the decoder
//! direction. Feed `CMSampleBuffer`s in via [`DecompressionSession::decode`],
//! receive `CVPixelBuffer`s out via the callback you registered at construction.

use core::ffi::c_void;
use core::ptr;
use std::sync::{Arc, Mutex};

use apple_cf::cf::{AsCFType, CFDictionary, CFType};
use apple_cf::cm::CMTime;
#[cfg(feature = "async")]
use doom_fish_utils::completion::AsyncCompletion;
use doom_fish_utils::panic_safe::catch_user_panic;

use crate::error::VTError;
use crate::ffi;
use crate::session::{self, Codec};
use crate::tagged_buffer_group::TaggedBufferGroup;

/// One decoded video frame.
pub struct DecodedFrame {
    /// Underlying `CVImageBuffer` (typically a `CVPixelBuffer`) — `None`
    /// when the decoder dropped or skipped a frame.
    pub image_buffer: Option<apple_cf::cv::CVPixelBuffer>,
    /// Presentation timestamp of the source sample buffer.
    pub presentation_time: CMTime,
    /// Presentation duration of the decoded frame.
    pub duration: CMTime,
    /// Decoder hint flags (asynchronous / image-buffer-modifiable / etc.).
    pub info_flags: ffi::VTDecodeInfoFlags,
    /// Apple's decoder status code. 0 indicates success.
    pub status: i32,
}

/// One decoded multi-image frame.
pub struct DecodedMultiImageFrame {
    /// Multi-image output (for example left/right eye pixel buffers).
    pub tagged_buffer_group: Option<TaggedBufferGroup>,
    /// Presentation timestamp of the source sample buffer.
    pub presentation_time: CMTime,
    /// Presentation duration of the decoded frame.
    pub duration: CMTime,
    /// Decoder hint flags (asynchronous / image-buffer-modifiable / etc.).
    pub info_flags: ffi::VTDecodeInfoFlags,
    /// Apple's decoder status code. 0 indicates success.
    pub status: i32,
}

type DecodeCallback = Box<dyn FnMut(DecodedFrame) + Send + 'static>;
type MultiImageDecodeCallback = Box<dyn FnMut(DecodedMultiImageFrame) + Send + 'static>;

struct CallbackState {
    callback: Mutex<DecodeCallback>,
    multi_image_callback: Mutex<Option<MultiImageDecodeCallback>>,
}

/// Hardware video decompression session.
///
/// Build with [`DecompressionSession::new`] passing a format description
/// (from the encoder side, or extracted from your input file). Decoded
/// frames flow through the callback you supply.
///
/// # Lifetime / threading
///
/// Drop the session to invalidate it. Decoder callbacks fire on Apple's
/// internal queue — they may run after `decode()` returns and before
/// `wait_for_async_frames()`.
pub struct DecompressionSession {
    session: ffi::VTDecompressionSessionRef,
    state: Arc<CallbackState>,
    callback_ref_con: *const CallbackState,
}

unsafe impl Send for DecompressionSession {}

impl DecompressionSession {
    /// CoreFoundation type identifier for `VTDecompressionSession`.
    #[must_use]
    pub fn type_id() -> usize {
        // SAFETY: `VTDecompressionSessionGetTypeID` is a standard Apple SDK function
        // that returns a static type ID. Safe to call from any thread.
        unsafe { ffi::VTDecompressionSessionGetTypeID() }
    }

    /// Returns `true` when the current machine advertises hardware decode for
    /// the given codec family.
    #[must_use]
    pub fn is_hardware_decode_supported(codec: Codec) -> bool {
        // SAFETY: `VTIsHardwareDecodeSupported` is a standard query function
        // that performs no I/O and has no side effects.
        unsafe { ffi::VTIsHardwareDecodeSupported(codec.as_cm_codec_type()) != 0 }
    }

    /// Returns `true` when the current machine advertises stereo MV-HEVC
    /// decode support.
    #[must_use]
    pub fn is_stereo_mvhevc_decode_supported() -> bool {
        ffi::dynamic::VTIsStereoMVHEVCDecodeSupported()
            .is_ok_and(|is_supported| unsafe { is_supported() } != 0)
    }

    /// Open a decompression session for the given format description.
    /// `format_description` is the `CMFormatDescriptionRef` Apple expects
    /// — typically obtained from `CMSampleBuffer.format_description()` on
    /// the first sample of the stream.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::EncoderCallback`] wrapping the raw `OSStatus`
    /// if `VTDecompressionSessionCreate` fails.
    pub fn new<F>(
        format_description: &apple_cf::cm::CMFormatDescription,
        callback: F,
    ) -> Result<Self, VTError>
    where
        F: FnMut(DecodedFrame) + Send + 'static,
    {
        Self::new_with_image_buffer_attributes(format_description, None, callback)
    }

    /// Like [`new`](Self::new) but lets you specify the decoder's destination
    /// image-buffer attributes (the `destinationImageBufferAttributes` argument
    /// to `VTDecompressionSessionCreate`).
    ///
    /// Use this to force the output pixel format (for example a `420f`
    /// full-range NV12 buffer required by some renderers) or to require
    /// `IOSurface` backing for zero-copy GPU interop, by passing a dictionary
    /// keyed on `kCVPixelBufferPixelFormatTypeKey` /
    /// `kCVPixelBufferIOSurfacePropertiesKey`.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::EncoderCallback`] wrapping the raw `OSStatus`
    /// if `VTDecompressionSessionCreate` fails.
    pub fn new_with_image_buffer_attributes<F>(
        format_description: &apple_cf::cm::CMFormatDescription,
        image_buffer_attributes: Option<&CFDictionary>,
        callback: F,
    ) -> Result<Self, VTError>
    where
        F: FnMut(DecodedFrame) + Send + 'static,
    {
        let state = Arc::new(CallbackState {
            callback: Mutex::new(Box::new(callback)),
            multi_image_callback: Mutex::new(None),
        });
        let callback_ref_con = Arc::into_raw(Arc::clone(&state));
        let ref_con = callback_ref_con.cast::<c_void>().cast_mut();

        let record = ffi::VTDecompressionOutputCallbackRecord {
            decompression_output_callback: decode_trampoline,
            decompression_output_ref_con: ref_con,
        };

        let mut session: ffi::VTDecompressionSessionRef = ptr::null_mut();
        let status = unsafe {
            ffi::VTDecompressionSessionCreate(
                ffi::kCFAllocatorDefault,
                format_description.as_ptr().cast(),
                ptr::null(),
                image_buffer_attributes.map_or(ptr::null(), |d| AsCFType::as_ptr(d).cast()),
                &raw const record,
                &raw mut session,
            )
        };
        if status != 0 || session.is_null() {
            unsafe { drop(Arc::from_raw(callback_ref_con)) };
            return Err(VTError::EncoderCallback(if status == 0 {
                -1
            } else {
                status
            }));
        }
        Ok(Self {
            session,
            state,
            callback_ref_con,
        })
    }

    /// Decode `sample_buffer`. The callback you registered at construction
    /// will fire with the resulting [`DecodedFrame`] — either synchronously
    /// before this method returns, or asynchronously after, depending on
    /// the decoder backend.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::EncoderCallback`] wrapping the raw `OSStatus`
    /// if `VTDecompressionSessionDecodeFrame` rejects the sample buffer.
    pub fn decode(&self, sample_buffer: &apple_cf::cm::CMSampleBuffer) -> Result<(), VTError> {
        self.decode_with_options(sample_buffer, 0, None).map(|_| ())
    }

    /// Decode `sample_buffer` with explicit `VTDecodeFrameFlags` and optional
    /// per-frame `kVTDecodeFrameOptionKey_*` entries.
    ///
    /// Returns the `VTDecodeInfoFlags` reported for the submit operation.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::Unsupported`] if `frame_options` is set before
    /// macOS 15.0 (`VTDecompressionSessionDecodeFrameWithOptions`), or
    /// [`VTError::EncoderCallback`] wrapping the raw `OSStatus` if the decoder
    /// rejects the sample buffer.
    pub fn decode_with_options(
        &self,
        sample_buffer: &apple_cf::cm::CMSampleBuffer,
        decode_flags: ffi::VTDecodeFrameFlags,
        frame_options: Option<&CFDictionary>,
    ) -> Result<ffi::VTDecodeInfoFlags, VTError> {
        let mut info_flags: ffi::VTDecodeInfoFlags = 0;
        let status = match frame_options {
            None => unsafe {
                ffi::VTDecompressionSessionDecodeFrame(
                    self.session,
                    sample_buffer.as_ptr().cast(),
                    decode_flags,
                    ptr::null_mut(),
                    &raw mut info_flags,
                )
            },
            Some(frame_options) => {
                let decode = ffi::dynamic::VTDecompressionSessionDecodeFrameWithOptions()?;
                unsafe {
                    decode(
                        self.session,
                        sample_buffer.as_ptr().cast(),
                        decode_flags,
                        frame_options.as_ptr().cast_const().cast(),
                        ptr::null_mut(),
                        &raw mut info_flags,
                    )
                }
            }
        };
        if status == 0 {
            Ok(info_flags)
        } else {
            Err(VTError::EncoderCallback(status))
        }
    }

    /// Submit `sample_buffer` for decoding and await the decoded `CVImageBuffer`.
    ///
    /// This method requires the crate's `async` feature.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::UnexpectedSampleCount`] if `sample_buffer` does not
    /// contain exactly one sample. Returns [`VTError::EncoderCallback`] if the
    /// decoder rejects the frame, reports an asynchronous failure, or completes
    /// without an image buffer.
    #[cfg(feature = "async")]
    #[cfg_attr(docsrs, doc(cfg(feature = "async")))]
    #[allow(clippy::future_not_send)]
    pub async fn decode_frame_async(
        &self,
        sample_buffer: apple_cf::cm::CMSampleBuffer,
        frame_flags: u32,
    ) -> Result<apple_cf::cv::CVImageBuffer, VTError> {
        validate_async_sample_count(&sample_buffer)?;

        let (future, completion) = AsyncCompletion::<apple_cf::cv::CVImageBuffer>::create();
        let status = unsafe {
            ffi::VTDecompressionSessionDecodeFrame(
                self.session,
                sample_buffer.as_ptr().cast(),
                frame_flags,
                completion,
                ptr::null_mut(),
            )
        };
        if status != 0 {
            unsafe {
                AsyncCompletion::<apple_cf::cv::CVImageBuffer>::complete_err(
                    completion,
                    status.to_string(),
                );
            };
            return Err(VTError::EncoderCallback(status));
        }

        future
            .await
            .map_err(|error| VTError::EncoderCallback(parse_async_status(&error)))
    }

    /// Install a callback that receives multi-image output when the decoder
    /// produces a `CMTaggedBufferGroup` instead of a single `CVImageBuffer`.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::Unsupported`] before macOS 14.0, or
    /// [`VTError::ApiFailed`] if the decoder rejects the callback.
    pub fn set_multi_image_callback<F>(&self, callback: F) -> Result<(), VTError>
    where
        F: FnMut(DecodedMultiImageFrame) + Send + 'static,
    {
        let set_callback = ffi::dynamic::VTDecompressionSessionSetMultiImageCallback()?;
        {
            let mut slot = self
                .state
                .multi_image_callback
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner);
            *slot = Some(Box::new(callback));
        }

        let status = unsafe {
            set_callback(
                self.session,
                decode_multi_image_trampoline,
                Arc::as_ptr(&self.state).cast::<c_void>().cast_mut(),
            )
        };
        if status != 0 {
            let mut slot = self
                .state
                .multi_image_callback
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner);
            *slot = None;
            drop(slot);
            return Err(VTError::ApiFailed {
                api: "VTDecompressionSessionSetMultiImageCallback",
                status,
            });
        }
        Ok(())
    }

    /// Wait for any queued async decodes to complete. Equivalent to
    /// `VTDecompressionSessionWaitForAsynchronousFrames`. Call this
    /// before dropping the session if you want to be sure every frame's
    /// callback has fired.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::EncoderCallback`] on a non-zero `OSStatus`.
    pub fn wait_for_async_frames(&self) -> Result<(), VTError> {
        let status = unsafe { ffi::VTDecompressionSessionWaitForAsynchronousFrames(self.session) };
        if status == 0 {
            Ok(())
        } else {
            Err(VTError::EncoderCallback(status))
        }
    }

    /// Drain pending callbacks, invalidate the decoder, and release its native resources.
    ///
    /// Unlike `Drop`, this surfaces a failure to prove that callbacks are
    /// quiescent. On that exceptional path the native callback context is kept
    /// alive to prevent an in-flight callback from observing freed Rust state.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::ApiFailed`] if
    /// `VTDecompressionSessionWaitForAsynchronousFrames` fails.
    pub fn invalidate(mut self) -> Result<(), VTError> {
        self.teardown()
    }

    /// Copy a black pixel buffer matching the session's current output format.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::ApiFailed`] on a non-zero `OSStatus`.
    pub fn copy_black_pixel_buffer(&self) -> Result<apple_cf::cv::CVPixelBuffer, VTError> {
        let mut out = ptr::null_mut();
        let status =
            unsafe { ffi::VTDecompressionSessionCopyBlackPixelBuffer(self.session, &raw mut out) };
        if status != 0 || out.is_null() {
            return Err(VTError::ApiFailed {
                api: "VTDecompressionSessionCopyBlackPixelBuffer",
                status,
            });
        }
        unsafe { apple_cf::cv::CVPixelBuffer::from_raw(out.cast()) }.ok_or(VTError::ApiFailed {
            api: "VTDecompressionSessionCopyBlackPixelBuffer",
            status,
        })
    }

    /// Copy one `VTSession` property from the decoder.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::ApiFailed`] if the underlying property query fails.
    ///
    /// # Safety
    ///
    /// `key` must be a valid CoreFoundation string pointer accepted by
    /// `VTSessionCopyProperty` for a decompression session.
    pub unsafe fn copy_property(&self, key: ffi::CFStringRef) -> Result<Option<CFType>, VTError> {
        session::copy_property(self.session.cast(), key)
    }

    /// Copy the decoder's supported-property dictionary.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::ApiFailed`] if the query fails.
    pub fn supported_property_dictionary(&self) -> Result<CFDictionary, VTError> {
        unsafe { session::copy_supported_property_dictionary(self.session.cast()) }
    }

    /// Copy the decoder's serializable property dictionary.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::ApiFailed`] if the query fails.
    pub fn serializable_properties(&self) -> Result<CFDictionary, VTError> {
        unsafe { session::copy_serializable_properties(self.session.cast()) }
    }

    /// Set multiple decoder properties at once.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::ApiFailed`] if `VideoToolbox` rejects the dictionary.
    pub fn set_properties(&self, properties: &CFDictionary) -> Result<(), VTError> {
        unsafe { session::set_properties(self.session.cast(), properties) }
    }

    /// Set an arbitrary property on the underlying
    /// `VTDecompressionSession`. `value` must be a CoreFoundation
    /// object matching Apple's per-key contract (see
    /// `VTDecompressionProperties.h`).
    ///
    /// # Errors
    ///
    /// Returns [`VTError::SetPropertyFailed`] if Apple rejects the
    /// key/value pair.
    ///
    /// # Safety
    ///
    /// `key` must be a valid `CFStringRef` and `value` must be a
    /// valid CoreFoundation pointer for the property's expected type.
    pub unsafe fn set_property(
        &self,
        key: ffi::CFStringRef,
        value: ffi::CFTypeRef,
    ) -> Result<(), VTError> {
        let status = ffi::VTSessionSetProperty(self.session.cast(), key, value);
        if status != 0 {
            return Err(VTError::SetPropertyFailed {
                key: "<custom>".to_string(),
                status,
            });
        }
        Ok(())
    }

    /// Tell the decoder that this is real-time playback (prioritise
    /// low latency over throughput). Wraps the boolean property
    /// `kVTDecompressionPropertyKey_RealTime`.
    ///
    /// # Errors
    ///
    /// See [`Self::set_property`].
    pub fn set_real_time(&self, real_time: bool) -> Result<(), VTError> {
        let v = unsafe {
            if real_time {
                ffi::kCFBooleanTrue
            } else {
                ffi::kCFBooleanFalse
            }
        };
        unsafe { self.set_property(ffi::kVTDecompressionPropertyKey_RealTime, v.cast()) }
    }

    /// Finish any decoded frames the decoder has been holding back
    /// for B-frame reordering. Wraps
    /// `VTDecompressionSessionFinishDelayedFrames`.
    ///
    /// # Errors
    ///
    /// Returns [`VTError::EncoderCallback`] on non-zero `OSStatus`.
    pub fn finish_delayed_frames(&self) -> Result<(), VTError> {
        let status = unsafe { ffi::VTDecompressionSessionFinishDelayedFrames(self.session) };
        if status == 0 {
            Ok(())
        } else {
            Err(VTError::EncoderCallback(status))
        }
    }

    /// True if this session can decode samples described by `format`
    /// without rebuilding the session. Wraps
    /// `VTDecompressionSessionCanAcceptFormatDescription`.
    ///
    /// # Safety
    ///
    /// `format` must be a valid `CMFormatDescriptionRef` (typically
    /// obtained from another `CMSampleBuffer`).
    #[must_use]
    pub unsafe fn can_accept_format(&self, format: ffi::CMFormatDescriptionRef) -> bool {
        ffi::VTDecompressionSessionCanAcceptFormatDescription(self.session, format)
    }

    fn teardown(&mut self) -> Result<(), VTError> {
        if self.session.is_null() {
            return Ok(());
        }

        let wait_status =
            unsafe { ffi::VTDecompressionSessionWaitForAsynchronousFrames(self.session) };
        unsafe {
            ffi::VTDecompressionSessionInvalidate(self.session);
            ffi::CFRelease(self.session.cast());
        }
        self.session = ptr::null_mut();

        if wait_status == 0 {
            self.release_callback_ref_con();
            Ok(())
        } else {
            // A failed drain cannot prove that native code is done with the ref-con.
            self.callback_ref_con = ptr::null();
            Err(VTError::ApiFailed {
                api: "VTDecompressionSessionWaitForAsynchronousFrames",
                status: wait_status,
            })
        }
    }

    fn release_callback_ref_con(&mut self) {
        let callback_ref_con = core::mem::replace(&mut self.callback_ref_con, ptr::null());
        if !callback_ref_con.is_null() {
            unsafe { drop(Arc::from_raw(callback_ref_con)) };
        }
    }
}

impl Drop for DecompressionSession {
    fn drop(&mut self) {
        let _ = self.teardown();
    }
}

#[cfg(feature = "async")]
fn parse_async_status(error: &str) -> ffi::OSStatus {
    error.parse().unwrap_or(-1)
}

#[cfg(feature = "async")]
fn validate_async_sample_count(
    sample_buffer: &apple_cf::cm::CMSampleBuffer,
) -> Result<(), VTError> {
    let actual = sample_buffer.num_samples();
    if actual == 1 {
        Ok(())
    } else {
        Err(VTError::UnexpectedSampleCount {
            operation: "DecompressionSession::decode_frame_async",
            expected: 1,
            actual,
        })
    }
}

#[cfg(feature = "async")]
fn complete_async_decode(
    source_frame_ref_con: *mut c_void,
    status: ffi::OSStatus,
    image_buffer: *mut c_void,
) {
    catch_user_panic("videotoolbox::decompression::decode_frame_async", || {
        if status != 0 {
            unsafe {
                AsyncCompletion::<apple_cf::cv::CVImageBuffer>::complete_err(
                    source_frame_ref_con,
                    status.to_string(),
                );
            };
            return;
        }

        if image_buffer.is_null() {
            unsafe {
                AsyncCompletion::<apple_cf::cv::CVImageBuffer>::complete_err(
                    source_frame_ref_con,
                    "-1".into(),
                );
            };
            return;
        }

        let Some(image_buffer) =
            (unsafe { apple_cf::cv::CVImageBuffer::from_raw_borrowed(image_buffer) })
        else {
            unsafe {
                AsyncCompletion::<apple_cf::cv::CVImageBuffer>::complete_err(
                    source_frame_ref_con,
                    "-1".into(),
                );
            };
            return;
        };

        unsafe {
            AsyncCompletion::<apple_cf::cv::CVImageBuffer>::complete_ok(
                source_frame_ref_con,
                image_buffer,
            );
        };
    });
}

unsafe extern "C" fn decode_trampoline(
    output_ref_con: *mut c_void,
    source_frame_ref_con: *mut c_void,
    status: ffi::OSStatus,
    info_flags: ffi::VTDecodeInfoFlags,
    image_buffer: *mut c_void,
    pts: ffi::CMTime,
    duration: ffi::CMTime,
) {
    #[cfg(not(feature = "async"))]
    let _ = source_frame_ref_con;
    #[cfg(feature = "async")]
    if !source_frame_ref_con.is_null() {
        complete_async_decode(source_frame_ref_con, status, image_buffer);
        return;
    }

    if output_ref_con.is_null() {
        return;
    }
    // Borrow the Arc without consuming the reference held by the session.
    let state = unsafe { Arc::from_raw(output_ref_con.cast::<CallbackState>()) };
    let state_clone = state.clone();
    core::mem::forget(state);

    let image = if image_buffer.is_null() {
        None
    } else {
        unsafe { apple_cf::cv::CVPixelBuffer::from_raw_borrowed(image_buffer) }
    };

    let frame = DecodedFrame {
        image_buffer: image,
        presentation_time: pts,
        duration,
        info_flags,
        status,
    };

    let Ok(mut guard) = state_clone.callback.lock() else {
        return;
    };
    // The user closure may panic. Unwinding across this `extern "C"` boundary
    // back into VideoToolbox is undefined behaviour, so guard the invocation.
    catch_user_panic("videotoolbox::decompression::decode_callback", || {
        guard(frame);
    });
}

unsafe extern "C" fn decode_multi_image_trampoline(
    output_ref_con: *mut c_void,
    source_frame_ref_con: *mut c_void,
    status: ffi::OSStatus,
    info_flags: ffi::VTDecodeInfoFlags,
    tagged_buffer_group: ffi::CMTaggedBufferGroupRef,
    pts: ffi::CMTime,
    duration: ffi::CMTime,
) {
    #[cfg(not(feature = "async"))]
    let _ = source_frame_ref_con;
    #[cfg(feature = "async")]
    if !source_frame_ref_con.is_null() {
        complete_async_decode(source_frame_ref_con, status, ptr::null_mut());
        return;
    }

    if output_ref_con.is_null() {
        return;
    }
    let state = unsafe { Arc::from_raw(output_ref_con.cast::<CallbackState>()) };
    let state_clone = state.clone();
    core::mem::forget(state);

    let frame = DecodedMultiImageFrame {
        tagged_buffer_group: unsafe { TaggedBufferGroup::from_raw_retained(tagged_buffer_group) },
        presentation_time: pts,
        duration,
        info_flags,
        status,
    };

    let Ok(mut guard) = state_clone.multi_image_callback.lock() else {
        return;
    };
    let Some(callback) = guard.as_mut() else {
        return;
    };
    // The user closure may panic; unwinding across this `extern "C"` boundary
    // back into VideoToolbox is undefined behaviour, so guard the invocation.
    catch_user_panic("videotoolbox::decompression::multi_image_callback", || {
        callback(frame);
    });
}

#[cfg(test)]
mod tests {
    use core::ptr;
    use std::sync::{Arc, Mutex};

    use apple_cf::cm::CMTime;

    use super::{decode_multi_image_trampoline, CallbackState};

    fn state() -> Arc<CallbackState> {
        Arc::new(CallbackState {
            callback: Mutex::new(Box::new(|_| {})),
            multi_image_callback: Mutex::new(None),
        })
    }

    #[cfg(feature = "async")]
    fn deliver_to_pending_decode(status: i32) -> Result<apple_cf::cv::CVImageBuffer, String> {
        use doom_fish_utils::completion::AsyncCompletion;

        let state = state();
        let (future, context) = AsyncCompletion::<apple_cf::cv::CVImageBuffer>::create();
        unsafe {
            decode_multi_image_trampoline(
                Arc::as_ptr(&state).cast_mut().cast(),
                context,
                status,
                0,
                ptr::null_mut(),
                CMTime::new(1, 30),
                CMTime::new(1, 30),
            );
        }
        pollster::block_on(future)
    }

    #[cfg(feature = "async")]
    #[test]
    fn multi_image_failure_resolves_the_pending_async_decode() {
        assert_eq!(
            deliver_to_pending_decode(-12909).err().as_deref(),
            Some("-12909")
        );
    }

    #[cfg(feature = "async")]
    #[test]
    fn multi_image_output_without_an_image_buffer_resolves_the_async_decode() {
        assert_eq!(deliver_to_pending_decode(0).err().as_deref(), Some("-1"));
    }

    #[test]
    fn multi_image_output_without_a_frame_context_reaches_the_callback() {
        let received = Arc::new(Mutex::new(Vec::new()));
        let sink = Arc::clone(&received);
        let state = state();
        *state.multi_image_callback.lock().expect("unpoisoned") =
            Some(Box::new(move |frame: super::DecodedMultiImageFrame| {
                sink.lock().expect("unpoisoned").push((
                    frame.status,
                    frame.presentation_time,
                    frame.duration,
                ));
            }));

        unsafe {
            decode_multi_image_trampoline(
                Arc::as_ptr(&state).cast_mut().cast(),
                ptr::null_mut(),
                -12909,
                0,
                ptr::null_mut(),
                CMTime::new(3, 30),
                CMTime::new(1, 30),
            );
        }

        assert_eq!(
            *received.lock().expect("unpoisoned"),
            [(-12909, CMTime::new(3, 30), CMTime::new(1, 30))]
        );
    }

    #[test]
    fn panicking_multi_image_callback_is_contained() {
        let state = state();
        *state.multi_image_callback.lock().expect("unpoisoned") =
            Some(Box::new(|_| panic!("callback panic")));

        unsafe {
            decode_multi_image_trampoline(
                Arc::as_ptr(&state).cast_mut().cast(),
                ptr::null_mut(),
                0,
                0,
                ptr::null_mut(),
                CMTime::new(0, 30),
                CMTime::new(1, 30),
            );
        }
    }
}