Struct AVVideoComposition

#[repr(C)]
pub struct AVVideoComposition { /* private fields */ }

Available on crate feature AVVideoComposition only.

The AVVideoCompositionRenderContext class defines the context within which custom compositors render new output pixels buffers.

An instance of AVVideoCompositionRenderContext provides size and scaling information and offers a service for efficiently providing pixel buffers from a managed pool of buffers.

See also Apple’s documentation

Implementations

impl AVVideoComposition

pub unsafe fn videoCompositionWithPropertiesOfAsset( asset: &AVAsset, ) -> Retained<AVVideoComposition>

👎Deprecated: Use videoCompositionWithPropertiesOfAsset:completionHandler: instead

Available on crate feature AVAsset only.

Returns a new instance of AVVideoComposition with values and instructions suitable for presenting the video tracks of the specified asset according to its temporal and geometric properties and those of its tracks.

Parameter asset: An instance of AVAsset. Ensure that the duration and tracks properties of the asset are already loaded before invoking this method.

Returns: An instance of AVVideoComposition.

The returned AVVideoComposition will have instructions that respect the spatial properties and timeRanges of the specified asset’s video tracks. It will also have the following values for its properties:

• If the asset has exactly one video track, the original timing of the source video track will be used. If the asset has more than one video track, and the nominal frame rate of any of video tracks is known, the reciprocal of the greatest known nominalFrameRate will be used as the value of frameDuration. Otherwise, a default framerate of 30fps is used.
• If the specified asset is an instance of AVComposition, the renderSize will be set to the naturalSize of the AVComposition; otherwise the renderSize will be set to a value that encompasses all of the asset’s video tracks.
• A renderScale of 1.0.
• A nil animationTool.

If the specified asset has no video tracks, this method will return an AVVideoComposition instance with an empty collection of instructions.

pub unsafe fn videoCompositionWithPropertiesOfAsset_completionHandler( asset: &AVAsset, completion_handler: &Block<dyn Fn(*mut AVVideoComposition, *mut NSError)>, )

Available on crate features AVAsset and block2 only.

Vends a new instance of AVVideoComposition with values and instructions suitable for presenting the video tracks of the specified asset according to its temporal and geometric properties and those of its tracks.

Parameter asset: An instance of AVAsset.

Parameter completionHandler: A block that is invoked when the new video composition has finished being created. If the videoComposition parameter is nil, the error parameter describes the failure that occurred.

The new AVVideoComposition will have instructions that respect the spatial properties and timeRanges of the specified asset’s video tracks. It will also have the following values for its properties:

• If the asset has exactly one video track, the original timing of the source video track will be used. If the asset has more than one video track, and the nominal frame rate of any of video tracks is known, the reciprocal of the greatest known nominalFrameRate will be used as the value of frameDuration. Otherwise, a default framerate of 30fps is used.
• If the specified asset is an instance of AVComposition, the renderSize will be set to the naturalSize of the AVComposition; otherwise the renderSize will be set to a value that encompasses all of the asset’s video tracks.
• A renderScale of 1.0.
• A nil animationTool.

If the specified asset has no video tracks, this method will return an AVVideoComposition instance with an empty collection of instructions.

pub unsafe fn customVideoCompositorClass(&self) -> Option<&'static AnyClass>

Available on crate feature AVVideoCompositing only.

pub unsafe fn frameDuration(&self) -> CMTime

Available on crate feature objc2-core-media only.

pub unsafe fn sourceTrackIDForFrameTiming(&self) -> CMPersistentTrackID

Available on crate feature objc2-core-media only.

pub unsafe fn renderSize(&self) -> CGSize

Available on crate feature objc2-core-foundation only.

pub unsafe fn renderScale(&self) -> c_float

pub unsafe fn instructions( &self, ) -> Retained<NSArray<ProtocolObject<dyn AVVideoCompositionInstructionProtocol>>>

Available on crate feature AVVideoCompositing only.

pub unsafe fn animationTool( &self, ) -> Option<Retained<AVVideoCompositionCoreAnimationTool>>

pub unsafe fn sourceSampleDataTrackIDs(&self) -> Retained<NSArray<NSNumber>>

