objc2_av_foundation/generated/

AVAssetImageGenerator.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
#[cfg(feature = "objc2-core-foundation")]
use objc2_core_foundation::*;
#[cfg(feature = "objc2-core-graphics")]
use objc2_core_graphics::*;
#[cfg(feature = "objc2-core-media")]
use objc2_core_media::*;
use objc2_foundation::*;

use crate::*;

/// The type of an aperture mode.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/avfoundation/avassetimagegeneratoraperturemode?language=objc)
// NS_TYPED_ENUM
pub type AVAssetImageGeneratorApertureMode = NSString;

extern "C" {
    /// Both pixel aspect ratio and clean aperture will be applied.
    ///
    /// An image's clean aperture is a region of video free from transition artifacts caused by the encoding of the signal.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/avfoundation/avassetimagegeneratoraperturemodecleanaperture?language=objc)
    pub static AVAssetImageGeneratorApertureModeCleanAperture:
        &'static AVAssetImageGeneratorApertureMode;
}

extern "C" {
    /// Only pixel aspect ratio will be applied.
    ///
    /// The image is not cropped to the clean aperture region, but it is scaled according to the pixel aspect ratio. Use this option when you want to see all the pixels in your video, including the edges.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/avfoundation/avassetimagegeneratoraperturemodeproductionaperture?language=objc)
    pub static AVAssetImageGeneratorApertureModeProductionAperture:
        &'static AVAssetImageGeneratorApertureMode;
}

extern "C" {
    /// Neither pixel aspect ratio nor clean aperture will be applied.
    ///
    /// The image is not cropped to the clean aperture region and is not scaled according to the pixel aspect ratio. The encoded dimensions of the image description are displayed.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/avfoundation/avassetimagegeneratoraperturemodeencodedpixels?language=objc)
    pub static AVAssetImageGeneratorApertureModeEncodedPixels:
        &'static AVAssetImageGeneratorApertureMode;
}

/// Configures the video dynamic range for the output CGImage
///
/// Default.  Force standard dynamic range by converting PQ or HLG transfer functions to 709, while maintaining color primaries and matrix.
///
/// SDR movies will vend SDR CGImages matching the source color parameters.  HDR movies will vend HDR CGImages matching the source color parameters.
/// HTTP Live Streaming assets will currently vend only SDR CGImages.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/avfoundation/avassetimagegeneratordynamicrangepolicy?language=objc)
// NS_TYPED_ENUM
pub type AVAssetImageGeneratorDynamicRangePolicy = NSString;

extern "C" {
    /// [Apple's documentation](https://developer.apple.com/documentation/avfoundation/avassetimagegeneratordynamicrangepolicyforcesdr?language=objc)
    pub static AVAssetImageGeneratorDynamicRangePolicyForceSDR:
        &'static AVAssetImageGeneratorDynamicRangePolicy;
}

extern "C" {
    /// [Apple's documentation](https://developer.apple.com/documentation/avfoundation/avassetimagegeneratordynamicrangepolicymatchsource?language=objc)
    pub static AVAssetImageGeneratorDynamicRangePolicyMatchSource:
        &'static AVAssetImageGeneratorDynamicRangePolicy;
}

/// [Apple's documentation](https://developer.apple.com/documentation/avfoundation/avassetimagegeneratorresult?language=objc)
// NS_ENUM
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct AVAssetImageGeneratorResult(pub NSInteger);
impl AVAssetImageGeneratorResult {
    #[doc(alias = "AVAssetImageGeneratorSucceeded")]
    pub const Succeeded: Self = Self(0);
    #[doc(alias = "AVAssetImageGeneratorFailed")]
    pub const Failed: Self = Self(1);
    #[doc(alias = "AVAssetImageGeneratorCancelled")]
    pub const Cancelled: Self = Self(2);
}

unsafe impl Encode for AVAssetImageGeneratorResult {
    const ENCODING: Encoding = NSInteger::ENCODING;
}

