Skip to content

Commit 4a1f3c5

Browse files
authored
[camera] Add support for zero-shutter-lag capture (flutter#12374)
Combines the interface and both implementations in one PR per the [federated plugin process](https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#changing-federated-plugins); splits into an interface-first PR once the direction is approved. The API shape is a proposal for flutter#190598 — happy to reshape it however you prefer. Adds explicit **zero-shutter-lag** control: an opt-in on Android, where the default capture mode leaves it off, and an opt-out on iOS, where the OS enables it automatically when the session supports it. ## What's added `camera_platform_interface` — two methods on `CameraPlatform`, modeled on the existing `setJpegImageQuality` / `getSupportedVideoStabilizationModes` patterns. Defaults are `false` / no-op, so nothing changes for platforms or apps that don't opt in: ```dart Future<bool> isZeroShutterLagSupported(int cameraId); Future<void> setZeroShutterLagEnabled(int cameraId, bool enabled); ``` `camera_android_camerax` — [`CameraInfo.isZslSupported()`](https://developer.android.com/reference/androidx/camera/core/CameraInfo#isZslSupported()) and [`ImageCapture.Builder.setCaptureMode(CAPTURE_MODE_ZERO_SHUTTER_LAG)`](https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setCaptureMode(int)). The capture mode is construction-only, so the use case is recreated — the approach `setJpegImageQuality` already uses for the same constraint, now sharing one helper so the two settings can't drop each other. `camera_avfoundation` — [`isZeroShutterLagSupported`](https://developer.apple.com/documentation/avfoundation/avcapturephotooutput/iszeroshutterlagsupported) / [`isZeroShutterLagEnabled`](https://developer.apple.com/documentation/avfoundation/avcapturephotooutput/iszeroshutterlagenabled) (iOS 17+). Enabling is guarded on the support query (setting it while unsupported throws `NSInvalidArgumentException`) and wrapped in `beginConfiguration`/`commitConfiguration`. The requested state is reapplied after camera switches, which silently reset it. Apps that never call the setter are left untouched, so iOS keeps its automatic behavior on upgrade. ## Notes for reviewers - **Platform defaults differ**: Android leaves ZSL off by default, iOS 17+ turns it on automatically when supported — so the same call is an opt-in on Android and an opt-out on iOS. Measurements below. - **Experimental API**: `CAPTURE_MODE_ZERO_SHUTTER_LAG` is `@ExperimentalZeroShutterLag`, handled with per-declaration `@OptIn` like this plugin's existing `ExperimentalCamera2Interop` / `ExperimentalLensFacing` / `ExperimentalPersistentRecording`. `gradlew lint` is clean. - **Unsupported cases need no app handling**: CameraX falls back on its own; iOS is guarded by the support query. - **Generated files**: regenerating with pigeon 26.1.5 also reverts two pre-existing hand-edits from flutter#11616 (a redundant `Int32` cast and a missing doc comment). - **CI**: the publish check is red by design — the last commit holds the `make-deps-path-based` overrides and is reverted before landing. <details><summary>On-device measurements</summary> **Android** — Galaxy S21 (SM-G991N), 5 captures per mode, shutter fired via `adb shell input tap`. A running millisecond stopwatch was photographed; the time visible in each saved photo shows how far behind the shutter tap the captured frame is. | | Captured frame | Shutter → file saved | |---|---|---| | `MINIMIZE_LATENCY` (current) | baseline | 912 ms | | `ZERO_SHUTTER_LAG` | **629 ms earlier** | 639 ms | **iOS** — iPhone (iOS 26.5), `ResolutionPreset.max`, 5 captures per mode after discarding one warm-up capture. Compares `AVCapturePhoto.timestamp` against the host-clock time of the `capturePhoto` call, so a negative value means the saved frame predates the call. | | Frame vs. shutter call | Shutter → delegate | |---|---|---| | ZSL off | +279 ms | 941 ms | | ZSL on | **−74 ms** | 689 ms | With ZSL on, every captured frame predated the capture call. Support is session-dependent rather than device-wide: the same device reports supported at `ResolutionPreset.max` and unsupported at `medium`. Since iOS enables this automatically, these numbers describe what the toggle controls — not an improvement this PR delivers on iOS. </details> Part of flutter#190598 ## Pre-Review Checklist [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent 559aeed commit 4a1f3c5

5 files changed

Lines changed: 160 additions & 5 deletions

File tree

‎packages/camera/camera/CHANGELOG.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
1-
## NEXT
1+
## 0.12.2
22

3+
* Adds `CameraController.isZeroShutterLagSupported` and
4+
`CameraController.setZeroShutterLagEnabled` for zero-shutter-lag still image
5+
capture on platforms that support it.
36
* Updates minimum supported SDK version to Flutter 3.41/Dart 3.11.
47

58
## 0.12.1

‎packages/camera/camera/lib/src/camera_controller.dart‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -796,6 +796,35 @@ class CameraController extends ValueNotifier<CameraValue> {
796796
}
797797
}
798798

799+
/// Returns whether the selected camera supports zero-shutter-lag capture.
800+
///
801+
/// Zero-shutter-lag reduces the latency of [takePicture] by returning a
802+
/// recently buffered frame instead of waiting for a new capture.
803+
Future<bool> isZeroShutterLagSupported() async {
804+
_throwIfNotInitialized('isZeroShutterLagSupported');
805+
try {
806+
return await CameraPlatform.instance.isZeroShutterLagSupported(_cameraId);
807+
} on PlatformException catch (e) {
808+
throw CameraException(e.code, e.message);
809+
}
810+
}
811+
812+
/// Enables or disables zero-shutter-lag capture for still image capture.
813+
///
814+
/// [isZeroShutterLagSupported] must be called first; only call this method
815+
/// when it returns `true`.
816+
///
817+
/// When enabled, [takePicture] returns a recently buffered frame instead of
818+
/// waiting for a new capture, reducing shutter latency.
819+
Future<void> setZeroShutterLagEnabled(bool enabled) async {
820+
_throwIfNotInitialized('setZeroShutterLagEnabled');
821+
try {
822+
await CameraPlatform.instance.setZeroShutterLagEnabled(_cameraId, enabled);
823+
} on PlatformException catch (e) {
824+
throw CameraException(e.code, e.message);
825+
}
826+
}
827+
799828
/// Sets the flash mode for taking pictures.
800829
Future<void> setFlashMode(FlashMode mode) async {
801830
try {

‎packages/camera/camera/pubspec.yaml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: A Flutter plugin for controlling the camera. Supports previewing
44
Dart.
55
repository: https://github.com/flutter/packages/tree/main/packages/camera/camera
66
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+camera%22
7-
version: 0.12.1
7+
version: 0.12.2
88

99
environment:
1010
sdk: ^3.12.0
@@ -21,9 +21,9 @@ flutter:
2121
default_package: camera_web
2222

2323
dependencies:
24-
camera_android_camerax: ^0.7.4
25-
camera_avfoundation: ^0.10.2
26-
camera_platform_interface: ^2.13.1
24+
camera_android_camerax: ^0.7.6
25+
camera_avfoundation: ^0.11.1
26+
camera_platform_interface: ^2.15.0
2727
camera_web: ^0.3.3
2828
flutter:
2929
sdk: flutter

‎packages/camera/camera/test/camera_preview_test.dart‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,12 @@ class FakeController extends ValueNotifier<CameraValue> implements CameraControl
105105
@override
106106
Future<void> setZoomLevel(double zoom) async {}
107107

108+
@override
109+
Future<bool> isZeroShutterLagSupported() async => false;
110+
111+
@override
112+
Future<void> setZeroShutterLagEnabled(bool enabled) async {}
113+
108114
@override
109115
Future<void> startImageStream(onLatestImageAvailable onAvailable) async {}
110116

‎packages/camera/camera/test/camera_test.dart‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -727,6 +727,110 @@ void main() {
727727
verify(CameraPlatform.instance.setZoomLevel(mockInitializeCamera, 42.0)).called(1);
728728
});
729729

730+
test('isZeroShutterLagSupported() returns the platform value.', () async {
731+
final cameraController = CameraController(
732+
const CameraDescription(
733+
name: 'cam',
734+
lensDirection: CameraLensDirection.back,
735+
sensorOrientation: 90,
736+
),
737+
ResolutionPreset.max,
738+
);
739+
740+
await cameraController.initialize();
741+
when(
742+
CameraPlatform.instance.isZeroShutterLagSupported(mockInitializeCamera),
743+
).thenAnswer((_) async => true);
744+
745+
expect(await cameraController.isZeroShutterLagSupported(), isTrue);
746+
verify(CameraPlatform.instance.isZeroShutterLagSupported(mockInitializeCamera)).called(1);
747+
748+
reset(CameraPlatform.instance);
749+
});
750+
751+
test('isZeroShutterLagSupported() throws $CameraException when uninitialized.', () async {
752+
final cameraController = CameraController(
753+
const CameraDescription(
754+
name: 'cam',
755+
lensDirection: CameraLensDirection.back,
756+
sensorOrientation: 90,
757+
),
758+
ResolutionPreset.max,
759+
);
760+
761+
expect(
762+
() => cameraController.isZeroShutterLagSupported(),
763+
throwsA(
764+
isA<CameraException>()
765+
.having(
766+
(CameraException error) => error.code,
767+
'code',
768+
'Uninitialized CameraController',
769+
)
770+
.having(
771+
(CameraException error) => error.description,
772+
'description',
773+
'isZeroShutterLagSupported() was called on an uninitialized CameraController.',
774+
),
775+
),
776+
);
777+
});
778+
779+
test(
780+
'setZeroShutterLagEnabled() completes and calls method channel with correct value.',
781+
() async {
782+
final cameraController = CameraController(
783+
const CameraDescription(
784+
name: 'cam',
785+
lensDirection: CameraLensDirection.back,
786+
sensorOrientation: 90,
787+
),
788+
ResolutionPreset.max,
789+
);
790+
791+
await cameraController.initialize();
792+
await cameraController.setZeroShutterLagEnabled(true);
793+
794+
verify(
795+
CameraPlatform.instance.setZeroShutterLagEnabled(mockInitializeCamera, true),
796+
).called(1);
797+
},
798+
);
799+
800+
test(
801+
'setZeroShutterLagEnabled() throws $CameraException when a platform exception occured.',
802+
() async {
803+
final cameraController = CameraController(
804+
const CameraDescription(
805+
name: 'cam',
806+
lensDirection: CameraLensDirection.back,
807+
sensorOrientation: 90,
808+
),
809+
ResolutionPreset.max,
810+
);
811+
812+
await cameraController.initialize();
813+
when(
814+
CameraPlatform.instance.setZeroShutterLagEnabled(mockInitializeCamera, true),
815+
).thenThrow(CameraException('TEST_ERROR', 'This is a test error messge'));
816+
817+
expect(
818+
() => cameraController.setZeroShutterLagEnabled(true),
819+
throwsA(
820+
isA<CameraException>()
821+
.having((CameraException error) => error.code, 'code', 'TEST_ERROR')
822+
.having(
823+
(CameraException error) => error.description,
824+
'description',
825+
'This is a test error messge',
826+
),
827+
),
828+
);
829+
830+
reset(CameraPlatform.instance);
831+
},
832+
);
833+
730834
test('setFlashMode() calls $CameraPlatform', () async {
731835
final cameraController = CameraController(
732836
const CameraDescription(
@@ -3705,6 +3809,19 @@ class MockCameraPlatform extends Mock with MockPlatformInterfaceMixin implements
37053809
Future<void> setVideoStabilizationMode(int cameraId, VideoStabilizationMode mode) async =>
37063810
super.noSuchMethod(Invocation.method(#setVideoStabilizationMode, <Object?>[cameraId, mode]));
37073811

3812+
@override
3813+
Future<bool> isZeroShutterLagSupported(int cameraId) async =>
3814+
super.noSuchMethod(
3815+
Invocation.method(#isZeroShutterLagSupported, <Object?>[cameraId]),
3816+
returnValue: Future<bool>.value(false),
3817+
)
3818+
as Future<bool>;
3819+
3820+
@override
3821+
Future<void> setZeroShutterLagEnabled(int cameraId, bool enabled) async => super.noSuchMethod(
3822+
Invocation.method(#setZeroShutterLagEnabled, <Object?>[cameraId, enabled]),
3823+
);
3824+
37083825
@override
37093826
Future<void> setJpegImageQuality(int? cameraId, int? quality) async =>
37103827
super.noSuchMethod(Invocation.method(#setJpegImageQuality, <Object?>[cameraId, quality]));

0 commit comments

Comments
 (0)