objc2_video_toolbox/generated/

VTMotionEstimationSession.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-video")]
use objc2_core_video::*;

use crate::*;

/// Flags to control processing of a frame you pass to the motion-estimation session.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/videotoolbox/vtmotionestimationframeflags?language=objc)
// NS_OPTIONS
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct VTMotionEstimationFrameFlags(pub u32);
bitflags::bitflags! {
    impl VTMotionEstimationFrameFlags: u32 {
/// A hint to the motion-estimation session that you are going to reuse the `currentBuffer` as `referenceBuffer` in
/// the next call to ``VTMotionEstimationSessionEstimateMotionVectors``. Using this flag allows the motion-estimation
/// processor to deliver better performance.
        #[doc(alias = "kVTMotionEstimationFrameFlags_CurrentBufferWillBeNextReferenceBuffer")]
        const CurrentBufferWillBeNextReferenceBuffer = 1<<0;
    }
}

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

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

/// Directives that provide information back to you with the results of motion-estimation.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/videotoolbox/vtmotionestimationinfoflags?language=objc)
// NS_OPTIONS
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct VTMotionEstimationInfoFlags(pub u32);
bitflags::bitflags! {
    impl VTMotionEstimationInfoFlags: u32 {
        #[doc(alias = "kVTMotionEstimationInfoFlags_Reserved0")]
        const Reserved0 = 1<<0;
    }
}

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

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

/// A reference to a Video Toolbox motion-estimation session.
///
/// A motion-estimation session supports two `CVPixelBuffer`s of the same size and type, and returns motion vectors in
/// the form of a ``CVPixelBuffer``. The session is a reference-counted CF object. To create a motion-estimation session,
/// call ``VTMotionEstimationSessionCreate``; then you can optionally configure the session using `VTSessionSetProperty`.
/// To create motion-estimations, call ``VTMotionEstimationSessionCreateMotionEstimation``. When you are done with the
/// session, you should call ``VTMotionEstimationSessionInvalidate`` to tear it down and ``CFRelease`` to release the
/// session object reference.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/videotoolbox/vtmotionestimationsession?language=objc)
#[doc(alias = "VTMotionEstimationSessionRef")]
#[repr(C)]
pub struct VTMotionEstimationSession {
    inner: [u8; 0],
    _p: UnsafeCell<PhantomData<(*const UnsafeCell<()>, PhantomPinned)>>,
}

cf_type!(
    unsafe impl VTMotionEstimationSession {}
);
#[cfg(feature = "objc2")]
cf_objc2_type!(
    unsafe impl RefEncode<"OpaqueVTMotionEstimationSession"> for VTMotionEstimationSession {}
);

unsafe impl ConcreteType for VTMotionEstimationSession {
    /// Get the CoreFoundation type identifier for motion-estimation session type.
    #[doc(alias = "VTMotionEstimationSessionGetTypeID")]
    #[inline]
    fn type_id() -> CFTypeID {
        extern "C-unwind" {
            fn VTMotionEstimationSessionGetTypeID() -> CFTypeID;
        }
        unsafe { VTMotionEstimationSessionGetTypeID() }
    }
}

impl VTMotionEstimationSession {
    /// Creates a session you use to generate a pixel buffer of motion vectors from two pixel buffers.
    ///
    /// The function creates a session for computing motion vectors between two pixel buffers.
    ///
    /// - Parameters:
    /// - allocator: An allocator for the session. Pass NULL to use the default allocator.
    /// - motionVectorProcessorSelectionOptions: Available creation options are:
    /// - term ``kVTMotionEstimationSessionCreationOption_MotionVectorSize``: Size of the search block.
    /// - term ``kVTMotionEstimationSessionCreationOption_UseMultiPassSearch``: Use multiple passes to detect true motion.
    /// - term ``kVTMotionEstimationSessionCreationOption_Label``: Label used for logging and resource tracking.
    /// - width: The width of frames in pixels.
    /// - height: The height of frames in pixels.
    /// - motionEstimationSessionOut: Points to a variable to receive the new motion-estimation session.
    ///
    /// # Safety
    ///
    /// - `motion_vector_processor_selection_options` generics must be of the correct type.
    /// - `motion_estimation_session_out` must be a valid pointer.
    #[doc(alias = "VTMotionEstimationSessionCreate")]
    #[inline]
    pub unsafe fn create(
        allocator: Option<&CFAllocator>,
        motion_vector_processor_selection_options: Option<&CFDictionary>,
        width: u32,
        height: u32,
        motion_estimation_session_out: NonNull<*mut VTMotionEstimationSession>,
    ) -> OSStatus {
        extern "C-unwind" {
            fn VTMotionEstimationSessionCreate(
                allocator: Option<&CFAllocator>,
                motion_vector_processor_selection_options: Option<&CFDictionary>,
                width: u32,
                height: u32,
                motion_estimation_session_out: NonNull<*mut VTMotionEstimationSession>,
            ) -> OSStatus;
        }
        unsafe {
            VTMotionEstimationSessionCreate(
                allocator,
                motion_vector_processor_selection_options,
                width,
                height,
                motion_estimation_session_out,
            )
        }
    }

