iOS Developer Library — Pre-Release

Developer

AVFoundation Framework Reference AVVideoCompositing Protocol Reference

Options
Deployment Target:

On This Page
Language:

AVVideoCompositing

Inheritance


Not Applicable

Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 7.0 and later.

The AVVideoCompositing protocol defines properties and methods that custom video compositors must implement.

For each AV Foundation object of class AVPlayerItem, AVAssetExportSession, AVAssetImageGenerator, or AVAssetReaderVideoCompositionOutput that has a non-nil value for its videoComposition property, and the value of the customVideoCompositorClass property of the AVVideoComposition is not nil, AV Foundation creates and uses an instance of that custom video compositor class to process the instructions contained in the AVVideoComposition.

The custom video compositor instance will be created when you assign videoComposition an instance of AVVideoComposition that's associated with a different custom video compositor class than the object was previously using.

When creating instances of custom video compositors, AV Foundation initializes them by calling init and then makes them available as the value of the customVideoCompositor property of the object to which it was assigned. You then can do any additional setup or configuration to the custom compositor.

Custom video compositor instances will then be retained by the AV Foundation object for as long as the value of its videoComposition property indicates that an instance of the same custom video compositor class should be used, even if the value is changed from one instance of AVVideoComposition to another instance that's associated with the same custom video compositor class.

  • init() - init Required

    Initializes an instance of the class that implements the video compositing protocol. (required)

    Declaration

    Swift

    init()

    Objective-C

    - (instancetype)init

    Return Value

    An initialized instance of the class implementing the protocol.

    Import Statement

    Objective-C

    @import ObjectiveC;

    Swift

    import ObjectiveC

    Availability

    Available in iOS 2.0 and later.

  • Directs a custom video compositor object to create a new pixel buffer composed asynchronously from a collection of sources. (required)

    Declaration

    Swift

    func startVideoCompositionRequest(_ asyncVideoCompositionRequest: AVAsynchronousVideoCompositionRequest!)

    Objective-C

    - (void)startVideoCompositionRequest:(AVAsynchronousVideoCompositionRequest *)asyncVideoCompositionRequest

    Parameters

    asyncVideoCompositionRequest

    An instance of AVAsynchronousVideoCompositionRequest that provides context for the requested composition.

    Discussion

    The custom compositor is expected to invoke, either subsequently or immediately, the asyncVideoCompositionRequest object’s finishWithComposedVideoFrame: or finishWithError: methods.

    If you intend to finish rendering the frame after handling of this message returns, you must retain asyncVideoCompositionRequest until after composition is finished.

    Note that if the custom compositor's implementation of this method returns without finishing the composition immediately, it may be invoked again with another composition request before the prior request is finished; in such cases the custom compositor should be prepared to manage multiple composition requests.

    If the rendered frame is exactly the same as one of the source frames, with no letterboxing, pillboxing or cropping needed, then the appropriate source pixel buffer may be returned, after CFRetain has been called on it).

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • Directs a custom video compositor object to cancel or finish all pending video composition requests.

    Declaration

    Swift

    optional func cancelAllPendingVideoCompositionRequests()

    Objective-C

    - (void)cancelAllPendingVideoCompositionRequests

    Discussion

    Upon receiving this message, a custom video compositor must block until it has either cancelled all pending frame requests, and called the finishCancelledRequest method for each of them. If cancellation is not possible, the method must block until it has finished processing of all the frames and called the finishWithComposedVideoFrame: method for each of them.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • Invoked to notify the custom compositor that a composition will switch to a different render context. (required)

    Declaration

    Swift

    func renderContextChanged(_ newRenderContext: AVVideoCompositionRenderContext!)

    Objective-C

    - (void)renderContextChanged:(AVVideoCompositionRenderContext *)newRenderContext

    Parameters

    newRenderContext

    The new render context that will be handling video composition.

    Discussion

    Instances of classes implementing the AVVideoComposting protocol must implement this method to be notified when the AVVideoCompositionRenderContext instance handing a video composition changes. AVVideoCompositionRenderContext instances being immutable, such a change will occur every time there is a change in the video composition parameters.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • Returns the pixel buffer attributes required by the video compositor for new buffers created for processing. (required) (read-only)

    Declaration

    Swift

    var requiredPixelBufferAttributesForRenderContext: [NSObject : AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSDictionary *requiredPixelBufferAttributesForRenderContext

    Discussion

    The property is required to provide a kCVPixelBufferPixelFormatTypeKey key in the dictionary, along with attributes for which the compositor needs specific values to work properly. Omitted attributes will be supplied by the composition engine to allow for the best performance. If the attribute kCVPixelBufferPixelFormatTypeKey key is not in the dictionary an exception will be raised. The value of the kCVPixelBufferPixelFormatTypeKey is an array of kCVPixelFormatType_* constants as defined in Pixel_Format_Types.

    The value of requiredPixelBufferAttributesForRenderContext is retrieved prior to the creation of a new render context; the combination of the attributes in the returned value and the additional attributes supplied by the composition engine will be used in the creation of subsequent render context's pixelBuffers.

    This property is queried once before any composition request is sent to the compositor. Changing required buffer attributes afterwards is not supported.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • Returns the kinds of source frame pixel buffer attributes a video compositor can accept as input. (required) (read-only)

    Declaration

    Swift

    var sourcePixelBufferAttributes: [NSObject : AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSDictionary *sourcePixelBufferAttributes

    Discussion

    The property is required to provide a kCVPixelBufferPixelFormatTypeKey key in the dictionary, along with attributes for which the compositor needs specific values to work properly. Omitted attributes will be supplied by the composition engine to allow for the best performance. If the attribute kCVPixelBufferPixelFormatTypeKey key is not in the dictionary an exception will be raised. The value of the kCVPixelBufferPixelFormatTypeKey is an array of kCVPixelFormatType_* constants as defined in Pixel_Format_Types.

    If the custom compositor is meant to be used with an AVVideoCompositionCoreAnimationTool created using the videoCompositionCoreAnimationToolWithAdditionalLayer:asTrackID: method, kCVPixelFormatType_32BGRA should be included as one of the supported pixel format types.

    Missing attributes will be set by the composition engine to values allowing the best performance.

    This property is queried once before any composition request is sent to the compositor. Changing source buffer attributes afterwards is not supported.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.