Camera2: Update awbMode related javadoc spec

Change-Id: I999d2bc94834c6f6d4483493707f05c92d7c5d67

4 files changed, 103 insertions, 19 deletions

diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java
index d5476fc9392d..0ef64d17dcb1 100644
--- a/core/java/android/hardware/camera2/CameraCharacteristics.java
+++ b/core/java/android/hardware/camera2/CameraCharacteristics.java
@@ -219,6 +219,22 @@ public final class CameraCharacteristics extends CameraMetadata {
             new Key<byte[]>("android.control.availableVideoStabilizationModes", byte[].class);
 
     /**
+     * <p>The set of auto-white-balance modes ({@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode})
+     * that are supported by this camera device.</p>
+     *
+     * @see CaptureRequest#CONTROL_AWB_MODE
+     * <p>Not all the auto-white-balance modes may be supported by a
+     * given camera device. This entry lists the valid modes for
+     * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} for this camera device.</p>
+     * <p>All camera devices will support ON mode.</p>
+     * <p>Full-capability camera devices will always support OFF mode,
+     * which enables application control of white balance, by using
+     * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains}({@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} must be set to TRANSFORM_MATRIX).</p>
+     *
+     * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
+     * @see CaptureRequest#COLOR_CORRECTION_MODE
+     * @see CaptureRequest#CONTROL_AWB_MODE
+     * @see CaptureRequest#COLOR_CORRECTION_GAINS
      */
     public static final Key<byte[]> CONTROL_AWB_AVAILABLE_MODES =
             new Key<byte[]>("android.control.awbAvailableModes", byte[].class);
diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java
index 64d055fbfa62..ef3e600f8368 100644
--- a/core/java/android/hardware/camera2/CameraMetadata.java
+++ b/core/java/android/hardware/camera2/CameraMetadata.java
@@ -351,8 +351,8 @@ public abstract class CameraMetadata {
      * {@link CaptureRequest#CONTROL_CAPTURE_INTENT android.control.captureIntent} field is set to
      * STILL_CAPTURE</p>
      *
-     * @see CaptureRequest#CONTROL_CAPTURE_INTENT
      * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
+     * @see CaptureRequest#CONTROL_CAPTURE_INTENT
      * @see CaptureRequest#CONTROL_AE_MODE
      */
     public static final int CONTROL_AE_MODE_ON_AUTO_FLASH = 2;
@@ -367,8 +367,8 @@ public abstract class CameraMetadata {
      * {@link CaptureRequest#CONTROL_CAPTURE_INTENT android.control.captureIntent} field is set to
      * STILL_CAPTURE</p>
      *
-     * @see CaptureRequest#CONTROL_CAPTURE_INTENT
      * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
+     * @see CaptureRequest#CONTROL_CAPTURE_INTENT
      * @see CaptureRequest#CONTROL_AE_MODE
      */
     public static final int CONTROL_AE_MODE_ON_ALWAYS_FLASH = 3;
@@ -521,46 +521,88 @@ public abstract class CameraMetadata {
     //
 
     /**
+     * <p>The camera device's auto white balance routine is disabled;
+     * the application-selected color transform matrix
+     * ({@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}) and gains
+     * ({@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains}) are used by the camera
+     * device for manual white balance control.</p>
+     *
+     * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
+     * @see CaptureRequest#COLOR_CORRECTION_GAINS
      * @see CaptureRequest#CONTROL_AWB_MODE
      */
     public static final int CONTROL_AWB_MODE_OFF = 0;
 
     /**
+     * <p>The camera device's auto white balance routine is active;
+     * the application's values for android.colorCorrection.transform
+     * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored.</p>
+     *
+     * @see CaptureRequest#COLOR_CORRECTION_GAINS
      * @see CaptureRequest#CONTROL_AWB_MODE
      */
     public static final int CONTROL_AWB_MODE_AUTO = 1;
 
     /**
+     * <p>The camera device's auto white balance routine is disabled;
+     * the camera device uses incandescent light as the assumed scene
+     * illumination for white balance. While the exact white balance
+     * transforms are up to the camera device, they will approximately
+     * match the CIE standard illuminant A.</p>
      * @see CaptureRequest#CONTROL_AWB_MODE
      */
     public static final int CONTROL_AWB_MODE_INCANDESCENT = 2;
 
     /**
+     * <p>The camera device's auto white balance routine is disabled;
+     * the camera device uses fluorescent light as the assumed scene
+     * illumination for white balance. While the exact white balance
+     * transforms are up to the camera device, they will approximately
+     * match the CIE standard illuminant F2.</p>
      * @see CaptureRequest#CONTROL_AWB_MODE
      */
     public static final int CONTROL_AWB_MODE_FLUORESCENT = 3;
 
     /**
+     * <p>The camera device's auto white balance routine is disabled;
+     * the camera device uses warm fluorescent light as the assumed scene
+     * illumination for white balance. While the exact white balance
+     * transforms are up to the camera device, they will approximately
+     * match the CIE standard illuminant F4.</p>
      * @see CaptureRequest#CONTROL_AWB_MODE
      */
     public static final int CONTROL_AWB_MODE_WARM_FLUORESCENT = 4;
 
     /**
+     * <p>The camera device's auto white balance routine is disabled;
+     * the camera device uses daylight light as the assumed scene
+     * illumination for white balance. While the exact white balance
+     * transforms are up to the camera device, they will approximately
+     * match the CIE standard illuminant D65.</p>
      * @see CaptureRequest#CONTROL_AWB_MODE
      */
     public static final int CONTROL_AWB_MODE_DAYLIGHT = 5;
 
     /**
+     * <p>The camera device's auto white balance routine is disabled;
+     * the camera device uses cloudy daylight light as the assumed scene
+     * illumination for white balance.</p>
      * @see CaptureRequest#CONTROL_AWB_MODE
      */
     public static final int CONTROL_AWB_MODE_CLOUDY_DAYLIGHT = 6;
 
     /**
+     * <p>The camera device's auto white balance routine is disabled;
+     * the camera device uses twilight light as the assumed scene
+     * illumination for white balance.</p>
      * @see CaptureRequest#CONTROL_AWB_MODE
      */
     public static final int CONTROL_AWB_MODE_TWILIGHT = 7;
 
     /**
+     * <p>The camera device's auto white balance routine is disabled;
+     * the camera device uses shade light as the assumed scene
+     * illumination for white balance.</p>
      * @see CaptureRequest#CONTROL_AWB_MODE
      */
     public static final int CONTROL_AWB_MODE_SHADE = 8;
diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java
index d6420766428f..dd17e9df29ca 100644
--- a/core/java/android/hardware/camera2/CaptureRequest.java
+++ b/core/java/android/hardware/camera2/CaptureRequest.java
@@ -399,10 +399,10 @@ public final class CaptureRequest extends CameraMetadata implements Parcelable {
      * issues. The {@link CaptureResult#STATISTICS_SCENE_FLICKER android.statistics.sceneFlicker} key can assist
      * the application in this.</p>
      *
-     * @see CaptureRequest#CONTROL_AE_MODE
-     * @see CaptureResult#STATISTICS_SCENE_FLICKER
-     * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES
      * @see CaptureRequest#CONTROL_MODE
+     * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES
+     * @see CaptureResult#STATISTICS_SCENE_FLICKER
+     * @see CaptureRequest#CONTROL_AE_MODE
      * @see #CONTROL_AE_ANTIBANDING_MODE_OFF
      * @see #CONTROL_AE_ANTIBANDING_MODE_50HZ
      * @see #CONTROL_AE_ANTIBANDING_MODE_60HZ
@@ -453,12 +453,12 @@ public final class CaptureRequest extends CameraMetadata implements Parcelable {
      * fields for a given capture will be available in its
      * CaptureResult.</p>
      *
+     * @see CaptureRequest#SENSOR_FRAME_DURATION
+     * @see CaptureRequest#SENSOR_SENSITIVITY
      * @see CaptureRequest#FLASH_MODE
      * @see CameraCharacteristics#FLASH_INFO_AVAILABLE
      * @see CaptureRequest#CONTROL_MODE
      * @see CaptureRequest#SENSOR_EXPOSURE_TIME
-     * @see CaptureRequest#SENSOR_FRAME_DURATION
-     * @see CaptureRequest#SENSOR_SENSITIVITY
      * @see #CONTROL_AE_MODE_OFF
      * @see #CONTROL_AE_MODE_ON
      * @see #CONTROL_AE_MODE_ON_AUTO_FLASH
@@ -592,10 +592,23 @@ public final class CaptureRequest extends CameraMetadata implements Parcelable {
      * <p>Whether AWB is currently setting the color
      * transform fields, and what its illumination target
      * is</p>
-     * <p>[BC - AWB lock,AWB modes]</p>
-     * <p>Only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} = AUTO.</p>
+     * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is AUTO.</p>
+     * <p>When set to the ON mode, the camera device's auto white balance
+     * routine is enabled, overriding the application's selected
+     * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} and
+     * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.</p>
+     * <p>When set to the OFF mode, the camera device's auto white balance
+     * routine is disabled. The applicantion manually controls the white
+     * balance by {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, android.colorCorrection.gains
+     * and {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.</p>
+     * <p>When set to any other modes, the camera device's auto white balance
+     * routine is disabled. The camera device uses each particular illumination
+     * target for white balance adjustment.</p>
      *
      * @see CaptureRequest#CONTROL_MODE
+     * @see CaptureRequest#COLOR_CORRECTION_MODE
+     * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
+     * @see CaptureRequest#COLOR_CORRECTION_GAINS
      * @see #CONTROL_AWB_MODE_OFF
      * @see #CONTROL_AWB_MODE_AUTO
      * @see #CONTROL_AWB_MODE_INCANDESCENT
@@ -826,10 +839,10 @@ public final class CaptureRequest extends CameraMetadata implements Parcelable {
      * auto-exposure algorithm, the overridden values are then provided
      * back to the user in the corresponding result.</p>
      *
-     * @see CaptureRequest#CONTROL_AE_MODE
-     * @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
-     * @see CaptureRequest#SENSOR_SENSITIVITY
      * @see CaptureRequest#SENSOR_EXPOSURE_TIME
+     * @see CaptureRequest#SENSOR_SENSITIVITY
+     * @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
+     * @see CaptureRequest#CONTROL_AE_MODE
      */
     public static final Key<Float> LENS_APERTURE =
             new Key<Float>("android.lens.aperture", float.class);
diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java
index 8e5af6d31c22..3600fffd1c3a 100644
--- a/core/java/android/hardware/camera2/CaptureResult.java
+++ b/core/java/android/hardware/camera2/CaptureResult.java
@@ -195,12 +195,12 @@ public final class CaptureResult extends CameraMetadata {
      * fields for a given capture will be available in its
      * CaptureResult.</p>
      *
+     * @see CaptureRequest#SENSOR_FRAME_DURATION
+     * @see CaptureRequest#SENSOR_SENSITIVITY
      * @see CaptureRequest#FLASH_MODE
      * @see CameraCharacteristics#FLASH_INFO_AVAILABLE
      * @see CaptureRequest#CONTROL_MODE
      * @see CaptureRequest#SENSOR_EXPOSURE_TIME
-     * @see CaptureRequest#SENSOR_FRAME_DURATION
-     * @see CaptureRequest#SENSOR_SENSITIVITY
      * @see #CONTROL_AE_MODE_OFF
      * @see #CONTROL_AE_MODE_ON
      * @see #CONTROL_AE_MODE_ON_AUTO_FLASH
@@ -323,10 +323,23 @@ public final class CaptureResult extends CameraMetadata {
      * <p>Whether AWB is currently setting the color
      * transform fields, and what its illumination target
      * is</p>
-     * <p>[BC - AWB lock,AWB modes]</p>
-     * <p>Only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} = AUTO.</p>
+     * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is AUTO.</p>
+     * <p>When set to the ON mode, the camera device's auto white balance
+     * routine is enabled, overriding the application's selected
+     * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} and
+     * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.</p>
+     * <p>When set to the OFF mode, the camera device's auto white balance
+     * routine is disabled. The applicantion manually controls the white
+     * balance by {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, android.colorCorrection.gains
+     * and {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.</p>
+     * <p>When set to any other modes, the camera device's auto white balance
+     * routine is disabled. The camera device uses each particular illumination
+     * target for white balance adjustment.</p>
      *
      * @see CaptureRequest#CONTROL_MODE
+     * @see CaptureRequest#COLOR_CORRECTION_MODE
+     * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
+     * @see CaptureRequest#COLOR_CORRECTION_GAINS
      * @see #CONTROL_AWB_MODE_OFF
      * @see #CONTROL_AWB_MODE_AUTO
      * @see #CONTROL_AWB_MODE_INCANDESCENT
@@ -508,10 +521,10 @@ public final class CaptureResult extends CameraMetadata {
      * auto-exposure algorithm, the overridden values are then provided
      * back to the user in the corresponding result.</p>
      *
-     * @see CaptureRequest#CONTROL_AE_MODE
-     * @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
-     * @see CaptureRequest#SENSOR_SENSITIVITY
      * @see CaptureRequest#SENSOR_EXPOSURE_TIME
+     * @see CaptureRequest#SENSOR_SENSITIVITY
+     * @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
+     * @see CaptureRequest#CONTROL_AE_MODE
      */
     public static final Key<Float> LENS_APERTURE =
             new Key<Float>("android.lens.aperture", float.class);