Skip to content

Commit 26d7196

Browse files
committed
[camera_android_camerax] Implement zero-shutter-lag capture
Android 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. Measured on a Galaxy S21 (SM-G991N): the captured frame lands 629 ms closer to the shutter tap, and shutter-to-file time drops 912 ms -> 639 ms (methodology and raw numbers in the issue). - `isZeroShutterLagSupported` -> [`CameraInfo.isZslSupported()`](https://developer.android.com/reference/androidx/camera/core/CameraInfo#isZslSupported()) - `setZeroShutterLagEnabled` -> [`ImageCapture.Builder.setCaptureMode`](https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setCaptureMode(int)) with [`CAPTURE_MODE_ZERO_SHUTTER_LAG`](https://developer.android.com/reference/androidx/camera/core/ImageCapture#CAPTURE_MODE_ZERO_SHUTTER_LAG) CameraX degrades on its own, and only for still capture. Per the CAPTURE_MODE_ZERO_SHUTTER_LAG reference above, the mode is disabled automatically when VideoCapture is bound, flash mode is not OFF, or an OEM extension is active. The granularity differs: flash falls back per shot ([`CaptureConfigAdapter.kt`](https://github.com/androidx/androidx/blob/androidx-main/camera/camera-camera2/src/main/java/androidx/camera/camera2/adapter/CaptureConfigAdapter.kt#L133-L138)), while a device without private reprocessing never activates the ZSL session at all ([`ZslControl.kt`](https://github.com/androidx/androidx/blob/androidx-main/camera/camera-camera2/src/main/java/androidx/camera/camera2/adapter/ZslControl.kt#L138-L150)). Apps need no special handling. <details><summary>Why the ImageCapture use case is recreated</summary> CameraX only accepts the capture mode at `Builder` time, so `setZeroShutterLagEnabled` unbinds and recreates the `ImageCapture` use case — the same approach the existing `setJpegImageQuality` uses for the same constraint. Both are refactored onto one shared `_recreateImageCapture()` helper, so both settings (`jpegQuality`, ZSL) are always reapplied together; `createCamera` applies them on initial construction as well. Regression tests cover both directions. </details> <details><summary>Experimental-API opt-in</summary> Both CameraX members are annotated [`@ExperimentalZeroShutterLag`](https://developer.android.com/reference/androidx/camera/core/ExperimentalZeroShutterLag), a `@RequiresOptIn` marker consumed per declaration. Handled with `@OptIn`, matching this plugin's existing opt-ins (`ExperimentalCamera2Interop`, `ExperimentalLensFacing`, `ExperimentalPersistentRecording`); no build configuration change and nothing reaches the Dart surface. Verified clean against the repo's lint setup (`warningsAsErrors` + baseline) with `gradlew lintDebug`. </details>
1 parent 5df210b commit 26d7196

14 files changed

Lines changed: 407 additions & 14 deletions

File tree

‎packages/camera/camera_android_camerax/CHANGELOG.md‎

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

38
* Adds explicit `androidx.concurrent:concurrent-futures:1.2.0` dependency to fix

‎packages/camera/camera_android_camerax/android/src/main/java/io/flutter/plugins/camerax/CameraInfoProxyApi.java‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
import androidx.camera.core.CameraInfo;
1010
import androidx.camera.core.CameraSelector;
1111
import androidx.camera.core.ExperimentalLensFacing;
12+
import androidx.camera.core.ExperimentalZeroShutterLag;
1213
import androidx.camera.core.ExposureState;
1314

1415
/**
@@ -61,4 +62,10 @@ public LiveDataProxyApi.LiveDataWrapper getZoomState(CameraInfo pigeonInstance)
6162
return new LiveDataProxyApi.LiveDataWrapper(
6263
pigeonInstance.getZoomState(), LiveDataSupportedType.ZOOM_STATE);
6364
}
65+
66+
@Override
67+
@OptIn(markerClass = ExperimentalZeroShutterLag.class)
68+
public boolean isZslSupported(CameraInfo pigeonInstance) {
69+
return pigeonInstance.isZslSupported();
70+
}
6471
}

‎packages/camera/camera_android_camerax/android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2199,6 +2199,13 @@ abstract class PigeonApiCameraInfo(
21992199
pigeon_instance: androidx.camera.core.CameraInfo
22002200
): io.flutter.plugins.camerax.LiveDataProxyApi.LiveDataWrapper
22012201

2202+
/**
2203+
* Returns whether the camera supports zero-shutter-lag capture.
2204+
*
2205+
* See https://developer.android.com/reference/androidx/camera/core/CameraInfo#isZslSupported().
2206+
*/
2207+
abstract fun isZslSupported(pigeon_instance: androidx.camera.core.CameraInfo): Boolean
2208+
22022209
companion object {
22032210
@Suppress("LocalVariableName")
22042211
fun setUpMessageHandlers(binaryMessenger: BinaryMessenger, api: PigeonApiCameraInfo?) {
@@ -2247,6 +2254,28 @@ abstract class PigeonApiCameraInfo(
22472254
channel.setMessageHandler(null)
22482255
}
22492256
}
2257+
run {
2258+
val channel =
2259+
BasicMessageChannel<Any?>(
2260+
binaryMessenger,
2261+
"dev.flutter.pigeon.camera_android_camerax.CameraInfo.isZslSupported",
2262+
codec)
2263+
if (api != null) {
2264+
channel.setMessageHandler { message, reply ->
2265+
val args = message as List<Any?>
2266+
val pigeon_instanceArg = args[0] as androidx.camera.core.CameraInfo
2267+
val wrapped: List<Any?> =
2268+
try {
2269+
listOf(api.isZslSupported(pigeon_instanceArg))
2270+
} catch (exception: Throwable) {
2271+
CameraXLibraryPigeonUtils.wrapError(exception)
2272+
}
2273+
reply.reply(wrapped)
2274+
}
2275+
} else {
2276+
channel.setMessageHandler(null)
2277+
}
2278+
}
22502279
}
22512280
}
22522281

