iOS Developer Library

Developer

AVFoundation Framework Reference AVCaptureVideoDataOutputSampleBufferDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

AVCaptureVideoDataOutputSampleBufferDelegate

Inherits From


Not Applicable

Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 4.0 and later

This protocol defines an interface for delegates of an AVCaptureVideoDataOutput object to receive captured video sample buffers and be notified of late sample buffers that were dropped.

The delegate of an AVCaptureVideoDataOutput object must adopt the AVCaptureVideoDataOutputSampleBufferDelegate protocol. The methods in this protocol are optional.

  • Notifies the delegate that a new video frame was written.

    Declaration

    Swift

    optional func captureOutput(_ captureOutput: AVCaptureOutput!, didOutputSampleBuffer sampleBuffer: CMSampleBuffer!, fromConnection connection: AVCaptureConnection!)

    Objective-C

    - (void)captureOutput:(AVCaptureOutput *)captureOutput didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer fromConnection:(AVCaptureConnection *)connection

    Parameters

    captureOutput

    The capture output object.

    sampleBuffer

    A CMSampleBuffer object containing the video frame data and additional information about the frame, such as its format and presentation time.

    connection

    The connection from which the video was received.

    Discussion

    Delegates receive this message whenever the output captures and outputs a new video frame, decoding or re-encoding it as specified by its videoSettings property. Delegates can use the provided video frame in conjunction with other APIs for further processing.

    This method is called on the dispatch queue specified by the output’s sampleBufferCallbackQueue property. It is called periodically, so it must be efficient to prevent capture performance problems, including dropped frames.

    If you need to reference the CMSampleBuffer object outside of the scope of this method, you must CFRetain it and then CFRelease it when you are finished with it.

    To maintain optimal performance, some sample buffers directly reference pools of memory that may need to be reused by the device system and other capture inputs. This is frequently the case for uncompressed device native capture where memory blocks are copied as little as possible. If multiple sample buffers reference such pools of memory for too long, inputs will no longer be able to copy new samples into memory and those samples will be dropped.

    If your application is causing samples to be dropped by retaining the provided CMSampleBufferRef objects for too long, but it needs access to the sample data for a long period of time, consider copying the data into a new buffer and then releasing the sample buffer (if it was previously retained) so that the memory it references can be reused.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • Notifies the delegate that a video frame was discarded.

    Declaration

    Swift

    optional func captureOutput(_ captureOutput: AVCaptureOutput!, didDropSampleBuffer sampleBuffer: CMSampleBuffer!, fromConnection connection: AVCaptureConnection!)

    Objective-C

    - (void)captureOutput:(AVCaptureOutput *)captureOutput didDropSampleBuffer:(CMSampleBufferRef)sampleBuffer fromConnection:(AVCaptureConnection *)connection

    Parameters

    captureOutput

    The capture output object.

    sampleBuffer

    A CMSampleBuffer object containing information about the dropped frame, such as its format and presentation time..

    This sample buffer contains none of the original video data.

    connection

    The connection from which the video was received.

    Discussion

    Delegates receive this message whenever a late video frame is dropped. This method is called once for each dropped frame. It is called on the dispatch queue specified by the output’s sampleBufferCallbackQueue property.

    The sampleBuffer will contain a kCMSampleBufferAttachmentKey_DroppedFrameReason attachment that details why the frame was dropped. The frame may be dropped because it was late (kCMSampleBufferDroppedFrameReason_FrameWasLate), typically caused by the client’s processing taking too long. It can also be dropped because the module providing frames is out of buffers (kCMSampleBufferDroppedFrameReason_OutOfBuffers). Frames can also be dropped due to a discontinuity (kCMSampleBufferDroppedFrameReason_Discontinuity), if the module providing sample buffers has experienced a discontinuity, and an unknown number of frames have been lost. This condition is typically caused by the system being too busy.

    Because this method is called on the same dispatch queue that is responsible for outputting video frames, it must be efficient to prevent further capture performance problems, such as additional dropped video frames.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later