objc2_video_toolbox/generated/

VTCompressionSession.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::cell::UnsafeCell;
use core::ffi::*;
use core::marker::{PhantomData, PhantomPinned};
use core::ptr::NonNull;
#[cfg(feature = "objc2")]
use objc2::__framework_prelude::*;
use objc2_core_foundation::*;
#[cfg(feature = "objc2-core-media")]
use objc2_core_media::*;
#[cfg(feature = "objc2-core-video")]
use objc2_core_video::*;

use crate::*;

/// A reference to a Video Toolbox Compression Session.
///
/// A compression session supports the compression of a sequence of video frames.
/// The session reference is a reference-counted CF object.
/// To create a compression session, call VTCompressionSessionCreate;
/// then you can optionally configure the session using VTSessionSetProperty;
/// then to encode frames, call VTCompressionSessionEncodeFrame.
/// To force completion of some or all pending frames, call VTCompressionSessionCompleteFrames.
/// When you are done with the session, you should call VTCompressionSessionInvalidate
/// to tear it down and CFRelease to release your object reference.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/videotoolbox/vtcompressionsession?language=objc)
#[repr(C)]
pub struct VTCompressionSession {
    inner: [u8; 0],
    _p: UnsafeCell<PhantomData<(*const UnsafeCell<()>, PhantomPinned)>>,
}

cf_type!(
    #[encoding_name = "OpaqueVTCompressionSession"]
    unsafe impl VTCompressionSession {}
);

/// Prototype for callback invoked when frame compression is complete.
///
/// When you create a compression session, you pass in a callback function to be called
/// for compressed frames.  This function will be called in decode order (which is not
/// necessarily the same as display order).
///
/// Parameter `outputCallbackRefCon`: The callback's reference value.
///
/// Parameter `sourceFrameRefCon`: The frame's reference value, copied from the sourceFrameRefCon argument to
/// VTCompressionSessionEncodeFrame.
///
/// Parameter `status`: noErr if compression was successful; an error code if compression was not successful.
///
/// Parameter `infoFlags`: Contains information about the encode operation.
/// The kVTEncodeInfo_Asynchronous bit may be set if the encode ran asynchronously.
/// The kVTEncodeInfo_FrameDropped bit may be set if the frame was dropped.
///
/// Parameter `sampleBuffer`: Contains the compressed frame, if compression was successful and the frame was not dropped;
/// otherwise, NULL.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/videotoolbox/vtcompressionoutputcallback?language=objc)
#[cfg(all(feature = "VTErrors", feature = "objc2-core-media"))]
pub type VTCompressionOutputCallback = Option<
    unsafe extern "C-unwind" fn(
        *mut c_void,
        *mut c_void,
        OSStatus,
        VTEncodeInfoFlags,
        *mut CMSampleBuffer,
    ),
>;

extern "C" {
    /// Specifies a particular video encoder by its ID string.
    ///
    /// To specify a particular video encoder when creating a compression session, pass an
    /// encoderSpecification CFDictionary containing this key and the EncoderID as its value.
    /// The EncoderID CFString may be obtained from the kVTVideoEncoderList_EncoderID entry in
    /// the array returned by VTCopyVideoEncoderList.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/videotoolbox/kvtvideoencoderspecification_encoderid?language=objc)
    pub static kVTVideoEncoderSpecification_EncoderID: &'static CFString;
}