@@ -4248,7 +4277,8 @@ abstract class PigeonApiImageCapture(
42484277
resolutionSelector: androidx.camera.core.resolutionselector.ResolutionSelector?,
42494278
targetRotation: Long?,
42504279
flashMode: CameraXFlashMode?,
4251-
jpegQuality: Long?
4280+
jpegQuality: Long?,
4281+
zeroShutterLagEnabled: Boolean?
42524282
): androidx.camera.core.ImageCapture
42534283

42544284
abstract fun resolutionSelector(
@@ -4290,11 +4320,16 @@ abstract class PigeonApiImageCapture(
42904320
val targetRotationArg = args[2] as Long?
42914321
val flashModeArg = args[3] as CameraXFlashMode?
42924322
val jpegQualityArg = args[4] as Long?
4323+
val zeroShutterLagEnabledArg = args[5] as Boolean?
42934324
val wrapped: List<Any?> =
42944325
try {
42954326
api.pigeonRegistrar.instanceManager.addDartCreatedInstance(
42964327
api.pigeon_defaultConstructor(
4297-
resolutionSelectorArg, targetRotationArg, flashModeArg, jpegQualityArg),
4328+
resolutionSelectorArg,
4329+
targetRotationArg,
4330+
flashModeArg,
4331+
jpegQualityArg,
4332+
zeroShutterLagEnabledArg),
42984333
pigeon_identifierArg)
42994334
listOf(null)
43004335
} catch (exception: Throwable) {

‎packages/camera/camera_android_camerax/android/src/main/java/io/flutter/plugins/camerax/ImageCaptureProxyApi.java‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66

77
import androidx.annotation.NonNull;
88
import androidx.annotation.Nullable;
9+
import androidx.annotation.OptIn;
10+
import androidx.camera.core.ExperimentalZeroShutterLag;
911
import androidx.camera.core.ImageCapture;
1012
import androidx.camera.core.ImageCaptureException;
1113
import androidx.camera.core.resolutionselector.ResolutionSelector;
@@ -37,15 +39,20 @@ public ProxyApiRegistrar getPigeonRegistrar() {
3739

3840
@NonNull
3941
@Override
42+
@OptIn(markerClass = ExperimentalZeroShutterLag.class)
4043
public ImageCapture pigeon_defaultConstructor(
4144
@Nullable ResolutionSelector resolutionSelector,
4245
@Nullable Long targetRotation,
4346
@Nullable CameraXFlashMode flashMode,
44-
@Nullable Long jpegQuality) {
47+
@Nullable Long jpegQuality,
48+
@Nullable Boolean zeroShutterLagEnabled) {
4549
final ImageCapture.Builder builder = new ImageCapture.Builder();
4650
if (targetRotation != null) {
4751
builder.setTargetRotation(targetRotation.intValue());
4852
}
53+
if (Boolean.TRUE.equals(zeroShutterLagEnabled)) {
54+
builder.setCaptureMode(ImageCapture.CAPTURE_MODE_ZERO_SHUTTER_LAG);
55+
}
4956
if (flashMode != null) {
5057
// This sets the requested flash mode, but may fail silently.
5158
switch (flashMode) {

‎packages/camera/camera_android_camerax/android/src/test/java/io/flutter/plugins/camerax/CameraInfoTest.java‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,15 @@
55
package io.flutter.plugins.camerax;
66

77
import static org.junit.Assert.assertEquals;
8+
import static org.junit.Assert.assertTrue;
89
import static org.mockito.Mockito.mock;
910
import static org.mockito.Mockito.when;
1011

12+
import androidx.annotation.OptIn;
1113
import androidx.camera.core.CameraInfo;
1214
import androidx.camera.core.CameraSelector;
1315
import androidx.camera.core.CameraState;
16+
import androidx.camera.core.ExperimentalZeroShutterLag;
1417
import androidx.camera.core.ExposureState;
1518
import androidx.camera.core.ZoomState;
1619
import androidx.lifecycle.LiveData;
@@ -19,6 +22,17 @@
1922
import org.junit.Test;
2023

2124
public class CameraInfoTest {
25+
@Test
26+
@OptIn(markerClass = ExperimentalZeroShutterLag.class)
27+
public void isZslSupported_makesCallToRetrieveZslSupport() {
28+
final PigeonApiCameraInfo api = new TestProxyApiRegistrar().getPigeonApiCameraInfo();
29+
30+
final CameraInfo instance = mock(CameraInfo.class);
31+
when(instance.isZslSupported()).thenReturn(true);
32+
33+
assertTrue(api.isZslSupported(instance));
34+
}
35+
2236
@Test
2337
public void sensorRotationDegrees_makesCallToRetrieveSensorRotationDegrees() {
2438
final PigeonApiCameraInfo api = new TestProxyApiRegistrar().getPigeonApiCameraInfo();

‎packages/camera/camera_android_camerax/android/src/test/java/io/flutter/plugins/camerax/ImageCaptureTest.java‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@
1818
import android.os.Looper;
1919
import android.view.Surface;
2020
import androidx.annotation.NonNull;
21+
import androidx.annotation.OptIn;
22+
import androidx.camera.core.ExperimentalZeroShutterLag;
2123
import androidx.camera.core.ImageCapture;
2224
import androidx.camera.core.ImageCaptureException;
2325
import androidx.camera.core.resolutionselector.ResolutionSelector;
@@ -44,7 +46,7 @@ public void pigeon_defaultConstructor_createsImageCaptureWithCorrectConfiguratio
4446
final long targetResolution = Surface.ROTATION_0;
4547
final ImageCapture imageCapture =
4648
api.pigeon_defaultConstructor(
47-
mockResolutionSelector, targetResolution, CameraXFlashMode.OFF, null);
49+
mockResolutionSelector, targetResolution, CameraXFlashMode.OFF, null, null);
4850

4951
assertEquals(imageCapture.getResolutionSelector(), mockResolutionSelector);
5052
assertEquals(imageCapture.getTargetRotation(), Surface.ROTATION_0);
@@ -60,14 +62,39 @@ public void pigeon_defaultConstructor_setsJpegQualityWhenProvided() {
6062
final long jpegQuality = 75;
6163
final ImageCapture imageCapture =
6264
api.pigeon_defaultConstructor(
63-
mockResolutionSelector, targetRotation, CameraXFlashMode.OFF, jpegQuality);
65+
mockResolutionSelector, targetRotation, CameraXFlashMode.OFF, jpegQuality, null);
6466

6567
assertEquals(imageCapture.getResolutionSelector(), mockResolutionSelector);
6668
assertEquals(imageCapture.getTargetRotation(), Surface.ROTATION_0);
6769
assertEquals(imageCapture.getFlashMode(), ImageCapture.FLASH_MODE_OFF);
6870
assertEquals(imageCapture.getJpegQuality(), 75);
6971
}
7072

73+
@Test
74+
@OptIn(markerClass = ExperimentalZeroShutterLag.class)
75+
public void pigeon_defaultConstructor_setsZeroShutterLagCaptureModeWhenEnabled() {
76+
final PigeonApiImageCapture api = new TestProxyApiRegistrar().getPigeonApiImageCapture();
77+
78+
final ImageCapture imageCapture =
79+
api.pigeon_defaultConstructor(null, null, CameraXFlashMode.OFF, null, true);
80+
81+
assertEquals(ImageCapture.CAPTURE_MODE_ZERO_SHUTTER_LAG, imageCapture.getCaptureMode());
82+
}
83+
84+
@Test
85+
public void pigeon_defaultConstructor_leavesDefaultCaptureModeWhenZeroShutterLagIsNotEnabled() {
86+
final PigeonApiImageCapture api = new TestProxyApiRegistrar().getPigeonApiImageCapture();
87+
88+
assertEquals(
89+
ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY,
90+
api.pigeon_defaultConstructor(null, null, CameraXFlashMode.OFF, null, false)
91+
.getCaptureMode());
92+
assertEquals(
93+
ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY,
94+
api.pigeon_defaultConstructor(null, null, CameraXFlashMode.OFF, null, null)
95+
.getCaptureMode());
96+
}
97+
7198
@Test
7299
public void resolutionSelector_returnsExpectedResolutionSelector() {
73100
final PigeonApiImageCapture api = new TestProxyApiRegistrar().getPigeonApiImageCapture();

‎packages/camera/camera_android_camerax/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
video_player: ^2.7.0

‎packages/camera/camera_android_camerax/lib/src/android_camera_camerax.dart‎

Lines changed: 56 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,14 @@ class AndroidCameraCameraX extends CameraPlatform {
202202
///
203203
int? _lockedCaptureOrientation;
204204

205+
/// Whether zero-shutter-lag capture was requested via
206+
/// [setZeroShutterLagEnabled].
207+
bool _zeroShutterLagEnabled = false;
208+
209+
/// The JPEG compression quality requested via [setJpegImageQuality], if
210+
/// any.
211+
int? _jpegQuality;
212+
205213
/// Whether or not the default rotation for [UseCase]s needs to be set
206214
/// manually because the capture orientation was previously locked.
207215
///
@@ -414,6 +422,8 @@ class AndroidCameraCameraX extends CameraPlatform {
414422
resolutionSelector: _presetResolutionSelector,
415423
/* use CameraX default target rotation */ targetRotation: await deviceOrientationManager
416424
.getDefaultDisplayRotation(),
425+
jpegQuality: _jpegQuality,
426+
zeroShutterLagEnabled: _zeroShutterLagEnabled,
417427
);
418428

419429
// Configure VideoCapture and Recorder instances.
@@ -1092,19 +1102,60 @@ class AndroidCameraCameraX extends CameraPlatform {
10921102
/// the new instance automatically.
10931103
@override
10941104
Future<void> setJpegImageQuality(int cameraId, int quality) async {
1095-
// Unbind the current ImageCapture if it exists and is bound.
1096-
if (imageCapture != null) {
1097-
await _unbindUseCaseFromLifecycle(imageCapture!);
1105+
_jpegQuality = quality;
1106+
await _recreateImageCapture();
1107+
}
1108+
1109+
/// Returns whether the selected camera supports zero-shutter-lag capture.
1110+
///
1111+
/// The default implementation returns `false`.
1112+
@override
1113+
Future<bool> isZeroShutterLagSupported(int cameraId) async {
1114+
return cameraInfo?.isZslSupported() ?? false;
1115+
}
1116+
1117+
/// Enables or disables zero-shutter-lag capture for still image capture.
1118+
///
1119+
/// CameraX only supports setting the capture mode via `ImageCapture.Builder`
1120+
/// at construction time, so this recreates the `ImageCapture` use case with
1121+
/// the requested mode. The next call to [takePicture] will bind the new
1122+
/// instance automatically.
1123+
///
1124+
/// This is a no-op on devices that do not support zero-shutter-lag; CameraX
1125+
/// falls back to the regular capture pipeline on its own.
1126+
@override
1127+
Future<void> setZeroShutterLagEnabled(int cameraId, bool enabled) async {
1128+
_zeroShutterLagEnabled = enabled;
1129+
await _recreateImageCapture();
1130+
}
1131+
1132+
/// Recreates [imageCapture] from the currently requested settings
1133+
/// ([_jpegQuality], [_zeroShutterLagEnabled]).
1134+
///
1135+
/// CameraX only supports several `ImageCapture` settings via
1136+
/// `ImageCapture.Builder` at construction time, so any change to one of
1137+
/// them requires unbinding and recreating the whole use case. The next
1138+
/// call to [takePicture] will bind the new instance automatically.
1139+
///
1140+
/// If no camera has been created yet, this only updates the requested
1141+
/// settings; [createCamera] applies them when the camera is created.
1142+
Future<void> _recreateImageCapture() async {
1143+
if (imageCapture == null) {
1144+
return;
10981145
}
10991146

1100-
// Recreate ImageCapture with the requested JPEG quality.
1147+
// Unbind the current ImageCapture if it exists and is bound.
1148+
await _unbindUseCaseFromLifecycle(imageCapture!);
1149+
1150+
// Recreate ImageCapture with the requested settings.
11011151
// Preserve locked orientation if set, otherwise use default display rotation.
11021152
final int targetRotation =
11031153
_lockedCaptureOrientation ?? await deviceOrientationManager.getDefaultDisplayRotation();
11041154
imageCapture = ImageCapture(
11051155
resolutionSelector: _presetResolutionSelector,
11061156
targetRotation: targetRotation,
1107-
jpegQuality: quality,
1157+
jpegQuality: _jpegQuality,
1158+
zeroShutterLagEnabled: _zeroShutterLagEnabled,
11081159
);
11091160
}
11101161

0 commit comments

Comments
 (0)