    /// Copies the attributes for source pixel buffers expected by motion-estimation session.
    ///
    /// This function provides a `CFDictionary` of attributes that you must release. Use this function to query
    /// ``VTMotionEstimationSession`` for the native source attributes. If you provide an input ``CVPixelBuffer`` that is
    /// not compatible with the attributes that this function returns, ``VTMotionEstimationSession`` automatically
    /// converts the input pixel buffer into a compatible pixel buffer for processing.
    ///
    /// - Parameters:
    /// - session: The motion-estimation session.
    /// - attributesOut: Points to a variable to receive the attributes dictionary.
    ///
    /// # Safety
    ///
    /// `attributes_out` must be a valid pointer.
    #[doc(alias = "VTMotionEstimationSessionCopySourcePixelBufferAttributes")]
    #[inline]
    pub unsafe fn copy_source_pixel_buffer_attributes(
        &self,
        attributes_out: NonNull<*const CFDictionary>,
    ) -> OSStatus {
        extern "C-unwind" {
            fn VTMotionEstimationSessionCopySourcePixelBufferAttributes(
                motion_estimation_session: &VTMotionEstimationSession,
                attributes_out: NonNull<*const CFDictionary>,
            ) -> OSStatus;
        }
        unsafe { VTMotionEstimationSessionCopySourcePixelBufferAttributes(self, attributes_out) }
    }

    /// Tears down a motion-estimation session.
    ///
    /// When you are done with a motion-estimation session you created, call this function to tear
    /// it down and then `CFRelease` to release the session object reference. When a motion-estimation session's retain count
    /// reaches zero, the system automatically invalidates it, but because multiple parties may retain sessions, it can be
    /// hard to predict when this happens. Calling this function ensures a deterministic, orderly teardown.
    #[doc(alias = "VTMotionEstimationSessionInvalidate")]
    #[inline]
    pub unsafe fn invalidate(&self) {
        extern "C-unwind" {
            fn VTMotionEstimationSessionInvalidate(session: &VTMotionEstimationSession);
        }
        unsafe { VTMotionEstimationSessionInvalidate(self) }
    }
}

/// A block invoked by motion-estimation session when frame processing is complete.
///
/// When the client requests a motion-estimation, the client passes in a callback block that the system invokes for the
/// result of that request. If the ``VTMotionEstimationSessionCreateMotionEstimation`` call returns an error, the system
/// does not invoke this block.
///
/// - Parameters:
/// - status: `noErr` if processing request was successful; an error code if motion-estimation was not successful.
/// - infoFlags: A bit field that contains information about the processing operation.
/// - additionalInfo: Additional processing information about the operation that cannot fit in `infoFlags`.
/// Currently, the system expects this to be NULL.
/// - motionVectorPixelBuffer: A `CVPixelBuffer` that contains the motion vector information, if processing request
/// was successful; otherwise, NULL.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/videotoolbox/vtmotionestimationoutputhandler?language=objc)
#[cfg(all(feature = "block2", feature = "objc2-core-video"))]
pub type VTMotionEstimationOutputHandler = *mut block2::DynBlock<
    dyn Fn(OSStatus, VTMotionEstimationInfoFlags, *const CFDictionary, *mut CVPixelBuffer),
>;

