CameraControl

interface CameraControl
androidx.camera.core.CameraControl

The CameraControl provides various asynchronous operations like zoom, focus and metering which affects output of all UseCases currently bound to that camera.

The application can retrieve the CameraControl instance via Camera#getCameraControl(). CameraControl is ready to start operations immediately after Camera is retrieved and UseCases are bound to that camera. When all UseCases are unbound, or when camera is closing or closed because lifecycle onStop happens, the CameraControl will reject all operations.

Each method Of CameraControl returns a ListenableFuture which apps can use to check the asynchronous result. If the operation is not allowed in current state, the returned ListenableFuture will fail immediately with CameraControl.OperationCanceledException.

Summary

Nested classes

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
abstract ListenableFuture<Void!>

Cancels current FocusMeteringAction and clears AF/AE/AWB regions.
abstract ListenableFuture<Void!>

Enable the torch or disable the torch.
abstract ListenableFuture<Void!>
setLinearZoom(linearZoom: Float)

Sets current zoom by a linear zoom value ranging from 0f to 1.
abstract ListenableFuture<Void!>

Sets current zoom by ratio.
abstract ListenableFuture<FocusMeteringResult!>

Starts a focus and metering action configured by the FocusMeteringAction.

Public methods

cancelFocusAndMetering

@NonNull abstract fun cancelFocusAndMetering(): ListenableFuture<Void!>

Cancels current 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 FocusMeteringAction has not completed, the returned ListenableFuture in startFocusAndMetering will fail with OperationCanceledException.

Return
ListenableFuture<Void!> A ListenableFuture which completes when the AF/AE/AWB regions is clear and AF mode is set to continuous focus (if supported).

enableTorch

@NonNull abstract fun enableTorch(torch: Boolean): ListenableFuture<Void!>

Enable the torch or disable the torch.

CameraInfo#getTorchState() can be used to query the torch state. If the camera doesn't have a flash unit (see CameraInfo#hasFlashUnit()), then the call will do nothing, the returned ListenableFuture will complete immediately with a failed result and the torch state will be 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 ImageCapture#setFlashMode(int) or ImageCapture.Builder#setFlashMode(int).

Parameters
torch Boolean: true to turn on the torch, false to turn it off.
Return
ListenableFuture<Void!> A ListenableFuture which is successful when the torch was changed to the value specified. It fails when it is unable to change the torch state.

setLinearZoom

@NonNull abstract fun setLinearZoom(linearZoom: Float): ListenableFuture<Void!>

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 setZoomRatio(float) works well for pinch-zoom gestures).

It modifies both current zoomRatio and linearZoom so if apps are observing zoomRatio or linearZoom, they will get the update as well. If the linearZoom is not in the range [0..1], the returned ListenableFuture will fail with IllegalArgumentException and it won't modify current linearZoom and zoomRatio. It is application's duty to clamp the linearZoom within [0..1].

Return
ListenableFuture<Void!> a ListenableFuture which is finished when current repeating request result contains the requested linearZoom. It fails with OperationCanceledException if there is newer value being set or camera is closed. If linearZoom is not in range [0..1], it fails with IllegalArgumentException.

setZoomRatio

@NonNull abstract fun setZoomRatio(ratio: Float): ListenableFuture<Void!>

Sets current zoom by ratio.

It modifies both current zoomRatio and linearZoom so if apps are observing zoomRatio or linearZoom, they will get the update as well. If the ratio is smaller than ZoomState#getMinZoomRatio() or larger than ZoomState#getMaxZoomRatio(), the returned ListenableFuture will fail with IllegalArgumentException and it won't modify current zoom ratio. It is the applications' duty to clamp the ratio.

Return
ListenableFuture<Void!> a ListenableFuture which is finished when current repeating request result contains the requested zoom ratio. It fails with OperationCanceledException if there is newer value being set or camera is closed. If the ratio is out of range, it fails with IllegalArgumentException.

startFocusAndMetering

@NonNull abstract fun startFocusAndMetering(@NonNull action: FocusMeteringAction): ListenableFuture<FocusMeteringResult!>

Starts a focus and metering action configured by the FocusMeteringAction.

It will trigger an auto focus action and enable AF/AE/AWB metering regions. The action is configured by a FocusMeteringAction which contains the configuration of multiple AF/AE/AWB MeteringPoints, auto-cancel duration. See FocusMeteringAction for more details.

Only one FocusMeteringAction is allowed to run at a time. If multiple FocusMeteringAction are executed in a row, only the latest one will work and other actions will be cancelled.

If the FocusMeteringAction specifies more AF/AE/AWB points than what is supported on 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, the returned ListenableFuture in CameraControl#startFocusAndMetering(FocusMeteringAction) will fail immediately.

Parameters
action FocusMeteringAction: the FocusMeteringAction to be executed.
Return
ListenableFuture<FocusMeteringResult!> A ListenableFuture which completes with 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 ListenableFuture completes when AE/AWB regions are updated.