FocusMeteringAction

class 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 startFocusAndMetering 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 addPoint or addPoint. An app can also use this API to enable different regions for AF and AE respectively.

When the action is submitted via startFocusAndMetering, the following operations are performed:

• Region Updates: The camera's metering regions are updated based on the specified MeteringPoints.
  • 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 setLockingMode):
  • AF: If AF points are specified and FLAG_AF is included in the locking mode (which is the default), it triggers an autofocus manual scan and locks focus. If 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).
  • AE/AWB: If AE/AWB points are specified and FLAG_AE / FLAG_AWB are included in the locking mode, the camera locks the exposure and white balance respectively. If not included, the regions are updated but exposure and white balance continue to adjust automatically.
• Completion: The returned ListenableFuture completes when the regions are updated and the requested locks are acquired. 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 FLAG_AF was excluded from the locking mode.

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

If a focus-metering action is completed with isFocusSuccessfultrue, the focus distance will be locked and continuous auto-focus will be disabled. Continuous autofocus will be re-enabled when 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 setLockingMode. Locking mode is a combination of flags consisting of FLAG_AF, FLAG_AE, and FLAG_AWB. For example, to lock both AF and AE, use FLAG_AF | FLAG_AE.

Summary

const val FLAG_AE = 2: Int

const val FLAG_AF = 1: Int

const val FLAG_AWB = 4: Int

fun getAutoCancelDurationInMillis(): Long

fun getLockingMode(): Int

fun getMeteringPointsAe(): (Mutable)List<MeteringPoint!>

fun getMeteringPointsAf(): (Mutable)List<MeteringPoint!>

fun getMeteringPointsAwb(): (Mutable)List<MeteringPoint!>

fun isAutoCancelEnabled(): Boolean