unsafe impl RefEncode for AVAssetImageGeneratorResult {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

/// [Apple's documentation](https://developer.apple.com/documentation/avfoundation/avassetimagegeneratorcompletionhandler?language=objc)
#[cfg(all(
    feature = "block2",
    feature = "objc2-core-graphics",
    feature = "objc2-core-media"
))]
pub type AVAssetImageGeneratorCompletionHandler = *mut block2::DynBlock<
    dyn Fn(CMTime, *mut CGImage, CMTime, AVAssetImageGeneratorResult, *mut NSError),
>;

extern_class!(
    /// [Apple's documentation](https://developer.apple.com/documentation/avfoundation/avassetimagegenerator?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct AVAssetImageGenerator;
);

extern_conformance!(
    unsafe impl NSObjectProtocol for AVAssetImageGenerator {}
);

impl AVAssetImageGenerator {
    extern_methods!(
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;

        #[cfg(feature = "AVAsset")]
        #[unsafe(method(asset))]
        #[unsafe(method_family = none)]
        pub unsafe fn asset(&self) -> Retained<AVAsset>;

        #[unsafe(method(appliesPreferredTrackTransform))]
        #[unsafe(method_family = none)]
        pub unsafe fn appliesPreferredTrackTransform(&self) -> bool;

        /// Setter for [`appliesPreferredTrackTransform`][Self::appliesPreferredTrackTransform].
        #[unsafe(method(setAppliesPreferredTrackTransform:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setAppliesPreferredTrackTransform(
            &self,
            applies_preferred_track_transform: bool,
        );

        #[cfg(feature = "objc2-core-foundation")]
        #[unsafe(method(maximumSize))]
        #[unsafe(method_family = none)]
        pub unsafe fn maximumSize(&self) -> CGSize;

        #[cfg(feature = "objc2-core-foundation")]
        /// Setter for [`maximumSize`][Self::maximumSize].
        #[unsafe(method(setMaximumSize:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setMaximumSize(&self, maximum_size: CGSize);

        #[unsafe(method(apertureMode))]
        #[unsafe(method_family = none)]
        pub unsafe fn apertureMode(&self) -> Option<Retained<AVAssetImageGeneratorApertureMode>>;

