AVCaptureConnection Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 and later.
Companion guide
AV Foundation Programming Guide
Declared in
AVCaptureSession.h
Related sample code

Overview

An AVCaptureConnection object represents a connection between capture input and capture output objects associated with a capture session.

Capture inputs (instances of AVCaptureInput) have one or more input ports (instances of AVCaptureInputPort). Capture outputs (instances of AVCaptureOutput) can accept data from one or more sources (for example, an AVCaptureMovieFileOutput object accepts both video and audio data).

You can only add an AVCaptureConnection instance to a session using addConnection: if canAddConnection: returns YES. When using addInput: or addOutput:, connections are formed automatically between all compatible inputs and outputs. You only need to add connections manually when adding an input or output with no connections. You can also use connections to enable or disable the flow of data from a given input or to a given output.

Tasks

Configuration

Managing Video Configuration

Managing the Video Mirroring Settings

Managing the Video Stabilization Settings

Properties

active

Indicates whether the connection is active. (read-only)

@property(nonatomic, readonly, getter=isActive) BOOL active
Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

audioChannels

An array of AVCaptureAudioChannel objects. (read-only)

@property(nonatomic, readonly) NSArray *audioChannels
Discussion

This property is only applicable to connections involving audio.

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

automaticallyAdjustsVideoMirroring

A Boolean value that indicates whether the value of videoMirrored can change based on configuration of the session.

@property (nonatomic) BOOL automaticallyAdjustsVideoMirroring
Discussion

For some session configurations, video data flowing through the connection will be mirrored by default. When the value of this property is YES, the value of videoMirrored may change depending on the configuration of the session, for example after switching to a different capture device input.

The default value is YES.

Availability
  • Available in iOS 6.0 and later.
See Also
Declared In
AVCaptureSession.h

enabled

Indicates whether the connection is enabled.

@property(nonatomic, getter=isEnabled) BOOL enabled
Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

enablesVideoStabilizationWhenAvailable

A Boolean value that indicates whether the system should enable video stabilization when it is available.

@property(nonatomic) BOOL enablesVideoStabilizationWhenAvailable
Discussion

The default value of this property is NO. If the supportsVideoStabilization property contains the value YES, you can change the value of this property to YES to enable video stabilization for the connection.

You can only enable video stabilization for connections that operate on video. Even so, not all source formats and video resolutions are supported. Enabling video stabilization may also introduce additional latency into the video capture pipeline. To detect when video stabilization is in use, use the videoStabilizationEnabled property.

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

inputPorts

The connection’s input ports. (read-only)

@property(nonatomic, readonly) NSArray *inputPorts
Discussion

Input ports are instances of AVCaptureInputPort.

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

output

The connection’s output port. (read-only)

@property(nonatomic, readonly) AVCaptureOutput *output
Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

supportsVideoMaxFrameDuration

A Boolean value that indicates whether the connection supports setting the videoMaxFrameDuration property. (read-only)

@property(nonatomic, readonly, getter=isVideoMaxFrameDurationSupported) BOOL supportsVideoMaxFrameDuration
Discussion

This property is only applicable to connections involving video.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
AVCaptureSession.h

supportsVideoMinFrameDuration

A Boolean value that indicates whether the connection supports setting the videoMinFrameDuration property. (read-only)

@property(nonatomic, readonly, getter=isVideoMinFrameDurationSupported) BOOL supportsVideoMinFrameDuration
Discussion

This property is only applicable to connections involving video.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
AVCaptureSession.h

supportsVideoMirroring

A Boolean value that indicates whether the connection supports video mirroring. (read-only)

@property(nonatomic, readonly, getter=isVideoMirroringSupported) BOOL supportsVideoMirroring
Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVCaptureSession.h

supportsVideoOrientation

A Boolean value that indicates whether the connection supports changing the orientation of the video. (read-only)

@property(nonatomic, readonly, getter=isVideoOrientationSupported) BOOL supportsVideoOrientation
Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVCaptureSession.h

supportsVideoStabilization

A Boolean value that indicates whether this connection supports video stabilization. (read-only)

@property(nonatomic, readonly, getter=isVideoStabilizationSupported) BOOL supportsVideoStabilization
Discussion

Video stabilization is supported only for video connection types. And even for video connections, it might not be available at all resolutions.

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

videoMaxFrameDuration

The maximum time interval between which the receiver should output consecutive video frames.

@property(nonatomic) CMTime videoMaxFrameDuration
Discussion

The value of this property specifies the maximum duration of each video frame output by the connection, placing an upper bound on the amount of time that should separate consecutive frames. The value is equivalent to the reciprocal of the minimum frame rate.

A value of kCMTimeZero or kCMTimeInvalid indicates an unlimited minimum frame rate.

The default value is kCMTimeInvalid.

You can only set this value if supportsVideoMaxFrameDuration is YES.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
AVCaptureSession.h

videoMaxScaleAndCropFactor

The maximum video scale and crop factor by the connection. (read-only)

@property(nonatomic, readonly) CGFloat videoMaxScaleAndCropFactor
Discussion

