CameraControl


public interface 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 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 types

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 @NonNull ListenableFuture<Void>

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

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

Enable the torch or disable the torch.

abstract @NonNull ListenableFuture<Integer>

Set the exposure compensation value for the camera.

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.

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

Sets current zoom by ratio.

abstract @NonNull ListenableFuture<FocusMeteringResult>

Starts a focus and metering action configured by the FocusMeteringAction.

Public methods

cancelFocusAndMetering

Added in 1.0.0
abstract @NonNull ListenableFuture<VoidcancelFocusAndMetering()

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.

Returns
@NonNull 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

Added in 1.0.0
abstract @NonNull ListenableFuture<VoidenableTorch(boolean torch)

Enable the torch or disable the torch.

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

Parameters
boolean torch

true to turn on the torch, false to turn it off.

Returns
@NonNull 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

Added in 1.0.0
abstract @NonNull ListenableFuture<IntegersetExposureCompensationIndex(int value)

Set the exposure compensation value for the camera.

Only one setExposureCompensationIndex is allowed to run at the same time. If multiple setExposureCompensationIndex 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 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 ListenableFuture will fail with IllegalArgumentException and the value from ExposureState#getExposureCompensationIndex will not change.

Returns
@NonNull 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

Added in 1.0.0
abstract @NonNull ListenableFuture<VoidsetLinearZoom(@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 setZoomRatio 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].

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

setZoomRatio

Added in 1.0.0
abstract @NonNull ListenableFuture<VoidsetZoomRatio(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 getMinZoomRatio or larger than 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.

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

startFocusAndMetering

Added in 1.0.0
abstract @NonNull ListenableFuture<FocusMeteringResultstartFocusAndMetering(@NonNull 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 will fail immediately.

Parameters
@NonNull FocusMeteringAction action

the FocusMeteringAction to be executed.

Returns
@NonNull 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. It fails with OperationCanceledException if there is newer value being set or camera is closed. If none of the specified AF/AE/AWB MeteringPoint is supported, it fails with IllegalArgumentException. Cancellation of this future is a no-op.