AVVideoCompositing Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 7.0 and later.
Declared in
AVVideoCompositing.h
objc/NSObject.h

Overview

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.

Tasks

Creating a Video Compositing Instance

Rendering the Composition

Render Context Settings

Pixel Buffer Attributes

Properties

requiredPixelBufferAttributesForRenderContext

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

@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.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVVideoCompositing.h

sourcePixelBufferAttributes

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

@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.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVVideoCompositing.h

Instance Methods

cancelAllPendingVideoCompositionRequests

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

- (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.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVVideoCompositing.h

init

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

- (id)init
Return Value

An initialized instance of the class implementing the protocol.

Availability
  • Available in iOS 2.0 and later.
Declared In
objc/NSObject.h

renderContextChanged:

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

- (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.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVVideoCompositing.h

startVideoCompositionRequest:

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

- (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).

Availability
  • Available in iOS 7.0 and later.
Declared In
AVVideoCompositing.h