CameraControl
public
interface
CameraControl
androidx.camera.core.CameraControl |
The CameraControl
provides various asynchronous operations like zoom, focus and
metering which affects output of all UseCase
s 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 UseCase
s are bound to that camera.
When all UseCase
s 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 |
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 |
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 MeteringPoint
s 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.
|
See also:
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2020-09-30 UTC.