Skip to content

Commit de3c258

Browse files
toyajiclaude
andcommitted
[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. 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> Co-Authored-By: Claude Sonnet 5 <[email protected]>
1 parent 62f038d commit de3c258

16 files changed

Lines changed: 1035 additions & 878 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: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,56 @@ 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_doesNotEnableWhenUnsupported() {
31+
let cam = createCam(with: DispatchQueue(label: "capture_session_queue"))
32+
let mockOutput = MockCapturePhotoOutput()
33+
mockOutput.flutterZeroShutterLagSupported = false
34+
cam.capturePhotoOutput = mockOutput
35+
36+
cam.setZeroShutterLagEnabled(true)
37+
38+
XCTAssertFalse(mockOutput.flutterZeroShutterLagEnabled)
39+
}
40+
41+
func testSetZeroShutterLagEnabled_appliesValueWithinConfigurationBlock() {
42+
let configuration = CameraTestUtils.createTestCameraConfiguration()
43+
let mockSession = MockCaptureSession()
44+
var beginCount = 0
45+
var commitCount = 0
46+
mockSession.beginConfigurationStub = { beginCount += 1 }
47+
mockSession.commitConfigurationStub = { commitCount += 1 }
48+
configuration.videoCaptureSession = mockSession
49+
let cam = CameraTestUtils.createTestCamera(configuration)
50+
51+
let mockOutput = MockCapturePhotoOutput()
52+
mockOutput.flutterZeroShutterLagSupported = true
53+
cam.capturePhotoOutput = mockOutput
54+
55+
cam.setZeroShutterLagEnabled(true)
56+
XCTAssertTrue(mockOutput.flutterZeroShutterLagEnabled)
57+
58+
cam.setZeroShutterLagEnabled(false)
59+
XCTAssertFalse(mockOutput.flutterZeroShutterLagEnabled)
60+
61+
// Setting the value it already has must not reconfigure the session.
62+
cam.setZeroShutterLagEnabled(false)
63+
64+
XCTAssertEqual(beginCount, 2)
65+
XCTAssertEqual(commitCount, 2)
66+
}
67+
1868
func testCaptureToFile_mustReportErrorToResultIfSavePhotoDelegateCompletionsWithError() {
1969
let errorExpectation = expectation(
2070
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: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -564,4 +564,19 @@ extension CameraPlugin: CameraApi {
564564
completion(.success(()))
565565
}
566566
}
567+
568+
func isZeroShutterLagSupported(completion: @escaping (Result<Bool, any Error>) -> Void) {
569+
captureSessionQueue.async { [weak self] in
570+
completion(.success(self?.camera?.isZeroShutterLagSupported() ?? false))
571+
}
572+
}
573+
574+
func setZeroShutterLagEnabled(
575+
enabled: Bool, completion: @escaping (Result<Void, any Error>) -> Void
576+
) {
577+
captureSessionQueue.async { [weak self] in
578+
self?.camera?.setZeroShutterLagEnabled(enabled)
579+
completion(.success(()))
580+
}
581+
}
567582
}

‎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: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -858,6 +858,30 @@ final class DefaultCamera: NSObject, Camera {
858858
self.imageQuality = quality
859859
}
860860

861+
func isZeroShutterLagSupported() -> Bool {
862+
return capturePhotoOutput.flutterZeroShutterLagSupported
863+
}
864+
865+
/// Applies the requested zero-shutter-lag state to the photo output.
866+
///
867+
/// Enabling is guarded on `flutterZeroShutterLagSupported`: setting
868+
/// `isZeroShutterLagEnabled` to `true` while unsupported throws
869+
/// `NSInvalidArgumentException`, and the platform interface documents this
870+
/// setting as best-effort. Changing the value requires a reconfiguration of
871+
/// the capture pipeline, so the update is wrapped in
872+
/// `beginConfiguration`/`commitConfiguration`.
873+
func setZeroShutterLagEnabled(_ enabled: Bool) {
874+
if enabled && !capturePhotoOutput.flutterZeroShutterLagSupported {
875+
return
876+
}
877+
if capturePhotoOutput.flutterZeroShutterLagEnabled == enabled {
878+
return
879+
}
880+
videoCaptureSession.beginConfiguration()
881+
capturePhotoOutput.flutterZeroShutterLagEnabled = enabled
882+
videoCaptureSession.commitConfiguration()
883+
}
884+
861885
func setExposureMode(_ mode: PlatformExposureMode) {
862886
exposureMode = mode
863887
applyExposureMode()

0 commit comments

Comments
 (0)