# FocusMeteringAction.Builder

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.Builder) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

*** ** * ** ***


```
public class FocusMeteringAction.Builder
```

<br />

*** ** * ** ***

The builder used to create the `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction`.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#Builder(androidx.camera.core.MeteringPoint)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/MeteringPoint point)` Creates a Builder from a `https://developer.android.com/reference/androidx/camera/core/MeteringPoint` with default mode `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()`. |
| `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#Builder(androidx.camera.core.MeteringPoint,int)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/MeteringPoint point, int meteringMode)` Creates a Builder from a `https://developer.android.com/reference/androidx/camera/core/MeteringPoint` and MeteringMode. |

| ### Public methods |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#addPoint(androidx.camera.core.MeteringPoint)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/MeteringPoint point)` Adds another `https://developer.android.com/reference/androidx/camera/core/MeteringPoint` with default metering mode `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()`. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#addPoint(androidx.camera.core.MeteringPoint,int)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/MeteringPoint point, int meteringMode)` Adds another `https://developer.android.com/reference/androidx/camera/core/MeteringPoint` with specified meteringMode. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#build()()` Builds the `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` instance. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#disableAutoCancel()()` Disables the auto-cancel. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#setAutoCancelDuration(long,java.util.concurrent.TimeUnit)( @https://developer.android.com/reference/androidx/annotation/IntRange(from = 1) long duration, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/TimeUnit.html timeUnit )` Sets the auto-cancel duration. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder` | `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#setLockingMode(int)(int lockingMode)` Sets the locking mode. |

## Public constructors

### Builder

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

```
public Builder(@NonNull MeteringPoint point)
```

Creates a Builder from a `https://developer.android.com/reference/androidx/camera/core/MeteringPoint` with default mode `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()`.

The default locking mode is `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF()`. Use `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#setLockingMode(int)` to lock AE or AWB as well.

### Builder

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

```
public Builder(@NonNull MeteringPoint point, int meteringMode)
```

Creates a Builder from a `https://developer.android.com/reference/androidx/camera/core/MeteringPoint` and MeteringMode.

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 AF(Auto Focus) region, AE(Auto Exposure) region or AWB(Auto White Balance) region.

The default locking mode is `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF()`. Use `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder#setLockingMode(int)` to lock AE or AWB as well.

## Public methods

### addPoint

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

```
public @NonNull FocusMeteringAction.Builder addPoint(@NonNull MeteringPoint point)
```

Adds another `https://developer.android.com/reference/androidx/camera/core/MeteringPoint` with default metering mode `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()`.

The points added here will be appended in order after the point set in builder constructor.

If more points are added than what current device supports for AF/AE/AWB, only the first point and then in order up to the number of points supported on the device will be enabled.

If none of the points is supported on the device, this `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` will cause `https://developer.android.com/reference/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` to fail.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` |   |

### addPoint

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

```
public @NonNull FocusMeteringAction.Builder addPoint(@NonNull MeteringPoint point, int meteringMode)
```

Adds another `https://developer.android.com/reference/androidx/camera/core/MeteringPoint` with specified meteringMode.

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 AF(Auto Focus) region, AE(Auto Exposure) region or AWB(Auto White Balance) region.

The points added here will be appended in order after the point set in builder constructor.

If more points are added than what current device supports for AF/AE/AWB, only the first point and then in order up to the number of points supported on the device will be enabled.

If none of the points is supported on the device, this `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` will cause `https://developer.android.com/reference/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` to fail.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` |   |

### build

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

```
public @NonNull FocusMeteringAction build()
```

Builds the `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction` instance.

### disableAutoCancel

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

```
public @NonNull FocusMeteringAction.Builder disableAutoCancel()
```

Disables the auto-cancel.

### setAutoCancelDuration

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

```
public @NonNull FocusMeteringAction.Builder setAutoCancelDuration(
    @IntRange(from = 1) long duration,
    @NonNull TimeUnit timeUnit
)
```

Sets the auto-cancel duration. After set, `https://developer.android.com/reference/androidx/camera/core/CameraControl#cancelFocusAndMetering()` will be called in specified duration. By default, auto-cancel is enabled with 5 seconds duration. The duration must be greater than or equal to 1 otherwise it will throw a `https://developer.android.com/reference/java/lang/IllegalArgumentException.html`.

### setLockingMode

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

```
public @NonNull FocusMeteringAction.Builder setLockingMode(int lockingMode)
```

Sets 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. For example, to lock both AF and AE, use `FLAG_AF | FLAG_AE`.

Locking will only occur if the corresponding 3A component has at least one `https://developer.android.com/reference/androidx/camera/core/MeteringPoint` specified in this action and the camera device supports locking for that component.

By default, only `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF()` is set. Apps can also use `0` to disable any 3A locking while still updating the 3A regions. For example, if AF points are specified but `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction#FLAG_AF()` is not included in the locking mode set through this API, the AF region will be updated but the camera will not explicitly trigger an autofocus scan. In this case, how and when the camera focuses on the new region will depend on the current AF mode (e.g., whether it is a continuous autofocus mode) and device-specific behavior. Note that excluding a 3A flag from the locking mode does not unlock that 3A component or re-enable continuous autofocus if it was already locked by a prior `https://developer.android.com/reference/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` call; call `https://developer.android.com/reference/androidx/camera/core/CameraControl#cancelFocusAndMetering()` (or rely on auto-cancel) to unlock 3A and restore continuous autofocus.

| Parameters |
|---|---|
| `int lockingMode` | 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()`. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder` | the current `https://developer.android.com/reference/androidx/camera/core/FocusMeteringAction.Builder`. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if the locking mode is invalid. |