From 228f4f92e70d9326d473e02bcdcc8faf9e706a4d Mon Sep 17 00:00:00 2001
From: Zhijun He 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. Autofocus must trigger now. Autofocus will trigger now. Autofocus must return to initial
- * state, and cancel any active trigger. Autofocus will return to its initial
+ * state, and cancel any currently active trigger. 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. AE doesn't yet have a good set of control values
- * for the current scene
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 KeyWhether 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 KeyWhether 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.
+ *State | + *Transition Cause | + *New State | + *Notes | + *
---|---|---|---|
INACTIVE | + *+ * | INACTIVE | + *Camera device auto exposure algorithm is disabled | + *
When {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is AE_MODE_ON_*:
+ *State | + *Transition Cause | + *New State | + *Notes | + *
---|---|---|---|
INACTIVE | + *Camera device initiates AE scan | + *SEARCHING | + *Values changing | + *
INACTIVE | + *{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON | + *LOCKED | + *Values locked | + *
SEARCHING | + *Camera device finishes AE scan | + *CONVERGED | + *Good values, not changing | + *
SEARCHING | + *Camera device finishes AE scan | + *FLASH_REQUIRED | + *Converged but too dark w/o flash | + *
SEARCHING | + *{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON | + *LOCKED | + *Values locked | + *
CONVERGED | + *Camera device initiates AE scan | + *SEARCHING | + *Values changing | + *
CONVERGED | + *{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON | + *LOCKED | + *Values locked | + *
FLASH_REQUIRED | + *Camera device initiates AE scan | + *SEARCHING | + *Values changing | + *
FLASH_REQUIRED | + *{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON | + *LOCKED | + *Values locked | + *
LOCKED | + *{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF | + *SEARCHING | + *Values not good after unlock | + *
LOCKED | + *{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF | + *CONVERGED | + *Values good after unlock | + *
LOCKED | + *{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF | + *FLASH_REQUIRED | + *Exposure good, but too dark | + *
PRECAPTURE | + *Sequence done. {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF | + *CONVERGED | + *Ready for high-quality capture | + *
PRECAPTURE | + *Sequence done. {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON | + *LOCKED | + *Ready for high-quality capture | + *
Any state | + *{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is START | + *PRECAPTURE | + *Start AE precapture metering sequence | + *
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:
+ *State | + *Transition Cause | + *New State | + *Notes | + *
---|---|---|---|
INACTIVE | + *+ * | INACTIVE | + *Never changes | + *
When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_AUTO or AF_MODE_MACRO:
+ *State | + *Transition Cause | + *New State | + *Notes | + *
---|---|---|---|
INACTIVE | + *AF_TRIGGER | + *ACTIVE_SCAN | + *Start AF sweep, Lens now moving | + *
ACTIVE_SCAN | + *AF sweep done | + *FOCUSED_LOCKED | + *Focused, Lens now locked | + *
ACTIVE_SCAN | + *AF sweep done | + *NOT_FOCUSED_LOCKED | + *Not focused, Lens now locked | + *
ACTIVE_SCAN | + *AF_CANCEL | + *INACTIVE | + *Cancel/reset AF, Lens now locked | + *
FOCUSED_LOCKED | + *AF_CANCEL | + *INACTIVE | + *Cancel/reset AF | + *
FOCUSED_LOCKED | + *AF_TRIGGER | + *ACTIVE_SCAN | + *Start new sweep, Lens now moving | + *
NOT_FOCUSED_LOCKED | + *AF_CANCEL | + *INACTIVE | + *Cancel/reset AF | + *
NOT_FOCUSED_LOCKED | + *AF_TRIGGER | + *ACTIVE_SCAN | + *Start new sweep, Lens now moving | + *
Any state | + *Mode change | + *INACTIVE | + *+ * |
When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_CONTINUOUS_VIDEO:
+ *State | + *Transition Cause | + *New State | + *Notes | + *
---|---|---|---|
INACTIVE | + *Camera device initiates new scan | + *PASSIVE_SCAN | + *Start AF scan, Lens now moving | + *
INACTIVE | + *AF_TRIGGER | + *NOT_FOCUSED_LOCKED | + *AF state query, Lens now locked | + *
PASSIVE_SCAN | + *Camera device completes current scan | + *PASSIVE_FOCUSED | + *End AF scan, Lens now locked | + *
PASSIVE_SCAN | + *Camera device fails current scan | + *PASSIVE_UNFOCUSED | + *End AF scan, Lens now locked | + *
PASSIVE_SCAN | + *AF_TRIGGER | + *FOCUSED_LOCKED | + *Immediate trans. If focus is good, Lens now locked | + *
PASSIVE_SCAN | + *AF_TRIGGER | + *NOT_FOCUSED_LOCKED | + *Immediate trans. if focus is bad, Lens now locked | + *
PASSIVE_SCAN | + *AF_CANCEL | + *INACTIVE | + *Reset lens position, Lens now locked | + *
PASSIVE_FOCUSED | + *Camera device initiates new scan | + *PASSIVE_SCAN | + *Start AF scan, Lens now moving | + *
PASSIVE_UNFOCUSED | + *Camera device initiates new scan | + *PASSIVE_SCAN | + *Start AF scan, Lens now moving | + *
PASSIVE_FOCUSED | + *AF_TRIGGER | + *FOCUSED_LOCKED | + *Immediate trans. Lens now locked | + *
PASSIVE_UNFOCUSED | + *AF_TRIGGER | + *NOT_FOCUSED_LOCKED | + *Immediate trans. Lens now locked | + *
FOCUSED_LOCKED | + *AF_TRIGGER | + *FOCUSED_LOCKED | + *No effect | + *
FOCUSED_LOCKED | + *AF_CANCEL | + *INACTIVE | + *Restart AF scan | + *
NOT_FOCUSED_LOCKED | + *AF_TRIGGER | + *NOT_FOCUSED_LOCKED | + *No effect | + *
NOT_FOCUSED_LOCKED | + *AF_CANCEL | + *INACTIVE | + *Restart AF scan | + *
When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_CONTINUOUS_PICTURE:
+ *State | + *Transition Cause | + *New State | + *Notes | + *
---|---|---|---|
INACTIVE | + *Camera device initiates new scan | + *PASSIVE_SCAN | + *Start AF scan, Lens now moving | + *
INACTIVE | + *AF_TRIGGER | + *NOT_FOCUSED_LOCKED | + *AF state query, Lens now locked | + *
PASSIVE_SCAN | + *Camera device completes current scan | + *PASSIVE_FOCUSED | + *End AF scan, Lens now locked | + *
PASSIVE_SCAN | + *Camera device fails current scan | + *PASSIVE_UNFOCUSED | + *End AF scan, Lens now locked | + *
PASSIVE_SCAN | + *AF_TRIGGER | + *FOCUSED_LOCKED | + *Eventual trans. once focus good, Lens now locked | + *
PASSIVE_SCAN | + *AF_TRIGGER | + *NOT_FOCUSED_LOCKED | + *Eventual trans. if cannot focus, Lens now locked | + *
PASSIVE_SCAN | + *AF_CANCEL | + *INACTIVE | + *Reset lens position, Lens now locked | + *
PASSIVE_FOCUSED | + *Camera device initiates new scan | + *PASSIVE_SCAN | + *Start AF scan, Lens now moving | + *
PASSIVE_UNFOCUSED | + *Camera device initiates new scan | + *PASSIVE_SCAN | + *Start AF scan, Lens now moving | + *
PASSIVE_FOCUSED | + *AF_TRIGGER | + *FOCUSED_LOCKED | + *Immediate trans. Lens now locked | + *
PASSIVE_UNFOCUSED | + *AF_TRIGGER | + *NOT_FOCUSED_LOCKED | + *Immediate trans. Lens now locked | + *
FOCUSED_LOCKED | + *AF_TRIGGER | + *FOCUSED_LOCKED | + *No effect | + *
FOCUSED_LOCKED | + *AF_CANCEL | + *INACTIVE | + *Restart AF scan | + *
NOT_FOCUSED_LOCKED | + *AF_TRIGGER | + *NOT_FOCUSED_LOCKED | + *No effect | + *
NOT_FOCUSED_LOCKED | + *AF_CANCEL | + *INACTIVE | + *Restart AF scan | + *
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
:
State | + *Transition Cause | + *New State | + *Notes | + *
---|---|---|---|
INACTIVE | + *+ * | INACTIVE | + *Camera device auto white balance algorithm is disabled | + *
When {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} is AWB_MODE_AUTO:
+ *State | + *Transition Cause | + *New State | + *Notes | + *
---|---|---|---|
INACTIVE | + *Camera device initiates AWB scan | + *SEARCHING | + *Values changing | + *
INACTIVE | + *{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ON | + *LOCKED | + *Values locked | + *
SEARCHING | + *Camera device finishes AWB scan | + *CONVERGED | + *Good values, not changing | + *
SEARCHING | + *{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ON | + *LOCKED | + *Values locked | + *
CONVERGED | + *Camera device initiates AWB scan | + *SEARCHING | + *Values changing | + *
CONVERGED | + *{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ON | + *LOCKED | + *Values locked | + *
LOCKED | + *{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is OFF | + *SEARCHING | + *Values not good after unlock | + *
LOCKED | + *{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is OFF | + *CONVERGED | + *Values good after unlock | + *