Android 12 Developer Preview is here! Try it out, and give us your feedback!

CameraControl

public 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

class CameraControl.OperationCanceledException

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> cancelFocusAndMetering()

Cancels current FocusMeteringAction and clears AF/AE/AWB regions.

abstract ListenableFuture<Void> enableTorch(boolean torch)

Enable the torch or disable the torch.

abstract ListenableFuture<Integer> setExposureCompensationIndex(int value)

Set the exposure compensation value for the camera.

abstract ListenableFuture<Void> setLinearZoom(float linearZoom)

Sets current zoom by a linear zoom value ranging from 0f to 1.0f.

abstract ListenableFuture<Void> setZoomRatio(float ratio)

Sets current zoom by ratio.

abstract ListenableFuture<FocusMeteringResult> startFocusAndMetering(FocusMeteringAction action)

Starts a focus and metering action configured by the FocusMeteringAction.

Public methods

cancelFocusAndMetering

public abstract ListenableFuture<Void> cancelFocusAndMetering ()

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(FocusMeteringAction) will fail with CameraControl.OperationCanceledException.

Returns
ListenableFuture<Void> A ListenableFuture 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.

enableTorch

public abstract ListenableFuture<Void> enableTorch (boolean torch)

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.
Returns
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. Cancellation of this future is a no-op.

setExposureCompensationIndex

public abstract ListenableFuture<Integer> setExposureCompensationIndex (int value)

Set the exposure compensation value for the camera.

Only one setExposureCompensationIndex(int) is allowed to run at the same time. If multiple 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 CameraControl.OperationCanceledException. After all the previous actions is cancelled, the camera device will adjust the brightness according to the latest setting.

Parameters
value int: 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 ListenableFuture will fail with IllegalArgumentException and the value from ExposureState#getExposureCompensationIndex will not change.
Returns
ListenableFuture<Integer> a ListenableFuture 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,

setLinearZoom

public abstract ListenableFuture<Void> setLinearZoom (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 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].

Parameters
linearZoom float

Value is between 0.0 and 1.0 inclusive.
Returns
ListenableFuture<Void> a ListenableFuture which is finished when current repeating request result contains the requested linearZoom. It fails with CameraControl.OperationCanceledException if there is newer value being set or camera is closed. If linearZoom is not in range [0..1], it fails with IllegalArgumentException. Cancellation of this future is a no-op.

setZoomRatio

public abstract ListenableFuture<Void> setZoomRatio (float ratio)

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.

Parameters
ratio float

Returns
ListenableFuture<Void> a ListenableFuture which is finished when current repeating request result contains the requested zoom ratio. It fails with CameraControl.OperationCanceledException if there is newer value being set or camera is closed. If the ratio is out of range, it fails with IllegalArgumentException. Cancellation of this future is a no-op.

startFocusAndMetering

public abstract ListenableFuture<FocusMeteringResult> startFocusAndMetering (FocusMeteringAction action)

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 and an 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 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 ListenableFuture in startFocusAndMetering(FocusMeteringAction) will fail immediately.

Parameters
action FocusMeteringAction: the FocusMeteringAction to be executed.
Returns
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. Cancellation of this future is a no-op.