# CameraControl

Artifact: [androidx.camera:camera-core](https://developer.android.com/jetpack/androidx/releases/camera) [View Source](https://cs.android.com/search?q=file:androidx/camera/core/CameraControl.java+class:androidx.camera.core.CameraControl) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

*** ** * ** ***


```
public interface CameraControl
```

<br />

*** ** * ** ***

The `https://developer.android.com/reference/androidx/camera/core/CameraControl` provides various asynchronous operations like zoom, focus and metering which affects output of all `https://developer.android.com/reference/androidx/camera/core/UseCase`s currently bound to that camera.

The application can retrieve the `https://developer.android.com/reference/androidx/camera/core/CameraControl` instance via `https://developer.android.com/reference/androidx/camera/core/Camera#getCameraControl()`. `https://developer.android.com/reference/androidx/camera/core/CameraControl` is ready to start operations immediately after `https://developer.android.com/reference/androidx/camera/core/Camera` is retrieved and `https://developer.android.com/reference/androidx/camera/core/UseCase`s are bound to that camera. When all `https://developer.android.com/reference/androidx/camera/core/UseCase`s are unbound, or when camera is closing or closed because lifecycle onStop happens, the `https://developer.android.com/reference/androidx/camera/core/CameraControl` will reject all operations.

Each method Of `https://developer.android.com/reference/androidx/camera/core/CameraControl` returns a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` which apps can use to check the asynchronous result. If the operation is not allowed in current state, the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` will fail immediately with `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException`.

## Summary

| ### Nested types |
|---|
| `public final class https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException extends https://developer.android.com/reference/java/lang/Exception.html` An exception representing a failure that the operation is canceled which might be caused by a new value is set or camera is closed. |

| ### Public methods |
|---|---|
| `default @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | `https://developer.android.com/reference/androidx/camera/core/CameraControl#applyInteropAsync(androidx.camera.core.InteropConfigurator<? super androidx.camera.core.CameraControl>)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/InteropConfigurator<https://developer.android.com/reference/androidx/camera/core/CameraControl> configurator )` Applies interoperability configuration to this camera control. |
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | `https://developer.android.com/reference/androidx/camera/core/CameraControl#cancelFocusAndMetering()()` Cancels current `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` and clears AF/AE/AWB regions. |
| `default @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | `https://developer.android.com/reference/androidx/camera/core/CameraControl#enableLowLightBoostAsync(boolean)(boolean lowLightBoost)` Enables low-light boost mode. |
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | `https://developer.android.com/reference/androidx/camera/core/CameraControl#enableTorch(boolean)(boolean torch)` Enable the torch or disable the torch. |
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Integer.html>` | `https://developer.android.com/reference/androidx/camera/core/CameraControl#setExposureCompensationIndex(int)(int value)` Set the exposure compensation value for the camera. |
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | `https://developer.android.com/reference/androidx/camera/core/CameraControl#setLinearZoom(float)(@https://developer.android.com/reference/androidx/annotation/FloatRange(from = 0.0, to = 1.0) float linearZoom)` Sets current zoom by a linear zoom value ranging from 0f to 1.0f. |
| `default @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | `https://developer.android.com/reference/androidx/camera/core/CameraControl#setTorchStrengthLevel(int)(@https://developer.android.com/reference/androidx/annotation/IntRange(from = 1) int torchStrengthLevel)` Sets torch strength level. |
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | `https://developer.android.com/reference/androidx/camera/core/CameraControl#setZoomRatio(float)(float ratio)` Sets current zoom by ratio. |
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/androidx/camera/core/FocusMeteringResult>` | `https://developer.android.com/reference/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction action)` Starts a focus and metering action configured by the `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction`. |

| ### Extension functions |
|---|---|
| `default final void` | `https://developer.android.com/reference/androidx/camera/core/Camera2InteropEx.https://developer.android.com/reference/androidx/camera/core/CameraControl#(androidx.camera.core.CameraControl).applyCamera2Interop(kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/core/CameraControl receiver, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/camera2/interop/CameraControlCamera2Interop, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block )` Applies Camera2 options to a `https://developer.android.com/reference/androidx/camera/core/CameraControl` asynchronously within a coroutine. |
| `default final @https://developer.android.com/reference/androidx/annotation/NonNull https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Void.html>` | `https://developer.android.com/reference/androidx/camera/core/Camera2InteropEx.https://developer.android.com/reference/androidx/camera/core/CameraControl#(androidx.camera.core.CameraControl).applyCamera2InteropAsync(kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/core/CameraControl receiver, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/camera2/interop/CameraControlCamera2Interop, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block )` Applies Camera2 options to a `https://developer.android.com/reference/androidx/camera/core/CameraControl` asynchronously. |

## Public methods

### applyInteropAsync

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
default @NonNull ListenableFuture<Void> applyInteropAsync(
    @NonNull InteropConfigurator<CameraControl> configurator
)
```

Applies interoperability configuration to this camera control.

To configure Camera2 options, use `Camera2Interop.forCameraControl(configurator)` (from the `camera-camera2` artifact) to create a configurator, then pass it to this method.

All parameters set within a single `configurator` are applied together atomically in a single repeating capture request update. Subsequent calls to `applyInteropAsync` add to or update the existing parameters incrementally without clearing previously set keys, unless explicitly cleared via methods such as `CameraControlCamera2Interop.clearCaptureRequestOption` or `CameraControlCamera2Interop.clearAllCaptureRequestOptions`. This overwrites options set with `SessionConfigInterop` via `https://developer.android.com/reference/androidx/camera/core/SessionConfig.Builder#setInterop(androidx.camera.core.InteropConfigurator<? super androidx.camera.core.SessionConfig.Builder>)`.

**Note:** Using Camera2 interop options can override internal CameraX configurations. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior or interfere with 3A routines and camera control APIs.

**Warning:** Callbacks configured via interop receive raw `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html` instances. Directly invoking state-altering methods on these raw objects (such as `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#close()` or `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#abortCaptures()`) bypasses CameraX pipeline management and may cause state desynchronization, stream interruption, or application crashes.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/InteropConfigurator<https://developer.android.com/reference/androidx/camera/core/CameraControl> configurator` | the configurator that sets the interoperability options |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` which completes with a `null` result when all the interoperability options specified in the given configurator have been successfully updated in the underlying repeating capture request. The future fails with `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException` if a newer configuration is applied before this operation takes effect or if the camera is closed. Cancellation of this future is a no-op. |

### cancelFocusAndMetering

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
abstract @NonNull ListenableFuture<Void> cancelFocusAndMetering()
```

Cancels current `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` and clears AF/AE/AWB regions.

Clear the AF/AE/AWB regions and update current AF mode to continuous AF (if supported). If current `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` has not completed, the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` in `https://developer.android.com/reference/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` will fail with `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException`.

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | A `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` which completes when the AF/AE/AWB regions is clear and AF mode is set to continuous focus (if supported). Cancellation of this future is a no-op. |

### enableLowLightBoostAsync

Added in [1.5.0](https://developer.android.com/jetpack/androidx/releases/camera#1.5.0)

```
default @NonNull ListenableFuture<Void> enableLowLightBoostAsync(boolean lowLightBoost)
```

Enables low-light boost mode.

Devices running Android 15 or higher can provide support for low-light boost. This feature can automatically adjust the brightness of the preview, video or image analysis streams in low-light conditions. This is different from how the night mode camera extension creates still images, because night mode combines a burst of photos to create a single, enhanced image. While night mode works very well for creating a still image, it can't create a continuous stream of frames, but Low Light Boost can. Thus, Low Light Boost enables new camera capabilities, such as the following:

- Providing an enhanced image preview, so users can better frame their low-light pictures.
- Recording brighter videos in low-light conditions.
- Scanning QR codes in low-light conditions.

Applications can query the low-light boost availability via `https://developer.android.com/reference/androidx/camera/core/CameraInfo#isLowLightBoostSupported()`. If you enable Low Light Boost, it automatically turns on when there's a low light level, and turns off when there's more light.

If the camera device does not support low-light boost, the value obtained via `https://developer.android.com/reference/androidx/camera/core/CameraInfo#getLowLightBoostState()` will always be `https://developer.android.com/reference/androidx/camera/core/LowLightBoostState#OFF()`.

Note that this mode may interact with other configurations:

- Low-light boost and torch (see `https://developer.android.com/reference/androidx/camera/core/CameraControl#enableTorch(boolean)`) are mutually exclusive and follow a "last setting wins" policy. Enabling low-light boost will automatically turn off the torch if it is active, and enabling the torch will automatically turn off low-light boost.
- When capturing a picture with `https://developer.android.com/reference/androidx/camera/core/ImageCapture` while low-light boost is active, flash (if enabled by `https://developer.android.com/reference/androidx/camera/core/ImageCapture#setFlashMode(int)`) is allowed to fire for the capture, and low-light boost will remain active for preview.
- When frame rate configuration results in an FPS exceeding 30, low-light boost will be disabled and the state will always be `https://developer.android.com/reference/androidx/camera/core/LowLightBoostState#OFF()`.

To ensure low-light boost mode functions correctly, the frame rate must not exceed 30 FPS.

| Parameters |
|---|---|
| `boolean lowLightBoost` | true to turn on the low-light boost mode, false to turn it off. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | A `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` which is successful when the low-light boost mode was changed to the value specified. It fails with `https://developer.android.com/reference/java/lang/IllegalStateException.html` when low-light boost is not available because the device does not support it or there is a settings conflict. It fails with `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException` if a newer value is set or camera is closed. The failure reason will be provided in the exception's message. Cancellation of this future is a no-op. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/camera/core/CameraInfo#isLowLightBoostSupported()` |   |

### enableTorch

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
abstract @NonNull ListenableFuture<Void> enableTorch(boolean torch)
```

Enable the torch or disable the torch.

`https://developer.android.com/reference/androidx/camera/core/CameraInfo#getTorchState()` can be used to query the torch state. If the camera doesn't have a flash unit (see `https://developer.android.com/reference/androidx/camera/core/CameraInfo#hasFlashUnit()`), then the call will do nothing, the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` will complete immediately with a failed result and the torch state will be `https://developer.android.com/reference/androidx/camera/core/TorchState#OFF()`.

When the torch is enabled, the torch will remain enabled during photo capture regardless of the flashMode setting. When the torch is disabled, flash will function as the flash mode set by either `https://developer.android.com/reference/androidx/camera/core/ImageCapture#setFlashMode(int)` or `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setFlashMode(int)`.

Torch and low-light boost (see `https://developer.android.com/reference/androidx/camera/core/CameraControl#enableLowLightBoostAsync(boolean)`) are mutually exclusive and follow a "last setting wins" policy. Enabling the torch will automatically turn off low-light boost if it is active. Disabling the torch will not restore low-light boost.

| Parameters |
|---|---|
| `boolean torch` | true to turn on the torch, false to turn it off. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | A `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` which is successful when the torch was changed to the value specified. It fails when it is unable to change the torch state. Cancellation of this future is a no-op. |

### setExposureCompensationIndex

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
abstract @NonNull ListenableFuture<Integer> setExposureCompensationIndex(int value)
```

Set the exposure compensation value for the camera.

Only one `https://developer.android.com/reference/androidx/camera/core/CameraControl#setExposureCompensationIndex(int)` is allowed to run at the same time. If multiple `https://developer.android.com/reference/androidx/camera/core/CameraControl#setExposureCompensationIndex(int)` are executed in a row, only the latest one setting will be kept in the camera. The other actions will be cancelled and the ListenableFuture will fail with the `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException`. After all the previous actions is cancelled, the camera device will adjust the brightness according to the latest setting.

| Parameters |
|---|---|
| `int value` | the exposure compensation value to set on the camera which must be within the range of ExposureState#getExposureCompensationRange(). If the exposure compensation value is not in the range defined above, the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` will fail with `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` and the value from ExposureState#getExposureCompensationIndex will not change. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Integer.html>` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` which is finished when the camera reaches the newly requested exposure target. Cancellation of this future is a no-op. The result of the ListenableFuture is the new target exposure value, or cancelled with the following exceptions, - `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException` when the camera is closed or a new `https://developer.android.com/reference/androidx/camera/core/CameraControl#setExposureCompensationIndex(int)` is called. - `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` while the exposure compensation value to ranging within `https://developer.android.com/reference/androidx/camera/core/ExposureState#getExposureCompensationRange()`. |

### setLinearZoom

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
abstract @NonNull ListenableFuture<Void> setLinearZoom(@FloatRange(from = 0.0, to = 1.0) float linearZoom)
```

Sets current zoom by a linear zoom value ranging from 0f to 1.0f. LinearZoom 0f represents the minimum zoom while linearZoom 1.0f represents the maximum zoom. The advantage of linearZoom is that it ensures the field of view (FOV) varies linearly with the linearZoom value, for use with slider UI elements (while `https://developer.android.com/reference/androidx/camera/core/CameraControl#setZoomRatio(float)` works well for pinch-zoom gestures).

It modifies both current `zoomRatio` and `linearZoom` in `https://developer.android.com/reference/androidx/camera/core/CameraInfo#getZoomState()`, so if apps are observing `zoomRatio` or `linearZoom`, they will get the update as well. When a valid `linearZoom` is provided, the `https://developer.android.com/reference/androidx/camera/core/ZoomState` in `https://developer.android.com/reference/androidx/camera/core/CameraInfo#getZoomState()` is updated immediately without waiting for the camera to apply the zoom, while the actual camera zoom adjustment is performed asynchronously and the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` completes when the repeating request result contains the requested zoom ratio.

If the linearZoom is not in the range \[0..1\], the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` will fail with `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` and it won't modify current linearZoom and zoomRatio. It is application's duty to clamp the linearZoom within \[0..1\].

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` which is finished when current repeating request result contains the requested linearZoom. It fails with `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException` if there is newer value being set or camera is closed. If linearZoom is not in range \[0..1\], it fails with `https://developer.android.com/reference/java/lang/IllegalArgumentException.html`. Cancellation of this future is a no-op. |

### setTorchStrengthLevel

Added in [1.5.0](https://developer.android.com/jetpack/androidx/releases/camera#1.5.0)

```
default @NonNull ListenableFuture<Void> setTorchStrengthLevel(@IntRange(from = 1) int torchStrengthLevel)
```

Sets torch strength level.

The torch strength level only applies on the case that torch is turned on by `https://developer.android.com/reference/androidx/camera/core/CameraControl#enableTorch(boolean)` and doesn't affect other usages of the flash unit.

Use the value returned by `https://developer.android.com/reference/androidx/camera/core/CameraInfo#getMaxTorchStrengthLevel()` to set the maximum level the device can provide and use `1` to set the minimum level. If a level greater than the maximum value or less than `1` is set, the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` will fail with an `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` and it won't modify the torch strength.

If the device doesn't have a flash unit or doesn't support configuring torch strength level, the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` will fail with an `https://developer.android.com/reference/java/lang/UnsupportedOperationException.html`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/IntRange(from = 1) int torchStrengthLevel` | The desired torch strength level. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` that is completed when the torch strength has been applied. |

### setZoomRatio

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
abstract @NonNull ListenableFuture<Void> setZoomRatio(float ratio)
```

Sets current zoom by ratio.

It modifies both current `zoomRatio` and `linearZoom` in `https://developer.android.com/reference/androidx/camera/core/CameraInfo#getZoomState()`, so if apps are observing `zoomRatio` or `linearZoom`, they will get the update as well. When a valid ratio is provided, the `https://developer.android.com/reference/androidx/camera/core/ZoomState` in `https://developer.android.com/reference/androidx/camera/core/CameraInfo#getZoomState()` is updated immediately without waiting for the camera to apply the zoom, while the actual camera zoom adjustment is performed asynchronously and the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` completes when the repeating request result contains the requested zoom ratio.

If the ratio is smaller than `https://developer.android.com/reference/androidx/camera/core/ZoomState#getMinZoomRatio()` or larger than `https://developer.android.com/reference/androidx/camera/core/ZoomState#getMaxZoomRatio()`, the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` will fail with `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` and it won't modify current zoom ratio. It is the applications' duty to clamp the ratio.

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html>` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` which is finished when current repeating request result contains the requested zoom ratio. It fails with `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException` if there is newer value being set or camera is closed. If the ratio is out of range, it fails with `https://developer.android.com/reference/java/lang/IllegalArgumentException.html`. Cancellation of this future is a no-op. |

### startFocusAndMetering

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
abstract @NonNull ListenableFuture<FocusMeteringResult> startFocusAndMetering(@NonNull FocusMeteringAction action)
```

Starts a focus and metering action configured by the `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction`.

It will trigger an auto focus action and enable AF/AE/AWB metering regions. The action is configured by a `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` which contains the configuration of multiple AF/AE/AWB `https://developer.android.com/reference/androidx/camera/core/MeteringPoint`s and an auto-cancel duration. See `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` for more details.

Only one `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` is allowed to run at a time. If multiple `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` are executed in a row, only the latest one will work and other actions will be cancelled. However, starting a new action does not unlock 3A components (AF, AE, or AWB) that were already locked by a previous action if they are not included in the new action's `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#setLockingMode(int)`; all 3A locks and continuous autofocus are only restored when `https://developer.android.com/reference/androidx/camera/core/CameraControl#cancelFocusAndMetering()` is called or the latest action's auto-cancel duration is reached.

If the `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` specifies more AF/AE/AWB points than what is supported on the current device, only the first point and then in order up to the number of points supported by the device will be enabled.

If none of the points with either AF/AE/AWB can be supported on the device or none of the points generates valid metering rectangles, the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` in `https://developer.android.com/reference/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` will fail immediately.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction action` | the `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` to be executed. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/androidx/camera/core/FocusMeteringResult>` | A `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` which completes with `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` when auto focus is done and AF/AE/AWB regions are updated. In case AF points are not added, auto focus will not be triggered and this `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` completes when AE/AWB regions are updated. It fails with `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException` if there is newer value being set or camera is closed. If none of the specified AF/AE/AWB `https://developer.android.com/reference/androidx/camera/core/MeteringPoint` is supported, it fails with `https://developer.android.com/reference/java/lang/IllegalArgumentException.html`. Cancellation of this future is a no-op. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` |   |

## Extension functions

### Camera2InteropEx.applyCamera2Interop

Artifact: [androidx.camera:camera-camera2](https://developer.android.com/jetpack/androidx/releases/camera) [View Source](https://cs.android.com/search?q=file:androidx/camera/camera2/interop/Camera2InteropEx.kt+function:applyCamera2Interop)

```
default final void Camera2InteropEx.applyCamera2Interop(
    @NonNull CameraControl receiver,
    @NonNull Function1<@NonNull CameraControlCamera2Interop, Unit> block
)
```

Applies Camera2 options to a `https://developer.android.com/reference/androidx/camera/core/CameraControl` asynchronously within a coroutine.

Dynamically updates repeating capture request parameters or capture request keys on an active camera session. Options configured within a single `https://developer.android.com/reference/androidx/camera/camera2/interop/package-summary#(androidx.camera.core.CameraControl).applyCamera2Interop(kotlin.Function1)` are applied atomically in a single repeating capture request update. Subsequent calls to `https://developer.android.com/reference/androidx/camera/camera2/interop/package-summary#(androidx.camera.core.CameraControl).applyCamera2Interop(kotlin.Function1)` update parameters incrementally without clearing previously set keys, unless explicitly cleared using `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#clearCaptureRequestOption(android.hardware.camera2.CaptureRequest.Key)` or `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#clearAllCaptureRequestOptions()`. This overwrites options set with `https://developer.android.com/reference/androidx/camera/camera2/interop/SessionConfigCamera2Interop` via `https://developer.android.com/reference/androidx/camera/core/SessionConfig.Builder#setInterop(androidx.camera.core.InteropConfigurator)` (or `https://developer.android.com/reference/androidx/camera/camera2/interop/package-summary#(androidx.camera.core.SessionConfig.Builder).camera2Interop(kotlin.Function1)`).

This function suspends until all specified interoperability options have been successfully updated in the underlying repeating capture request. Throws `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException` if a newer configuration is applied before this operation takes effect or if the camera is closed.

Options configured via `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraControlCamera2Interop` include:

- Capture request key-value pairs (`https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#captureRequest()` via `captureRequest[...]` or `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#setCaptureRequestOption(android.hardware.camera2.CaptureRequest.Key,kotlin.Any)`)

- Clearing specific capture request keys (`https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#clearCaptureRequestOption(android.hardware.camera2.CaptureRequest.Key)`)

- Clearing all capture request keys (`https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#clearAllCaptureRequestOptions()`)

- Capture request template type (`https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#repeatingCaptureRequestTemplate()`)

- Repeating capture callbacks (`https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#setRepeatingCaptureCallback(java.util.concurrent.Executor,android.hardware.camera2.CameraCaptureSession.CaptureCallback)` or `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#repeatingCaptureCallback()`)

**Note:** Using Camera2 interop options can override internal CameraX configurations. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior or interfere with 3A routines and camera control APIs.

**Warning:** Callbacks configured via interop receive raw `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html` instances. Directly invoking state-altering, lifecycle, or request-submitting methods on these raw objects bypasses CameraX pipeline management and causes state desynchronization, stream freezing, or crashes. Do not invoke:

- Session lifecycle methods: `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#close()`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#abortCaptures()`, or `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#stopRepeating()`

- Request submission methods: `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#setRepeatingBurst(java.util.List&lt;android.hardware.camera2.CaptureRequest&gt;, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`, or `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#captureBurst(java.util.List&lt;android.hardware.camera2.CaptureRequest&gt;, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`

- Surface / output configuration methods: `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#updateOutputConfiguration(android.hardware.camera2.params.OutputConfiguration)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#finalizeOutputConfigurations(java.util.List&lt;android.hardware.camera2.params.OutputConfiguration&gt;)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#prepare(android.view.Surface)`, or `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#switchToOffline(java.util.Collection&lt;android.view.Surface&gt;, java.util.concurrent.Executor, android.hardware.camera2.CameraOfflineSession.CameraOfflineSessionCallback)`

```kotlin
import androidx.camera.camera2.interop.applyCamera2Interop

cameraControl.applyCamera2Interop {
    captureRequest[CaptureRequest.CONTROL_AE_MODE] = CaptureRequest.CONTROL_AE_MODE_OFF
    repeatingCaptureCallback = object : CameraCaptureSession.CaptureCallback() {}
}
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/camera2/interop/CameraControlCamera2Interop, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block` | configuration block setting Camera2 options on `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraControlCamera2Interop` |

| Throws |
|---|---|
| `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException` | if a newer configuration is applied before this operation takes effect or if the camera is closed |

### Camera2InteropEx.applyCamera2InteropAsync

Artifact: [androidx.camera:camera-camera2](https://developer.android.com/jetpack/androidx/releases/camera) [View Source](https://cs.android.com/search?q=file:androidx/camera/camera2/interop/Camera2InteropEx.kt+function:applyCamera2InteropAsync)

```
default final @NonNull ListenableFuture<@NonNull Void> Camera2InteropEx.applyCamera2InteropAsync(
    @NonNull CameraControl receiver,
    @NonNull Function1<@NonNull CameraControlCamera2Interop, Unit> block
)
```

Applies Camera2 options to a `https://developer.android.com/reference/androidx/camera/core/CameraControl` asynchronously.

Dynamically updates repeating capture request parameters or capture request keys on an active camera session. Options configured within a single `https://developer.android.com/reference/androidx/camera/camera2/interop/package-summary#(androidx.camera.core.CameraControl).applyCamera2InteropAsync(kotlin.Function1)` are applied atomically in a single repeating capture request update. Subsequent calls to `https://developer.android.com/reference/androidx/camera/camera2/interop/package-summary#(androidx.camera.core.CameraControl).applyCamera2InteropAsync(kotlin.Function1)` update parameters incrementally without clearing previously set keys, unless explicitly cleared using `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#clearCaptureRequestOption(android.hardware.camera2.CaptureRequest.Key)` or `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#clearAllCaptureRequestOptions()`. This overwrites options set with `https://developer.android.com/reference/androidx/camera/camera2/interop/SessionConfigCamera2Interop` via `https://developer.android.com/reference/androidx/camera/core/SessionConfig.Builder#setInterop(androidx.camera.core.InteropConfigurator)` (or `https://developer.android.com/reference/androidx/camera/camera2/interop/package-summary#(androidx.camera.core.SessionConfig.Builder).camera2Interop(kotlin.Function1)`).

Options configured via `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraControlCamera2Interop` include:

- Capture request key-value pairs (`https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#captureRequest()` via `captureRequest[...]` or `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#setCaptureRequestOption(android.hardware.camera2.CaptureRequest.Key,kotlin.Any)`)

- Clearing specific capture request keys (`https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#clearCaptureRequestOption(android.hardware.camera2.CaptureRequest.Key)`)

- Clearing all capture request keys (`https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#clearAllCaptureRequestOptions()`)

- Capture request template type (`https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#repeatingCaptureRequestTemplate()`)

- Repeating capture callbacks (`https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#setRepeatingCaptureCallback(java.util.concurrent.Executor,android.hardware.camera2.CameraCaptureSession.CaptureCallback)` or `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraCaptureSessionInterop#repeatingCaptureCallback()`)

**Note:** Using Camera2 interop options can override internal CameraX configurations. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior or interfere with 3A routines and camera control APIs.

**Warning:** Callbacks configured via interop receive raw `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html` instances. Directly invoking state-altering, lifecycle, or request-submitting methods on these raw objects bypasses CameraX pipeline management and causes state desynchronization, stream freezing, or crashes. Do not invoke:

- Session lifecycle methods: `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#close()`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#abortCaptures()`, or `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#stopRepeating()`

- Request submission methods: `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#setRepeatingBurst(java.util.List&lt;android.hardware.camera2.CaptureRequest&gt;, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`, or `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#captureBurst(java.util.List&lt;android.hardware.camera2.CaptureRequest&gt;, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`

- Surface / output configuration methods: `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#updateOutputConfiguration(android.hardware.camera2.params.OutputConfiguration)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#finalizeOutputConfigurations(java.util.List&lt;android.hardware.camera2.params.OutputConfiguration&gt;)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#prepare(android.view.Surface)`, or `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#switchToOffline(java.util.Collection&lt;android.view.Surface&gt;, java.util.concurrent.Executor, android.hardware.camera2.CameraOfflineSession.CameraOfflineSessionCallback)`

```kotlin
import androidx.camera.camera2.interop.applyCamera2Interop
import androidx.camera.camera2.interop.applyCamera2InteropAsync

cameraControl.applyCamera2InteropAsync {
    captureRequest[CaptureRequest.CONTROL_AE_MODE] = CaptureRequest.CONTROL_AE_MODE_OFF
    repeatingCaptureCallback = object : CameraCaptureSession.CaptureCallback() {}
}
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/camera2/interop/CameraControlCamera2Interop, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block` | configuration block setting Camera2 options on `https://developer.android.com/reference/androidx/camera/camera2/interop/CameraControlCamera2Interop` |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Void.html>` | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` completing with `null` when all specified interoperability options have been successfully updated in the underlying repeating capture request. The future fails with `https://developer.android.com/reference/androidx/camera/core/CameraControl.OperationCanceledException` if a newer configuration is applied before this operation takes effect or if the camera is closed. Cancelling the future is a no-op. |