setExposureModeCustom(lensAperture:duration:iso:completionHandler:)

Sets a custom exposure mode with the specified lens aperture, exposure duration, and ISO values.

Declaration

func setExposureModeCustom(lensAperture: Float, duration: CMTime, iso ISO: Float, completionHandler handler: (@Sendable (CMTime) -> Void)? = nil)

func setExposureModeCustom(lensAperture: Float, duration: CMTime, iso ISO: Float) async -> CMTime

Parameters

lensAperture:
The lens aperture, as described in the documentation for the Lensaperture property. You may specify one of the special AVFCapture/AVCaptureLensApertureCurrent or AVFCapture/AVCaptureLensApertureAuto constants listed in the discussion section below, or values between the Minlensaperture and Maxlensaperture of the Activeformat.
duration:
The exposure duration, as described in the documentation for the Exposureduration property. You may specify one of the special AVFCapture/AVCaptureExposureDurationCurrent or AVFCapture/AVCaptureExposureDurationAuto constants listed in the discussion section below, or values between the Minexposureduration and Maxexposureduration of the Activeformat.
ISO:
The exposure ISO value, as described in the documentation for the Iso property. You may specify one of the special AVFCapture/AVCaptureISOCurrent or AVFCapture/AVCaptureISOAuto constants listed in the discussion section below, or values between the Miniso and Maxiso of the Activeformat.
handler:
A block to be called when all parameters have been set to the values specified and Exposuremode Swift.property is set to Custom. If the setExposureModeCustom... methods are called multiple times, their completion handlers are always called in FIFO order. The block receives a timestamp which matches that of the first buffer to which all settings have been applied. Note that the timestamp is synchronized to the device clock, and thus must be converted to the Synchronizationclock prior to comparison with the timestamps of buffers delivered via an Avcapturevideodataoutput. The client may pass nil for the handler parameter if knowledge of the operation’s completion is not required.

Discussion

Besides a numeric value, each of the exposure parameters can be set to either of these special constants:

The applied exposure duration of streaming frames are limited to activeMaxExposureDuration when either lensAperture or ISO is set to “Auto”, but the full exposure duration may be applied during still capture. Auto parameter(s) will attempt to simulate how a still capture will appear, while maintaining the current frame rate for responsive preview. If none of the parameters are “Auto”, changes to the exposure duration may result in changes to activeVideoMaxFrameDuration.

If you wish to use the custom locked values for AVCapturePhotoOutput captures, you must set the photoQualityPrioritization property to AVCapturePhotoOutput.QualityPrioritization.speed. The default value of AVCapturePhotoOutput.QualityPrioritization.balanced allows photo capture to temporarily override the capture device’s ISO and exposureDuration values if the scene is dark enough to warrant some form of multi-image fusion to improve quality.

Note selecting speed prioritization disables image stabilization. If you then re-enable image stabilization via the deprecated isAutoStillImageStabilizationEnabled property or automaticallyEnablesStillImageStabilizationWhenAvailable property, this counteracts speed prioritization and can result in image capture adopting different exposure settings.