extern "C-unwind" {
    /// Creates a session for compressing video frames.
    ///
    /// Compressed frames will be emitted through calls to outputCallback.
    ///
    /// Parameter `allocator`: An allocator for the session.  Pass NULL to use the default allocator.
    ///
    /// Parameter `width`: The width of frames, in pixels.
    /// If the video encoder cannot support the provided width and height it may change them.
    ///
    /// Parameter `height`: The height of frames in pixels.
    ///
    /// Parameter `codecType`: The codec type.
    ///
    /// Parameter `encoderSpecification`: Specifies a particular video encoder that must be used.
    /// Pass NULL to let the video toolbox choose a encoder.
    ///
    /// Parameter `sourceImageBufferAttributes`: Required attributes for source pixel buffers, used when creating a pixel buffer pool
    /// for source frames.  If you do not want the Video Toolbox to create one for you, pass NULL.
    /// (Using pixel buffers not allocated by the Video Toolbox may increase the chance that
    /// it will be necessary to copy image data.)
    ///
    /// Parameter `compressedDataAllocator`: An allocator for the compressed data.  Pass NULL to use the default allocator.
    /// Note: on MacOS 10.12 and later, using a compressedDataAllocator may trigger an extra buffer copy.
    ///
    /// Parameter `outputCallback`: The callback to be called with compressed frames.
    /// This function may be called asynchronously, on a different thread from the one that calls VTCompressionSessionEncodeFrame.
    /// Pass NULL if and only if you will be calling VTCompressionSessionEncodeFrameWithOutputHandler for encoding frames.
    ///
    /// Parameter `outputCallbackRefCon`: Client-defined reference value for the output callback.
    ///
    /// Parameter `compressionSessionOut`: Points to a variable to receive the new compression session.
    #[cfg(all(feature = "VTErrors", feature = "objc2-core-media"))]
    pub fn VTCompressionSessionCreate(
        allocator: Option<&CFAllocator>,
        width: i32,
        height: i32,
        codec_type: CMVideoCodecType,
        encoder_specification: Option<&CFDictionary>,
        source_image_buffer_attributes: Option<&CFDictionary>,
        compressed_data_allocator: Option<&CFAllocator>,
        output_callback: VTCompressionOutputCallback,
        output_callback_ref_con: *mut c_void,
        compression_session_out: NonNull<*mut VTCompressionSession>,
    ) -> OSStatus;
}

extern "C-unwind" {
    /// Tears down a compression session.
    ///
    /// When you are done with a compression session you created, call VTCompressionSessionInvalidate
    /// to tear it down and then CFRelease to release your object reference.
    /// When a compression session's retain count reaches zero, it is automatically invalidated, but
    /// since sessions may be retained by multiple parties, it can be hard to predict when this will happen.
    /// Calling VTCompressionSessionInvalidate ensures a deterministic, orderly teardown.
    pub fn VTCompressionSessionInvalidate(session: &VTCompressionSession);
}

unsafe impl ConcreteType for VTCompressionSession {
    /// Returns the CFTypeID for compression sessions.
    #[doc(alias = "VTCompressionSessionGetTypeID")]
    #[inline]
    fn type_id() -> CFTypeID {
        extern "C-unwind" {
            fn VTCompressionSessionGetTypeID() -> CFTypeID;
        }
        unsafe { VTCompressionSessionGetTypeID() }
    }
}

/// Returns a pool that can provide ideal source pixel buffers for a compression session.
///
/// The compression session creates this pixel buffer pool based on
/// the compressor's pixel buffer attributes and any pixel buffer
/// attributes passed in to VTCompressionSessionCreate.  If the
/// source pixel buffer attributes and the compressor pixel buffer
/// attributes cannot be reconciled, the pool is based on the source
/// pixel buffer attributes and the Video Toolbox converts each CVImageBuffer
/// internally.
/// <BR
/// >
/// While clients can call VTCompressionSessionGetPixelBufferPool once
/// and retain the resulting pool, the call is cheap enough that it's OK
/// to call it once per frame.  If a change of session properties causes
/// the compressor's pixel buffer attributes to change, it's possible that
/// VTCompressionSessionGetPixelBufferPool might return a different pool.
#[cfg(feature = "objc2-core-video")]
#[inline]
pub unsafe extern "C-unwind" fn VTCompressionSessionGetPixelBufferPool(
    session: &VTCompressionSession,
) -> Option<CFRetained<CVPixelBufferPool>> {
    extern "C-unwind" {
        fn VTCompressionSessionGetPixelBufferPool(
            session: &VTCompressionSession,
        ) -> Option<NonNull<CVPixelBufferPool>>;
    }
    let ret = unsafe { VTCompressionSessionGetPixelBufferPool(session) };
    ret.map(|ret| unsafe { CFRetained::retain(ret) })
}

