AVCaptureVideoPreviewLayer Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 and later.
Declared in
AVCaptureVideoPreviewLayer.h
Related sample code

Overview

AVCaptureVideoPreviewLayer is a subclass of CALayer that you use to display video as it is being captured by an input device.

You use this preview layer in conjunction with an AV capture session, as illustrated in the following code fragment:

AVCaptureSession *captureSession = <#Get a capture session#>;
AVCaptureVideoPreviewLayer *previewLayer = [AVCaptureVideoPreviewLayer layerWithSession:captureSession];
UIView *aView = <#The view in which to present the layer#>;
previewLayer.frame = aView.bounds; // Assume you want the preview layer to fill the view.
[aView.layer addSublayer:previewLayer];

You use the videoGravity property to influence how content is viewed relative to the layer bounds. On some hardware configurations, you can manipulate the orientation of the layer using orientation and mirrored.

Tasks

Creating a Preview Layer

Layer Configuration

Configuration

Converting Between Coordinate Systems

Properties

connection

The capture connection describing the AVCaptureInputPort to which the preview layer is connected. (read-only)

@property(nonatomic, readonly) AVCaptureConnection *connection
Discussion

If you invoke initWithSession:, layerWithSession:, or setSession: (see session) with a valid AVCaptureSession instance, a connection is formed to the first eligible video AVCaptureInput object. If the preview layer is detached from a session, the connection property becomes nil.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVCaptureVideoPreviewLayer.h

session

The capture session instance being previewed.

@property(nonatomic, retain) AVCaptureSession *session
Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVCaptureVideoPreviewLayer.h

videoGravity

Indicates how the video is displayed within a player layer’s bounds rect.

@property(copy) NSString *videoGravity
Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureVideoPreviewLayer.h

Class Methods

layerWithSession:

Returns a preview layer initialized with a given capture session.

+ (id)layerWithSession:(AVCaptureSession *)session
Parameters
session

The capture session from which to derive the preview.

Return Value

A preview layer initialized to use session.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureVideoPreviewLayer.h

Instance Methods

captureDevicePointOfInterestForPoint:

Converts a point from layer coordinates to the coordinate space of the capture device.

- (CGPoint)captureDevicePointOfInterestForPoint:(CGPoint)pointInLayer
Parameters
pointInLayer

A point in the coordinate system of this layer object. The coordinates of this point represent pixel values.

Return Value

A scalar point whose coordinates are relative to the coordinate system of the capture device that is providing input to the layer.

Discussion

The coordinates in the point structure returned by this method are in the range 0.0 to 1.0. The point (0.0, 0.0) corresponds to the top left corner of the unrotated picture and the point (1.0, 1.0) represents the bottom right corner of the unrotated picture.

The conversion performed by this method takes the layer’s frame size and the receiver’s videoGravity property into consideration.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVCaptureVideoPreviewLayer.h

initWithSession:

Initializes a preview layer with a given capture session.

- (id)initWithSession:(AVCaptureSession *)session
Parameters
session

The capture session from which to derive the preview.

Return Value

A preview layer initialized to use session.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVCaptureVideoPreviewLayer.h

metadataOutputRectOfInterestForRect:

Converts a rectangle in the preview layer’s coordinate system to one in the coordinate system used for metadata outputs.

- (CGRect)metadataOutputRectOfInterestForRect:(CGRect)rectInLayerCoordinates
Parameters
rectInLayerCoordinates

A rectangle in the AVCaptureVideoPreviewLayer object’s coordinate system.

Return Value

A rectangle in the AVCaptureMetadataOutput coordinate system.

Discussion

The rectangle of interest for an AVCaptureMetadataOutput object is in a coordinate system extending from (0,0) in the top left to (1,1) in the bottom right, relative to the device’s natural orientation. A capture output object uses a pixel coordinate space which may be zoomed, rotated, or mirrored. Use this convenience method to quickly convert between coordinate spaces.

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

pointForCaptureDevicePointOfInterest:

Converts a point from the coordinate space of the capture device to the coordinate space of the layer.

- (CGPoint)pointForCaptureDevicePointOfInterest:(CGPoint)captureDevicePointOfInterest
Parameters
captureDevicePointOfInterest

A scalar point whose coordinates are relative to the coordinate system of the capture device that is providing input to the layer. The coordinates in this point must be in the range 0.0 to 1.0, where the point (0.0, 0.0) corresponds to the top left corner of the unrotated picture and the point (1.0, 1.0) represents the bottom right corner of the unrotated picture.

Return Value

A point in the coordinate system of this layer object. The coordinates of this point represent pixel values.

Discussion

The conversion performed by this method takes the layer’s frame size and the receiver’s videoGravity property into consideration.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVCaptureVideoPreviewLayer.h

rectForMetadataOutputRectOfInterest:

Converts a rectangle in the coordinate system used for metadata outputs to one in the preview layer’s coordinate system.

- (CGRect)rectForMetadataOutputRectOfInterest:(CGRect)rectInMetadataOutputCoordinates
Parameters
rectInMetadataOutputCoordinates

A rectangle in the AVCaptureMetadataOutput coordinate system.

Return Value

A rectangle in the AVCaptureVideoPreviewLayer object’s coordinate system.

Discussion

The rectangle of interest for an AVCaptureMetadataOutput object is in a coordinate system extending from (0,0) in the top left to (1,1) in the bottom right, relative to the device’s natural orientation. A capture output object uses a pixel coordinate space which may be zoomed, rotated, or mirrored. Use this convenience method to quickly convert between coordinate spaces.

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

transformedMetadataObjectForMetadataObject:

Converts a metadata object’s visual properties to layer coordinates.

- (AVMetadataObject *)transformedMetadataObjectForMetadataObject:(AVMetadataObject *)metadataObject
Parameters
metadataObject

The metadata object whose visual properties you want to convert. The metadata object must originate from the same AVCaptureInput as the preview layer.

Return Value

A metadata object whose visual properties have been converted into layer coordinates, or nil if the metadataObject originates from an input source other than that of the preview layer.

Discussion

An AVMetadataObject's bounds may be expressed as a rect, where an origin point of (0.0, 0.0) represents the top-left corner of an unrotated picture and (1.0, 1.0) represents the bottom-right corner of an unrotated picture. Face metadata objects also express a yaw and roll angle with respect to an unrotated picture. This method converts all of the metadata object’s visual properties to the coordinate space of the receiver, taking into account orientation, mirroring, layer bounds and videoGravity.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVCaptureVideoPreviewLayer.h