AVCaptureStillImageOutput Class Reference

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

Overview

AVCaptureStillImageOutput is a concrete sub class of AVCaptureOutput that you use to capture a high-quality still image with accompanying metadata.

Tasks

Capturing an Image

Getting and Setting Image Stabilization Settings

Configuring Image Settings

Image Format Conversion

Properties

automaticallyEnablesStillImageStabilizationWhenAvailable

A Boolean value that indicates whether still image stabilization should be automatically enabled.

@property(nonatomic) BOOL automaticallyEnablesStillImageStabilizationWhenAvailable
Discussion

If stillImageStabilizationSupported returns YES, image stabilization may be applied to reduce blur commonly found in low light photos. When stabilization is enabled, still image captures incur additional latency.

The default value is YES when supported by the input device; otherwise NO.

Setting this property throws an exception (NSInvalidArgumentException) if stillImageStabilizationSupported returns NO.

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

availableImageDataCodecTypes

The supported image codec formats that can be specified as output settings. (read-only)

@property(nonatomic, readonly) NSArray *availableImageDataCodecTypes
Discussion

The value of this property is an array of NSString objects that you can use as values for the AVVideoCodecKey in the outputSettings property.

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

availableImageDataCVPixelFormatTypes

The supported image pixel formats that can be specified as output settings. (read-only)

@property(nonatomic, readonly) NSArray *availableImageDataCVPixelFormatTypes
Discussion

The value of this property is an array of NSNumber objects that you can use as values for the kCVPixelBufferPixelFormatTypeKey in the outputSettings property.

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

capturingStillImage

Indicates whether a still image is being captured. (read-only)

@property(readonly, getter=isCapturingStillImage) BOOL capturingStillImage
Discussion

The value of this property is YES when a still image is being captured, and NO when no still image capture is underway.

This property supports Key-value observing.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVCaptureOutput.h

outputSettings

The compression settings for the output.

@property(nonatomic, copy) NSDictionary *outputSettings
Discussion

Use availableImageDataCVPixelFormatTypes and availableImageDataCodecTypes to determine what codec keys and pixel formats are supported.

On iOS the currently the only supported keys are AVVideoCodecKey and kCVPixelBufferPixelFormatTypeKey. The keys are mutually exclusive, only one may be present. The recommended values are kCMVideoCodecType_JPEG for AVVideoCodecKey and kCVPixelFormatType_420YpCbCr8BiPlanarFullRange and kCVPixelFormatType_32BGRA for kCVPixelBufferPixelFormatTypeKey.

On iOS 6.0 and later the AVVideoQualityKey is supported, and may only be used when AVVideoCodecKey is set to AVVideoCodecJPEG.

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

stillImageStabilizationActive

Indicates whether still image stabilization is in use for the current capture. (read-only)

@property(nonatomic, readonly, getter=isStillImageStabilizationActive) BOOL stillImageStabilizationActive
Discussion

The property returns YES if video stabilization is currently in use; otherwise NO.

This property supports Key-value observing.

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

stillImageStabilizationSupported

A Boolean value that indicates whether the still image currently being captured supports still image stabilization. (read-only)

@property(nonatomic, readonly, getter=isStillImageStabilizationSupported) BOOL stillImageStabilizationSupported
Discussion

The automaticallyEnablesStillImageStabilizationWhenAvailable property can only be set if this property returns YES.

The value may change as the session's sessionPreset or the input device's activeFormat changes.

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

Class Methods

jpegStillImageNSDataRepresentation:

Returns an NSData representation of a still image data and metadata attachments in a JPEG sample buffer.

+ (NSData *)jpegStillImageNSDataRepresentation:(CMSampleBufferRef)jpegSampleBuffer
Parameters
jpegSampleBuffer

The sample buffer carrying JPEG image data, optionally with Exif metadata sample buffer attachments.

This method throws an NSInvalidArgumentException if jpegSampleBuffer is NULL or not in the JPEG format.

Return Value

An NSData representation of jpegSampleBuffer.

Discussion

This method merges the image data and Exif metadata sample buffer attachments without re-compressing the image.

The returned NSData object is suitable for writing to disk.

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

Instance Methods

captureStillImageAsynchronouslyFromConnection:completionHandler:

Initiates a still image capture and returns immediately.

- (void)captureStillImageAsynchronouslyFromConnection:(AVCaptureConnection *)connection completionHandler:(void (^)(CMSampleBufferRef imageDataSampleBuffer, NSError *error))handler
Parameters
connection

The connection from which to capture the image.

handler

A block to invoke after the image has been captured. The block parameters are as follows:

imageDataSampleBuffer

The data that was captured.

The buffer attachments may contain metadata appropriate to the image data format. For example, a buffer containing JPEG data may carry a kCGImagePropertyExifDictionary as an attachment. See ImageIO/CGImageProperties.h for a list of keys and value types.

error

If the request could not be completed, an NSError object that describes the problem; otherwise nil.

Discussion

This method returns immediately after it is invoked, later calling the provided completion handler block when image data is ready. If the request could not be completed, the error parameter will contain an NSError object describing the failure.

You should not assume that the completion handler will be called on a specific thread.

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