        /// Setter for [`apertureMode`][Self::apertureMode].
        ///
        /// This is [copied][objc2_foundation::NSCopying::copy] when set.
        #[unsafe(method(setApertureMode:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setApertureMode(
            &self,
            aperture_mode: Option<&AVAssetImageGeneratorApertureMode>,
        );

        /// Configures the video dynamic range for the output CGImage
        ///
        /// Default is AVAssetImageGeneratorDynamicRangePolicyForceSDR
        #[unsafe(method(dynamicRangePolicy))]
        #[unsafe(method_family = none)]
        pub unsafe fn dynamicRangePolicy(
            &self,
        ) -> Retained<AVAssetImageGeneratorDynamicRangePolicy>;

        /// Setter for [`dynamicRangePolicy`][Self::dynamicRangePolicy].
        ///
        /// This is [copied][objc2_foundation::NSCopying::copy] when set.
        #[unsafe(method(setDynamicRangePolicy:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setDynamicRangePolicy(
            &self,
            dynamic_range_policy: &AVAssetImageGeneratorDynamicRangePolicy,
        );

        #[cfg(feature = "AVVideoComposition")]
        /// Specifies the video composition to use when extracting images from assets with multiple video tracks.
        ///
        /// If no videoComposition is specified, only the first enabled video track will be used.
        /// If a videoComposition is specified, the value of appliesPreferredTrackTransform is ignored.
        /// This property throws an exception if a video composition is set with any of the following property values:
        /// - "renderScale" is not equal to one
        /// - "renderSize" width or height is less than zero
        /// - "frameDuration" is invalid or less than or equal to zero
        /// - "sourceTrackIDForFrameTiming" is less than zero
        /// - "outputBufferDescription" is non-nil
        #[unsafe(method(videoComposition))]
        #[unsafe(method_family = none)]
        pub unsafe fn videoComposition(&self) -> Option<Retained<AVVideoComposition>>;

        #[cfg(feature = "AVVideoComposition")]
        /// Setter for [`videoComposition`][Self::videoComposition].
        ///
        /// This is [copied][objc2_foundation::NSCopying::copy] when set.
        #[unsafe(method(setVideoComposition:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setVideoComposition(&self, video_composition: Option<&AVVideoComposition>);

        #[cfg(feature = "AVVideoCompositing")]
        #[unsafe(method(customVideoCompositor))]
        #[unsafe(method_family = none)]
        pub unsafe fn customVideoCompositor(
            &self,
        ) -> Option<Retained<ProtocolObject<dyn AVVideoCompositing>>>;

        #[cfg(feature = "objc2-core-media")]
        #[unsafe(method(requestedTimeToleranceBefore))]
        #[unsafe(method_family = none)]
        pub unsafe fn requestedTimeToleranceBefore(&self) -> CMTime;

        #[cfg(feature = "objc2-core-media")]
        /// Setter for [`requestedTimeToleranceBefore`][Self::requestedTimeToleranceBefore].
        #[unsafe(method(setRequestedTimeToleranceBefore:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setRequestedTimeToleranceBefore(
            &self,
            requested_time_tolerance_before: CMTime,
        );

        #[cfg(feature = "objc2-core-media")]
        #[unsafe(method(requestedTimeToleranceAfter))]
        #[unsafe(method_family = none)]
        pub unsafe fn requestedTimeToleranceAfter(&self) -> CMTime;

        #[cfg(feature = "objc2-core-media")]
        /// Setter for [`requestedTimeToleranceAfter`][Self::requestedTimeToleranceAfter].
        #[unsafe(method(setRequestedTimeToleranceAfter:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setRequestedTimeToleranceAfter(&self, requested_time_tolerance_after: CMTime);

        #[cfg(feature = "AVAsset")]
        /// Returns an instance of AVAssetImageGenerator for use with the specified asset.
        ///
        /// Parameter `asset`: The asset from which images will be extracted.
        ///
        /// Returns: An instance of AVAssetImageGenerator
        ///
        /// This method may succeed even if the asset possesses no visual tracks at the time of initialization.
        /// Clients may wish to test whether an asset has any tracks with the visual characteristic via
        /// -[AVAsset tracksWithMediaCharacteristic:].
        ///
        /// Note also that assets that belong to a mutable subclass of AVAsset, AVMutableComposition or AVMutableMovie,
        /// may gain visual tracks after initialization of an associated AVAssetImageGenerator.
        ///
        /// However, the results of image generation are undefined if mutations of the asset occur while images
        /// are being generated.
        ///
        /// AVAssetImageGenerator will use the default enabled video track(s) to generate images.
        #[unsafe(method(assetImageGeneratorWithAsset:))]
        #[unsafe(method_family = none)]
        pub unsafe fn assetImageGeneratorWithAsset(asset: &AVAsset) -> Retained<Self>;

        #[cfg(feature = "AVAsset")]
        /// Initializes an instance of AVAssetImageGenerator for use with the specified asset.
        ///
        /// Parameter `asset`: The asset from which images will be extracted.
        ///
        /// Returns: An instance of AVAssetImageGenerator
        ///
        /// This method may succeed even if the asset possesses no visual tracks at the time of initialization.
        /// Clients may wish to test whether an asset has any tracks with the visual characteristic via
        /// -[AVAsset tracksWithMediaCharacteristic:].
        ///
        /// Note also that assets that belong to a mutable subclass of AVAsset, AVMutableComposition or AVMutableMovie,
        /// may gain visual tracks after initialization of an associated AVAssetImageGenerator.
        ///
        /// However, the results of image generation are undefined if mutations of the asset occur while images
        /// are being generated.
        ///
        /// AVAssetImageGenerator will use the default enabled video track(s) to generate images.
        #[unsafe(method(initWithAsset:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithAsset(this: Allocated<Self>, asset: &AVAsset) -> Retained<Self>;

        #[cfg(all(feature = "objc2-core-graphics", feature = "objc2-core-media"))]
        /// Returns a CFRetained CGImageRef for an asset at or near the specified time.
        ///
        /// Parameter `requestedTime`: The time at which the image of the asset is to be created.
        ///
        /// Parameter `actualTime`: A pointer to a CMTime to receive the time at which the image was actually generated. If you are not interested
        /// in this information, pass NULL.
        ///
        /// Parameter `outError`: An error object describing the reason for failure, in the event that this method returns NULL.
        ///
        /// Returns: A CGImageRef.
        ///
        /// Returns the CGImage synchronously. Ownership follows the Create Rule.
        ///
        /// Because of the nature of timed audiovisual media, generating an image may take significant time. AVAssetImageGenerator may have to block the calling thread in order to do so.  In order to avoid blocking, clients can use -generateCGImagesAsynchronouslyForTimes:completionHandler: to request that one or more images be generated asynchronously and to be notified when they become available.
        ///
        /// On iOS and tvOS, it is particularly important to avoid blocking.  To preserve responsiveness, a synchronous request that blocks for too long (eg, a request to generate an image from an asset on a slow HTTP server) may lead to media services being reset.
        ///
        /// # Safety
        ///
        /// `actual_time` must be a valid pointer or null.
        #[deprecated = "Use generateCGImageAsynchronouslyForTime:completionHandler: instead"]
        #[unsafe(method(copyCGImageAtTime:actualTime:error:_))]
        #[unsafe(method_family = copy)]
        pub unsafe fn copyCGImageAtTime_actualTime_error(
            &self,
            requested_time: CMTime,
            actual_time: *mut CMTime,
        ) -> Result<Retained<CGImage>, Retained<NSError>>;

        #[cfg(all(
            feature = "block2",
            feature = "objc2-core-graphics",
            feature = "objc2-core-media"
        ))]
        /// Returns a series of CGImageRefs for an asset at or near the specified times.
        ///
        /// Parameter `requestedTimes`: An NSArray of NSValues, each containing a CMTime, specifying the asset times at which an image is requested.
        ///
        /// Parameter `handler`: A block that will be called when an image request is complete.
        ///
        /// Employs an efficient "batch mode" for getting images in time order.
        /// The client will receive exactly one handler callback for each requested time in requestedTimes.
        /// Changes to generator properties (snap behavior, maximum size, etc...) will not affect outstanding asynchronous image generation requests.
        /// The generated image is not retained.  Clients should retain the image if they wish it to persist after the completion handler returns.
        ///
        /// # Safety
        ///
        /// `handler` must be a valid pointer.
        #[unsafe(method(generateCGImagesAsynchronouslyForTimes:completionHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn generateCGImagesAsynchronouslyForTimes_completionHandler(
            &self,
            requested_times: &NSArray<NSValue>,
            handler: AVAssetImageGeneratorCompletionHandler,
        );

        #[cfg(all(
            feature = "block2",
            feature = "objc2-core-graphics",
            feature = "objc2-core-media"
        ))]
        /// Returns a CGImageRef for an asset at or near the specified time.
        ///
        /// Parameter `requestedTime`: A CMTime, specifying the asset time at which an image is requested.
        ///
        /// Parameter `handler`: A block that will be called when the image request is complete.
        ///
        /// The client will receive exactly one handler callback for requestedTime.
        /// Changes to generator properties (snap behavior, maximum size, etc...) will not affect outstanding asynchronous image generation requests.
        /// The generated image is not retained.  Clients should retain the image if they wish it to persist after the completion handler returns.
        /// If image generation succeeds, the `image` parameter to the completion handler will be non-NULL and the `error` parameter will be nil.  If image generation fails or was cancelled, the `image` parameter will be NULL and the `error` parameter will describe what went wrong.  For cancelled images, the returned error will be AVErrorOperationCancelled.
        ///
        /// # Safety
        ///
        /// `handler` block must be sendable.
        #[unsafe(method(generateCGImageAsynchronouslyForTime:completionHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn generateCGImageAsynchronouslyForTime_completionHandler(
            &self,
            requested_time: CMTime,
            handler: &block2::DynBlock<dyn Fn(*mut CGImage, CMTime, *mut NSError)>,
        );

        /// Cancels all outstanding image generation requests.
        ///
        /// Calls the handler block with AVAssetImageGeneratorCancelled for each image time in every previous invocation of -generateCGImagesAsynchronouslyForTimes:completionHandler:
        /// for which images have not yet been supplied.
        #[unsafe(method(cancelAllCGImageGeneration))]
        #[unsafe(method_family = none)]
        pub unsafe fn cancelAllCGImageGeneration(&self);
    );
}