Google is committed to advancing racial equity for Black communities. See how.

FocusMeteringAction

class FocusMeteringAction
kotlin.Any
   ↳ androidx.camera.core.FocusMeteringAction

A configuration used to trigger a focus and/or metering action.

A FocusMeteringAction must be created by the Builder. To construct a Builder, a MeteringPoint is required to specify the focus/metering area. Apps can use various MeteringPointFactory to create the points. After the FocusMeteringAction is built, apps can pass it to CameraControl#startFocusAndMetering(FocusMeteringAction) to initiate the focus and metering action.

When specifying a MeteringPoint, a metering mode can also be specified. Metering mode is a combination of flags consisting of FLAG_AF, FLAG_AE, and FLAG_AWB. This combination indicates whether the MeteringPoint is used to set an AF(Auto Focus) region, AE(Auto Exposure) region or AWB(Auto White Balance) region. The default meteringMode is FLAG_AF | FLAG_AE | FLAG_AWB which means the point is used for all AF/AE/AWB regions. Apps can set the proper metering mode to optionally exclude some 3A regions. Multiple regions for specific 3A types are also supported via Builder#addPoint(MeteringPoint) or Builder#addPoint(MeteringPoint, int). An app can also use this API to enable different regions for AF and AE respectively.

If any AF points are specified, it will trigger autofocus to start a manual scan. When focus is locked and the specified AF/AE/AWB regions are updated in capture result, the returned ListenableFuture in CameraControl#startFocusAndMetering(FocusMeteringAction) will complete with FocusMeteringResult#isFocusSuccessful() set to indicate if focus is done successfully or not. If an AF point is not specified, it will not trigger autofocus and simply wait for specified AE/AWB regions being updated to complete the returned ListenableFuture. In the case of AF points not specified, FocusMeteringResult#isFocusSuccessful() will be set to false. If Af points are specified but current camera does not support auto focus, FocusMeteringResult#isFocusSuccessful() will be set to true .

App can set a auto-cancel duration to let CameraX call CameraControl#cancelFocusAndMetering() automatically in the specified duration. By default the auto-cancel duration is 5 seconds. Apps can call Builder#disableAutoCancel() to disable auto-cancel.

Summary

Nested classes

The builder used to create the FocusMeteringAction.

Constants
static Int

A flag used in metering mode indicating the AE (Auto Exposure) region is enabled.

static Int

A flag used in metering mode indicating the AF (Auto Focus) region is enabled.

static Int

A flag used in metering mode indicating the AWB (Auto White Balance) region is enabled.

Public methods
Long

Returns auto-cancel duration.

MutableList<MeteringPoint!>

Returns all MeteringPoints used for AE regions.

MutableList<MeteringPoint!>

Returns all MeteringPoints used for AF regions.

MutableList<MeteringPoint!>

Returns all MeteringPoints used for AWB regions.

Boolean

Returns if auto-cancel is enabled or not.

Constants

FLAG_AE

static val FLAG_AE: Int

A flag used in metering mode indicating the AE (Auto Exposure) region is enabled.

Value: 1 << 1

FLAG_AF

static val FLAG_AF: Int

A flag used in metering mode indicating the AF (Auto Focus) region is enabled. An autofocus scan is also triggered when FLAG_AF is assigned.

Value: 1

FLAG_AWB

static val FLAG_AWB: Int

A flag used in metering mode indicating the AWB (Auto White Balance) region is enabled.

Value: 1 << 2

Public methods

getAutoCancelDurationInMillis

fun getAutoCancelDurationInMillis(): Long

Returns auto-cancel duration. Returns 0 if auto-cancel is disabled.

getMeteringPointsAe

@NonNull fun getMeteringPointsAe(): MutableList<MeteringPoint!>

Returns all MeteringPoints used for AE regions.

getMeteringPointsAf

@NonNull fun getMeteringPointsAf(): MutableList<MeteringPoint!>

Returns all MeteringPoints used for AF regions.

getMeteringPointsAwb

@NonNull fun getMeteringPointsAwb(): MutableList<MeteringPoint!>

Returns all MeteringPoints used for AWB regions.

isAutoCancelEnabled

fun isAutoCancelEnabled(): Boolean

Returns if auto-cancel is enabled or not.