Class

AVCapturePhotoOutput

A capture output for use in workflows related to still photography.

Overview

AVCapturePhotoOutput provides a modern interface for most capture workflows related to still photography. In addition to basic capture of still images, a photo output supports RAW-format capture, bracketed capture of multiple images, Live Photos, and wide-gamut color. You can have images delivered in RAW format, a compressed format such as JPEG, or both. You can also enable automatic delivery of preview-sized images in addition to a main image. In addition, the AVCapturePhotoOutput class can format captured photos for output in the JPEG/JFIF and DNG file format.

To capture photos with the AVCapturePhotoOutput class, follow these steps:

  1. Create an AVCapturePhotoOutput object. Use its properties to determine supported capture settings and to enable certain features (for example, whether to capture Live Photos).

  2. Create and configure an AVCapturePhotoSettings object to choose features and settings for a specific capture (for example, whether to enable image stabilization or flash).

  3. Capture an image by passing your photo settings object to the capturePhoto(with:delegate:) method along with a delegate object implementing the AVCapturePhotoCaptureDelegate protocol. The photo capture output then calls your delegate to notify you of significant events during the capture process.

Some photo capture settings, such as the flashMode property, include options for automatic behavior. For such settings, the photo output determines whether to use that feature at the moment of capture—you don’t know when requesting a capture whether the feature will be enabled when the capture completes. When the photo capture output calls your AVCapturePhotoCaptureDelegate methods with information about the completed or in-progress capture, it also provides an AVCaptureResolvedPhotoSettings object that details which automatic features have been set for that capture. The resolved settings object’s uniqueID property matches the uniqueID value of the AVCapturePhotoSettings object you used to request capture.

Enabling certain photo features (Live Photo capture and high resolution capture) requires a reconfiguration of the capture render pipeline. To opt into these features, set the isHighResolutionCaptureEnabled, isLivePhotoCaptureEnabled, and isLivePhotoAutoTrimmingEnabled properties before calling your AVCaptureSession object’s startRunning() method. Changing any of these properties while the session is running disrupts the capture render pipeline: Live Photo captures in progress end immediately, unfulfilled photo requests abort, and video preview temporarily freezes.

Using a photo capture output adds other requirements to your AVCaptureSession object:

The AVCapturePhotoOutput class implicitly supports wide-gamut color photography. If the source AVCaptureDevice object’s activeColorSpace value is P3_D65, the capture output produces photos with wide color information (unless your AVCapturePhotoSettings object specifies an output format that does not support wide color).

Symbols

Capturing a Photo

Determining Available Settings

var availablePhotoPixelFormatTypes: [NSNumber]

The pixel formats this capture output currently supports for photo capture.

var availablePhotoCodecTypes: [String]

The compression codecs this capture output currently supports for photo capture.

var availableRawPhotoPixelFormatTypes: [NSNumber]

The pixel formats this capture output currently supports for RAW photo capture.

var isStillImageStabilizationSupported: Bool

A Boolean value indicating whether the capture output currently supports automatic stabilization for still image capture.

var isDualCameraFusionSupported: Bool

A Boolean value indicating whether the capture output currently supports automatically combining image data on a dual camera device.

var maxBracketedCapturePhotoCount: Int

The maximum number of images that the photo capture output can support in a single bracketed capture.

var isLensStabilizationDuringBracketedCaptureSupported: Bool

A Boolean value indicating whether the capture output currently supports lens stabilization during bracketed image capture.

var supportedFlashModes: [NSNumber]

The flash settings this capture output currently supports.

Monitoring the Visible Scene

var isFlashScene: Bool

A Boolean value indicating whether the scene currently being previewed by the camera warrants use of the flash.

var isStillImageStabilizationScene: Bool

A Boolean value indicating whether the scene currently being previewed by the camera warrants image stabilization.

var photoSettingsForSceneMonitoring: AVCapturePhotoSettings?

A photo settings object that controls how the photo output detects and handles automatic flash and stabilization modes.

Configuring High-Resolution Still Capture

var isHighResolutionCaptureEnabled: Bool

A Boolean value that specifies whether to configure the capture pipeline for high resolution still image capture.

Configuring Live Photo Capture

var isLivePhotoCaptureSupported: Bool

A Boolean value indicating whether the capture output currently supports Live Photo capture.

var isLivePhotoCaptureEnabled: Bool

A Boolean value that specifies whether to configure the capture pipeline for Live Photo capture.

var isLivePhotoCaptureSuspended: Bool

A Boolean value that specifies whether to suspend, but not disable, Live Photo capture.

var isLivePhotoAutoTrimmingEnabled: Bool

A Boolean value that specifies whether to automatically trim Live Photo movie captures to avoid excessive movement.

Preparing for Resource-Intensive Captures

var preparedPhotoSettingsArray: [AVCapturePhotoSettings]

An array of photo settings for which the photo output has prepared capture resources.

func setPreparedPhotoSettingsArray([AVCapturePhotoSettings], completionHandler: ((Bool, Error?) -> Void)? = nil)

Tells the photo capture output to prepare resources for future capture requests with the specified settings.

Getting Formatted Output Data

class func jpegPhotoDataRepresentation(forJPEGSampleBuffer: CMSampleBuffer, previewPhotoSampleBuffer: CMSampleBuffer?)

Returns data in JPEG format corresponding to the captured photo in the specified sample buffer.

class func dngPhotoDataRepresentation(forRawSampleBuffer: CMSampleBuffer, previewPhotoSampleBuffer: CMSampleBuffer?)

Returns data in digital negative (DNG) format corresponding to the captured RAW photo in the specified sample buffer.

Relationships

Inherits From