From 228f4f92e70d9326d473e02bcdcc8faf9e706a4d Mon Sep 17 00:00:00 2001 From: Zhijun He Date: Thu, 16 Jan 2014 17:22:05 -0800 Subject: [PATCH] Camera2: Update 3A state doc Change-Id: Id484bdff38af34ad2c8b64863d036ff81124401e --- .../android/hardware/camera2/CameraMetadata.java | 40 +- .../android/hardware/camera2/CaptureRequest.java | 26 +- .../android/hardware/camera2/CaptureResult.java | 550 ++++++++++++++++++++- 3 files changed, 575 insertions(+), 41 deletions(-) diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java index 84d87106811d..81640a6f96a8 100644 --- a/core/java/android/hardware/camera2/CameraMetadata.java +++ b/core/java/android/hardware/camera2/CameraMetadata.java @@ -393,10 +393,9 @@ public abstract class CameraMetadata { public static final int CONTROL_AE_PRECAPTURE_TRIGGER_IDLE = 0; /** - *

The precapture metering sequence - * must be started. The exact effect of the precapture - * trigger depends on the current AE mode and - * state.

+ *

The precapture metering sequence will be started + * by the camera device. The exact effect of the precapture + * trigger depends on the current AE mode and state.

* @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER */ public static final int CONTROL_AE_PRECAPTURE_TRIGGER_START = 1; @@ -504,14 +503,14 @@ public abstract class CameraMetadata { public static final int CONTROL_AF_TRIGGER_IDLE = 0; /** - *

Autofocus must trigger now.

+ *

Autofocus will trigger now.

* @see CaptureRequest#CONTROL_AF_TRIGGER */ public static final int CONTROL_AF_TRIGGER_START = 1; /** - *

Autofocus must return to initial - * state, and cancel any active trigger.

+ *

Autofocus will return to its initial + * state, and cancel any currently active trigger.

* @see CaptureRequest#CONTROL_AF_TRIGGER */ public static final int CONTROL_AF_TRIGGER_CANCEL = 2; @@ -993,7 +992,7 @@ public abstract class CameraMetadata { // /** - *

AE is off. When a camera device is opened, it starts in + *

AE is off or recently reset. When a camera device is opened, it starts in * this state.

* @see CaptureResult#CONTROL_AE_STATE */ @@ -1001,21 +1000,20 @@ public abstract class CameraMetadata { /** *

AE doesn't yet have a good set of control values - * for the current scene

+ * for the current scene.

* @see CaptureResult#CONTROL_AE_STATE */ public static final int CONTROL_AE_STATE_SEARCHING = 1; /** *

AE has a good set of control values for the - * current scene

+ * current scene.

* @see CaptureResult#CONTROL_AE_STATE */ public static final int CONTROL_AE_STATE_CONVERGED = 2; /** - *

AE has been locked (aeMode = - * LOCKED)

+ *

AE has been locked.

* @see CaptureResult#CONTROL_AE_STATE */ public static final int CONTROL_AE_STATE_LOCKED = 3; @@ -1023,18 +1021,19 @@ public abstract class CameraMetadata { /** *

AE has a good set of control values, but flash * needs to be fired for good quality still - * capture

+ * capture.

* @see CaptureResult#CONTROL_AE_STATE */ public static final int CONTROL_AE_STATE_FLASH_REQUIRED = 4; /** *

AE has been asked to do a precapture sequence - * (through the - * trigger_action(CAMERA2_TRIGGER_PRECAPTURE_METERING) - * call), and is currently executing it. Once PRECAPTURE + * (through the {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} START), + * and is currently executing it. Once PRECAPTURE * completes, AE will transition to CONVERGED or - * FLASH_REQUIRED as appropriate

+ * FLASH_REQUIRED as appropriate.

+ * + * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER * @see CaptureResult#CONTROL_AE_STATE */ public static final int CONTROL_AE_STATE_PRECAPTURE = 5; @@ -1112,21 +1111,20 @@ public abstract class CameraMetadata { /** *

AWB doesn't yet have a good set of control - * values for the current scene

+ * values for the current scene.

* @see CaptureResult#CONTROL_AWB_STATE */ public static final int CONTROL_AWB_STATE_SEARCHING = 1; /** *

AWB has a good set of control values for the - * current scene

+ * current scene.

* @see CaptureResult#CONTROL_AWB_STATE */ public static final int CONTROL_AWB_STATE_CONVERGED = 2; /** - *

AE has been locked (aeMode = - * LOCKED)

+ *

AWB has been locked.

* @see CaptureResult#CONTROL_AWB_STATE */ public static final int CONTROL_AWB_STATE_LOCKED = 3; diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java index 37b19ec08108..fbcc39b08dfd 100644 --- a/core/java/android/hardware/camera2/CaptureRequest.java +++ b/core/java/android/hardware/camera2/CaptureRequest.java @@ -504,15 +504,17 @@ public final class CaptureRequest extends CameraMetadata implements Parcelable { new Key("android.control.aeTargetFpsRange", int[].class); /** - *

Whether the HAL must trigger precapture - * metering.

+ *

Whether the camera device will trigger a precapture + * metering sequence when it processes this request.

*

This entry is normally set to IDLE, or is not * included at all in the request settings. When included and - * set to START, the HAL must trigger the autoexposure + * set to START, the camera device will trigger the autoexposure * precapture metering sequence.

*

The effect of AE precapture trigger depends on the current - * AE mode and state; see the camera HAL device v3 header for - * details.

+ * AE mode and state; see {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture + * state transition details.

+ * + * @see CaptureResult#CONTROL_AE_STATE * @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE * @see #CONTROL_AE_PRECAPTURE_TRIGGER_START */ @@ -563,14 +565,16 @@ public final class CaptureRequest extends CameraMetadata implements Parcelable { new Key("android.control.afRegions", int[].class); /** - *

Whether the HAL must trigger autofocus.

+ *

Whether the camera device will trigger autofocus for this request.

*

This entry is normally set to IDLE, or is not * included at all in the request settings.

- *

When included and set to START, the HAL must trigger the - * autofocus algorithm. The effect of AF trigger depends on the - * current AF mode and state; see the camera HAL device v3 - * header for details. When set to CANCEL, the HAL must cancel - * any active trigger, and return to initial AF state.

+ *

When included and set to START, the camera device will trigger the + * autofocus algorithm. If autofocus is disabled, this trigger has no effect.

+ *

When set to CANCEL, the camera device will cancel any active trigger, + * and return to its initial AF state.

+ *

See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what that means for each AF mode.

+ * + * @see CaptureResult#CONTROL_AF_STATE * @see #CONTROL_AF_TRIGGER_IDLE * @see #CONTROL_AF_TRIGGER_START * @see #CONTROL_AF_TRIGGER_CANCEL diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java index 91733f6ae8d0..99ae161ec0a6 100644 --- a/core/java/android/hardware/camera2/CaptureResult.java +++ b/core/java/android/hardware/camera2/CaptureResult.java @@ -236,9 +236,144 @@ public final class CaptureResult extends CameraMetadata { /** *

Current state of AE algorithm

- *

Whenever the AE algorithm state changes, a - * MSG_AUTOEXPOSURE notification must be send if a - * notification callback is registered.

+ *

Switching between or enabling AE modes ({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}) always + * resets the AE state to INACTIVE. Similarly, switching between {@link CaptureRequest#CONTROL_MODE android.control.mode}, + * or {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} if {@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE resets all + * the algorithm states to INACTIVE.

+ *

The camera device can do several state transitions between two results, if it is + * allowed by the state transition table. For example: INACTIVE may never actually be + * seen in a result.

+ *

The state in the result is the state for this image (in sync with this image): if + * AE state becomes CONVERGED, then the image data associated with this result should + * be good to use.

+ *

Below are state transition tables for different AE modes.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
StateTransition CauseNew StateNotes
INACTIVEINACTIVECamera device auto exposure algorithm is disabled
+ *

When {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is AE_MODE_ON_*:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
StateTransition CauseNew StateNotes
INACTIVECamera device initiates AE scanSEARCHINGValues changing
INACTIVE{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ONLOCKEDValues locked
SEARCHINGCamera device finishes AE scanCONVERGEDGood values, not changing
SEARCHINGCamera device finishes AE scanFLASH_REQUIREDConverged but too dark w/o flash
SEARCHING{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ONLOCKEDValues locked
CONVERGEDCamera device initiates AE scanSEARCHINGValues changing
CONVERGED{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ONLOCKEDValues locked
FLASH_REQUIREDCamera device initiates AE scanSEARCHINGValues changing
FLASH_REQUIRED{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ONLOCKEDValues locked
LOCKED{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFFSEARCHINGValues not good after unlock
LOCKED{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFFCONVERGEDValues good after unlock
LOCKED{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFFFLASH_REQUIREDExposure good, but too dark
PRECAPTURESequence done. {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFFCONVERGEDReady for high-quality capture
PRECAPTURESequence done. {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ONLOCKEDReady for high-quality capture
Any state{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is STARTPRECAPTUREStart AE precapture metering sequence
+ * + * @see CaptureRequest#CONTROL_AE_LOCK + * @see CaptureRequest#CONTROL_AE_MODE + * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER + * @see CaptureRequest#CONTROL_MODE + * @see CaptureRequest#CONTROL_SCENE_MODE * @see #CONTROL_AE_STATE_INACTIVE * @see #CONTROL_AE_STATE_SEARCHING * @see #CONTROL_AE_STATE_CONVERGED @@ -294,9 +429,313 @@ public final class CaptureResult extends CameraMetadata { /** *

Current state of AF algorithm

- *

Whenever the AF algorithm state changes, a - * MSG_AUTOFOCUS notification must be send if a notification - * callback is registered.

+ *

Switching between or enabling AF modes ({@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}) always + * resets the AF state to INACTIVE. Similarly, switching between {@link CaptureRequest#CONTROL_MODE android.control.mode}, + * or {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} if {@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE resets all + * the algorithm states to INACTIVE.

+ *

The camera device can do several state transitions between two results, if it is + * allowed by the state transition table. For example: INACTIVE may never actually be + * seen in a result.

+ *

The state in the result is the state for this image (in sync with this image): if + * AF state becomes FOCUSED, then the image data associated with this result should + * be sharp.

+ *

Below are state transition tables for different AF modes.

+ *

When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_OFF or AF_MODE_EDOF:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
StateTransition CauseNew StateNotes
INACTIVEINACTIVENever changes
+ *

When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_AUTO or AF_MODE_MACRO:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
StateTransition CauseNew StateNotes
INACTIVEAF_TRIGGERACTIVE_SCANStart AF sweep, Lens now moving
ACTIVE_SCANAF sweep doneFOCUSED_LOCKEDFocused, Lens now locked
ACTIVE_SCANAF sweep doneNOT_FOCUSED_LOCKEDNot focused, Lens now locked
ACTIVE_SCANAF_CANCELINACTIVECancel/reset AF, Lens now locked
FOCUSED_LOCKEDAF_CANCELINACTIVECancel/reset AF
FOCUSED_LOCKEDAF_TRIGGERACTIVE_SCANStart new sweep, Lens now moving
NOT_FOCUSED_LOCKEDAF_CANCELINACTIVECancel/reset AF
NOT_FOCUSED_LOCKEDAF_TRIGGERACTIVE_SCANStart new sweep, Lens now moving
Any stateMode changeINACTIVE
+ *

When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_CONTINUOUS_VIDEO:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
StateTransition CauseNew StateNotes
INACTIVECamera device initiates new scanPASSIVE_SCANStart AF scan, Lens now moving
INACTIVEAF_TRIGGERNOT_FOCUSED_LOCKEDAF state query, Lens now locked
PASSIVE_SCANCamera device completes current scanPASSIVE_FOCUSEDEnd AF scan, Lens now locked
PASSIVE_SCANCamera device fails current scanPASSIVE_UNFOCUSEDEnd AF scan, Lens now locked
PASSIVE_SCANAF_TRIGGERFOCUSED_LOCKEDImmediate trans. If focus is good, Lens now locked
PASSIVE_SCANAF_TRIGGERNOT_FOCUSED_LOCKEDImmediate trans. if focus is bad, Lens now locked
PASSIVE_SCANAF_CANCELINACTIVEReset lens position, Lens now locked
PASSIVE_FOCUSEDCamera device initiates new scanPASSIVE_SCANStart AF scan, Lens now moving
PASSIVE_UNFOCUSEDCamera device initiates new scanPASSIVE_SCANStart AF scan, Lens now moving
PASSIVE_FOCUSEDAF_TRIGGERFOCUSED_LOCKEDImmediate trans. Lens now locked
PASSIVE_UNFOCUSEDAF_TRIGGERNOT_FOCUSED_LOCKEDImmediate trans. Lens now locked
FOCUSED_LOCKEDAF_TRIGGERFOCUSED_LOCKEDNo effect
FOCUSED_LOCKEDAF_CANCELINACTIVERestart AF scan
NOT_FOCUSED_LOCKEDAF_TRIGGERNOT_FOCUSED_LOCKEDNo effect
NOT_FOCUSED_LOCKEDAF_CANCELINACTIVERestart AF scan
+ *

When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_CONTINUOUS_PICTURE:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
StateTransition CauseNew StateNotes
INACTIVECamera device initiates new scanPASSIVE_SCANStart AF scan, Lens now moving
INACTIVEAF_TRIGGERNOT_FOCUSED_LOCKEDAF state query, Lens now locked
PASSIVE_SCANCamera device completes current scanPASSIVE_FOCUSEDEnd AF scan, Lens now locked
PASSIVE_SCANCamera device fails current scanPASSIVE_UNFOCUSEDEnd AF scan, Lens now locked
PASSIVE_SCANAF_TRIGGERFOCUSED_LOCKEDEventual trans. once focus good, Lens now locked
PASSIVE_SCANAF_TRIGGERNOT_FOCUSED_LOCKEDEventual trans. if cannot focus, Lens now locked
PASSIVE_SCANAF_CANCELINACTIVEReset lens position, Lens now locked
PASSIVE_FOCUSEDCamera device initiates new scanPASSIVE_SCANStart AF scan, Lens now moving
PASSIVE_UNFOCUSEDCamera device initiates new scanPASSIVE_SCANStart AF scan, Lens now moving
PASSIVE_FOCUSEDAF_TRIGGERFOCUSED_LOCKEDImmediate trans. Lens now locked
PASSIVE_UNFOCUSEDAF_TRIGGERNOT_FOCUSED_LOCKEDImmediate trans. Lens now locked
FOCUSED_LOCKEDAF_TRIGGERFOCUSED_LOCKEDNo effect
FOCUSED_LOCKEDAF_CANCELINACTIVERestart AF scan
NOT_FOCUSED_LOCKEDAF_TRIGGERNOT_FOCUSED_LOCKEDNo effect
NOT_FOCUSED_LOCKEDAF_CANCELINACTIVERestart AF scan
+ * + * @see CaptureRequest#CONTROL_AF_MODE + * @see CaptureRequest#CONTROL_MODE + * @see CaptureRequest#CONTROL_SCENE_MODE * @see #CONTROL_AF_STATE_INACTIVE * @see #CONTROL_AF_STATE_PASSIVE_SCAN * @see #CONTROL_AF_STATE_PASSIVE_FOCUSED @@ -380,9 +819,102 @@ public final class CaptureResult extends CameraMetadata { /** *

Current state of AWB algorithm

- *

Whenever the AWB algorithm state changes, a - * MSG_AUTOWHITEBALANCE notification must be send if a - * notification callback is registered.

+ *

Switching between or enabling AWB modes ({@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}) always + * resets the AWB state to INACTIVE. Similarly, switching between {@link CaptureRequest#CONTROL_MODE android.control.mode}, + * or {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} if {@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE resets all + * the algorithm states to INACTIVE.

+ *

The camera device can do several state transitions between two results, if it is + * allowed by the state transition table. So INACTIVE may never actually be seen in + * a result.

+ *

The state in the result is the state for this image (in sync with this image): if + * AWB state becomes CONVERGED, then the image data associated with this result should + * be good to use.

+ *

Below are state transition tables for different AWB modes.

+ *

When {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != AWB_MODE_AUTO:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
StateTransition CauseNew StateNotes
INACTIVEINACTIVECamera device auto white balance algorithm is disabled
+ *

When {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} is AWB_MODE_AUTO:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
StateTransition CauseNew StateNotes
INACTIVECamera device initiates AWB scanSEARCHINGValues changing
INACTIVE{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ONLOCKEDValues locked
SEARCHINGCamera device finishes AWB scanCONVERGEDGood values, not changing
SEARCHING{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ONLOCKEDValues locked
CONVERGEDCamera device initiates AWB scanSEARCHINGValues changing
CONVERGED{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ONLOCKEDValues locked
LOCKED{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is OFFSEARCHINGValues not good after unlock
LOCKED{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is OFFCONVERGEDValues good after unlock
+ * + * @see CaptureRequest#CONTROL_AWB_LOCK + * @see CaptureRequest#CONTROL_AWB_MODE + * @see CaptureRequest#CONTROL_MODE + * @see CaptureRequest#CONTROL_SCENE_MODE * @see #CONTROL_AWB_STATE_INACTIVE * @see #CONTROL_AWB_STATE_SEARCHING * @see #CONTROL_AWB_STATE_CONVERGED -- 2.11.0