impl AVVideoComposition

Methods declared on superclass NSObject.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn new() -> Retained<Self>

impl AVVideoComposition

AVVideoCompositionColorimetery.

pub unsafe fn colorPrimaries(&self) -> Option<Retained<NSString>>

pub unsafe fn colorYCbCrMatrix(&self) -> Option<Retained<NSString>>

pub unsafe fn colorTransferFunction(&self) -> Option<Retained<NSString>>

pub unsafe fn perFrameHDRDisplayMetadataPolicy( &self, ) -> Retained<AVVideoCompositionPerFrameHDRDisplayMetadataPolicy>

impl AVVideoComposition

AVVideoCompositionFiltering.

pub unsafe fn videoCompositionWithAsset_applyingCIFiltersWithHandler( asset: &AVAsset, applier: &Block<dyn Fn(NonNull<AVAsynchronousCIImageFilteringRequest>)>, ) -> Retained<AVVideoComposition>

👎Deprecated: Use videoCompositionWithAsset:applyingCIFiltersWithHandler:completionHandler: instead

Available on crate features AVAsset and AVVideoCompositing and block2 only.

Returns a new instance of AVVideoComposition with values and instructions that will apply the specified handler block to video frames represented as instances of CIImage.

Parameter asset: An instance of AVAsset. For best performance, ensure that the duration and tracks properties of the asset are already loaded before invoking this method.

Returns: An instance of AVVideoComposition.

The returned AVVideoComposition will cause the specified handler block to be called to filter each frame of the asset’s first enabled video track. The handler block should use the properties of the provided AVAsynchronousCIImageFilteringRequest and respond using finishWithImage:context: with a “filtered” new CIImage (or the provided source image for no affect). In the event of an error, respond to the request using finishWithError:. The error can be observed via AVPlayerItemFailedToPlayToEndTimeNotification, see AVPlayerItemFailedToPlayToEndTimeErrorKey in notification payload.

NOTE: The returned AVVideoComposition’s properties are private and support only CIFilter-based operations. Mutations are not supported, either in the values of properties of the AVVideoComposition itself or in its private instructions. If rotations or other transformations are desired, they must be accomplished via the application of CIFilters during the execution of your specified handler.

The video composition will also have the following values for its properties:

• The original timing of the asset’s first enabled video track will be used.
• A renderSize that encompasses the asset’s first enabled video track respecting the track’s preferredTransform.
• A renderScale of 1.0.

The default CIContext has the following properties:

• iOS: Device RGB color space
• macOS: sRGB color space

Example usage:

playerItem.videoComposition = [AVVideoComposition videoCompositionWithAsset:srcAsset applyingCIFiltersWithHandler: ^(AVAsynchronousCIImageFilteringRequest *request) { NSError *err = nil; CIImage *filtered = myRenderer(request, &err ); if (filtered) [request finishWithImage:filtered context:nil]; else [request finishWithError:err]; }];

pub unsafe fn videoCompositionWithAsset_applyingCIFiltersWithHandler_completionHandler( asset: &AVAsset, applier: &Block<dyn Fn(NonNull<AVAsynchronousCIImageFilteringRequest>)>, completion_handler: &Block<dyn Fn(*mut AVVideoComposition, *mut NSError)>, )

Available on crate features AVAsset and AVVideoCompositing and block2 only.

Vends a new instance of AVVideoComposition with values and instructions that will apply the specified handler block to video frames represented as instances of CIImage.

Parameter asset: An instance of AVAsset.

Parameter completionHandler: A block that is invoked when the new video composition has finished being created. If the videoComposition parameter is nil, the error parameter describes the failure that occurred.

The new AVVideoComposition will cause the specified handler block to be called to filter each frame of the asset’s first enabled video track. The handler block should use the properties of the provided AVAsynchronousCIImageFilteringRequest and respond using finishWithImage:context: with a “filtered” new CIImage (or the provided source image for no affect). In the event of an error, respond to the request using finishWithError:. The error can be observed via AVPlayerItemFailedToPlayToEndTimeNotification, see AVPlayerItemFailedToPlayToEndTimeErrorKey in notification payload.

