Camera2: Update awbMode related javadoc spec
Change-Id: I999d2bc94834c6f6d4483493707f05c92d7c5d67
diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java
index d5476fc..0ef64d1 100644
--- a/core/java/android/hardware/camera2/CameraCharacteristics.java
+++ b/core/java/android/hardware/camera2/CameraCharacteristics.java
@@ -219,6 +219,22 @@
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 64d055f..ef3e600 100644
--- a/core/java/android/hardware/camera2/CameraMetadata.java
+++ b/core/java/android/hardware/camera2/CameraMetadata.java
@@ -351,8 +351,8 @@
* {@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 @@
* {@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 @@
//
/**
+ * <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 d642076..dd17e9d 100644
--- a/core/java/android/hardware/camera2/CaptureRequest.java
+++ b/core/java/android/hardware/camera2/CaptureRequest.java
@@ -399,10 +399,10 @@
* 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 @@
* 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 @@
* <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 @@
* 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 8e5af6d..3600fff 100644
--- a/core/java/android/hardware/camera2/CaptureResult.java
+++ b/core/java/android/hardware/camera2/CaptureResult.java
@@ -195,12 +195,12 @@
* 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 @@
* <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 @@
* 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);