From 60b19dc2df1afef1caf151b9df4cc60af3c395e8 Mon Sep 17 00:00:00 2001 From: Zhijun He Date: Mon, 24 Feb 2014 10:19:20 -0800 Subject: [PATCH] Camera2: update 3A state related metadata key docs Bug: 12840262 Change-Id: I2092e1d24b262a0568b880094b8ad6a87510b346 --- .../hardware/camera2/CameraMetadata.java | 36 +++-- .../hardware/camera2/CaptureResult.java | 153 +++++++++++++++++- 2 files changed, 174 insertions(+), 15 deletions(-) diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java index cbd6ec30a6387..c4b07cc5670c0 100644 --- a/core/java/android/hardware/camera2/CameraMetadata.java +++ b/core/java/android/hardware/camera2/CameraMetadata.java @@ -1468,14 +1468,16 @@ public abstract class CameraMetadata { /** *

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

+ * this state. This is a transient state, the camera device may skip reporting + * this state in capture result.

* @see CaptureResult#CONTROL_AE_STATE */ public static final int CONTROL_AE_STATE_INACTIVE = 0; /** *

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

+ * for the current scene. This is a transient state, the camera device may skip + * reporting this state in capture result.

* @see CaptureResult#CONTROL_AE_STATE */ public static final int CONTROL_AE_STATE_SEARCHING = 1; @@ -1506,7 +1508,8 @@ public abstract class CameraMetadata { * (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. This is a transient state, the + * camera device may skip reporting this state in capture result.

* * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER * @see CaptureResult#CONTROL_AE_STATE @@ -1520,7 +1523,8 @@ public abstract class CameraMetadata { /** *

AF off or has not yet tried to scan/been asked * to scan. When a camera device is opened, it starts in - * this state.

+ * this state. This is a transient state, the camera device may + * skip reporting this state in capture result.

* @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_INACTIVE = 0; @@ -1528,7 +1532,8 @@ public abstract class CameraMetadata { /** *

if CONTINUOUS_* modes are supported. AF is * currently doing an AF scan initiated by a continuous - * autofocus mode

+ * autofocus mode. This is a transient state, the camera device may + * skip reporting this state in capture result.

* @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_PASSIVE_SCAN = 1; @@ -1536,15 +1541,17 @@ public abstract class CameraMetadata { /** *

if CONTINUOUS_* modes are supported. AF currently * believes it is in focus, but may restart scanning at - * any time.

+ * any time. This is a transient state, the camera device may skip + * reporting this state in capture result.

* @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_PASSIVE_FOCUSED = 2; /** *

if AUTO or MACRO modes are supported. AF is doing - * an AF scan because it was triggered by AF - * trigger

+ * an AF scan because it was triggered by AF trigger. This is a + * transient state, the camera device may skip reporting + * this state in capture result.

* @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_ACTIVE_SCAN = 3; @@ -1552,7 +1559,7 @@ public abstract class CameraMetadata { /** *

if any AF mode besides OFF is supported. AF * believes it is focused correctly and is - * locked

+ * locked.

* @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_FOCUSED_LOCKED = 4; @@ -1560,7 +1567,7 @@ public abstract class CameraMetadata { /** *

if any AF mode besides OFF is supported. AF has * failed to focus successfully and is - * locked

+ * locked.

* @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_NOT_FOCUSED_LOCKED = 5; @@ -1568,7 +1575,8 @@ public abstract class CameraMetadata { /** *

if CONTINUOUS_* modes are supported. AF finished a * passive scan without finding focus, and may restart - * scanning at any time.

+ * scanning at any time. This is a transient state, the camera + * device may skip reporting this state in capture result.

* @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_PASSIVE_UNFOCUSED = 6; @@ -1579,14 +1587,16 @@ public abstract class CameraMetadata { /** *

AWB is not in auto mode. When a camera device is opened, it - * starts in this state.

+ * starts in this state. This is a transient state, the camera device may + * skip reporting this state in capture result.

* @see CaptureResult#CONTROL_AWB_STATE */ public static final int CONTROL_AWB_STATE_INACTIVE = 0; /** *

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

+ * values for the current scene. This is a transient state, the camera device + * may skip reporting this state in capture result.

* @see CaptureResult#CONTROL_AWB_STATE */ public static final int CONTROL_AWB_STATE_SEARCHING = 1; diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java index bd9ba2f1bd906..9981bf9a87e48 100644 --- a/core/java/android/hardware/camera2/CaptureResult.java +++ b/core/java/android/hardware/camera2/CaptureResult.java @@ -370,6 +370,54 @@ public final class CaptureResult extends CameraMetadata { * * * + *

For the above table, the camera device may skip reporting any state changes that happen + * without application intervention (i.e. mode switch, trigger, locking). Any state that + * can be skipped in that manner is called a transient state.

+ *

For example, for above AE modes (AE_MODE_ON_*), in addition to the state transitions + * listed in above table, it is also legal for the camera device to skip one or more + * transient states between two results. See below table for examples:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
StateTransition CauseNew StateNotes
INACTIVECamera device finished AE scanCONVERGEDValues are already good, transient states are skipped by camera device.
Any state{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is START, sequence doneFLASH_REQUIREDConverged but too dark w/o flash after a precapture sequence, transient states are skipped by camera device.
Any state{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is START, sequence doneCONVERGEDConverged after a precapture sequence, transient states are skipped by camera device.
CONVERGEDCamera device finished AE scanFLASH_REQUIREDConverged but too dark w/o flash after a new scan, transient states are skipped by camera device.
FLASH_REQUIREDCamera device finished AE scanCONVERGEDConverged after a new scan, transient states are skipped by camera device.
* * @see CaptureRequest#CONTROL_AE_LOCK * @see CaptureRequest#CONTROL_AE_MODE @@ -431,7 +479,7 @@ public final class CaptureResult extends CameraMetadata { new Key("android.control.afRegions", int[].class); /** - *

Current state of AF algorithm

+ *

Current state of AF algorithm.

*

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 @@ -529,6 +577,48 @@ public final class CaptureResult extends CameraMetadata { * * * + *

For the above table, the camera device may skip reporting any state changes that happen + * without application intervention (i.e. mode switch, trigger, locking). Any state that + * can be skipped in that manner is called a transient state.

+ *

For example, for these AF modes (AF_MODE_AUTO and AF_MODE_MACRO), in addition to the + * state transitions listed in above table, it is also legal for the camera device to skip + * one or more transient states between two results. See below table for examples:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
StateTransition CauseNew StateNotes
INACTIVEAF_TRIGGERFOCUSED_LOCKEDFocus is already good or good after a scan, lens is now locked.
INACTIVEAF_TRIGGERNOT_FOCUSED_LOCKEDFocus failed after a scan, lens is now locked.
FOCUSED_LOCKEDAF_TRIGGERFOCUSED_LOCKEDFocus is already good or good after a scan, lens is now locked.
NOT_FOCUSED_LOCKEDAF_TRIGGERFOCUSED_LOCKEDFocus is good after a scan, lens is not locked.
*

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

* * @@ -735,6 +825,41 @@ public final class CaptureResult extends CameraMetadata { * * *
+ *

When switch between AF_MODE_CONTINUOUS_* (CAF modes) and AF_MODE_AUTO/AF_MODE_MACRO + * (AUTO modes), the initial INACTIVE or PASSIVE_SCAN states may be skipped by the + * camera device. When a trigger is included in a mode switch request, the trigger + * will be evaluated in the context of the new mode in the request. + * See below table for examples:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
StateTransition CauseNew StateNotes
any stateCAF-->AUTO mode switchINACTIVEMode switch without trigger, initial state must be INACTIVE
any stateCAF-->AUTO mode switch with AF_TRIGGERtrigger-reachable states from INACTIVEMode switch with trigger, INACTIVE is skipped
any stateAUTO-->CAF mode switchpassively reachable states from INACTIVEMode switch without trigger, passive transient state is skipped
* * @see CaptureRequest#CONTROL_AF_MODE * @see CaptureRequest#CONTROL_MODE @@ -905,11 +1030,35 @@ public final class CaptureResult extends CameraMetadata { * SEARCHING * Values not good after unlock * + * + * + *

For the above table, the camera device may skip reporting any state changes that happen + * without application intervention (i.e. mode switch, trigger, locking). Any state that + * can be skipped in that manner is called a transient state.

+ *

For example, for this AWB mode (AWB_MODE_AUTO), in addition to the state transitions + * listed in above table, it is also legal for the camera device to skip one or more + * transient states between two results. See below table for examples:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * * * * * - * + * * * *
StateTransition CauseNew StateNotes
INACTIVECamera device finished AWB scanCONVERGEDValues are already good, transient states are skipped by camera device.
LOCKED{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is OFFCONVERGEDValues good after unlockValues good after unlock, transient states are skipped by camera device.