NOTE: The returned AVVideoComposition’s properties are private and support only CIFilter-based operations. Mutations are not supported, either in the values of properties of the AVVideoComposition itself or in its private instructions. If rotations or other transformations are desired, they must be accomplished via the application of CIFilters during the execution of your specified handler.

The video composition will also have the following values for its properties:

• The original timing of the asset’s first enabled video track will be used.
• A renderSize that encompasses the asset’s first enabled video track respecting the track’s preferredTransform.
• A renderScale of 1.0.

The default CIContext has the following properties:

• iOS: Device RGB color space
• macOS: sRGB color space

Example usage:

[AVVideoComposition videoCompositionWithAsset:srcAsset applyingCIFiltersWithHandler: ^(AVAsynchronousCIImageFilteringRequest *request) { NSError *err = nil; CIImage *filtered = myRenderer(request, &err ); if (filtered) [request finishWithImage:filtered context:nil]; else [request finishWithError:err]; } completionHandler: ^(AVVideoComposition * _Nullable videoComposition, NSError * _Nullable error) { if (videoComposition != nil) { playerItem.videoComposition = videoComposition else { // handle error }];

impl AVVideoComposition

AVVideoCompositionValidation.

pub unsafe fn isValidForAsset_timeRange_validationDelegate( &self, asset: Option<&AVAsset>, time_range: CMTimeRange, validation_delegate: Option<&ProtocolObject<dyn AVVideoCompositionValidationHandling>>, ) -> bool

👎Deprecated: Use isValidForTracks:assetDuration:timeRange:validationDelegate: instead

Available on crate features AVAsset and objc2-core-media only.

Indicates whether the timeRanges of the receiver’s instructions conform to the requirements described for them immediately above (in connection with the instructions property) and also whether all of the layer instructions have a value for trackID that corresponds either to a track of the specified asset or to the receiver’s animationTool.

Parameter asset: Pass a reference to an AVAsset if you wish to validate the timeRanges of the instructions against the duration of the asset and the trackIDs of the layer instructions against the asset’s tracks. Pass nil to skip that validation. Clients should ensure that the keys “ tracks“ and @“duration” are already loaded on the AVAsset before validation is attempted.

Parameter timeRange: A CMTimeRange. Only those instructions with timeRanges that overlap with the specified timeRange will be validated. To validate all instructions that may be used for playback or other processing, regardless of timeRange, pass CMTimeRangeMake(kCMTimeZero, kCMTimePositiveInfinity).

Parameter validationDelegate: Indicates an object implementing the AVVideoCompositionValidationHandling protocol to receive information about troublesome portions of a video composition during processing of -isValidForAsset:. May be nil.

In the course of validation, the receiver will invoke its validationDelegate with reference to any trouble spots in the video composition. An exception will be raised if the delegate modifies the receiver’s array of instructions or the array of layerInstructions of any AVVideoCompositionInstruction contained therein during validation.

pub unsafe fn determineValidityForAsset_timeRange_validationDelegate_completionHandler( &self, asset: Option<&AVAsset>, time_range: CMTimeRange, validation_delegate: Option<&ProtocolObject<dyn AVVideoCompositionValidationHandling>>, completion_handler: &Block<dyn Fn(Bool, *mut NSError)>, )

👎Deprecated

Available on crate features AVAsset and block2 and objc2-core-media only.

Determines whether the timeRanges of the receiver’s instructions conform to the requirements described for them immediately above (in connection with the instructions property) and also whether all of the layer instructions have a value for trackID that corresponds either to a track of the specified asset or to the receiver’s animationTool.

Parameter asset: Pass a reference to an AVAsset if you wish to validate the timeRanges of the instructions against the duration of the asset and the trackIDs of the layer instructions against the asset’s tracks. Pass nil to skip that validation.

Parameter timeRange: A CMTimeRange. Only those instructions with timeRanges that overlap with the specified timeRange will be validated. To validate all instructions that may be used for playback or other processing, regardless of timeRange, pass CMTimeRangeMake(kCMTimeZero, kCMTimePositiveInfinity).

Parameter validationDelegate: Indicates an object implementing the AVVideoCompositionValidationHandling protocol to receive information about troublesome portions of a video composition during processing of -determineValidityForAsset:. May be nil.

Parameter completionHandler: A block that is invoked when a determination is made about whether the video composition is valid. If the isValid parameter is NO, either the video composition is not valid, in which case the error parameter will be nil, or the answer could not be determined, in which case the error parameter will be non-nil and describe the failure that occurred.

In the course of validation, the receiver will invoke its validationDelegate with reference to any trouble spots in the video composition. An exception will be raised if the delegate modifies the receiver’s array of instructions or the array of layerInstructions of any AVVideoCompositionInstruction contained therein during validation.

pub unsafe fn isValidForTracks_assetDuration_timeRange_validationDelegate( &self, tracks: &NSArray<AVAssetTrack>, duration: CMTime, time_range: CMTimeRange, validation_delegate: Option<&ProtocolObject<dyn AVVideoCompositionValidationHandling>>, ) -> bool

Available on crate features AVAssetTrack and objc2-core-media only.

Indicates whether the timeRanges of the receiver’s instructions conform to the requirements described for them immediately above (in connection with the instructions property) and also whether all of the layer instructions have a value for trackID that corresponds either to a track of the specified asset or to the receiver’s animationTool.

Parameter tracks: Pass a reference to an AVAsset’s tracks if you wish to validate the trackIDs of the layer instructions against the asset’s tracks. Pass nil to skip that validation. This method throws an exception if the tracks are not all from the same asset.

Parameter duration: Pass an AVAsset if you wish to validate the timeRanges of the instructions against the duration of the asset. Pass kCMTimeInvalid to skip that validation.

Parameter timeRange: A CMTimeRange. Only those instructions with timeRanges that overlap with the specified timeRange will be validated. To validate all instructions that may be used for playback or other processing, regardless of timeRange, pass CMTimeRangeMake(kCMTimeZero, kCMTimePositiveInfinity).

Parameter validationDelegate: Indicates an object implementing the AVVideoCompositionValidationHandling protocol to receive information about troublesome portions of a video composition during processing of -isValidForAsset:. May be nil.

In the course of validation, the receiver will invoke its validationDelegate with reference to any trouble spots in the video composition. An exception will be raised if the delegate modifies the receiver’s array of instructions or the array of layerInstructions of any AVVideoCompositionInstruction contained therein during validation.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AVVideoComposition> for AVMutableVideoComposition

fn as_ref(&self) -> &AVVideoComposition

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<AVVideoComposition> for AVVideoComposition

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<AnyObject> for AVVideoComposition

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for AVVideoComposition

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AVVideoComposition> for AVMutableVideoComposition

fn borrow(&self) -> &AVVideoComposition

Immutably borrows from an owned value.

impl Borrow<AnyObject> for AVVideoComposition

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for AVVideoComposition

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for AVVideoComposition

const NAME: &'static str = "AVVideoComposition"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<AVVideoComposition as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl CopyingHelper for AVVideoComposition

type Result = AVVideoComposition

The immutable counterpart of the type, or Self if the type has no immutable counterpart.

impl Debug for AVVideoComposition

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for AVVideoComposition

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for AVVideoComposition

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for AVVideoComposition

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl MutableCopyingHelper for AVVideoComposition

type Result = AVMutableVideoComposition

The mutable counterpart of the type, or Self if the type has no mutable counterpart.

impl NSCopying for AVVideoComposition

fn copy(&self) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

unsafe fn copyWithZone(&self, zone: *mut NSZone) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

impl NSMutableCopying for AVVideoComposition

fn mutableCopy(&self) -> Retained<Self::Result>

where Self: Sized + Message + MutableCopyingHelper,

Returns a new instance that’s a mutable copy of the receiver.

unsafe fn mutableCopyWithZone( &self, zone: *mut NSZone, ) -> Retained<Self::Result>

where Self: Sized + Message + MutableCopyingHelper,

Returns a new instance that’s a mutable copy of the receiver.

impl NSObjectProtocol for AVVideoComposition

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for AVVideoComposition

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for AVVideoComposition

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for AVVideoComposition

impl Eq for AVVideoComposition