FocusMeteringAction.Builder

Builder(point: MeteringPoint)

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.

Builder(point: MeteringPoint, meteringMode: Int)

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.

fun addPoint(point: MeteringPoint): FocusMeteringAction.Builder

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.

fun addPoint(point: MeteringPoint, meteringMode: Int): FocusMeteringAction.Builder

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.

fun build(): FocusMeteringAction

Builds the FocusMeteringAction instance.

fun disableAutoCancel(): FocusMeteringAction.Builder

Disables the auto-cancel.

fun setAutoCancelDuration(duration: @IntRange(from = 1) Long, timeUnit: TimeUnit): FocusMeteringAction.Builder

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.

fun setLockingMode(lockingMode: Int): FocusMeteringAction.Builder

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.