FocusMeteringAction.Builder

public Builder(@NonNull MeteringPoint point)

Creates a Builder from a MeteringPoint with default mode FLAG_AF | FLAG_AE | FLAG_AWB.

The default locking mode is FLAG_AF. Use setLockingMode to lock AE or AWB as well.

public Builder(@NonNull MeteringPoint point, int meteringMode)

Creates a Builder from a MeteringPoint and MeteringMode.

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

The default locking mode is FLAG_AF. Use setLockingMode to lock AE or AWB as well.

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

Adds another MeteringPoint with default metering mode FLAG_AF | FLAG_AE | 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 FocusMeteringAction will cause startFocusAndMetering to fail.

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

Adds another MeteringPoint with specified meteringMode.

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 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 FocusMeteringAction will cause startFocusAndMetering to fail.

public @NonNull FocusMeteringAction build()

Builds the FocusMeteringAction instance.

public @NonNull FocusMeteringAction.Builder disableAutoCancel()

Disables the auto-cancel.

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

Sets the auto-cancel duration. After set, 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 IllegalArgumentException.

public @NonNull FocusMeteringAction.Builder setLockingMode(int lockingMode)

Sets the locking mode.

Locking mode is a combination of flags consisting of FLAG_AF, FLAG_AE, and 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 MeteringPoint specified in this action and the camera device supports locking for that component.

By default, only 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 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.