AVCaptureConnection Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in OS X v10.7 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

Creating a Connection

Configuration

Managing Video Configuration

Managing the Video Mirroring Settings

Properties

active

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

@property(nonatomic, readonly, getter=isActive) BOOL active
Availability
  • Available in OS X v10.7 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 OS X v10.7 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 OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.h

enabled

Indicates whether the connection is enabled.

@property(nonatomic, getter=isEnabled) BOOL enabled
Availability
  • Available in OS X v10.7 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 OS X v10.7 and later.
Declared In
AVCaptureSession.h

output

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

@property(nonatomic, readonly) AVCaptureOutput *output
Availability
  • Available in OS X v10.7 and later.
Declared In
AVCaptureSession.h

supportsVideoFieldMode

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

@property (nonatomic, readonly, getter=isVideoFieldModeSupported) BOOL supportsVideoFieldMode
Discussion

This property is only applicable to connections involving video.

Availability
  • Available in OS X v10.7 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 OS X v10.7 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 OS X v10.7 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 OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.h

videoFieldMode

An indicator of how interlaced video flowing through the connection should be treated

@property (nonatomic) AVVideoFieldMode videoFieldMode
Discussion

This property is only applicable to connections involving video.

You can only set this value if supportsVideoFieldMode is YES.

Availability
  • Available in OS X v10.7 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 OS X v10.7 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 OS X v10.7 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 OS X v10.7 and later.
See Also
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 OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.h

Class Methods

connectionWithInputPort:videoPreviewLayer:

Returns a capture connection describing a connection between the specified input port and the specified video preview layer.

+ (AVCaptureConnection *)connectionWithInputPort:(AVCaptureInputPort *)port videoPreviewLayer:(AVCaptureVideoPreviewLayer *)layer
Parameters
port

An AVCaptureInputPort object associated with an AVCaptureInput object.

layer

An AVCaptureVideoPreviewLayer object.

Return Value

A capture connection describing a connection between the port and layer.

Discussion

You can add the connection returned by this method to an AVCaptureSession instance using addConnection:.

When using addInput:: or addOutput:, connections are automatically formed between all compatible inputs and outputs. You do not need to manually create and add connections to the session unless you use the primitive addInputWithNoConnections: or addOutputWithNoConnections: methods.

Availability
  • Available in OS X v10.7 and later.
See Also
Related Sample Code
Declared In
AVCaptureSession.h

connectionWithInputPorts:output:

Returns a capture connection describing a connection between the specified input ports and the specified output.

+ (AVCaptureConnection *)connectionWithInputPorts:(NSArray *)ports output:(AVCaptureOutput *)output
Parameters
ports

An array of AVCaptureInputPort objects associated with AVCaptureInput objects.

output

An AVCaptureOutput object.

Return Value

A capture connection describing a connection between inputPorts and the output.

Discussion

You can add the connection returned by this method to an AVCaptureSession instance using addConnection:.

When using addInput:: or addOutput:, connections are automatically formed between all compatible inputs and outputs. You do not need to manually create and add connections to the session unless you use the primitive addInputWithNoConnections: or addOutputWithNoConnections: methods.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.h

Instance Methods

initWithInputPort:videoPreviewLayer:

Initializes a capture connection to describe a connection between the specified input port and the specified video preview layer.

- (id)initWithInputPort:(AVCaptureInputPort *)port videoPreviewLayer:(AVCaptureVideoPreviewLayer *)layer
Parameters
port

An AVCaptureInputPort object associated with an AVCaptureInput object.

layer

An AVCaptureVideoPreviewLayer object.

Return Value

A capture connection describing a connection between the port and layer.

Discussion

You can add the connection returned by this method to an AVCaptureSession instance using addConnection:.

When using addInput:: or addOutput:, connections are automatically formed between all compatible inputs and outputs. You do not need to manually create and add connections to the session unless you use the primitive addInputWithNoConnections: or addOutputWithNoConnections: methods.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.h

initWithInputPorts:output:

Initializes a capture connection to describe a connection between the specified input ports and the specified output.

- (id)initWithInputPorts:(NSArray *)ports output:(AVCaptureOutput *)output
Parameters
ports

An array of AVCaptureInputPort objects associated with AVCaptureInput objects.

output

An AVCaptureOutput object.

Return Value

A capture connection initialized to describe a connection between inputPorts and the output.

Discussion

You can add the connection returned by this method to an AVCaptureSession instance using addConnection:.

When using addInput:: or addOutput:, connections are automatically formed between all compatible inputs and outputs. You do not need to manually create and add connections to the session unless you use the primitive addInputWithNoConnections: or addOutputWithNoConnections: methods.

Availability
  • Available in OS X v10.7 and later.
See Also
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 OS X v10.7 and later.

Declared in AVCaptureSession.h.

AVCaptureVideoOrientationPortraitUpsideDown

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

Available in OS X v10.7 and later.

Declared in AVCaptureSession.h.

AVCaptureVideoOrientationLandscapeRight

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

Available in OS X v10.7 and later.

Declared in AVCaptureSession.h.

AVCaptureVideoOrientationLandscapeLeft

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

Available in OS X v10.7 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 OS X v10.7 and later.

Declared in AVCaptureSession.h.

AVVideoFieldModeTopOnly

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

Available in OS X v10.7 and later.

Declared in AVCaptureSession.h.

AVVideoFieldModeBottomOnly

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

Available in OS X v10.7 and later.

Declared in AVCaptureSession.h.

AVVideoFieldModeDeinterlace

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

Available in OS X v10.7 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...