Skip to content

Commit 6ba32f3

Browse files
committed
[camera_avfoundation] Implement zero-shutter-lag capture
iOS implementation of the zero-shutter-lag API added in camera_platform_interface 2.14.0 (this bumps the constraint to ^2.14.0). Part of flutter/flutter#190598. ## What - `isZeroShutterLagSupported` -> [`AVCapturePhotoOutput.isZeroShutterLagSupported`](https://developer.apple.com/documentation/avfoundation/avcapturephotooutput/iszeroshutterlagsupported) (iOS 17+/macOS 14+; `false` on older versions) - `setZeroShutterLagEnabled` -> [`AVCapturePhotoOutput.isZeroShutterLagEnabled`](https://developer.apple.com/documentation/avfoundation/avcapturephotooutput/iszeroshutterlagenabled) ## Why explicit control when iOS auto-enables it Per the `AVCapturePhotoOutput.h` header, "For apps linked on or after iOS 17 zero shutter lag is automatically enabled when supported." The documented role of the setter is the explicit opt-out (WWDC23 session 10105: "you can set AVCapturePhotoOutput.isZeroShutterLagEnabled to false to opt out" - https://developer.apple.com/videos/play/wwdc2023/10105/), plus deterministic re-enable: support can be revoked by configuration changes, and when it is, the enabled state silently reverts. Because of that auto-enable, iOS 17+ starts with zero shutter lag on while Android starts with it off, so the same Dart call is an opt-out here and an opt-in there. No latency numbers are quoted for iOS: the platform already enables the mode by default, so this change is about making that state explicit and controllable, not about improving it. <details><summary>Guard and configuration timing</summary> The header states the property "may only be set to YES if zeroShutterLagSupported is YES, otherwise an NSInvalidArgumentException is thrown", and that changing it "requires a lengthy reconfiguration of the capture render pipeline", to be done within `beginConfiguration`/`commitConfiguration` while running. The implementation guards enabling on the support query and wraps the write in a configuration block. The requested state is kept (plugin- and camera-level) and reapplied after session reconfigurations and camera switches, which silently reset it — mirroring the settings-retention approach on the Android side. Availability is handled inside the `CapturePhotoOutput` protocol passthrough (`flutter`-prefixed members, matching the existing `CaptureDevice.flutterActiveFormat` pattern), so callers need no availability checks and pre-iOS 17 devices report unsupported / ignore writes. </details> Regenerating with pigeon 26.1.5 also reverts two pre-existing hand-edits to the generated files from flutter#11616 (a redundant Int32 fallback cast and a missing Dart doc comment).
1 parent ce9feb9 commit 6ba32f3

16 files changed

Lines changed: 349 additions & 6 deletions

File tree

‎packages/camera/camera_avfoundation/CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
## 0.10.3
2+
3+
* Adds support for zero-shutter-lag still image capture via
4+
`isZeroShutterLagSupported` and `setZeroShutterLagEnabled` (iOS 17+).
5+
16
## 0.10.2
27

38
* Adds `setJpegImageQuality` for controlling JPEG compression quality.

