iOS Developer Library

Developer

AVFoundation Framework Reference AVCaptureVideoPreviewLayer Class Reference

Options
Deployment Target:

On This Page
Language:

AVCaptureVideoPreviewLayer

Inheritance


Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 4.0 and later.

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.

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

    Declaration

    Swift

    var videoGravity: String!

    Objective-C

    @property(copy) NSString *videoGravity

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • orientation orientation (iOS 6.0) Property

    The layer’s orientation.

    Deprecation Statement

    Use videoOrientation (AVCaptureConnection) instead.

    Declaration

    Objective-C

    @property(nonatomic) AVCaptureVideoOrientation orientation

    Discussion

    Changes in orientation are not supported on all hardware configurations. You should check the value of supportsVideoOrientation (AVCaptureConnection) before attempting to change the orientation of the receiver. An exception is raised if this requirement is ignored.

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 6.0.

  • Indicates whether the layer display supports changing the orientation. (read-only)

    Deprecation Statement

    Use supportsVideoOrientation (AVCaptureConnection) instead.

    Declaration

    Objective-C

    @property(nonatomic, readonly, getter=isOrientationSupported) BOOL orientationSupported

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 6.0.

    See Also

    orientation

  • mirrored mirrored (iOS 6.0) Property

    Indicates whether the layer display is mirrored.

    Deprecation Statement

    Use videoMirrored (AVCaptureConnection) instead.

    Declaration

    Objective-C

    @property(nonatomic, getter=isMirrored) BOOL mirrored

    Discussion

    To change the value of this property, the value of automaticallyAdjustsMirroring must be NOfalse.

    Mirroring is not supported on all hardware configurations. You should check the value of supportsVideoMirroring (AVCaptureConnection) before attempting to change this value.

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 6.0.

  • Indicates whether the layer display supports mirroring. (read-only)

    Deprecation Statement

    Use supportsVideoMirroring (AVCaptureConnection) instead.

    Declaration

    Objective-C

    @property(nonatomic, readonly, getter=isMirroringSupported) BOOL mirroringSupported

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 6.0.

    See Also

    mirrored

  • Indicates whether the layer display automatically adjusts mirroring.

    Deprecation Statement

    Use automaticallyAdjustsVideoMirroring (AVCaptureConnection) instead.

    Declaration

    Objective-C

    @property(nonatomic) BOOL automaticallyAdjustsMirroring

    Discussion

    For some session configurations, preview will be mirrored by default.

    When the value of this property is YEStrue, the value of mirrored may change depending on the configuration of the session, for example after switching to a different capture device input.

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 6.0.

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

    Declaration

    Swift

    var connection: AVCaptureConnection! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • session session Property

    The capture session instance being previewed.

    Declaration

    Swift

    var session: AVCaptureSession!

    Objective-C

    @property(nonatomic, retain) AVCaptureSession *session

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Attaches the receiver to a given session without implicitly forming a connection.

    Declaration

    Swift

    func setSessionWithNoConnection(_ session: AVCaptureSession!)

    Objective-C

    - (void)setSessionWithNoConnection:(AVCaptureSession *)session

    Parameters

    session

    A capture session.

    Discussion

    This method attaches the receiver to a given session without implicitly forming a connection to the first eligible video AVCaptureInputPort object. You should only use this method if you intend to manually form a connection between a desired AVCaptureInputPort object and the receiver using addConnection:.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    func captureDevicePointOfInterestForPoint(_ pointInLayer: CGPoint) -> CGPoint

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func pointForCaptureDevicePointOfInterest(_ captureDevicePointOfInterest: CGPoint) -> CGPoint

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func transformedMetadataObjectForMetadataObject(_ metadataObject: AVMetadataObject!) -> AVMetadataObject!

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func metadataOutputRectOfInterestForRect(_ rectInLayerCoordinates: CGRect) -> CGRect

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func rectForMetadataOutputRectOfInterest(_ rectInMetadataOutputCoordinates: CGRect) -> CGRect

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.