extern "C-unwind" {
    /// You can optionally call this function to provide the encoder with an opportunity to perform
    /// any necessary resource allocation before it begins encoding frames.
    ///
    /// This optional call can be used to provide the encoder an opportunity to allocate
    /// any resources necessary before it begins encoding frames.  If this isn't called, any
    /// necessary resources will be allocated on the first VTCompressionSessionEncodeFrame call.
    /// Extra calls to this function will have no effect.
    ///
    /// Parameter `session`: The compression session.
    pub fn VTCompressionSessionPrepareToEncodeFrames(session: &VTCompressionSession) -> OSStatus;
}

extern "C-unwind" {
    /// Call this function to present frames to the compression session.
    /// Encoded frames may or may not be output before the function returns.
    ///
    /// The client should not modify the pixel data after making this call.
    /// The session and/or encoder will retain the image buffer as long as necessary.
    ///
    /// Parameter `session`: The compression session.
    ///
    /// Parameter `imageBuffer`: A CVImageBuffer containing a video frame to be compressed.
    /// Must have a nonzero reference count.
    ///
    /// Parameter `presentationTimeStamp`: The presentation timestamp for this frame, to be attached to the sample buffer.
    /// Each presentation timestamp passed to a session must be greater than the previous one.
    ///
    /// Parameter `duration`: The presentation duration for this frame, to be attached to the sample buffer.
    /// If you do not have duration information, pass kCMTimeInvalid.
    ///
    /// Parameter `frameProperties`: Contains key/value pairs specifying additional properties for encoding this frame.
    /// Note that some session properties may also be changed between frames.
    /// Such changes have effect on subsequently encoded frames.
    ///
    /// Parameter `sourceFrameRefcon`: Your reference value for the frame, which will be passed to the output callback function.
    ///
    /// Parameter `infoFlagsOut`: Points to a VTEncodeInfoFlags to receive information about the encode operation.
    /// The kVTEncodeInfo_Asynchronous bit may be set if the encode is (or was) running
    /// asynchronously.
    /// The kVTEncodeInfo_FrameDropped bit may be set if the frame was dropped (synchronously).
    /// Pass NULL if you do not want to receive this information.
    #[cfg(all(
        feature = "VTErrors",
        feature = "objc2-core-media",
        feature = "objc2-core-video"
    ))]
    pub fn VTCompressionSessionEncodeFrame(
        session: &VTCompressionSession,
        image_buffer: &CVImageBuffer,
        presentation_time_stamp: CMTime,
        duration: CMTime,
        frame_properties: Option<&CFDictionary>,
        source_frame_refcon: *mut c_void,
        info_flags_out: *mut VTEncodeInfoFlags,
    ) -> OSStatus;
}

/// Prototype for block invoked when frame compression is complete.
///
/// When you encode a frame, you pass in a callback block to be called
/// for that compressed frame.  This block will be called in decode order (which is not
/// necessarily the same as display order).
///
/// Parameter `status`: noErr if compression was successful; an error code if compression was not successful.
///
/// Parameter `infoFlags`: Contains information about the encode operation.
/// The kVTEncodeInfo_Asynchronous bit may be set if the encode ran asynchronously.
/// The kVTEncodeInfo_FrameDropped bit may be set if the frame was dropped.
///
/// Parameter `sampleBuffer`: Contains the compressed frame, if compression was successful and the frame was not dropped;
/// otherwise, NULL.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/videotoolbox/vtcompressionoutputhandler?language=objc)
#[cfg(all(feature = "VTErrors", feature = "block2", feature = "objc2-core-media"))]
pub type VTCompressionOutputHandler =
    *mut block2::Block<dyn Fn(OSStatus, VTEncodeInfoFlags, *mut CMSampleBuffer)>;

extern "C-unwind" {
    /// Call this function to present frames to the compression session.
    /// Encoded frames may or may not be output before the function returns.
    ///
    /// The client should not modify the pixel data after making this call.
    /// The session and/or encoder will retain the image buffer as long as necessary.
    /// Cannot be called with a session created with a VTCompressionOutputCallback.
    ///
    /// Parameter `session`: The compression session.
    ///
    /// Parameter `imageBuffer`: A CVImageBuffer containing a video frame to be compressed.
    /// Must have a nonzero reference count.
    ///
    /// Parameter `presentationTimeStamp`: The presentation timestamp for this frame, to be attached to the sample buffer.
    /// Each presentation timestamp passed to a session must be greater than the previous one.
    ///
    /// Parameter `duration`: The presentation duration for this frame, to be attached to the sample buffer.
    /// If you do not have duration information, pass kCMTimeInvalid.
    ///
    /// Parameter `frameProperties`: Contains key/value pairs specifying additional properties for encoding this frame.
    /// Note that some session properties may also be changed between frames.
    /// Such changes have effect on subsequently encoded frames.
    ///
    /// Parameter `infoFlagsOut`: Points to a VTEncodeInfoFlags to receive information about the encode operation.
    /// The kVTEncodeInfo_Asynchronous bit may be set if the encode is (or was) running
    /// asynchronously.
    /// The kVTEncodeInfo_FrameDropped bit may be set if the frame was dropped (synchronously).
    /// Pass NULL if you do not want to receive this information.
    ///
    /// Parameter `outputHandler`: The block to be called when encoding the frame is completed.
    /// This block may be called asynchronously, on a different thread from the one that calls VTCompressionSessionEncodeFrameWithOutputHandler.
    #[cfg(all(
        feature = "VTErrors",
        feature = "block2",
        feature = "objc2-core-media",
        feature = "objc2-core-video"
    ))]
    pub fn VTCompressionSessionEncodeFrameWithOutputHandler(
        session: &VTCompressionSession,
        image_buffer: &CVImageBuffer,
        presentation_time_stamp: CMTime,
        duration: CMTime,
        frame_properties: Option<&CFDictionary>,
        info_flags_out: *mut VTEncodeInfoFlags,
        output_handler: VTCompressionOutputHandler,
    ) -> OSStatus;
}

extern "C-unwind" {
    /// Forces the compression session to complete encoding frames.
    ///
    /// If completeUntilPresentationTimeStamp is numeric, frames with presentation timestamps
    /// up to and including this timestamp will be emitted before the function returns.
    /// If completeUntilPresentationTimeStamp is non-numeric, all pending frames
    /// will be emitted before the function returns.
    #[cfg(feature = "objc2-core-media")]
    pub fn VTCompressionSessionCompleteFrames(
        session: &VTCompressionSession,
        complete_until_presentation_time_stamp: CMTime,
    ) -> OSStatus;
}

/// Indicates whether the current system supports stereo MV-HEVC encode.
///
/// This call returning true does not guarantee that encode resources will be available at all times.
#[inline]
pub unsafe extern "C-unwind" fn VTIsStereoMVHEVCEncodeSupported() -> bool {
    extern "C-unwind" {
        fn VTIsStereoMVHEVCEncodeSupported() -> Boolean;
    }
    let ret = unsafe { VTIsStereoMVHEVCEncodeSupported() };
    ret != 0
}