‎packages/camera/camera_avfoundation/darwin/Tests/Mocks/MockCamera.swift‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ final class MockCamera: NSObject, Camera {
2828
var unlockCaptureOrientationStub: (() -> Void)?
2929
var setImageFileFormatStub: ((PlatformImageFileFormat) -> Void)?
3030
var setJpegImageQualityStub: ((Int64) -> Void)?
31+
var isZeroShutterLagSupportedStub: (() -> Bool)?
32+
var setZeroShutterLagEnabledStub: ((Bool) -> Void)?
3133
var setExposureModeStub: ((PlatformExposureMode) -> Void)?
3234
var setExposureOffsetStub: ((Double) -> Void)?
3335
var setExposurePointStub: ((PlatformPoint?, @escaping (Result<Void, any Error>) -> Void) -> Void)?
@@ -149,6 +151,14 @@ final class MockCamera: NSObject, Camera {
149151
setJpegImageQualityStub?(quality)
150152
}
151153

154+
func isZeroShutterLagSupported() -> Bool {
155+
return isZeroShutterLagSupportedStub?() ?? false
156+
}
157+
158+
func setZeroShutterLagEnabled(_ enabled: Bool) {
159+
setZeroShutterLagEnabledStub?(enabled)
160+
}
161+
152162
func setExposureMode(_ mode: PlatformExposureMode) {
153163
setExposureModeStub?(mode)
154164
}

‎packages/camera/camera_avfoundation/darwin/Tests/Mocks/MockCapturePhotoOutput.swift‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ final class MockCapturePhotoOutput: NSObject, CapturePhotoOutput {
1313
var availablePhotoCodecTypes: [AVVideoCodecType] = []
1414
var isHighResolutionCaptureEnabled = false
1515
var supportedFlashModes: [AVCaptureDevice.FlashMode] = []
16+
var flutterZeroShutterLagSupported = false
17+
var flutterZeroShutterLagEnabled = false
1618

1719
// Stub that is called when the corresponding public method is called.
1820
var capturePhotoWithSettingsStub:

‎packages/camera/camera_avfoundation/darwin/Tests/PhotoCaptureTests.swift‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,82 @@ final class PhotoCaptureTests: XCTestCase {
1515
return CameraTestUtils.createTestCamera(configuration)
1616
}
1717

18+
func testIsZeroShutterLagSupported_returnsValueReportedByPhotoOutput() {
19+
let cam = createCam(with: DispatchQueue(label: "capture_session_queue"))
20+
let mockOutput = MockCapturePhotoOutput()
21+
mockOutput.flutterZeroShutterLagSupported = true
22+
cam.capturePhotoOutput = mockOutput
23+
24+
XCTAssertTrue(cam.isZeroShutterLagSupported())
25+
26+
mockOutput.flutterZeroShutterLagSupported = false
27+
XCTAssertFalse(cam.isZeroShutterLagSupported())
28+
}
29+
30+
func testSetZeroShutterLagEnabled_doesNotEnableOrReconfigureWhenUnsupported() {
31+
let configuration = CameraTestUtils.createTestCameraConfiguration()
32+
let mockSession = MockCaptureSession()
33+
var beginCount = 0
34+
mockSession.beginConfigurationStub = { beginCount += 1 }
35+
configuration.videoCaptureSession = mockSession
36+
let cam = CameraTestUtils.createTestCamera(configuration)
37+
38+
let mockOutput = MockCapturePhotoOutput()
39+
mockOutput.flutterZeroShutterLagSupported = false
40+
cam.capturePhotoOutput = mockOutput
41+
42+
cam.setZeroShutterLagEnabled(true)
43+
44+
XCTAssertFalse(mockOutput.flutterZeroShutterLagEnabled)
45+
XCTAssertEqual(beginCount, 0)
46+
}
47+
48+
func testSetZeroShutterLagEnabled_doesNotReconfigureWhenValueAlreadyMatches() {
49+
let configuration = CameraTestUtils.createTestCameraConfiguration()
50+
let mockSession = MockCaptureSession()
51+
var beginCount = 0
52+
mockSession.beginConfigurationStub = { beginCount += 1 }
53+
configuration.videoCaptureSession = mockSession
54+
let cam = CameraTestUtils.createTestCamera(configuration)
55+
56+
let mockOutput = MockCapturePhotoOutput()
57+
mockOutput.flutterZeroShutterLagSupported = true
58+
mockOutput.flutterZeroShutterLagEnabled = true
59+
cam.capturePhotoOutput = mockOutput
60+
61+
cam.setZeroShutterLagEnabled(true)
62+
63+
XCTAssertTrue(mockOutput.flutterZeroShutterLagEnabled)
64+
XCTAssertEqual(beginCount, 0)
65+
}
66+
67+
func testSetZeroShutterLagEnabled_appliesValueAndReconfiguresSession() {
68+
let configuration = CameraTestUtils.createTestCameraConfiguration()
69+
let mockSession = MockCaptureSession()
70+
var beginCount = 0
71+
var commitCount = 0
72+
mockSession.beginConfigurationStub = { beginCount += 1 }
73+
mockSession.commitConfigurationStub = { commitCount += 1 }
74+
configuration.videoCaptureSession = mockSession
75+
let cam = CameraTestUtils.createTestCamera(configuration)
76+
77+
let mockOutput = MockCapturePhotoOutput()
78+
mockOutput.flutterZeroShutterLagSupported = true
79+
cam.capturePhotoOutput = mockOutput
80+
81+
cam.setZeroShutterLagEnabled(true)
82+
XCTAssertTrue(mockOutput.flutterZeroShutterLagEnabled)
83+
84+
cam.setZeroShutterLagEnabled(false)
85+
XCTAssertFalse(mockOutput.flutterZeroShutterLagEnabled)
86+
87+
// Setting the value it already has must not reconfigure the session.
88+
cam.setZeroShutterLagEnabled(false)
89+
90+
XCTAssertEqual(beginCount, 2)
91+
XCTAssertEqual(commitCount, 2)
92+
}
93+
1894
func testCaptureToFile_mustReportErrorToResultIfSavePhotoDelegateCompletionsWithError() {
1995
let errorExpectation = expectation(
2096
description: "Must send error to result if save photo delegate completes with error.")

‎packages/camera/camera_avfoundation/darwin/camera_avfoundation/Sources/camera_avfoundation/Camera.swift‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,9 @@ protocol Camera: FlutterTexture, AVCaptureVideoDataOutputSampleBufferDelegate,
6464
func setImageFileFormat(_ fileFormat: PlatformImageFileFormat)
6565
func setJpegImageQuality(_ quality: Int64)
6666

67+
func isZeroShutterLagSupported() -> Bool
68+
func setZeroShutterLagEnabled(_ enabled: Bool)
69+
6770
func setExposureMode(_ mode: PlatformExposureMode)
6871
func setExposureOffset(_ offset: Double)
6972

‎packages/camera/camera_avfoundation/darwin/camera_avfoundation/Sources/camera_avfoundation/CameraPlugin.swift‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,11 @@ public final class CameraPlugin: NSObject, FlutterPlugin {
2121
/// An internal camera object that manages camera's state and performs camera operations.
2222
var camera: Camera?
2323

24+
/// The zero-shutter-lag state last requested via `setZeroShutterLagEnabled`,
25+
/// if any. Kept here so it survives camera recreation (e.g. switching
26+
/// cameras) and is applied to newly created cameras.
27+
private var zeroShutterLagRequested: Bool?
28+
2429
public static func register(with registrar: FlutterPluginRegistrar) {
2530
let instance = CameraPlugin(
2631
registry: registrar.textures(),
@@ -262,6 +267,11 @@ extension CameraPlugin: CameraApi {
262267
camera?.close()
263268
camera = newCamera
264269

270+
// Apply the zero-shutter-lag state requested before this camera existed.
271+
if let zeroShutterLagRequested = zeroShutterLagRequested {
272+
newCamera.setZeroShutterLagEnabled(zeroShutterLagRequested)
273+
}
274+
265275
ensureToRunOnMainQueue { [weak self] in
266276
guard let strongSelf = self else { return }
267277
completion(.success(strongSelf.registry.register(newCamera)))
@@ -564,4 +574,20 @@ extension CameraPlugin: CameraApi {
564574
completion(.success(()))
565575
}
566576
}
577+
578+
func isZeroShutterLagSupported(completion: @escaping (Result<Bool, any Error>) -> Void) {
579+
captureSessionQueue.async { [weak self] in
580+
completion(.success(self?.camera?.isZeroShutterLagSupported() ?? false))
581+
}
582+
}
583+
584+
func setZeroShutterLagEnabled(
585+
enabled: Bool, completion: @escaping (Result<Void, any Error>) -> Void
586+
) {
587+
captureSessionQueue.async { [weak self] in
588+
self?.zeroShutterLagRequested = enabled
589+
self?.camera?.setZeroShutterLagEnabled(enabled)
590+
completion(.success(()))
591+
}
592+
}
567593
}

‎packages/camera/camera_avfoundation/darwin/camera_avfoundation/Sources/camera_avfoundation/CaptureOutput.swift‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,15 @@ protocol CapturePhotoOutput: CaptureOutput {
5959
/// Corresponds to the `supportedFlashModes` property of `AVCapturePhotoOutput`
6060
var supportedFlashModes: [AVCaptureDevice.FlashMode] { get }
6161

62+
/// Corresponds to the `isZeroShutterLagSupported` property of
63+
/// `AVCapturePhotoOutput` on iOS 17+/macOS 14+; `false` on older versions.
64+
var flutterZeroShutterLagSupported: Bool { get }
65+
66+
/// Corresponds to the `isZeroShutterLagEnabled` property of
67+
/// `AVCapturePhotoOutput` on iOS 17+/macOS 14+; reads `false` and ignores
68+
/// writes on older versions.
69+
var flutterZeroShutterLagEnabled: Bool { get set }
70+
6271
/// Corresponds to the `capturePhotoWithSettings` method of `AVCapturePhotoOutput`
6372
func capturePhoto(with settings: AVCapturePhotoSettings, delegate: AVCapturePhotoCaptureDelegate)
6473
}
@@ -69,6 +78,27 @@ extension AVCapturePhotoOutput: CapturePhotoOutput {
6978
return self
7079
}
7180

81+
var flutterZeroShutterLagSupported: Bool {
82+
if #available(iOS 17.0, macOS 14.0, *) {
83+
return isZeroShutterLagSupported
84+
}
85+
return false
86+
}
87+
88+
var flutterZeroShutterLagEnabled: Bool {
89+
get {
90+
if #available(iOS 17.0, macOS 14.0, *) {
91+
return isZeroShutterLagEnabled
92+
}
93+
return false
94+
}
95+
set {
96+
if #available(iOS 17.0, macOS 14.0, *) {
97+
isZeroShutterLagEnabled = newValue
98+
}
99+
}
100+
}
101+
72102
func connection(with mediaType: AVMediaType) -> CaptureConnection? {
73103
// Explicit type is required to access the underlying AVCapturePhotoOutput.connection method
74104
let connection: AVCaptureConnection? = connection(with: mediaType)

‎packages/camera/camera_avfoundation/darwin/camera_avfoundation/Sources/camera_avfoundation/DefaultCamera.swift‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,12 @@ final class DefaultCamera: NSObject, Camera {
122122

123123
private var fileFormat = PlatformImageFileFormat.jpeg
124124
private var imageQuality: Int64 = 100
125+
126+
/// The zero-shutter-lag state last requested via [setZeroShutterLagEnabled],
127+
/// if any. Session reconfiguration (e.g. switching cameras) silently resets
128+
/// `isZeroShutterLagEnabled`, so the requested state is kept here and
129+
/// reapplied afterwards.
130+
private var zeroShutterLagRequested: Bool?
125131
private var lockedCaptureOrientation = UIDeviceOrientation.unknown
126132
private var exposureMode = PlatformExposureMode.auto
127133
private var focusMode = PlatformFocusMode.auto
@@ -858,6 +864,35 @@ final class DefaultCamera: NSObject, Camera {
858864
self.imageQuality = quality
859865
}
860866

867+
func isZeroShutterLagSupported() -> Bool {
868+
return capturePhotoOutput.flutterZeroShutterLagSupported
869+
}
870+
871+
/// Applies the requested zero-shutter-lag state to the photo output.
872+
///
873+
/// Enabling is guarded on `flutterZeroShutterLagSupported`: setting
874+
/// `isZeroShutterLagEnabled` to `true` while unsupported throws
875+
/// `NSInvalidArgumentException`, and the platform interface documents this
876+
/// setting as best-effort. Changing the value requires a reconfiguration of
877+
/// the capture pipeline, so the update is wrapped in
878+
/// `beginConfiguration`/`commitConfiguration`.
879+
func setZeroShutterLagEnabled(_ enabled: Bool) {
880+
zeroShutterLagRequested = enabled
881+
applyZeroShutterLag(enabled)
882+
}
883+
884+
private func applyZeroShutterLag(_ enabled: Bool) {
885+
if enabled && !capturePhotoOutput.flutterZeroShutterLagSupported {
886+
return
887+
}
888+
if capturePhotoOutput.flutterZeroShutterLagEnabled == enabled {
889+
return
890+
}
891+
videoCaptureSession.beginConfiguration()
892+
capturePhotoOutput.flutterZeroShutterLagEnabled = enabled
893+
videoCaptureSession.commitConfiguration()
894+
}
895+
861896
func setExposureMode(_ mode: PlatformExposureMode) {
862897
exposureMode = mode
863898
applyExposureMode()
@@ -1208,6 +1243,12 @@ final class DefaultCamera: NSObject, Camera {
12081243
videoCaptureSession.addConnection(newConnection)
12091244
videoCaptureSession.commitConfiguration()
12101245

1246+
// Reconfiguring the session silently resets `isZeroShutterLagEnabled`;
1247+
// reapply the state the caller last requested.
1248+
if let zeroShutterLagRequested = zeroShutterLagRequested {
1249+
applyZeroShutterLag(zeroShutterLagRequested)
1250+
}
1251+
12111252
completion(.success(()))
12121253
}
12131254

‎packages/camera/camera_avfoundation/darwin/camera_avfoundation/Sources/camera_avfoundation/Messages.swift‎

Lines changed: 48 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -724,8 +724,12 @@ protocol CameraApi {
724724
func setImageFileFormat(
725725
format: PlatformImageFileFormat, completion: @escaping (Result<Void, Error>) -> Void)
726726
/// Sets the JPEG compression quality for still image capture.
727-
func setJpegImageQuality(
728-
quality: Int64, completion: @escaping (Result<Void, Error>) -> Void)
727+
func setJpegImageQuality(quality: Int64, completion: @escaping (Result<Void, Error>) -> Void)
728+
/// Returns whether the current session configuration supports
729+
/// zero-shutter-lag capture.
730+
func isZeroShutterLagSupported(completion: @escaping (Result<Bool, Error>) -> Void)
731+
/// Enables or disables zero-shutter-lag capture.
732+
func setZeroShutterLagEnabled(enabled: Bool, completion: @escaping (Result<Void, Error>) -> Void)
729733
}
730734

731735
/// Generated setup class from Pigeon to handle messages through the `binaryMessenger`.
@@ -1373,7 +1377,7 @@ class CameraApiSetup {
13731377
if let api = api {
13741378
setJpegImageQualityChannel.setMessageHandler { message, reply in
13751379
let args = message as! [Any?]
1376-
let qualityArg = args[0] is Int64 ? args[0] as! Int64 : Int64(args[0] as! Int32)
1380+
let qualityArg = args[0] as! Int64
13771381
api.setJpegImageQuality(quality: qualityArg) { result in
13781382
switch result {
13791383
case .success:
@@ -1386,6 +1390,47 @@ class CameraApiSetup {
13861390
} else {
13871391
setJpegImageQualityChannel.setMessageHandler(nil)
13881392
}
1393+
/// Returns whether the current session configuration supports
1394+
/// zero-shutter-lag capture.
1395+
let isZeroShutterLagSupportedChannel = FlutterBasicMessageChannel(
1396+
name:
1397+
"dev.flutter.pigeon.camera_avfoundation.CameraApi.isZeroShutterLagSupported\(channelSuffix)",
1398+
binaryMessenger: binaryMessenger, codec: codec)
1399+
if let api = api {
1400+
isZeroShutterLagSupportedChannel.setMessageHandler { _, reply in
1401+
api.isZeroShutterLagSupported { result in
1402+
switch result {
1403+
case .success(let res):
1404+
reply(wrapResult(res))
1405+
case .failure(let error):
1406+
reply(wrapError(error))
1407+
}
1408+
}
1409+
}
1410+
} else {
1411+
isZeroShutterLagSupportedChannel.setMessageHandler(nil)
1412+
}
1413+
/// Enables or disables zero-shutter-lag capture.
1414+
let setZeroShutterLagEnabledChannel = FlutterBasicMessageChannel(
1415+
name:
1416+
"dev.flutter.pigeon.camera_avfoundation.CameraApi.setZeroShutterLagEnabled\(channelSuffix)",
1417+
binaryMessenger: binaryMessenger, codec: codec)
1418+
if let api = api {
1419+
setZeroShutterLagEnabledChannel.setMessageHandler { message, reply in
1420+
let args = message as! [Any?]
1421+
let enabledArg = args[0] as! Bool
1422+
api.setZeroShutterLagEnabled(enabled: enabledArg) { result in
1423+
switch result {
1424+
case .success:
1425+
reply(wrapResult(nil))
1426+
case .failure(let error):
1427+
reply(wrapError(error))
1428+
}
1429+
}
1430+
}
1431+
} else {
1432+
setZeroShutterLagEnabledChannel.setMessageHandler(nil)
1433+
}
13891434
}
13901435
}
13911436

‎packages/camera/camera_avfoundation/example/pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ dependencies:
1414
# The example app is bundled with the plugin so we use a path dependency on
1515
# the parent directory to use the current plugin's version.
1616
path: ../
17-
camera_platform_interface: ^2.13.0
17+
camera_platform_interface: ^2.14.0
1818
flutter:
1919
sdk: flutter
2020
path_provider: ^2.0.0

0 commit comments

Comments
 (0)