# FocusMeteringAction

Artifact: [androidx.camera:camera-core](https://developer.android.com/jetpack/androidx/releases/camera) [View Source](https://cs.android.com/search?q=file:androidx/camera/core/FocusMeteringAction.java+class:androidx.camera.core.FocusMeteringAction) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

*** ** * ** ***


```
public final class FocusMeteringAction
```

<br />

*** ** * ** ***

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

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

When specifying a `https://developer.android.com/reference/androidx/camera/core/MeteringPoint`, a metering mode can also be specified. Metering mode is a combination of flags consisting of `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF()`, `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AE()`, and `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AWB()`. This combination indicates whether the `https://developer.android.com/reference/androidx/camera/core/MeteringPoint` is used to set an AF(Auto Focus) region, AE(Auto Exposure) region or AWB(Auto White Balance) region. The default meteringMode is `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF()` \| `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AE()` \| `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#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 `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#addPoint(androidx.camera.core.MeteringPoint)` or `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#addPoint(androidx.camera.core.MeteringPoint,int)`. An app can also use this API to enable different regions for AF and AE respectively.

When the action is submitted via `https://developer.android.com/reference/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)`, the following operations are performed:

- **Region Updates:** The camera's metering regions are updated based on the specified `https://developer.android.com/reference/androidx/camera/core/MeteringPoint`s.
  - This update happens regardless of the locking modes set for AF, AE, and AWB.
  - If a 3A component (AF/AE/AWB) does not support metering regions on the device, or if the maximum region count is 0, the points for that component are ignored.
  - If more points are specified than supported, only the first supported points are used.
- **Trigger and Lock:** The camera then applies the locks specified in the locking mode (see `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#setLockingMode(int)`):
  - **AF:** If AF points are specified and `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF()` is included in the locking mode (which is the default), it triggers an autofocus manual scan and locks focus. If `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF()` is NOT in the locking mode, it updates the AF region without triggering a scan, allowing the camera to continue in its current AF mode (e.g., continuous autofocus, or remaining locked if AF was already locked by a previous action).
  - **AE/AWB:** If AE/AWB points are specified and `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AE()` / `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AWB()` are included in the locking mode, the camera locks the exposure and white balance respectively. If not included, the regions are updated without acquiring new AE/AWB locks (allowing exposure and white balance to continue adjusting automatically unless already locked by a previous action).
- **Completion:** The returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` completes when the regions are updated and the requested locks are acquired. `https://developer.android.com/reference/androidx/camera/core/FocusMeteringResult#isFocusSuccessful()` will be `true` if an AF lock was requested and successfully acquired, or if AF is not supported on the device. It will be `false` if the AF lock failed, if no AF points were specified, or if `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF()` was excluded from the locking mode.

App can set a auto-cancel duration to let CameraX call `https://developer.android.com/reference/androidx/camera/core/CameraControl#cancelFocusAndMetering()` automatically in the specified duration. By default, the auto-cancel duration is 5 seconds. Apps can call `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#disableAutoCancel()` to disable auto-cancel.

If a focus-metering action is completed with `https://developer.android.com/reference/androidx/camera/core/FocusMeteringResult#isFocusSuccessful()``true`, the focus distance will be locked and continuous auto-focus will be disabled. Continuous autofocus will be re-enabled when `https://developer.android.com/reference/androidx/camera/core/CameraControl#cancelFocusAndMetering()` is called or the auto-cancel duration is reached.

AE (Auto Exposure) and AWB (Auto White Balance) can also be locked if they are enabled in `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#setLockingMode(int)`. Locking mode is a combination of flags consisting of `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF()`, `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AE()`, and `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AWB()`. For example, to lock both AF and AE, use `FLAG_AF | FLAG_AE`.

Starting a new `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` via `https://developer.android.com/reference/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` does not unlock 3A components (AF, AE, or AWB) that were locked by a previous action if those components are excluded from the new action's locking mode. For example, if an action locks AF (`setLockingMode(FLAG_AF)`) and a subsequent action only locks AE (`setLockingMode(FLAG_AE)`), AF remains locked and continuous autofocus stays disabled. Any acquired 3A locks and disabled continuous autofocus are only reset when `https://developer.android.com/reference/androidx/camera/core/CameraControl#cancelFocusAndMetering()` is called or the latest action's auto-cancel duration is reached.

## Summary

| ### Nested types |
|---|
| `public class https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder` The builder used to create the `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction`. |

| ### Constants |
|---|---|
| `static final int` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AE() = 2` A flag used in metering mode indicating the AE (Auto Exposure) region is enabled. |
| `static final int` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF() = 1` A flag used in metering mode indicating the AF (Auto Focus) region is enabled. |
| `static final int` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AWB() = 4` A flag used in metering mode indicating the AWB (Auto White Balance) region is enabled. |

| ### Public methods |
|---|---|
| `long` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#getAutoCancelDurationInMillis()()` Returns auto-cancel duration. |
| `int` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#getLockingMode()()` Returns the locking mode. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/androidx/camera/core/MeteringPoint>` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#getMeteringPointsAe()()` Returns all `https://developer.android.com/reference/androidx/camera/core/MeteringPoint`s used for AE regions. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/androidx/camera/core/MeteringPoint>` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#getMeteringPointsAf()()` Returns all `https://developer.android.com/reference/androidx/camera/core/MeteringPoint`s used for AF regions. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/androidx/camera/core/MeteringPoint>` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#getMeteringPointsAwb()()` Returns all `https://developer.android.com/reference/androidx/camera/core/MeteringPoint`s used for AWB regions. |
| `boolean` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#isAutoCancelEnabled()()` Returns if auto-cancel is enabled or not. |

## Constants

### FLAG_AE

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public static final int FLAG_AE = 2
```

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

### FLAG_AF

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public static final int FLAG_AF = 1
```

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.

### FLAG_AWB

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public static final int FLAG_AWB = 4
```

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

## Public methods

### getAutoCancelDurationInMillis

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public long getAutoCancelDurationInMillis()
```

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

### getLockingMode

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
public int getLockingMode()
```

Returns the locking mode.

Locking mode is a combination of flags consisting of `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF()`, `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AE()`, and `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AWB()`. This combination indicates whether the AF (Auto Focus), AE (Auto Exposure) or AWB (Auto White Balance) should be locked after focus and metering action is completed.

### getMeteringPointsAe

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public @NonNull List<MeteringPoint> getMeteringPointsAe()
```

Returns all `https://developer.android.com/reference/androidx/camera/core/MeteringPoint`s used for AE regions.

### getMeteringPointsAf

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public @NonNull List<MeteringPoint> getMeteringPointsAf()
```

Returns all `https://developer.android.com/reference/androidx/camera/core/MeteringPoint`s used for AF regions.

### getMeteringPointsAwb

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public @NonNull List<MeteringPoint> getMeteringPointsAwb()
```

Returns all `https://developer.android.com/reference/androidx/camera/core/MeteringPoint`s used for AWB regions.

### isAutoCancelEnabled

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public boolean isAutoCancelEnabled()
```

Returns if auto-cancel is enabled or not.