extern "C-unwind" {
    /// Call this function to present a multi-image frame to the compression session.
    /// Encoded frames may or may not be output before the function returns.
    ///
    /// The client should not modify the pixel data after making this call.
    /// The session and/or encoder will retain the image buffer as long as necessary.
    ///
    /// Parameter `session`: The compression session.
    ///
    /// Parameter `taggedBufferGroup`: A CMTaggedBufferGroup containing the multiple images for a video frame to be compressed.
    ///
    /// Parameter `presentationTimeStamp`: The presentation timestamp for this frame, to be attached to the sample buffer.
    /// Each presentation timestamp passed to a session must be greater than the previous one.
    ///
    /// Parameter `duration`: The presentation duration for this frame, to be attached to the sample buffer.
    /// If you do not have duration information, pass kCMTimeInvalid.
    ///
    /// Parameter `frameProperties`: Contains key/value pairs specifying additional properties for encoding this frame.
    /// Note that some session properties may also be changed between frames.
    /// Such changes have effect on subsequently encoded frames.
    ///
    /// Parameter `sourceFrameRefcon`: Your reference value for the frame, which will be passed to the output callback function.
    ///
    /// Parameter `infoFlagsOut`: Points to a VTEncodeInfoFlags to receive information about the encode operation.
    /// The kVTEncodeInfo_Asynchronous bit may be set if the encode is (or was) running
    /// asynchronously.
    /// The kVTEncodeInfo_FrameDropped bit may be set if the frame was dropped (synchronously).
    /// Pass NULL if you do not want to receive this information.
    #[cfg(all(feature = "VTErrors", feature = "objc2-core-media"))]
    pub fn VTCompressionSessionEncodeMultiImageFrame(
        session: &VTCompressionSession,
        tagged_buffer_group: &CMTaggedBufferGroup,
        presentation_time_stamp: CMTime,
        duration: CMTime,
        frame_properties: Option<&CFDictionary>,
        source_frame_refcon: *mut c_void,
        info_flags_out: *mut VTEncodeInfoFlags,
    ) -> OSStatus;
}

extern "C-unwind" {
    /// Call this function to present a multi-image frame to the compression session.
    /// Encoded frames may or may not be output before the function returns.
    ///
    /// The client should not modify the pixel data after making this call.
    /// The session and/or encoder will retain the image buffer as long as necessary.
    /// Cannot be called with a session created with a VTCompressionOutputCallback.
    ///
    /// Parameter `session`: The compression session.
    ///
    /// Parameter `taggedBufferGroup`: A CMTaggedBufferGroup containing the multiple images for a video frame to be compressed.
    ///
    /// Parameter `presentationTimeStamp`: The presentation timestamp for this frame, to be attached to the sample buffer.
    /// Each presentation timestamp passed to a session must be greater than the previous one.
    ///
    /// Parameter `duration`: The presentation duration for this frame, to be attached to the sample buffer.
    /// If you do not have duration information, pass kCMTimeInvalid.
    ///
    /// Parameter `frameProperties`: Contains key/value pairs specifying additional properties for encoding this frame.
    /// Note that some session properties may also be changed between frames.
    /// Such changes have effect on subsequently encoded frames.
    ///
    /// Parameter `infoFlagsOut`: Points to a VTEncodeInfoFlags to receive information about the encode operation.
    /// The kVTEncodeInfo_Asynchronous bit may be set if the encode is (or was) running
    /// asynchronously.
    /// The kVTEncodeInfo_FrameDropped bit may be set if the frame was dropped (synchronously).
    /// Pass NULL if you do not want to receive this information.
    ///
    /// Parameter `outputHandler`: The block to be called when encoding the frame is completed.
    /// This block may be called asynchronously, on a different thread from the one that calls VTCompressionSessionEncodeMultiImageFrameWithOutputHandler.
    #[cfg(all(feature = "VTErrors", feature = "block2", feature = "objc2-core-media"))]
    pub fn VTCompressionSessionEncodeMultiImageFrameWithOutputHandler(
        session: &VTCompressionSession,
        tagged_buffer_group: &CMTaggedBufferGroup,
        presentation_time_stamp: CMTime,
        duration: CMTime,
        frame_properties: Option<&CFDictionary>,
        info_flags_out: *mut VTEncodeInfoFlags,
        output_handler: VTCompressionOutputHandler,
    ) -> OSStatus;
}

/// [Apple's documentation](https://developer.apple.com/documentation/videotoolbox/vtcompressionsessionoptionflags?language=objc)
// NS_OPTIONS
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct VTCompressionSessionOptionFlags(pub u32);
bitflags::bitflags! {
    impl VTCompressionSessionOptionFlags: u32 {
        #[doc(alias = "kVTCompressionSessionBeginFinalPass")]
        const BeginFinalPass = 1<<0;
    }
}

#[cfg(feature = "objc2")]
unsafe impl Encode for VTCompressionSessionOptionFlags {
    const ENCODING: Encoding = u32::ENCODING;
}

#[cfg(feature = "objc2")]
unsafe impl RefEncode for VTCompressionSessionOptionFlags {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

extern "C-unwind" {
    /// Call to announce the start of a specific compression pass.
    ///
    /// During multi-pass encoding, this function must be called before VTCompressionSessionEncodeFrame.
    /// It is an error to call this function when multi-pass encoding has not been enabled by setting kVTCompressionPropertyKey_MultiPassStorage.
    ///
    /// Parameter `beginPassFlags`: Pass kVTCompressionSessionBeginFinalPass to inform the encoder that the pass must be the final pass.
    pub fn VTCompressionSessionBeginPass(
        session: &VTCompressionSession,
        begin_pass_flags: VTCompressionSessionOptionFlags,
        reserved: *mut u32,
    ) -> OSStatus;
}

extern "C-unwind" {
    /// Call to announce the end of a pass.
    ///
    /// VTCompressionSessionEndPass can take a long time, since the video encoder may perform significant processing between passes.
    /// VTCompressionSessionEndPass will indicate via the furtherPassesRequestedOut argument whether the video encoder would like to perform another pass.  There is no particular bound on the number of passes the video encoder may request, but the client is free to disregard this request and use the last-emitted set of frames.
    /// It is an error to call this function when multi-pass encoding has not been enabled by setting kVTCompressionPropertyKey_MultiPassStorage.
    ///
    /// Parameter `furtherPassesRequestedOut`: Points to a Boolean that will be set to true if the video encoder would like to perform another pass, false otherwise.
    /// You may pass NULL to indicate that the client is certain to use this as the final pass, in which case the video encoder can skip that evaluation step.
    pub fn VTCompressionSessionEndPass(
        session: &VTCompressionSession,
        further_passes_requested_out: *mut Boolean,
        reserved: *mut u32,
    ) -> OSStatus;
}

extern "C-unwind" {
    /// Retrieves the time ranges for the next pass.
    ///
    /// If VTCompressionSessionEndPass sets *furtherPassesRequestedOut to true, call VTCompressionSessionGetTimeRangesForNextPass to find out the time ranges for the next pass.  Source frames outside these time ranges should be skipped.
    /// Each time range is considered to include any frame at its start time and not to include any frame at its end time.
    /// It is an error to call this function when multi-pass encoding has not been enabled by setting kVTCompressionPropertyKey_MultiPassStorage, or when VTCompressionSessionEndPass did not set *furtherPassesRequestedOut to true.
    ///
    /// Parameter `timeRangeCountOut`: Points to a CMItemCount to receive the number of CMTimeRanges.
    ///
    /// Parameter `timeRangeArrayOut`: Points to a const CMTimeRange * to receive a pointer to a C array of CMTimeRanges.
    /// The storage for this array belongs to the VTCompressionSession and should not be modified.
    /// The pointer will be valid until the next call to VTCompressionSessionEndPass, or until the VTCompressionSession is invalidated or finalized.
    #[cfg(feature = "objc2-core-media")]
    pub fn VTCompressionSessionGetTimeRangesForNextPass(
        session: &VTCompressionSession,
        time_range_count_out: NonNull<CMItemCount>,
        time_range_array_out: NonNull<*const CMTimeRange>,
    ) -> OSStatus;
}