Camera2: Update 3A state doc

Change-Id: Id484bdff38af34ad2c8b64863d036ff81124401e

diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java
index 84d8710..81640a6 100644 (file)
--- 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;
 
     /**
-     * <p>The precapture metering sequence
-     * must be started. The exact effect of the precapture
-     * trigger depends on the current AE mode and
-     * state.</p>
+     * <p>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.</p>
      * @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;
 
     /**
-     * <p>Autofocus must trigger now.</p>
+     * <p>Autofocus will trigger now.</p>
      * @see CaptureRequest#CONTROL_AF_TRIGGER
      */
     public static final int CONTROL_AF_TRIGGER_START = 1;
 
     /**
-     * <p>Autofocus must return to initial
-     * state, and cancel any active trigger.</p>
+     * <p>Autofocus will return to its initial
+     * state, and cancel any currently active trigger.</p>
      * @see CaptureRequest#CONTROL_AF_TRIGGER
      */
     public static final int CONTROL_AF_TRIGGER_CANCEL = 2;
@@ -993,7 +992,7 @@ public abstract class CameraMetadata {
     //
 
     /**
-     * <p>AE is off.  When a camera device is opened, it starts in
+     * <p>AE is off or recently reset. When a camera device is opened, it starts in
      * this state.</p>
      * @see CaptureResult#CONTROL_AE_STATE
      */
@@ -1001,21 +1000,20 @@ public abstract class CameraMetadata {
 
     /**
      * <p>AE doesn't yet have a good set of control values
-     * for the current scene</p>
+     * for the current scene.</p>
      * @see CaptureResult#CONTROL_AE_STATE
      */
     public static final int CONTROL_AE_STATE_SEARCHING = 1;
 
     /**
      * <p>AE has a good set of control values for the
-     * current scene</p>
+     * current scene.</p>
      * @see CaptureResult#CONTROL_AE_STATE
      */
     public static final int CONTROL_AE_STATE_CONVERGED = 2;
 
     /**
-     * <p>AE has been locked (aeMode =
-     * LOCKED)</p>
+     * <p>AE has been locked.</p>
      * @see CaptureResult#CONTROL_AE_STATE
      */
     public static final int CONTROL_AE_STATE_LOCKED = 3;
@@ -1023,18 +1021,19 @@ public abstract class CameraMetadata {
     /**
      * <p>AE has a good set of control values, but flash
      * needs to be fired for good quality still
-     * capture</p>
+     * capture.</p>
      * @see CaptureResult#CONTROL_AE_STATE
      */
     public static final int CONTROL_AE_STATE_FLASH_REQUIRED = 4;
 
     /**
      * <p>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</p>
+     * FLASH_REQUIRED as appropriate.</p>
+     *
+     * @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 {
 
     /**
      * <p>AWB doesn't yet have a good set of control
-     * values for the current scene</p>
+     * values for the current scene.</p>
      * @see CaptureResult#CONTROL_AWB_STATE
      */
     public static final int CONTROL_AWB_STATE_SEARCHING = 1;
 
     /**
      * <p>AWB has a good set of control values for the
-     * current scene</p>
+     * current scene.</p>
      * @see CaptureResult#CONTROL_AWB_STATE
      */
     public static final int CONTROL_AWB_STATE_CONVERGED = 2;
 
     /**
-     * <p>AE has been locked (aeMode =
-     * LOCKED)</p>
+     * <p>AWB has been locked.</p>
      * @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 37b19ec..fbcc39b 100644 (file)
--- 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<int[]>("android.control.aeTargetFpsRange", int[].class);
 
     /**
-     * <p>Whether the HAL must trigger precapture
-     * metering.</p>
+     * <p>Whether the camera device will trigger a precapture
+     * metering sequence when it processes this request.</p>
      * <p>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.</p>
      * <p>The effect of AE precapture trigger depends on the current
-     * AE mode and state; see the camera HAL device v3 header for
-     * details.</p>
+     * AE mode and state; see {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture
+     * state transition details.</p>
+     *
+     * @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<int[]>("android.control.afRegions", int[].class);
 
     /**
-     * <p>Whether the HAL must trigger autofocus.</p>
+     * <p>Whether the camera device will trigger autofocus for this request.</p>
      * <p>This entry is normally set to IDLE, or is not
      * included at all in the request settings.</p>
-     * <p>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.</p>
+     * <p>When included and set to START, the camera device will trigger the
+     * autofocus algorithm. If autofocus is disabled, this trigger has no effect.</p>
+     * <p>When set to CANCEL, the camera device will cancel any active trigger,
+     * and return to its initial AF state.</p>
+     * <p>See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what that means for each AF mode.</p>
+     *
+     * @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 91733f6..99ae161 100644 (file)
--- 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 {
 
     /**
      * <p>Current state of AE algorithm</p>
-     * <p>Whenever the AE algorithm state changes, a
-     * MSG_AUTOEXPOSURE notification must be send if a
-     * notification callback is registered.</p>
+     * <p>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 <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code> resets all
+     * the algorithm states to INACTIVE.</p>
+     * <p>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.</p>
+     * <p>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.</p>
+     * <p>Below are state transition tables for different AE modes.</p>
+     * <table>
+     * <thead>
+     * <tr>
+     * <th align="center">State</th>
+     * <th align="center">Transition Cause</th>
+     * <th align="center">New State</th>
+     * <th align="center">Notes</th>
+     * </tr>
+     * </thead>
+     * <tbody>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center"></td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Camera device auto exposure algorithm is disabled</td>
+     * </tr>
+     * </tbody>
+     * </table>
+     * <p>When {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is AE_MODE_ON_*:</p>
+     * <table>
+     * <thead>
+     * <tr>
+     * <th align="center">State</th>
+     * <th align="center">Transition Cause</th>
+     * <th align="center">New State</th>
+     * <th align="center">Notes</th>
+     * </tr>
+     * </thead>
+     * <tbody>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Camera device initiates AE scan</td>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">Values changing</td>
+     * </tr>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON</td>
+     * <td align="center">LOCKED</td>
+     * <td align="center">Values locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">Camera device finishes AE scan</td>
+     * <td align="center">CONVERGED</td>
+     * <td align="center">Good values, not changing</td>
+     * </tr>
+     * <tr>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">Camera device finishes AE scan</td>
+     * <td align="center">FLASH_REQUIRED</td>
+     * <td align="center">Converged but too dark w/o flash</td>
+     * </tr>
+     * <tr>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON</td>
+     * <td align="center">LOCKED</td>
+     * <td align="center">Values locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">CONVERGED</td>
+     * <td align="center">Camera device initiates AE scan</td>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">Values changing</td>
+     * </tr>
+     * <tr>
+     * <td align="center">CONVERGED</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON</td>
+     * <td align="center">LOCKED</td>
+     * <td align="center">Values locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">FLASH_REQUIRED</td>
+     * <td align="center">Camera device initiates AE scan</td>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">Values changing</td>
+     * </tr>
+     * <tr>
+     * <td align="center">FLASH_REQUIRED</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON</td>
+     * <td align="center">LOCKED</td>
+     * <td align="center">Values locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">LOCKED</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF</td>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">Values not good after unlock</td>
+     * </tr>
+     * <tr>
+     * <td align="center">LOCKED</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF</td>
+     * <td align="center">CONVERGED</td>
+     * <td align="center">Values good after unlock</td>
+     * </tr>
+     * <tr>
+     * <td align="center">LOCKED</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF</td>
+     * <td align="center">FLASH_REQUIRED</td>
+     * <td align="center">Exposure good, but too dark</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PRECAPTURE</td>
+     * <td align="center">Sequence done. {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF</td>
+     * <td align="center">CONVERGED</td>
+     * <td align="center">Ready for high-quality capture</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PRECAPTURE</td>
+     * <td align="center">Sequence done. {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON</td>
+     * <td align="center">LOCKED</td>
+     * <td align="center">Ready for high-quality capture</td>
+     * </tr>
+     * <tr>
+     * <td align="center">Any state</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is START</td>
+     * <td align="center">PRECAPTURE</td>
+     * <td align="center">Start AE precapture metering sequence</td>
+     * </tr>
+     * </tbody>
+     * </table>
+     *
+     * @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 {
 
     /**
      * <p>Current state of AF algorithm</p>
-     * <p>Whenever the AF algorithm state changes, a
-     * MSG_AUTOFOCUS notification must be send if a notification
-     * callback is registered.</p>
+     * <p>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 <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code> resets all
+     * the algorithm states to INACTIVE.</p>
+     * <p>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.</p>
+     * <p>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.</p>
+     * <p>Below are state transition tables for different AF modes.</p>
+     * <p>When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_OFF or AF_MODE_EDOF:</p>
+     * <table>
+     * <thead>
+     * <tr>
+     * <th align="center">State</th>
+     * <th align="center">Transition Cause</th>
+     * <th align="center">New State</th>
+     * <th align="center">Notes</th>
+     * </tr>
+     * </thead>
+     * <tbody>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center"></td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Never changes</td>
+     * </tr>
+     * </tbody>
+     * </table>
+     * <p>When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_AUTO or AF_MODE_MACRO:</p>
+     * <table>
+     * <thead>
+     * <tr>
+     * <th align="center">State</th>
+     * <th align="center">Transition Cause</th>
+     * <th align="center">New State</th>
+     * <th align="center">Notes</th>
+     * </tr>
+     * </thead>
+     * <tbody>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">ACTIVE_SCAN</td>
+     * <td align="center">Start AF sweep, Lens now moving</td>
+     * </tr>
+     * <tr>
+     * <td align="center">ACTIVE_SCAN</td>
+     * <td align="center">AF sweep done</td>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">Focused, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">ACTIVE_SCAN</td>
+     * <td align="center">AF sweep done</td>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">Not focused, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">ACTIVE_SCAN</td>
+     * <td align="center">AF_CANCEL</td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Cancel/reset AF, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">AF_CANCEL</td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Cancel/reset AF</td>
+     * </tr>
+     * <tr>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">ACTIVE_SCAN</td>
+     * <td align="center">Start new sweep, Lens now moving</td>
+     * </tr>
+     * <tr>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">AF_CANCEL</td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Cancel/reset AF</td>
+     * </tr>
+     * <tr>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">ACTIVE_SCAN</td>
+     * <td align="center">Start new sweep, Lens now moving</td>
+     * </tr>
+     * <tr>
+     * <td align="center">Any state</td>
+     * <td align="center">Mode change</td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center"></td>
+     * </tr>
+     * </tbody>
+     * </table>
+     * <p>When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_CONTINUOUS_VIDEO:</p>
+     * <table>
+     * <thead>
+     * <tr>
+     * <th align="center">State</th>
+     * <th align="center">Transition Cause</th>
+     * <th align="center">New State</th>
+     * <th align="center">Notes</th>
+     * </tr>
+     * </thead>
+     * <tbody>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Camera device initiates new scan</td>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">Start AF scan, Lens now moving</td>
+     * </tr>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">AF state query, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">Camera device completes current scan</td>
+     * <td align="center">PASSIVE_FOCUSED</td>
+     * <td align="center">End AF scan, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">Camera device fails current scan</td>
+     * <td align="center">PASSIVE_UNFOCUSED</td>
+     * <td align="center">End AF scan, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">Immediate trans. If focus is good, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">Immediate trans. if focus is bad, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">AF_CANCEL</td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Reset lens position, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_FOCUSED</td>
+     * <td align="center">Camera device initiates new scan</td>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">Start AF scan, Lens now moving</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_UNFOCUSED</td>
+     * <td align="center">Camera device initiates new scan</td>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">Start AF scan, Lens now moving</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_FOCUSED</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">Immediate trans. Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_UNFOCUSED</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">Immediate trans. Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">No effect</td>
+     * </tr>
+     * <tr>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">AF_CANCEL</td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Restart AF scan</td>
+     * </tr>
+     * <tr>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">No effect</td>
+     * </tr>
+     * <tr>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">AF_CANCEL</td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Restart AF scan</td>
+     * </tr>
+     * </tbody>
+     * </table>
+     * <p>When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_CONTINUOUS_PICTURE:</p>
+     * <table>
+     * <thead>
+     * <tr>
+     * <th align="center">State</th>
+     * <th align="center">Transition Cause</th>
+     * <th align="center">New State</th>
+     * <th align="center">Notes</th>
+     * </tr>
+     * </thead>
+     * <tbody>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Camera device initiates new scan</td>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">Start AF scan, Lens now moving</td>
+     * </tr>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">AF state query, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">Camera device completes current scan</td>
+     * <td align="center">PASSIVE_FOCUSED</td>
+     * <td align="center">End AF scan, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">Camera device fails current scan</td>
+     * <td align="center">PASSIVE_UNFOCUSED</td>
+     * <td align="center">End AF scan, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">Eventual trans. once focus good, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">Eventual trans. if cannot focus, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">AF_CANCEL</td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Reset lens position, Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_FOCUSED</td>
+     * <td align="center">Camera device initiates new scan</td>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">Start AF scan, Lens now moving</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_UNFOCUSED</td>
+     * <td align="center">Camera device initiates new scan</td>
+     * <td align="center">PASSIVE_SCAN</td>
+     * <td align="center">Start AF scan, Lens now moving</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_FOCUSED</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">Immediate trans. Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">PASSIVE_UNFOCUSED</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">Immediate trans. Lens now locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">No effect</td>
+     * </tr>
+     * <tr>
+     * <td align="center">FOCUSED_LOCKED</td>
+     * <td align="center">AF_CANCEL</td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Restart AF scan</td>
+     * </tr>
+     * <tr>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">AF_TRIGGER</td>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">No effect</td>
+     * </tr>
+     * <tr>
+     * <td align="center">NOT_FOCUSED_LOCKED</td>
+     * <td align="center">AF_CANCEL</td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Restart AF scan</td>
+     * </tr>
+     * </tbody>
+     * </table>
+     *
+     * @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 {
 
     /**
      * <p>Current state of AWB algorithm</p>
-     * <p>Whenever the AWB algorithm state changes, a
-     * MSG_AUTOWHITEBALANCE notification must be send if a
-     * notification callback is registered.</p>
+     * <p>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 <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code> resets all
+     * the algorithm states to INACTIVE.</p>
+     * <p>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.</p>
+     * <p>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.</p>
+     * <p>Below are state transition tables for different AWB modes.</p>
+     * <p>When <code>{@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != AWB_MODE_AUTO</code>:</p>
+     * <table>
+     * <thead>
+     * <tr>
+     * <th align="center">State</th>
+     * <th align="center">Transition Cause</th>
+     * <th align="center">New State</th>
+     * <th align="center">Notes</th>
+     * </tr>
+     * </thead>
+     * <tbody>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center"></td>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Camera device auto white balance algorithm is disabled</td>
+     * </tr>
+     * </tbody>
+     * </table>
+     * <p>When {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} is AWB_MODE_AUTO:</p>
+     * <table>
+     * <thead>
+     * <tr>
+     * <th align="center">State</th>
+     * <th align="center">Transition Cause</th>
+     * <th align="center">New State</th>
+     * <th align="center">Notes</th>
+     * </tr>
+     * </thead>
+     * <tbody>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">Camera device initiates AWB scan</td>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">Values changing</td>
+     * </tr>
+     * <tr>
+     * <td align="center">INACTIVE</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ON</td>
+     * <td align="center">LOCKED</td>
+     * <td align="center">Values locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">Camera device finishes AWB scan</td>
+     * <td align="center">CONVERGED</td>
+     * <td align="center">Good values, not changing</td>
+     * </tr>
+     * <tr>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ON</td>
+     * <td align="center">LOCKED</td>
+     * <td align="center">Values locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">CONVERGED</td>
+     * <td align="center">Camera device initiates AWB scan</td>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">Values changing</td>
+     * </tr>
+     * <tr>
+     * <td align="center">CONVERGED</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ON</td>
+     * <td align="center">LOCKED</td>
+     * <td align="center">Values locked</td>
+     * </tr>
+     * <tr>
+     * <td align="center">LOCKED</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is OFF</td>
+     * <td align="center">SEARCHING</td>
+     * <td align="center">Values not good after unlock</td>
+     * </tr>
+     * <tr>
+     * <td align="center">LOCKED</td>
+     * <td align="center">{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is OFF</td>
+     * <td align="center">CONVERGED</td>
+     * <td align="center">Values good after unlock</td>
+     * </tr>
+     * </tbody>
+     * </table>
+     *
+     * @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