The value specifies the maximum value that you can use when setting the videoScaleAndCropFactor property.

This property is only applicable to connections involving video.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
AVCaptureSession.h

videoMinFrameDuration

The minimum time interval between which the receiver should output consecutive video frames.

@property(nonatomic) CMTime videoMinFrameDuration
Discussion

The value of this property specifies the minimum duration of each video frame output by the connection, placing a lower bound on the amount of time that should separate consecutive frames. The value is equivalent to the reciprocal of the maximum frame rate.

A value of kCMTimeZero or kCMTimeInvalid indicates an unlimited maximum frame rate.

The default value is kCMTimeInvalid.

You can only set this value if supportsVideoMinFrameDuration is YES.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
AVCaptureSession.h

videoMirrored

A Boolean value that indicates whether the video flowing through the connection should be mirrored about its vertical axis..

@property(nonatomic, getter=isVideoMirrored) BOOL videoMirrored
Discussion

This property is only applicable to connections involving video.

if the value of supportsVideoMirroring is YES, you can set videoMirrored to YES to flip the video about its vertical axis and produce a mirror-image effect.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVCaptureSession.h

videoOrientation

The orientation of the video.

@property(nonatomic) AVCaptureVideoOrientation videoOrientation
Discussion

This property is only applicable to connections involving video.

If the value of supportsVideoOrientation is YES, you can set videoOrientation to rotate the video buffers being consumed by the connection’s output. Setting videoOrientation does not necessarily result in a physical rotation of video buffers. For example, a video connection to an AVCaptureMovieFileOutput object handles orientation using a Quicktime track matrix; using an AVCaptureStillImageOutput object, orientation is handled using Exif tags.

Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
AVCaptureSession.h

videoPreviewLayer

The video preview layer associated with the connection. (read-only)

@property (nonatomic, readonly) AVCaptureVideoPreviewLayer *videoPreviewLayer
Discussion

This property is the set if you initialized the connection using initWithInputPort:videoPreviewLayer: or connectionWithInputPort:videoPreviewLayer:.

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

videoScaleAndCropFactor

The current video scale and crop factor in use by the receiver.

@property(nonatomic) CGFloat videoScaleAndCropFactor
Discussion

This property is only applicable to connections involving video.

You can set this property to a value in the range of 1.0 to the value of videoMaxScaleAndCropFactor. At a factor of 1.0, the image is its original size. At a factor greater than 1.0, the image is scaled by the factor and center-cropped to its original dimensions.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
AVCaptureSession.h

videoStabilizationEnabled

A Boolean value that indicates whether video stabilization is active for the connection. (read-only)

@property(nonatomic, readonly, getter=isVideoStabilizationEnabled) BOOL videoStabilizationEnabled
Discussion

If video stabilization is supported for the current connection type, and you enable it using the enablesVideoStabilizationWhenAvailable property, this property reports when stabilization is actively in use for the connection.

You can monitor this property using key-value observing if you want to detect when video stabilization is being applied to the video data.

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

Constants

AVCaptureVideoOrientation

Constants indicating video orientation.

enum {
   AVCaptureVideoOrientationPortrait           = 1,
   AVCaptureVideoOrientationPortraitUpsideDown = 2,
   AVCaptureVideoOrientationLandscapeRight     = 3,
   AVCaptureVideoOrientationLandscapeLeft      = 4,
};
typedef NSInteger AVCaptureVideoOrientation;
Constants
AVCaptureVideoOrientationPortrait

Indicates that video should be oriented vertically, top at the top.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureVideoOrientationPortraitUpsideDown

Indicates that video should be oriented vertically, top at the bottom.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureVideoOrientationLandscapeRight

Indicates that video should be oriented horizontally, top on the left.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureVideoOrientationLandscapeLeft

Indicates that video should be oriented horizontally, top on the right.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

Discussion

You use these constants in conjunction with an AVCaptureVideoPreviewLayer object; see videoOrientation.

AVVideoFieldMode

Constants indicating video field mode, for use with the videoFieldMode property.

enum {
   AVVideoFieldModeBoth        = 0,
   AVVideoFieldModeTopOnly     = 1,
   AVVideoFieldModeBottomOnly  = 2,
   AVVideoFieldModeDeinterlace = 3,
};
typedef NSInteger AVVideoFieldMode;
Constants
AVVideoFieldModeBoth

Indicates that both top and bottom video fields in interlaced content should be passed through.

Available in iOS 6.0 and later.

Declared in AVCaptureSession.h.

AVVideoFieldModeTopOnly

Indicates that only the top video field in interlaced content should be passed through.

Available in iOS 6.0 and later.

Declared in AVCaptureSession.h.

AVVideoFieldModeBottomOnly

Indicates that the bottom video field only in interlaced content should be passed through.

Available in iOS 6.0 and later.

Declared in AVCaptureSession.h.

AVVideoFieldModeDeinterlace

Indicates that top and bottom video fields in interlaced content should be deinterlaced.

Available in iOS 6.0 and later.

Declared in AVCaptureSession.h.



© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...