impl VTMotionEstimationSession {
    /// Creates a new pixel buffer that contains motion vectors between the input pixel buffers.
    ///
    /// The motion-estimation session compares the reference frame to the current frame, and generates motion vectors in
    /// the form of a `CVPixelBuffer`.
    ///
    /// - Parameters:
    /// - session: The motion-estimation session.
    /// - referenceImage: The reference image.
    /// - currentImage: The current image.
    /// - motionEstimationFrameFlags: A bit field with per-frame options. See ``kVTMotionEstimationFrameFlags_CurrentBufferWillBeNextReferenceBuffer``.
    /// - additionalFrameOptions: A way to pass additional information that doesn't fit in `motionEstimationFrameFlags`;
    /// currently the system expects it to be `NULL`.
    /// - outputHandler: The block invoked by the syetem when the processing request is completed. If the
    /// `VTMotionEstimationSessionCreateMotionEstimation` call returns an error, the system does not invoke the block.
    ///
    /// - Returns: If the call was successful, returns `noErr`; otherwise, returns an error code, such as `kVTMotionEstimationNotSupportedErr`.
    ///
    /// # Safety
    ///
    /// - `additional_frame_options` generics must be of the correct type.
    /// - `output_handler` must be a valid pointer.
    #[doc(alias = "VTMotionEstimationSessionEstimateMotionVectors")]
    #[cfg(all(feature = "block2", feature = "objc2-core-video"))]
    #[inline]
    pub unsafe fn estimate_motion_vectors(
        &self,
        reference_image: &CVPixelBuffer,
        current_image: &CVPixelBuffer,
        motion_estimation_frame_flags: VTMotionEstimationFrameFlags,
        additional_frame_options: Option<&CFDictionary>,
        output_handler: VTMotionEstimationOutputHandler,
    ) -> OSStatus {
        extern "C-unwind" {
            fn VTMotionEstimationSessionEstimateMotionVectors(
                session: &VTMotionEstimationSession,
                reference_image: &CVPixelBuffer,
                current_image: &CVPixelBuffer,
                motion_estimation_frame_flags: VTMotionEstimationFrameFlags,
                additional_frame_options: Option<&CFDictionary>,
                output_handler: VTMotionEstimationOutputHandler,
            ) -> OSStatus;
        }
        unsafe {
            VTMotionEstimationSessionEstimateMotionVectors(
                self,
                reference_image,
                current_image,
                motion_estimation_frame_flags,
                additional_frame_options,
                output_handler,
            )
        }
    }

    /// Directs the motion-estimation session to emit all pending frames and waits for completion.
    ///
    /// Directs the motion-estimation session to emit all pending frames, then waits for all outstanding requests to complete, then returns.
    #[doc(alias = "VTMotionEstimationSessionCompleteFrames")]
    #[inline]
    pub unsafe fn complete_frames(&self) -> OSStatus {
        extern "C-unwind" {
            fn VTMotionEstimationSessionCompleteFrames(
                session: &VTMotionEstimationSession,
            ) -> OSStatus;
        }
        unsafe { VTMotionEstimationSessionCompleteFrames(self) }
    }
}

extern "C-unwind" {
    #[deprecated = "renamed to `VTMotionEstimationSession::create`"]
    pub fn VTMotionEstimationSessionCreate(
        allocator: Option<&CFAllocator>,
        motion_vector_processor_selection_options: Option<&CFDictionary>,
        width: u32,
        height: u32,
        motion_estimation_session_out: NonNull<*mut VTMotionEstimationSession>,
    ) -> OSStatus;
}

extern "C-unwind" {
    #[deprecated = "renamed to `VTMotionEstimationSession::copy_source_pixel_buffer_attributes`"]
    pub fn VTMotionEstimationSessionCopySourcePixelBufferAttributes(
        motion_estimation_session: &VTMotionEstimationSession,
        attributes_out: NonNull<*const CFDictionary>,
    ) -> OSStatus;
}

extern "C-unwind" {
    #[deprecated = "renamed to `VTMotionEstimationSession::invalidate`"]
    pub fn VTMotionEstimationSessionInvalidate(session: &VTMotionEstimationSession);
}

extern "C-unwind" {
    #[cfg(all(feature = "block2", feature = "objc2-core-video"))]
    #[deprecated = "renamed to `VTMotionEstimationSession::estimate_motion_vectors`"]
    pub fn VTMotionEstimationSessionEstimateMotionVectors(
        session: &VTMotionEstimationSession,
        reference_image: &CVPixelBuffer,
        current_image: &CVPixelBuffer,
        motion_estimation_frame_flags: VTMotionEstimationFrameFlags,
        additional_frame_options: Option<&CFDictionary>,
        output_handler: VTMotionEstimationOutputHandler,
    ) -> OSStatus;
}

extern "C-unwind" {
    #[deprecated = "renamed to `VTMotionEstimationSession::complete_frames`"]
    pub fn VTMotionEstimationSessionCompleteFrames(session: &VTMotionEstimationSession)
        -> OSStatus;
}