---

QTCaptureVideoPreviewOutput Class Reference

Overview

This class represents an output destination for a QTCaptureSession that can be used to preview the video being captured. Instances of QTCaptureVideoPreviewOutput produce decompressed video frames suitable for preview. Because the output video is intended for preview only, instances may drop frames or reduce output quality in order to improve overall performance of the capture session. Applications that need to process full-quality frames without dropping them should use QTCaptureDecompressedVideoOutput instead. Applications can access the decompressed frames from a QuickTime visual context for each output connection, or via the captureOutput:didOutputVideoFrame:withSampleBuffer:fromConnection: delegate method. In addition, clients can create subclasses of QTCaptureVideoPreviewOutput to add custom capturing behavior. Application Kit clients wishing to preview video do not normally need to use QTCaptureVideoPreviewOutput instances directly, as they are created and managed by instances of QTCaptureView. Clients should use QTCaptureVideoPreviewOutput directly only when they require preview functionality not provided by QTCaptureView or when they need to process decompressed frames directly.

Tasks

Previewing Output

• – delegate
• – visualContextForConnection:
• – outputVideoFrame:withSampleBuffer:fromConnection:
• – setDelegate:
• – setVisualContext:forConnection:

Capturing Output

• – captureOutput:didOutputVideoFrame:withSampleBuffer:fromConnection:  delegate method

Instance Methods

delegate

Returns the receiver’s delegate.

- (id)delegate

Availability

• Available in Mac OS X v10.5 and later.

Declared In

QTCaptureVideoPreviewOutput.h

outputVideoFrame:withSampleBuffer:fromConnection:

Called whenever the receiver outputs a new video frame.

- (void)outputVideoFrame:(CVImageBufferRef)videoFrame withSampleBuffer:(QTSampleBuffer *)sampleBuffer fromConnection:(QTCaptureConnection *)connection

Parameters

videoFrame

A buffer containing the decompressed frame.

sampleBuffer

A sample buffer containing additional information about the frame, such as its presentation time.

connection

The connection from which the video was received.

Discussion

This method should not be invoked directly. Subclasses can override this method to provide custom processing behavior for each frame. The default implementation calls the delegate’s captureOutput:didOutputVideoFrame:withSampleBuffer:fromConnection: method. Subclasses should not assume that this method will be called on the main thread. In addition, this method is called periodically, so it must be efficient to prevent capture performance problems.

Availability

• Mac OS X v10.5 and later.
• Not available to 64-bit applications.

Declared In

QTCaptureVideoPreviewOutput.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)delegate

Availability

• Available in Mac OS X v10.5 and later.

Declared In

QTCaptureVideoPreviewOutput.h

setVisualContext:forConnection:

Sets the QuickTime visual context used to preview the video for the described connection.

- (void)setVisualContext:(QTVisualContextRef)visualContext forConnection:(QTCaptureConnection *)connection

Parameters

visualContext

A QTVisualContextRef to be used for the preview of the given connection.

connection

The connection to be previewed by the given visual context.

Discussion

If the application has an existing visual context being used to display video, this method can be used to set the visual context for the preview.

Availability

• Mac OS X v10.5 and later.
• Not available to 64-bit applications.

Declared In

QTCaptureVideoPreviewOutput.h

visualContextForConnection:

Returns the QuickTime visual context used to preview the video for the given connection.

- (QTVisualContextRef)visualContextForConnection:(QTCaptureConnection *)connection

Parameters

connection

The connection previewed by the returned visual context.

Return Value

A QTVisualContextRef that provides access to a video preview for the given connection.

Discussion

The returned visual context can be used to obtain frames that can be used to display a video preview of the capture session. By default this method returns NULL, until a visual context is set using setVisualContext:forConnection:.

Availability

• Mac OS X v10.5 and later.
• Not available to 64-bit applications.

Declared In

QTCaptureVideoPreviewOutput.h

Delegate Methods

captureOutput:didOutputVideoFrame:withSampleBuffer:fromConnection:

Called whenever the video preview output outputs a new video frame.

- (void)captureOutput:(QTCaptureOutput *)captureOutput didOutputVideoFrame:(CVImageBufferRef)videoFrame withSampleBuffer:(QTSampleBuffer *)sampleBuffer fromConnection:(QTCaptureConnection *)connection

Parameters

captureOutput

The QTCaptureVideoPreviewOutput instance that output the frame.

videoFrame

A CVImageBufferRef containing the decompressed frame.

sampleBuffer

A QTSampleBuffer object containing additional information about the frame, such as its presentation time.

connection

The connection from which the video was received.

Discussion

Delegates receive this method whenever the output decompresses and outputs a new video frame. Delegates can use the provided video frame for a custom preview or for further image processing. Delegates should not assume that this method will be called on the main thread. In addition, this method is called periodically, so it must be efficient to prevent capture performance problems.

Availability

• Mac OS X v10.5 and later.

Declared In

QTCaptureDecompressedVideoOutput.h

---