am ef773e35: Merge changes Id09663d8,Ie88f3750 into lmp-dev
* commit 'ef773e3569969592fb220b7ccc49dafcabfdd67a':
Camera2: Docs cleanup, especially units and range
camera2: Update docs only for legacy devices
diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java
index 55ca486..fb3eaff 100644
--- a/core/java/android/hardware/camera2/CameraCharacteristics.java
+++ b/core/java/android/hardware/camera2/CameraCharacteristics.java
@@ -310,14 +310,18 @@
* modify the comment blocks at the start or end.
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/
-
/**
- * <p>The set of aberration correction modes supported by this camera device.</p>
- * <p>This metadata lists the valid modes for {@link CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE android.colorCorrection.aberrationMode}.
- * If no aberration correction modes are available for a device, this list will solely include
+ * <p>List of aberration correction modes for {@link CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE android.colorCorrection.aberrationMode} that are
+ * supported by this camera device.</p>
+ * <p>This key lists the valid modes for {@link CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE android.colorCorrection.aberrationMode}. If no
+ * aberration correction modes are available for a device, this list will solely include
* OFF mode.</p>
- * <p>For FULL capability device ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} <code>==</code> FULL), OFF must be
- * included.</p>
+ * <p>For FULL capability device ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} <code>==</code> FULL), OFF is
+ * always included.</p>
+ * <p>LEGACY devices will always only support FAST mode.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE android.colorCorrection.aberrationMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
@@ -327,30 +331,42 @@
new Key<int[]>("android.colorCorrection.availableAberrationModes", int[].class);
/**
- * <p>The set of auto-exposure antibanding modes that are
+ * <p>List of auto-exposure antibanding modes for {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} that are
* supported by this camera device.</p>
* <p>Not all of the auto-exposure anti-banding modes may be
* supported by a given camera device. This field lists the
* valid anti-banding modes that the application may request
- * for this camera device; they must include AUTO.</p>
+ * for this camera device with the
+ * {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} control. This list
+ * always includes AUTO.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode}</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#CONTROL_AE_ANTIBANDING_MODE
*/
@PublicKey
public static final Key<int[]> CONTROL_AE_AVAILABLE_ANTIBANDING_MODES =
new Key<int[]>("android.control.aeAvailableAntibandingModes", int[].class);
/**
- * <p>The set of auto-exposure modes that are supported by this
- * camera device.</p>
+ * <p>List of auto-exposure modes for {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} that are supported by this camera
+ * device.</p>
* <p>Not all the auto-exposure modes may be supported by a
* given camera device, especially if no flash unit is
* available. This entry lists the valid modes for
* {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} for this camera device.</p>
- * <p>All camera devices support ON, and all camera devices with
- * flash units support ON_AUTO_FLASH and
- * ON_ALWAYS_FLASH.</p>
+ * <p>All camera devices support ON, and all camera devices with flash
+ * units support ON_AUTO_FLASH and ON_ALWAYS_FLASH.</p>
* <p>FULL mode camera devices always support OFF mode,
* which enables application control of camera exposure time,
* sensitivity, and frame duration.</p>
+ * <p>LEGACY mode camera devices never support OFF mode.
+ * LIMITED mode devices support OFF if they support the MANUAL_SENSOR
+ * capability.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
*/
@@ -359,43 +375,70 @@
new Key<int[]>("android.control.aeAvailableModes", int[].class);
/**
- * <p>List of frame rate ranges supported by the
- * auto-exposure (AE) algorithm/hardware</p>
+ * <p>List of frame rate ranges for {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE android.control.aeTargetFpsRange} supported by
+ * this camera device.</p>
+ * <p>For devices at the LIMITED level or above, this list will include at least (30, 30) for
+ * constant-framerate recording.</p>
+ * <p><b>Units</b>: Frames per second (FPS)</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE
*/
@PublicKey
public static final Key<android.util.Range<Integer>[]> CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES =
new Key<android.util.Range<Integer>[]>("android.control.aeAvailableTargetFpsRanges", new TypeReference<android.util.Range<Integer>[]>() {{ }});
/**
- * <p>Maximum and minimum exposure compensation
- * setting, in counts of
- * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep}.</p>
+ * <p>Maximum and minimum exposure compensation values for
+ * {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation}, in counts of {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep},
+ * that are supported by this camera device.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p><code>Min.exposure compensation * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep} <= -2 EV</code></p>
+ * <p><code>Max.exposure compensation * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep} >= 2 EV</code></p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP
+ * @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION
*/
@PublicKey
public static final Key<android.util.Range<Integer>> CONTROL_AE_COMPENSATION_RANGE =
new Key<android.util.Range<Integer>>("android.control.aeCompensationRange", new TypeReference<android.util.Range<Integer>>() {{ }});
/**
- * <p>Smallest step by which exposure compensation
- * can be changed</p>
+ * <p>Smallest step by which the exposure compensation
+ * can be changed.</p>
+ * <p>This is the unit for {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation}. For example, if this key has
+ * a value of <code>1/2</code>, then a setting of <code>-2</code> for {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation} means
+ * that the target EV offset for the auto-exposure routine is -1 EV.</p>
+ * <p>One unit of EV compensation changes the brightness of the captured image by a factor
+ * of two. +1 EV doubles the image brightness, while -1 EV halves the image brightness.</p>
+ * <p><b>Units</b>: Exposure Value (EV)</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION
*/
@PublicKey
public static final Key<Rational> CONTROL_AE_COMPENSATION_STEP =
new Key<Rational>("android.control.aeCompensationStep", Rational.class);
/**
- * <p>List of auto-focus (AF) modes that can be
- * selected with {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}.</p>
+ * <p>List of auto-focus (AF) modes for {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} that are
+ * supported by this camera device.</p>
* <p>Not all the auto-focus modes may be supported by a
* given camera device. This entry lists the valid modes for
* {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} for this camera device.</p>
* <p>All LIMITED and FULL mode camera devices will support OFF mode, and all
* camera devices with adjustable focuser units
* (<code>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} > 0</code>) will support AUTO mode.</p>
+ * <p>LEGACY devices will support OFF mode only if they support
+ * focusing to infinity (by also setting {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} to
+ * <code>0.0f</code>).</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AF_MODE
+ * @see CaptureRequest#LENS_FOCUS_DISTANCE
* @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
*/
@PublicKey
@@ -403,17 +446,20 @@
new Key<int[]>("android.control.afAvailableModes", int[].class);
/**
- * <p>List containing the subset of color effects
- * specified in {@link CaptureRequest#CONTROL_EFFECT_MODE android.control.effectMode} that is supported by
- * this device.</p>
+ * <p>List of color effects for {@link CaptureRequest#CONTROL_EFFECT_MODE android.control.effectMode} that are supported by this camera
+ * device.</p>
* <p>This list contains the color effect modes that can be applied to
- * images produced by the camera device. Only modes that have
- * been fully implemented for the current device may be included here.
+ * images produced by the camera device.
* Implementations are not expected to be consistent across all devices.
- * If no color effect modes are available for a device, this should
- * simply be set to OFF.</p>
+ * If no color effect modes are available for a device, this will only list
+ * OFF.</p>
* <p>A color effect will only be applied if
- * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.</p>
+ * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF. OFF is always included in this list.</p>
+ * <p>This control has no effect on the operation of other control routines such
+ * as auto-exposure, white balance, or focus.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_EFFECT_MODE android.control.effectMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_EFFECT_MODE
* @see CaptureRequest#CONTROL_MODE
@@ -423,38 +469,56 @@
new Key<int[]>("android.control.availableEffects", int[].class);
/**
- * <p>List containing a subset of scene modes
- * specified in {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode}.</p>
+ * <p>List of scene modes for {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} that are supported by this camera
+ * device.</p>
* <p>This list contains scene modes that can be set for the camera device.
* Only scene modes that have been fully implemented for the
* camera device may be included here. Implementations are not expected
- * to be consistent across all devices. If no scene modes are supported
- * by the camera device, this will be set to <code>[DISABLED]</code>.</p>
+ * to be consistent across all devices.</p>
+ * <p>If no scene modes are supported by the camera device, this
+ * will be set to DISABLED. Otherwise DISABLED will not be listed.</p>
+ * <p>FACE_PRIORITY is always listed if face detection is
+ * supported (i.e.<code>{@link CameraCharacteristics#STATISTICS_INFO_MAX_FACE_COUNT android.statistics.info.maxFaceCount} >
+ * 0</code>).</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_SCENE_MODE
+ * @see CameraCharacteristics#STATISTICS_INFO_MAX_FACE_COUNT
*/
@PublicKey
public static final Key<int[]> CONTROL_AVAILABLE_SCENE_MODES =
new Key<int[]>("android.control.availableSceneModes", int[].class);
/**
- * <p>List of video stabilization modes that can
- * be supported</p>
+ * <p>List of video stabilization modes for {@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}
+ * that are supported by this camera device.</p>
+ * <p>OFF will always be listed.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE
*/
@PublicKey
public static final Key<int[]> CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES =
new Key<int[]>("android.control.availableVideoStabilizationModes", int[].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>
+ * <p>List of auto-white-balance modes for {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} that are supported by this
+ * camera device.</p>
* <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 mode 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>
+ * <p>Camera devices that support the MANUAL_POST_PROCESSING capability 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). This includes all FULL
+ * mode camera devices.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#COLOR_CORRECTION_GAINS
* @see CaptureRequest#COLOR_CORRECTION_MODE
@@ -471,6 +535,11 @@
* this corresponds to the the maximum number of elements in
* {@link CaptureRequest#CONTROL_AE_REGIONS android.control.aeRegions}, {@link CaptureRequest#CONTROL_AWB_REGIONS android.control.awbRegions},
* and {@link CaptureRequest#CONTROL_AF_REGIONS android.control.afRegions}.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>Value must be >= 0 for each element. For full-capability devices
+ * this value must be >= 1 for AE and AF. The order of the elements is:
+ * <code>(AE, AWB, AF)</code>.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_REGIONS
* @see CaptureRequest#CONTROL_AF_REGIONS
@@ -481,10 +550,14 @@
new Key<int[]>("android.control.maxRegions", int[].class);
/**
- * <p>List of the maximum number of regions that can be used for metering in
- * auto-exposure (AE);
- * this corresponds to the the maximum number of elements in
+ * <p>The maximum number of metering regions that can be used by the auto-exposure (AE)
+ * routine.</p>
+ * <p>This corresponds to the the maximum allowed number of elements in
* {@link CaptureRequest#CONTROL_AE_REGIONS android.control.aeRegions}.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Value will be >= 0. For FULL-capability devices, this
+ * value will be >= 1.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_REGIONS
*/
@@ -494,10 +567,13 @@
new Key<Integer>("android.control.maxRegionsAe", int.class);
/**
- * <p>List of the maximum number of regions that can be used for metering in
- * auto-white balance (AWB);
- * this corresponds to the the maximum number of elements in
+ * <p>The maximum number of metering regions that can be used by the auto-white balance (AWB)
+ * routine.</p>
+ * <p>This corresponds to the the maximum allowed number of elements in
* {@link CaptureRequest#CONTROL_AWB_REGIONS android.control.awbRegions}.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Value will be >= 0.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AWB_REGIONS
*/
@@ -507,10 +583,13 @@
new Key<Integer>("android.control.maxRegionsAwb", int.class);
/**
- * <p>List of the maximum number of regions that can be used for metering in
- * auto-focus (AF);
- * this corresponds to the the maximum number of elements in
+ * <p>The maximum number of metering regions that can be used by the auto-focus (AF) routine.</p>
+ * <p>This corresponds to the the maximum allowed number of elements in
* {@link CaptureRequest#CONTROL_AF_REGIONS android.control.afRegions}.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Value will be >= 0. For FULL-capability devices, this
+ * value will be >= 1.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AF_REGIONS
*/
@@ -541,20 +620,34 @@
* {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} to HIGH_SPEED_VIDEO in capture requests, the fps ranges
* reported in this metadata must not be used to setup capture requests, or it will cause
* request error.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>For each configuration, the fps_max >= 60fps.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES
* @see CaptureRequest#CONTROL_SCENE_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<android.hardware.camera2.params.HighSpeedVideoConfiguration[]> CONTROL_AVAILABLE_HIGH_SPEED_VIDEO_CONFIGURATIONS =
new Key<android.hardware.camera2.params.HighSpeedVideoConfiguration[]>("android.control.availableHighSpeedVideoConfigurations", android.hardware.camera2.params.HighSpeedVideoConfiguration[].class);
/**
- * <p>The set of edge enhancement modes supported by this camera device.</p>
- * <p>This tag lists the valid modes for {@link CaptureRequest#EDGE_MODE android.edge.mode}.</p>
- * <p>Full-capability camera devices must always support OFF and FAST.</p>
+ * <p>List of edge enhancement modes for {@link CaptureRequest#EDGE_MODE android.edge.mode} that are supported by this camera
+ * device.</p>
+ * <p>Full-capability camera devices must always support OFF; all devices will list FAST.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#EDGE_MODE android.edge.mode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#EDGE_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<int[]> EDGE_AVAILABLE_EDGE_MODES =
@@ -562,19 +655,23 @@
/**
* <p>Whether this camera device has a
- * flash.</p>
- * <p>If no flash, none of the flash controls do
- * anything. All other metadata should return 0.</p>
+ * flash unit.</p>
+ * <p>Will be <code>false</code> if no flash is available.</p>
+ * <p>If there is no flash unit, none of the flash controls do
+ * anything.
+ * This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Boolean> FLASH_INFO_AVAILABLE =
new Key<Boolean>("android.flash.info.available", boolean.class);
/**
- * <p>The set of hot pixel correction modes that are supported by this
+ * <p>List of hot pixel correction modes for {@link CaptureRequest#HOT_PIXEL_MODE android.hotPixel.mode} that are supported by this
* camera device.</p>
- * <p>This tag lists valid modes for {@link CaptureRequest#HOT_PIXEL_MODE android.hotPixel.mode}.</p>
* <p>FULL mode camera devices will always support FAST.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#HOT_PIXEL_MODE android.hotPixel.mode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CaptureRequest#HOT_PIXEL_MODE
*/
@@ -583,7 +680,10 @@
new Key<int[]>("android.hotPixel.availableHotPixelModes", int[].class);
/**
- * <p>Supported resolutions for the JPEG thumbnail.</p>
+ * <p>List of JPEG thumbnail sizes for {@link CaptureRequest#JPEG_THUMBNAIL_SIZE android.jpeg.thumbnailSize} supported by this
+ * camera device.</p>
+ * <p>This list will include at least one non-zero resolution, plus <code>(0,0)</code> for indicating no
+ * thumbnail should be generated.</p>
* <p>Below condiditions will be satisfied for this size list:</p>
* <ul>
* <li>The sizes will be sorted by increasing pixel area (width x height).
@@ -595,33 +695,51 @@
* <li>Each output JPEG size in android.scaler.availableStreamConfigurations will have at least
* one corresponding size that has the same aspect ratio in availableThumbnailSizes,
* and vice versa.</li>
- * <li>All non (0, 0) sizes will have non-zero widths and heights.</li>
+ * <li>All non-<code>(0, 0)</code> sizes will have non-zero widths and heights.
+ * This key is available on all devices.</li>
* </ul>
+ *
+ * @see CaptureRequest#JPEG_THUMBNAIL_SIZE
*/
@PublicKey
public static final Key<android.util.Size[]> JPEG_AVAILABLE_THUMBNAIL_SIZES =
new Key<android.util.Size[]>("android.jpeg.availableThumbnailSizes", android.util.Size[].class);
/**
- * <p>List of supported aperture
- * values.</p>
- * <p>If the camera device doesn't support variable apertures,
- * listed value will be the fixed aperture.</p>
- * <p>If the camera device supports variable apertures, the aperture value
+ * <p>List of aperture size values for {@link CaptureRequest#LENS_APERTURE android.lens.aperture} that are
+ * supported by this camera device.</p>
+ * <p>If the camera device doesn't support a variable lens aperture,
+ * this list will contain only one value, which is the fixed aperture size.</p>
+ * <p>If the camera device supports a variable aperture, the aperture values
* in this list will be sorted in ascending order.</p>
+ * <p><b>Units</b>: The aperture f-number</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CaptureRequest#LENS_APERTURE
*/
@PublicKey
public static final Key<float[]> LENS_INFO_AVAILABLE_APERTURES =
new Key<float[]>("android.lens.info.availableApertures", float[].class);
/**
- * <p>List of supported neutral density filter values for
- * {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity}.</p>
- * <p>If changing {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity} is not supported,
- * availableFilterDensities must contain only 0. Otherwise, this
- * list contains only the exact filter density values available on
- * this camera device.</p>
+ * <p>List of neutral density filter values for
+ * {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity} that are supported by this camera device.</p>
+ * <p>If a neutral density filter is not supported by this camera device,
+ * this list will contain only 0. Otherwise, this list will include every
+ * filter density supported by the camera device, in ascending order.</p>
+ * <p><b>Units</b>: Exposure value (EV)</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>Values are >= 0</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#LENS_FILTER_DENSITY
*/
@PublicKey
@@ -629,12 +747,16 @@
new Key<float[]>("android.lens.info.availableFilterDensities", float[].class);
/**
- * <p>The available focal lengths for this device for use with
- * {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}.</p>
- * <p>If optical zoom is not supported, this will only report
- * a single value corresponding to the static focal length of the
- * device. Otherwise, this will report every focal length supported
- * by the device.</p>
+ * <p>List of focal lengths for {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength} that are supported by this camera
+ * device.</p>
+ * <p>If optical zoom is not supported, this list will only contain
+ * a single value corresponding to the fixed focal length of the
+ * device. Otherwise, this list will include every focal length supported
+ * by the camera device, in ascending order.</p>
+ * <p><b>Units</b>: Millimeters</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>Values are > 0</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#LENS_FOCAL_LENGTH
*/
@@ -643,12 +765,18 @@
new Key<float[]>("android.lens.info.availableFocalLengths", float[].class);
/**
- * <p>List containing a subset of the optical image
- * stabilization (OIS) modes specified in
- * {@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}.</p>
- * <p>If OIS is not implemented for a given camera device, this will
+ * <p>List of optical image stabilization (OIS) modes for
+ * {@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode} that are supported by this camera device.</p>
+ * <p>If OIS is not supported by a given camera device, this list will
* contain only OFF.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE
*/
@PublicKey
@@ -656,12 +784,21 @@
new Key<int[]>("android.lens.info.availableOpticalStabilization", int[].class);
/**
- * <p>Optional. Hyperfocal distance for this lens.</p>
+ * <p>Hyperfocal distance for this lens.</p>
* <p>If the lens is not fixed focus, the camera device will report this
* field when {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} is APPROXIMATE or CALIBRATED.</p>
+ * <p><b>Units</b>: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details</p>
+ * <p><b>Range of valid values:</b><br>
+ * If lens is fixed focus, >= 0. If lens has focuser unit, the value is
+ * within <code>(0.0f, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}]</code></p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
+ * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
*/
@PublicKey
public static final Key<Float> LENS_INFO_HYPERFOCAL_DISTANCE =
@@ -669,10 +806,19 @@
/**
* <p>Shortest distance from frontmost surface
- * of the lens that can be focused correctly.</p>
- * <p>If the lens is fixed-focus, this should be
+ * of the lens that can be brought into sharp focus.</p>
+ * <p>If the lens is fixed-focus, this will be
* 0.</p>
+ * <p><b>Units</b>: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 0</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
*/
@PublicKey
public static final Key<Float> LENS_INFO_MINIMUM_FOCUS_DISTANCE =
@@ -682,6 +828,14 @@
* <p>Dimensions of lens shading map.</p>
* <p>The map should be on the order of 30-40 rows and columns, and
* must be smaller than 64x64.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Both values >= 1</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<android.util.Size> LENS_INFO_SHADING_MAP_SIZE =
@@ -693,7 +847,27 @@
* focus related metadata entries, i.e. {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance},
* {@link CaptureResult#LENS_FOCUS_RANGE android.lens.focusRange}, {@link CameraCharacteristics#LENS_INFO_HYPERFOCAL_DISTANCE android.lens.info.hyperfocalDistance}, and
* {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}.</p>
+ * <p>APPROXIMATE and CALIBRATED devices report the focus metadata in
+ * units of diopters (1/meter), so <code>0.0f</code> represents focusing at infinity,
+ * and increasing positive numbers represent focusing closer and closer
+ * to the camera device. The focus distance control also uses diopters
+ * on these devices.</p>
+ * <p>UNCALIBRATED devices do not use units that are directly comparable
+ * to any real physical measurement, but <code>0.0f</code> still represents farthest
+ * focus, and {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} represents the
+ * nearest focus the device can achieve.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LENS_INFO_FOCUS_DISTANCE_CALIBRATION_UNCALIBRATED UNCALIBRATED}</li>
+ * <li>{@link #LENS_INFO_FOCUS_DISTANCE_CALIBRATION_APPROXIMATE APPROXIMATE}</li>
+ * <li>{@link #LENS_INFO_FOCUS_DISTANCE_CALIBRATION_CALIBRATED CALIBRATED}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#LENS_FOCUS_DISTANCE
* @see CaptureResult#LENS_FOCUS_RANGE
* @see CameraCharacteristics#LENS_INFO_HYPERFOCAL_DISTANCE
@@ -709,6 +883,12 @@
/**
* <p>Direction the camera faces relative to
* device screen.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LENS_FACING_FRONT FRONT}</li>
+ * <li>{@link #LENS_FACING_BACK BACK}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
* @see #LENS_FACING_FRONT
* @see #LENS_FACING_BACK
*/
@@ -717,10 +897,18 @@
new Key<Integer>("android.lens.facing", int.class);
/**
- * <p>The set of noise reduction modes supported by this camera device.</p>
- * <p>This tag lists the valid modes for {@link CaptureRequest#NOISE_REDUCTION_MODE android.noiseReduction.mode}.</p>
- * <p>Full-capability camera devices must always support OFF and FAST.</p>
+ * <p>List of noise reduction modes for {@link CaptureRequest#NOISE_REDUCTION_MODE android.noiseReduction.mode} that are supported
+ * by this camera device.</p>
+ * <p>Full-capability camera devices will always support OFF and FAST.</p>
+ * <p>Legacy-capability camera devices will only support FAST mode.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#NOISE_REDUCTION_MODE android.noiseReduction.mode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#NOISE_REDUCTION_MODE
*/
@PublicKey
@@ -765,6 +953,15 @@
* <li>Processed (but not-stalling): any non-RAW format without a stall duration.
* Typically ImageFormat#YUV_420_888, ImageFormat#NV21, ImageFormat#YV12.</li>
* </ul>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>For processed (and stalling) format streams, >= 1.</p>
+ * <p>For Raw format (either stalling or non-stalling) streams, >= 0.</p>
+ * <p>For processed (but not stalling) format streams, >= 3
+ * for FULL mode devices (<code>{@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL</code>);
+ * >= 2 for LIMITED mode devices (<code>{@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == LIMITED</code>).</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<int[]> REQUEST_MAX_NUM_OUTPUT_STREAMS =
@@ -786,7 +983,13 @@
* <li>ImageFormat#RAW10</li>
* <li>Opaque <code>RAW</code></li>
* </ul>
+ * <p>LEGACY mode devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} <code>==</code> LEGACY)
+ * never support raw streams.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>>= 0</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
*/
@PublicKey
@@ -814,7 +1017,14 @@
* </ul>
* <p>For full guarantees, query StreamConfigurationMap#getOutputStallDuration with
* a processed format -- it will return 0 for a non-stalling stream.</p>
+ * <p>LEGACY devices will support at least 2 processing/non-stalling streams.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>>= 3
+ * for FULL mode devices (<code>{@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL</code>);
+ * >= 2 for LIMITED mode devices (<code>{@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == LIMITED</code>).</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
*/
@PublicKey
@@ -833,9 +1043,13 @@
* CPU resources that will consume more power. The image format for this kind of an output stream can
* be any non-<code>RAW</code> and supported format provided by {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}.</p>
* <p>A processed and stalling format is defined as any non-RAW format with a stallDurations > 0.
- * Typically only the <code>JPEG</code> format (ImageFormat#JPEG)</p>
+ * Typically only the <code>JPEG</code> format (ImageFormat#JPEG) is a stalling format.</p>
* <p>For full guarantees, query StreamConfigurationMap#getOutputStallDuration with
* a processed format -- it will return a non-0 value for a stalling stream.</p>
+ * <p>LEGACY devices will support up to 1 processing/stalling stream.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>>= 1</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
*/
@@ -856,6 +1070,14 @@
* <p>For example, for Zero Shutter Lag (ZSL) still capture use case, the input
* stream image format will be RAW_OPAQUE, the associated output stream image format
* should be JPEG.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>0 or 1.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<Integer> REQUEST_MAX_NUM_INPUT_STREAMS =
@@ -876,6 +1098,7 @@
* <p>A pipeline depth of X stages is equivalent to a pipeline latency of
* X frame intervals.</p>
* <p>This value will be 8 or less.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureResult#REQUEST_PIPELINE_DEPTH
*/
@@ -898,6 +1121,8 @@
* then immediately dispatch this state via a partial result to
* the application, and the rest of the metadata via later
* partial results.</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 1</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*/
@PublicKey
@@ -905,7 +1130,7 @@
new Key<Integer>("android.request.partialResultCount", int.class);
/**
- * <p>List of capabilities that the camera device
+ * <p>List of capabilities that this camera device
* advertises as fully supporting.</p>
* <p>A capability is a contract that the camera device makes in order
* to be able to satisfy one or more use cases.</p>
@@ -923,7 +1148,15 @@
* <li>MANUAL_POST_PROCESSING</li>
* </ul>
* <p>Other capabilities may be available on either FULL or LIMITED
- * devices, but the application should query this field to be sure.</p>
+ * devices, but the application should query this key to be sure.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE BACKWARD_COMPATIBLE}</li>
+ * <li>{@link #REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR MANUAL_SENSOR}</li>
+ * <li>{@link #REQUEST_AVAILABLE_CAPABILITIES_MANUAL_POST_PROCESSING MANUAL_POST_PROCESSING}</li>
+ * <li>{@link #REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE
@@ -945,6 +1178,7 @@
* at a more granular level than capabilities. This is especially
* important for optional keys that are not listed under any capability
* in {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
* @hide
@@ -957,18 +1191,19 @@
* to use with CaptureResult.</p>
* <p>Attempting to get a key from a CaptureResult that is not
* listed here will always return a <code>null</code> value. Getting a key from
- * a CaptureResult that is listed here must never return a <code>null</code>
+ * a CaptureResult that is listed here will generally never return a <code>null</code>
* value.</p>
* <p>The following keys may return <code>null</code> unless they are enabled:</p>
* <ul>
* <li>android.statistics.lensShadingMap (non-null iff {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON)</li>
* </ul>
- * <p>(Those sometimes-null keys should nevertheless be listed here
+ * <p>(Those sometimes-null keys will nevertheless be listed here
* if they are available.)</p>
* <p>This field can be used to query the feature set of a camera device
* at a more granular level than capabilities. This is especially
* important for optional keys that are not listed under any capability
* in {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
* @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE
@@ -984,6 +1219,7 @@
* android.request.availableResultKeys (except that it applies for
* CameraCharacteristics instead of CaptureResult). See above for more
* details.</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<int[]> REQUEST_AVAILABLE_CHARACTERISTICS_KEYS =
@@ -994,6 +1230,7 @@
* camera device for output streams.</p>
* <p>All camera devices will support JPEG and YUV_420_888 formats.</p>
* <p>When set to YUV_420_888, application can access the YUV420 data directly.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
*/
@@ -1010,6 +1247,10 @@
* <p>When multiple streams are configured, the minimum
* frame duration will be >= max(individual stream min
* durations)</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * TODO: Remove property.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
*/
@@ -1021,6 +1262,9 @@
* <p>The JPEG resolutions that are supported by this camera device.</p>
* <p>The resolutions are listed as <code>(width, height)</code> pairs. All camera devices will support
* sensor maximum resolution (defined by {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}).</p>
+ * <p><b>Range of valid values:</b><br>
+ * TODO: Remove property.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
* @deprecated
@@ -1033,13 +1277,19 @@
/**
* <p>The maximum ratio between both active area width
* and crop region width, and active area height and
- * crop region height.</p>
+ * crop region height, for {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}.</p>
* <p>This represents the maximum amount of zooming possible by
* the camera device, or equivalently, the minimum cropping
* window size.</p>
* <p>Crop regions that have a width or height that is smaller
* than this ratio allows will be rounded up to the minimum
* allowed size by the camera device.</p>
+ * <p><b>Units</b>: Zoom scale factor</p>
+ * <p><b>Range of valid values:</b><br>
+ * >=1</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#SCALER_CROP_REGION
*/
@PublicKey
public static final Key<Float> SCALER_AVAILABLE_MAX_DIGITAL_ZOOM =
@@ -1054,6 +1304,8 @@
* set to FAST.</p>
* <p>When multiple streams are configured, the minimum frame duration will
* be >= max(individual stream min durations).</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
*/
@@ -1075,6 +1327,7 @@
* can provide.</p>
* <p>Please reference the documentation for the image data destination to
* check if it limits the maximum size for image data.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
*/
@@ -1133,6 +1386,12 @@
* <p>Attempting to configure an input stream with output streams not
* listed as available in this map is not valid.</p>
* <p>TODO: typedef to ReprocessFormatMap</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<int[]> SCALER_AVAILABLE_INPUT_OUTPUT_FORMATS_MAP =
@@ -1220,6 +1479,7 @@
* </table>
* <p>Refer to {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} for additional
* mandatory stream configurations on a per-capability basis.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
@@ -1244,6 +1504,8 @@
* calculating the max frame rate.</p>
* <p>(Keep in sync with
* StreamConfigurationMap#getOutputMinFrameDuration)</p>
+ * <p><b>Units</b>: (format, width, height, ns) x n</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#SENSOR_FRAME_DURATION
* @hide
@@ -1309,6 +1571,8 @@
* calculating the max frame rate (absent stalls).</p>
* <p>(Keep up to date with
* StreamConfigurationMap#getOutputStallDuration(int, Size) )</p>
+ * <p><b>Units</b>: (format, width, height, ns) x n</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
* @see CaptureRequest#SENSOR_FRAME_DURATION
@@ -1396,6 +1660,7 @@
* </table>
* <p>Refer to {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} for additional
* mandatory stream configurations on a per-capability basis.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
@@ -1417,7 +1682,13 @@
* is inside of the active array. The camera device will apply the same crop region and
* return the final used crop region in capture result metadata {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}.</p>
* <p>FULL capability devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} <code>==</code> FULL) will support
- * FREEFORM cropping.</p>
+ * FREEFORM cropping. LEGACY capability devices will only support CENTER_ONLY cropping.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SCALER_CROPPING_TYPE_CENTER_ONLY CENTER_ONLY}</li>
+ * <li>{@link #SCALER_CROPPING_TYPE_FREEFORM FREEFORM}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#SCALER_CROP_REGION
@@ -1430,22 +1701,41 @@
new Key<Integer>("android.scaler.croppingType", int.class);
/**
- * <p>Area of raw data which corresponds to only
+ * <p>The area of the image sensor which corresponds to
* active pixels.</p>
- * <p>It is smaller or equal to
- * sensor full pixel array, which could include the black calibration pixels.</p>
+ * <p>This is the region of the sensor that actually receives light from the scene.
+ * Therefore, the size of this region determines the maximum field of view and the maximum
+ * number of pixels that an image from this sensor can contain.</p>
+ * <p>The rectangle is defined in terms of the full pixel array; (0,0) is the top-left of the
+ * full pixel array, and the size of the full pixel array is given by
+ * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.</p>
+ * <p>Most other keys listing pixel coordinates have their coordinate systems based on the
+ * active array, with <code>(0, 0)</code> being the top-left of the active array rectangle.</p>
+ * <p>The active array may be smaller than the full pixel array, since the full array may
+ * include black calibration pixels or other inactive regions.</p>
+ * <p><b>Units</b>: Pixel coordinates on the image sensor</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE
*/
@PublicKey
public static final Key<android.graphics.Rect> SENSOR_INFO_ACTIVE_ARRAY_SIZE =
new Key<android.graphics.Rect>("android.sensor.info.activeArraySize", android.graphics.Rect.class);
/**
- * <p>Range of valid sensitivities.</p>
- * <p>The minimum and maximum valid values for the
- * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} control.</p>
+ * <p>Range of sensitivities for {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} supported by this
+ * camera device.</p>
* <p>The values are the standard ISO sensitivity values,
* as defined in ISO 12232:2006.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Min <= 100, Max >= 800</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#SENSOR_SENSITIVITY
*/
@PublicKey
@@ -1456,6 +1746,20 @@
* <p>The arrangement of color filters on sensor;
* represents the colors in the top-left 2x2 section of
* the sensor, in reading order.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGGB RGGB}</li>
+ * <li>{@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GRBG GRBG}</li>
+ * <li>{@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GBRG GBRG}</li>
+ * <li>{@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_BGGR BGGR}</li>
+ * <li>{@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGB RGB}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGGB
* @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GRBG
* @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GBRG
@@ -1467,11 +1771,17 @@
new Key<Integer>("android.sensor.info.colorFilterArrangement", int.class);
/**
- * <p>Range of valid exposure
- * times used by {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}.</p>
- * <p>The min value will be <= 100e3 (100 us). For FULL
+ * <p>The range of image exposure times for {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} supported
+ * by this camera device.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * The minimum exposure time will be less than 100 us. For FULL
* capability devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL),
- * max will be >= 100e6 (100ms)</p>
+ * the maximum exposure time will be greater than 100ms.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
@@ -1481,18 +1791,21 @@
new Key<android.util.Range<Long>>("android.sensor.info.exposureTimeRange", new TypeReference<android.util.Range<Long>>() {{ }});
/**
- * <p>Maximum possible frame duration (minimum frame
- * rate).</p>
- * <p>The largest possible {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}
- * that will be accepted by the camera device. Attempting to use
- * frame durations beyond the maximum will result in the frame duration
- * being clipped to the maximum. See that control
- * for a full definition of frame durations.</p>
- * <p>Refer to
- * StreamConfigurationMap#getOutputMinFrameDuration(int,Size)
- * for the minimum frame duration values.</p>
- * <p>For FULL capability devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL),
- * max will be >= 100e6 (100ms).</p>
+ * <p>The maximum possible frame duration (minimum frame rate) for
+ * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration} that is supported this camera device.</p>
+ * <p>Attempting to use frame durations beyond the maximum will result in the frame
+ * duration being clipped to the maximum. See that control for a full definition of frame
+ * durations.</p>
+ * <p>Refer to StreamConfigurationMap#getOutputMinFrameDuration(int,Size) for the minimum
+ * frame duration values.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * For FULL capability devices
+ * ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL), at least 100ms.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#SENSOR_FRAME_DURATION
@@ -1506,6 +1819,8 @@
* array.</p>
* <p>This is the physical size of the sensor pixel
* array defined by {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.</p>
+ * <p><b>Units</b>: Millimeters</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE
*/
@@ -1514,7 +1829,7 @@
new Key<android.util.SizeF>("android.sensor.info.physicalSize", android.util.SizeF.class);
/**
- * <p>Dimensions of full pixel array, possibly
+ * <p>Dimensions of the full pixel array, possibly
* including black calibration pixels.</p>
* <p>The pixel count of the full pixel array,
* which covers {@link CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE android.sensor.info.physicalSize} area.</p>
@@ -1523,6 +1838,11 @@
* raw size listed in {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}.
* If a size corresponding to pixelArraySize is listed, the resulting
* raw sensor image will include black pixels.</p>
+ * <p>Some parts of the full pixel array may not receive light from the scene,
+ * or are otherwise inactive. The {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} key
+ * defines the rectangle of active pixels that actually forms an image.</p>
+ * <p><b>Units</b>: Pixels</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
@@ -1538,11 +1858,14 @@
* sample values from the sensor. This is typically caused by the
* sensor becoming highly non-linear or clipping. The minimum for
* each channel is specified by the offset in the
- * {@link CameraCharacteristics#SENSOR_BLACK_LEVEL_PATTERN android.sensor.blackLevelPattern} tag.</p>
+ * {@link CameraCharacteristics#SENSOR_BLACK_LEVEL_PATTERN android.sensor.blackLevelPattern} key.</p>
* <p>The white level is typically determined either by sensor bit depth
* (8-14 bits is expected), or by the point where the sensor response
* becomes too non-linear to be useful. The default value for this is
* maximum representable value for a 16-bit raw sample (2^16 - 1).</p>
+ * <p><b>Range of valid values:</b><br>
+ * > 255 (8-bit output)</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_BLACK_LEVEL_PATTERN
*/
@@ -1556,6 +1879,12 @@
* may not based on a time source that can be compared to other system time sources.</p>
* <p>This characteristic defines the source for the timestamps, and therefore whether they
* can be compared against other system time sources/timestamps.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SENSOR_INFO_TIMESTAMP_SOURCE_UNKNOWN UNKNOWN}</li>
+ * <li>{@link #SENSOR_INFO_TIMESTAMP_SOURCE_REALTIME REALTIME}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
* @see #SENSOR_INFO_TIMESTAMP_SOURCE_UNKNOWN
* @see #SENSOR_INFO_TIMESTAMP_SOURCE_REALTIME
*/
@@ -1568,15 +1897,38 @@
* calculating the {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM1 android.sensor.colorTransform1},
* {@link CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM1 android.sensor.calibrationTransform1}, and
* {@link CameraCharacteristics#SENSOR_FORWARD_MATRIX1 android.sensor.forwardMatrix1} matrices.</p>
- * <p>The values in this tag correspond to the values defined for the
+ * <p>The values in this key correspond to the values defined for the
* EXIF LightSource tag. These illuminants are standard light sources
* that are often used calibrating camera devices.</p>
- * <p>If this tag is present, then {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM1 android.sensor.colorTransform1},
+ * <p>If this key is present, then {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM1 android.sensor.colorTransform1},
* {@link CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM1 android.sensor.calibrationTransform1}, and
* {@link CameraCharacteristics#SENSOR_FORWARD_MATRIX1 android.sensor.forwardMatrix1} will also be present.</p>
* <p>Some devices may choose to provide a second set of calibration
* information for improved quality, including
* {@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT2 android.sensor.referenceIlluminant2} and its corresponding matrices.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_DAYLIGHT DAYLIGHT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_FLUORESCENT FLUORESCENT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_TUNGSTEN TUNGSTEN}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_FLASH FLASH}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_FINE_WEATHER FINE_WEATHER}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_CLOUDY_WEATHER CLOUDY_WEATHER}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_SHADE SHADE}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_DAYLIGHT_FLUORESCENT DAYLIGHT_FLUORESCENT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_DAY_WHITE_FLUORESCENT DAY_WHITE_FLUORESCENT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_COOL_WHITE_FLUORESCENT COOL_WHITE_FLUORESCENT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_WHITE_FLUORESCENT WHITE_FLUORESCENT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_STANDARD_A STANDARD_A}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_STANDARD_B STANDARD_B}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_STANDARD_C STANDARD_C}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_D55 D55}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_D65 D65}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_D75 D75}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_D50 D50}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_ISO_STUDIO_TUNGSTEN ISO_STUDIO_TUNGSTEN}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM1
* @see CameraCharacteristics#SENSOR_COLOR_TRANSFORM1
@@ -1611,12 +1963,13 @@
* calculating the {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM2 android.sensor.colorTransform2},
* {@link CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM2 android.sensor.calibrationTransform2}, and
* {@link CameraCharacteristics#SENSOR_FORWARD_MATRIX2 android.sensor.forwardMatrix2} matrices.</p>
- * <p>See {@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT1 android.sensor.referenceIlluminant1} for more details.
- * Valid values for this are the same as those given for the first
- * reference illuminant.</p>
- * <p>If this tag is present, then {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM2 android.sensor.colorTransform2},
+ * <p>See {@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT1 android.sensor.referenceIlluminant1} for more details.</p>
+ * <p>If this key is present, then {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM2 android.sensor.colorTransform2},
* {@link CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM2 android.sensor.calibrationTransform2}, and
* {@link CameraCharacteristics#SENSOR_FORWARD_MATRIX2 android.sensor.forwardMatrix2} will also be present.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT1 android.sensor.referenceIlluminant1}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM2
* @see CameraCharacteristics#SENSOR_COLOR_TRANSFORM2
@@ -1763,13 +2116,15 @@
/**
* <p>A fixed black level offset for each of the color filter arrangement
* (CFA) mosaic channels.</p>
- * <p>This tag specifies the zero light value for each of the CFA mosaic
+ * <p>This key specifies the zero light value for each of the CFA mosaic
* channels in the camera sensor. The maximal value output by the
* sensor is represented by the value in {@link CameraCharacteristics#SENSOR_INFO_WHITE_LEVEL android.sensor.info.whiteLevel}.</p>
* <p>The values are given in the same order as channels listed for the CFA
- * layout tag (see {@link CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT android.sensor.info.colorFilterArrangement}), i.e. the
+ * layout key (see {@link CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT android.sensor.info.colorFilterArrangement}), i.e. the
* nth value given corresponds to the black level offset for the nth
* color channel listed in the CFA.</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 0 for each.</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
@@ -1799,19 +2154,26 @@
new Key<Integer>("android.sensor.maxAnalogSensitivity", int.class);
/**
- * <p>Clockwise angle through which the output
- * image needs to be rotated to be upright on the device
- * screen in its native orientation. Also defines the
- * direction of rolling shutter readout, which is from top
- * to bottom in the sensor's coordinate system</p>
+ * <p>Clockwise angle through which the output image needs to be rotated to be
+ * upright on the device screen in its native orientation.</p>
+ * <p>Also defines the direction of rolling shutter readout, which is from top to bottom in
+ * the sensor's coordinate system.</p>
+ * <p><b>Units</b>: Degrees of clockwise rotation; always a multiple of
+ * 90</p>
+ * <p><b>Range of valid values:</b><br>
+ * 0, 90, 180, 270</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Integer> SENSOR_ORIENTATION =
new Key<Integer>("android.sensor.orientation", int.class);
/**
- * <p>Lists the supported sensor test pattern modes for {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}.</p>
- * <p>Optional. Defaults to [OFF].</p>
+ * <p>List of sensor test pattern modes for {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}
+ * supported by this camera device.</p>
+ * <p>Defaults to OFF, and always includes OFF if defined.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CaptureRequest#SENSOR_TEST_PATTERN_MODE
@@ -1821,15 +2183,14 @@
new Key<int[]>("android.sensor.availableTestPatternModes", int[].class);
/**
- * <p>The face detection modes that are available
- * for this camera device.</p>
+ * <p>List of face detection modes for {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} that are
+ * supported by this camera device.</p>
* <p>OFF is always supported.</p>
- * <p>SIMPLE means the device supports the
- * android.statistics.faceRectangles and
- * android.statistics.faceScores outputs.</p>
- * <p>FULL means the device additionally supports the
- * android.statistics.faceIds and
- * android.statistics.faceLandmarks outputs.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode}</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
*/
@PublicKey
public static final Key<int[]> STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES =
@@ -1838,17 +2199,25 @@
/**
* <p>The maximum number of simultaneously detectable
* faces.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 0 for cameras without available face detection; otherwise:
+ * <code>>=4</code> for LIMITED or FULL hwlevel devices or
+ * <code>>0</code> for LEGACY devices.</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Integer> STATISTICS_INFO_MAX_FACE_COUNT =
new Key<Integer>("android.statistics.info.maxFaceCount", int.class);
/**
- * <p>The set of hot pixel map output modes supported by this camera device.</p>
- * <p>This tag lists valid output modes for {@link CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE android.statistics.hotPixelMapMode}.</p>
- * <p>If no hotpixel map is available for this camera device, this will contain
- * only OFF. If the hotpixel map is available, this will include both
- * the ON and OFF options.</p>
+ * <p>List of hot pixel map output modes for {@link CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE android.statistics.hotPixelMapMode} that are
+ * supported by this camera device.</p>
+ * <p>If no hotpixel map output is available for this camera device, this will contain only
+ * <code>false</code>.</p>
+ * <p>ON is always supported on devices with the RAW capability.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE android.statistics.hotPixelMapMode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE
*/
@@ -1859,14 +2228,18 @@
/**
* <p>Maximum number of supported points in the
* tonemap curve that can be used for {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}.</p>
- * <p>If the actual number of points provided by the application (in
- * {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}*) is less than max, the camera device will
- * resample the curve to its internal representation, using linear
- * interpolation.</p>
+ * <p>If the actual number of points provided by the application (in {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}*) is
+ * less than this maximum, the camera device will resample the curve to its internal
+ * representation, using linear interpolation.</p>
* <p>The output curves in the result metadata may have a different number
* of points than the input curves, and will represent the actual
* hardware curves used as closely as possible when linearly interpolated.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_CURVE
*/
@PublicKey
@@ -1874,11 +2247,18 @@
new Key<Integer>("android.tonemap.maxCurvePoints", int.class);
/**
- * <p>The set of tonemapping modes supported by this camera device.</p>
- * <p>This tag lists the valid modes for {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode}.</p>
- * <p>Full-capability camera devices must always support CONTRAST_CURVE and
- * FAST.</p>
+ * <p>List of tonemapping modes for {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} that are supported by this camera
+ * device.</p>
+ * <p>Camera devices that support the MANUAL_POST_PROCESSING capability will always list
+ * CONTRAST_CURVE and FAST. This includes all FULL level devices.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_MODE
*/
@PublicKey
@@ -1887,6 +2267,11 @@
/**
* <p>A list of camera LEDs that are available on this system.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LED_AVAILABLE_LEDS_TRANSMIT TRANSMIT}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @see #LED_AVAILABLE_LEDS_TRANSMIT
* @hide
*/
@@ -1895,8 +2280,8 @@
/**
* <p>Generally classifies the overall set of the camera device functionality.</p>
- * <p>Camera devices will come in two flavors: LIMITED and FULL.</p>
- * <p>A FULL device has the most support possible and will support below capabilities:</p>
+ * <p>Camera devices will come in three flavors: LEGACY, LIMITED and FULL.</p>
+ * <p>A FULL device will support below capabilities:</p>
* <ul>
* <li>30fps at maximum resolution (== sensor resolution) is preferred, more than 20fps is required.</li>
* <li>Per frame control ({@link CameraCharacteristics#SYNC_MAX_LATENCY android.sync.maxLatency} <code>==</code> PER_FRAME_CONTROL)</li>
@@ -1910,14 +2295,38 @@
* </ul>
* <p>A LIMITED device may have some or none of the above characteristics.
* To find out more refer to {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}.</p>
+ * <p>Some features are not part of any particular hardware level or capability and must be
+ * queried separately. These include:</p>
+ * <ul>
+ * <li>Calibrated timestamps ({@link CameraCharacteristics#SENSOR_INFO_TIMESTAMP_SOURCE android.sensor.info.timestampSource} <code>==</code> REALTIME)</li>
+ * <li>Precision lens control ({@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} <code>==</code> CALIBRATED)</li>
+ * <li>Face detection ({@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes})</li>
+ * <li>Optical or electrical image stabilization
+ * ({@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization},
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES android.control.availableVideoStabilizationModes})</li>
+ * </ul>
* <p>A LEGACY device does not support per-frame control, manual sensor control, manual
* post-processing, arbitrary cropping regions, and has relaxed performance constraints.</p>
+ * <p>Each higher level supports everything the lower level supports
+ * in this order: FULL <code>></code> LIMITED <code>></code> LEGACY.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}</li>
+ * <li>{@link #INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}</li>
+ * <li>{@link #INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES
+ * @see CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION
+ * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
* @see CameraCharacteristics#REQUEST_MAX_NUM_OUTPUT_PROC
* @see CameraCharacteristics#SCALER_CROPPING_TYPE
* @see CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE
* @see CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION
+ * @see CameraCharacteristics#SENSOR_INFO_TIMESTAMP_SOURCE
+ * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES
* @see CameraCharacteristics#SYNC_MAX_LATENCY
* @see #INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED
* @see #INFO_SUPPORTED_HARDWARE_LEVEL_FULL
@@ -1959,6 +2368,15 @@
* <p>Since <code>result4</code> has a <code>frameNumber == 4</code> and
* <code>android.sync.frameNumber == 2</code>, the distance is clearly
* <code>4 - 2 = 2</code>.</p>
+ * <p><b>Units</b>: Frame counts</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SYNC_MAX_LATENCY_PER_FRAME_CONTROL PER_FRAME_CONTROL}</li>
+ * <li>{@link #SYNC_MAX_LATENCY_UNKNOWN UNKNOWN}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * A positive value, PER_FRAME_CONTROL, or UNKNOWN.</p>
+ * <p>This key is available on all devices.</p>
* @see #SYNC_MAX_LATENCY_PER_FRAME_CONTROL
* @see #SYNC_MAX_LATENCY_UNKNOWN
*/
@@ -1970,4 +2388,6 @@
* End generated code
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/
+
+
}
diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java
index a57b361..16df844 100644
--- a/core/java/android/hardware/camera2/CameraMetadata.java
+++ b/core/java/android/hardware/camera2/CameraMetadata.java
@@ -418,11 +418,11 @@
* <ul>
* <li>RAW_SENSOR is supported as an output format.</li>
* <li>The maximum available resolution for RAW_SENSOR streams
- * will match either the value in
- * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize} or
- * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</li>
+ * will match either the value in
+ * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize} or
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</li>
* <li>All DNG-related optional metadata entries are provided
- * by the camera device.</li>
+ * by the camera device.</li>
* </ul>
*
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
@@ -437,13 +437,13 @@
* <li>At least one input stream can be used.</li>
* <li>RAW_OPAQUE is supported as an output/input format</li>
* <li>Using RAW_OPAQUE does not cause a frame rate drop
- * relative to the sensor's maximum capture rate (at that
- * resolution).</li>
+ * relative to the sensor's maximum capture rate (at that
+ * resolution).</li>
* <li>RAW_OPAQUE will be reprocessable into both YUV_420_888
- * and JPEG formats.</li>
+ * and JPEG formats.</li>
* <li>The maximum available resolution for RAW_OPAQUE streams
- * (both input/output) will match the maximum available
- * resolution of JPEG streams.</li>
+ * (both input/output) will match the maximum available
+ * resolution of JPEG streams.</li>
* </ul>
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
* @hide
@@ -807,6 +807,8 @@
* {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration} are used by the camera
* device, along with android.flash.* fields, if there's
* a flash unit for this camera device.</p>
+ * <p>LEGACY devices do not support the OFF mode and will
+ * override attempts to use this value to ON.</p>
*
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
* @see CaptureRequest#SENSOR_FRAME_DURATION
@@ -1213,8 +1215,7 @@
* image while recording video) use case.</p>
* <p>The camera device should take the highest-quality image
* possible (given the other settings) without disrupting the
- * frame rate of video recording.<br />
- * </p>
+ * frame rate of video recording. </p>
* @see CaptureRequest#CONTROL_CAPTURE_INTENT
*/
public static final int CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT = 4;
@@ -1577,6 +1578,8 @@
/**
* <p>Turn on custom high dynamic range (HDR) mode.</p>
+ * <p>This is intended for LEGACY mode devices only;
+ * HAL3+ camera devices should not implement this mode.</p>
* @see CaptureRequest#CONTROL_SCENE_MODE
* @hide
*/
@@ -1862,8 +1865,6 @@
/**
* <p>Return face rectangle and confidence values only.</p>
- * <p>In this mode, only android.statistics.faceRectangles and
- * android.statistics.faceScores outputs are valid.</p>
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
*/
public static final int STATISTICS_FACE_DETECT_MODE_SIMPLE = 1;
@@ -1871,11 +1872,7 @@
/**
* <p>Return all face
* metadata.</p>
- * <p>In this mode,
- * android.statistics.faceRectangles,
- * android.statistics.faceScores,
- * android.statistics.faceIds, and
- * android.statistics.faceLandmarks outputs are valid.</p>
+ * <p>In this mode, face rectangles, scores, landmarks, and face IDs are all valid.</p>
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
*/
public static final int STATISTICS_FACE_DETECT_MODE_FULL = 2;
@@ -2064,6 +2061,8 @@
* and may restart scanning at any time.</p>
* <p>Only used by CONTINUOUS_* AF modes. This is a transient state, the camera
* device may skip reporting this state in capture result.</p>
+ * <p>LEGACY camera devices do not support this state. When a passive
+ * scan has finished, it will always go to PASSIVE_FOCUSED.</p>
* @see CaptureResult#CONTROL_AF_STATE
*/
public static final int CONTROL_AF_STATE_PASSIVE_UNFOCUSED = 6;
diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java
index 93eb3de..6aec72a 100644
--- a/core/java/android/hardware/camera2/CaptureRequest.java
+++ b/core/java/android/hardware/camera2/CaptureRequest.java
@@ -476,7 +476,6 @@
* modify the comment blocks at the start or end.
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/
-
/**
* <p>The mode control selects how the image data is converted from the
* sensor's native color into linear sRGB color.</p>
@@ -518,10 +517,21 @@
* </code></pre>
* <p>Both the input and output value ranges must match. Overflow/underflow
* values are clipped to fit within the range.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX TRANSFORM_MATRIX}</li>
+ * <li>{@link #COLOR_CORRECTION_MODE_FAST FAST}</li>
+ * <li>{@link #COLOR_CORRECTION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_GAINS
* @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
* @see CaptureRequest#CONTROL_AWB_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX
* @see #COLOR_CORRECTION_MODE_FAST
* @see #COLOR_CORRECTION_MODE_HIGH_QUALITY
@@ -542,8 +552,14 @@
* in this matrix result metadata. The transform should keep the magnitude
* of the output color values within <code>[0, 1.0]</code> (assuming input color
* values is within the normalized range <code>[0, 1.0]</code>), or clipping may occur.</p>
+ * <p><b>Units</b>: Unitless scale factors</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<android.hardware.camera2.params.ColorSpaceTransform> COLOR_CORRECTION_TRANSFORM =
@@ -559,8 +575,14 @@
* TRANSFORM_MATRIX.</p>
* <p>The gains in the result metadata are the gains actually
* applied by the camera device to the current frame.</p>
+ * <p><b>Units</b>: Unitless gain factors</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<android.hardware.camera2.params.RggbChannelVector> COLOR_CORRECTION_GAINS =
@@ -568,8 +590,6 @@
/**
* <p>Mode of operation for the chromatic aberration correction algorithm.</p>
- * <p>This must be set to a valid mode from
- * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}.</p>
* <p>Chromatic (color) aberration is caused by the fact that different wavelengths of light
* can not focus on the same point after exiting from the lens. This metadata defines
* the high level control of chromatic aberration correction algorithm, which aims to
@@ -580,6 +600,16 @@
* use the highest-quality aberration correction algorithms, even if it slows down
* capture rate. FAST means the camera device will not slow down capture rate when
* applying aberration correction.</p>
+ * <p>LEGACY devices will always be in FAST mode.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_OFF OFF}</li>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_FAST FAST}</li>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES
* @see #COLOR_CORRECTION_ABERRATION_MODE_OFF
@@ -612,7 +642,7 @@
* options for the antibanding mode. The
* {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes} key contains
* the available modes for a given camera device.</p>
- * <p>The default mode is AUTO, which must be supported by all
+ * <p>The default mode is AUTO, which is supported by all
* camera devices.</p>
* <p>If manual exposure control is enabled (by setting
* {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} to OFF),
@@ -620,6 +650,16 @@
* ensure it selects exposure times that do not cause banding
* issues. The {@link CaptureResult#STATISTICS_SCENE_FLICKER android.statistics.sceneFlicker} key can assist
* the application in this.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_50HZ 50HZ}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_60HZ 60HZ}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_AUTO AUTO}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br></p>
+ * <p>{@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES
* @see CaptureRequest#CONTROL_AE_MODE
@@ -652,6 +692,10 @@
* state. Once the new exposure target is reached, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} will
* change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or
* FLASH_REQUIRED (if the scene is too dark for still capture).</p>
+ * <p><b>Units</b>: Compensation steps</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE android.control.aeCompensationRange}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE
* @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP
@@ -666,9 +710,11 @@
/**
* <p>Whether auto-exposure (AE) is currently locked to its latest
* calculated values.</p>
- * <p>Note that even when AE is locked, the flash may be
- * fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH / ON_ALWAYS_FLASH /
- * ON_AUTO_FLASH_REDEYE.</p>
+ * <p>When set to <code>true</code> (ON), the AE algorithm is locked to its latest parameters,
+ * and will not change exposure settings until the lock is set to <code>false</code> (OFF).</p>
+ * <p>Note that even when AE is locked, the flash may be fired if
+ * the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH /
+ * ON_ALWAYS_FLASH / ON_AUTO_FLASH_REDEYE.</p>
* <p>When {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation} is changed, even if the AE lock
* is ON, the camera device will still adjust its exposure value.</p>
* <p>If AE precapture is triggered (see {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger})
@@ -677,7 +723,21 @@
* parameters. The flash may be fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}
* is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the
* {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_ALWAYS_FLASH, the scene may become overexposed.</p>
+ * <p>Since the camera device has a pipeline of in-flight requests, the settings that
+ * get locked do not necessarily correspond to the settings that were present in the
+ * latest capture result received from the camera device, since additional captures
+ * and AE updates may have occurred even before the result was sent out. If an
+ * application is switching between automatic and manual control and wishes to eliminate
+ * any flicker during the switch, the following procedure is recommended:</p>
+ * <ol>
+ * <li>Starting in auto-AE mode:</li>
+ * <li>Lock AE</li>
+ * <li>Wait for the first result to be output that has the AE locked</li>
+ * <li>Copy exposure settings from that result into a request, set the request to manual AE</li>
+ * <li>Submit the capture request, proceed to run manual AE as desired.</li>
+ * </ol>
* <p>See {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE lock related state transition details.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION
* @see CaptureRequest#CONTROL_AE_MODE
@@ -711,7 +771,19 @@
* camera device auto-exposure routine for the overridden
* fields for a given capture will be available in its
* CaptureResult.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON ON}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_AUTO_FLASH ON_AUTO_FLASH}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_ALWAYS_FLASH ON_ALWAYS_FLASH}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE ON_AUTO_FLASH_REDEYE}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES android.control.aeAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#FLASH_INFO_AVAILABLE
* @see CaptureRequest#FLASH_MODE
@@ -729,25 +801,35 @@
new Key<Integer>("android.control.aeMode", int.class);
/**
- * <p>List of areas to use for
- * metering.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0.
+ * <p>List of metering areas to use for auto-exposure adjustment.</p>
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of regions supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
* bottom-right pixel in the active pixel array.</p>
- * <p>The weight must range from 0 to 1000, and represents a weight
+ * <p>The weight must be within <code>[0, 1000]</code>, and represents a weight
* for every pixel in the area. This means that a large metering area
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other exposure metering regions, so if only one
+ * region is used, all non-zero weights will have the same effect. A region with 0
+ * weight is ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AE
@@ -759,12 +841,20 @@
new Key<android.hardware.camera2.params.MeteringRectangle[]>("android.control.aeRegions", android.hardware.camera2.params.MeteringRectangle[].class);
/**
- * <p>Range over which fps can be adjusted to
- * maintain exposure.</p>
+ * <p>Range over which the auto-exposure routine can
+ * adjust the capture frame rate to maintain good
+ * exposure.</p>
* <p>Only constrains auto-exposure (AE) algorithm, not
- * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p>
+ * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} and
+ * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}.</p>
+ * <p><b>Units</b>: Frames per second (FPS)</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any of the entries in {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES android.control.aeAvailableTargetFpsRanges}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
+ * @see CaptureRequest#SENSOR_FRAME_DURATION
*/
@PublicKey
public static final Key<android.util.Range<Integer>> CONTROL_AE_TARGET_FPS_RANGE =
@@ -789,8 +879,22 @@
* depends on the current AE mode and state; see
* {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition
* details.</p>
+ * <p>On LEGACY-level devices, the precapture trigger is not supported;
+ * capturing a high-resolution JPEG image will automatically trigger a
+ * precapture sequence before the high-resolution capture, including
+ * potentially firing a pre-capture flash.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE IDLE}</li>
+ * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_START START}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureResult#CONTROL_AE_STATE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE
* @see #CONTROL_AE_PRECAPTURE_TRIGGER_START
*/
@@ -806,7 +910,20 @@
* <p>If the lens is controlled by the camera device auto-focus algorithm,
* the camera device will report the current AF status in {@link CaptureResult#CONTROL_AF_STATE android.control.afState}
* in result metadata.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AF_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AF_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_AF_MODE_MACRO MACRO}</li>
+ * <li>{@link #CONTROL_AF_MODE_CONTINUOUS_VIDEO CONTINUOUS_VIDEO}</li>
+ * <li>{@link #CONTROL_AF_MODE_CONTINUOUS_PICTURE CONTINUOUS_PICTURE}</li>
+ * <li>{@link #CONTROL_AF_MODE_EDOF EDOF}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES android.control.afAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES
* @see CaptureResult#CONTROL_AF_STATE
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
@@ -822,25 +939,35 @@
new Key<Integer>("android.control.afMode", int.class);
/**
- * <p>List of areas to use for focus
- * estimation.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0.
+ * <p>List of metering areas to use for auto-focus.</p>
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of focus areas supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
* bottom-right pixel in the active pixel array.</p>
- * <p>The weight must range from 0 to 1000, and represents a weight
+ * <p>The weight must be within <code>[0, 1000]</code>, and represents a weight
* for every pixel in the area. This means that a large metering area
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other metering regions, so if only one region
+ * is used, all non-zero weights will have the same effect. A region with 0 weight is
+ * ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AF
@@ -864,6 +991,13 @@
* START for multiple captures in a row means restarting the AF operation over
* and over again.</p>
* <p>See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what the trigger means for each AF mode.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AF_TRIGGER_IDLE IDLE}</li>
+ * <li>{@link #CONTROL_AF_TRIGGER_START START}</li>
+ * <li>{@link #CONTROL_AF_TRIGGER_CANCEL CANCEL}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureResult#CONTROL_AF_STATE
* @see #CONTROL_AF_TRIGGER_IDLE
@@ -877,9 +1011,26 @@
/**
* <p>Whether auto-white balance (AWB) is currently locked to its
* latest calculated values.</p>
+ * <p>When set to <code>true</code> (ON), the AWB algorithm is locked to its latest parameters,
+ * and will not change color balance settings until the lock is set to <code>false</code> (OFF).</p>
+ * <p>Since the camera device has a pipeline of in-flight requests, the settings that
+ * get locked do not necessarily correspond to the settings that were present in the
+ * latest capture result received from the camera device, since additional captures
+ * and AWB updates may have occurred even before the result was sent out. If an
+ * application is switching between automatic and manual control and wishes to eliminate
+ * any flicker during the switch, the following procedure is recommended:</p>
+ * <ol>
+ * <li>Starting in auto-AWB mode:</li>
+ * <li>Lock AWB</li>
+ * <li>Wait for the first result to be output that has the AWB locked</li>
+ * <li>Copy AWB settings from that result into a request, set the request to manual AWB</li>
+ * <li>Submit the capture request, proceed to run manual AWB as desired.</li>
+ * </ol>
* <p>Note that AWB lock is only meaningful when
* {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} is in the AUTO mode; in other modes,
* AWB is already fixed to a specific setting.</p>
+ * <p>Some LEGACY devices may not support ON; the value is then overridden to OFF.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AWB_MODE
*/
@@ -907,10 +1058,26 @@
* {@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} are ignored.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AWB_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AWB_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_AWB_MODE_INCANDESCENT INCANDESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_FLUORESCENT FLUORESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_WARM_FLUORESCENT WARM_FLUORESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_DAYLIGHT DAYLIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_CLOUDY_DAYLIGHT CLOUDY_DAYLIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_TWILIGHT TWILIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_SHADE SHADE}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AWB_AVAILABLE_MODES android.control.awbAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#COLOR_CORRECTION_GAINS
* @see CaptureRequest#COLOR_CORRECTION_MODE
* @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
+ * @see CameraCharacteristics#CONTROL_AWB_AVAILABLE_MODES
* @see CaptureRequest#CONTROL_MODE
* @see #CONTROL_AWB_MODE_OFF
* @see #CONTROL_AWB_MODE_AUTO
@@ -927,10 +1094,12 @@
new Key<Integer>("android.control.awbMode", int.class);
/**
- * <p>List of areas to use for illuminant
+ * <p>List of metering areas to use for auto-white-balance illuminant
* estimation.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0.
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of regions supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
@@ -941,11 +1110,20 @@
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other white balance metering regions, so if
+ * only one region is used, all non-zero weights will have the same effect. A region with
+ * 0 weight is ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AWB
@@ -965,7 +1143,18 @@
* <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF</code> and any 3A routine is active.</p>
* <p>ZERO_SHUTTER_LAG will be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
* contains ZSL. MANUAL will be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
- * contains MANUAL_SENSOR.</p>
+ * contains MANUAL_SENSOR. Other intent values are always supported.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_CUSTOM CUSTOM}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_PREVIEW PREVIEW}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_STILL_CAPTURE STILL_CAPTURE}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_VIDEO_RECORD VIDEO_RECORD}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT VIDEO_SNAPSHOT}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_ZERO_SHUTTER_LAG ZERO_SHUTTER_LAG}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_MANUAL MANUAL}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
@@ -989,10 +1178,23 @@
* implementor of the camera device, and should not be
* depended on to be consistent (or present) across all
* devices.</p>
- * <p>A color effect will only be applied if
- * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_EFFECT_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_MONO MONO}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_NEGATIVE NEGATIVE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_SOLARIZE SOLARIZE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_SEPIA SEPIA}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_POSTERIZE POSTERIZE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_WHITEBOARD WHITEBOARD}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_BLACKBOARD BLACKBOARD}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_AQUA AQUA}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS android.control.availableEffects}</p>
+ * <p>This key is available on all devices.</p>
*
- * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS
* @see #CONTROL_EFFECT_MODE_OFF
* @see #CONTROL_EFFECT_MODE_MONO
* @see #CONTROL_EFFECT_MODE_NEGATIVE
@@ -1008,9 +1210,9 @@
new Key<Integer>("android.control.effectMode", int.class);
/**
- * <p>Overall mode of 3A control
+ * <p>Overall mode of 3A (auto-exposure, auto-white-balance, auto-focus) control
* routines.</p>
- * <p>High-level 3A control. When set to OFF, all 3A control
+ * <p>This is a top-level 3A control switch. When set to OFF, all 3A control
* by the camera device is disabled. The application must set the fields for
* capture parameters itself.</p>
* <p>When set to AUTO, the individual algorithm controls in
@@ -1025,6 +1227,18 @@
* update, as if this frame is never captured. This mode can be used in the scenario
* where the application doesn't want a 3A manual control capture to affect
* the subsequent auto 3A capture results.</p>
+ * <p>LEGACY mode devices will only support AUTO and USE_SCENE_MODE modes.
+ * LIMITED mode devices will only support OFF and OFF_KEEP_STATE if they
+ * support the MANUAL_SENSOR and MANUAL_POST_PROCSESING capabilities.
+ * FULL mode devices will always support OFF and OFF_KEEP_STATE.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_MODE_USE_SCENE_MODE USE_SCENE_MODE}</li>
+ * <li>{@link #CONTROL_MODE_OFF_KEEP_STATE OFF_KEEP_STATE}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AF_MODE
* @see #CONTROL_MODE_OFF
@@ -1037,18 +1251,41 @@
new Key<Integer>("android.control.mode", int.class);
/**
- * <p>A camera mode optimized for conditions typical in a particular
- * capture setting.</p>
+ * <p>Control for which scene mode is currently active.</p>
+ * <p>Scene modes are custom camera modes optimized for a certain set of conditions and
+ * capture settings.</p>
* <p>This is the mode that that is active when
* <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code>. Aside from FACE_PRIORITY,
* these modes will disable {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode},
- * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.
- * The scene modes available for a given camera device are listed in
- * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes}.</p>
+ * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.</p>
* <p>The interpretation and implementation of these scene modes is left
* to the implementor of the camera device. Their behavior will not be
* consistent across all devices, and any given device may only implement
* a subset of these modes.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_SCENE_MODE_DISABLED DISABLED}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_FACE_PRIORITY FACE_PRIORITY}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_ACTION ACTION}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_PORTRAIT PORTRAIT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_LANDSCAPE LANDSCAPE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_NIGHT NIGHT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_NIGHT_PORTRAIT NIGHT_PORTRAIT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_THEATRE THEATRE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_BEACH BEACH}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SNOW SNOW}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SUNSET SUNSET}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_STEADYPHOTO STEADYPHOTO}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_FIREWORKS FIREWORKS}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SPORTS SPORTS}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_PARTY PARTY}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_CANDLELIGHT CANDLELIGHT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_BARCODE BARCODE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AF_MODE
@@ -1081,18 +1318,26 @@
/**
* <p>Whether video stabilization is
* active.</p>
- * <p>Video stabilization automatically translates and scales images from the camera
- * in order to stabilize motion between consecutive frames.</p>
+ * <p>Video stabilization automatically translates and scales images from
+ * the camera in order to stabilize motion between consecutive frames.</p>
* <p>If enabled, video stabilization can modify the
* {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream stabilized.</p>
- * <p>Switching between different video stabilization modes may take several frames
- * to initialize, the camera device will report the current mode in capture result
- * metadata. For example, When "ON" mode is requested, the video stabilization modes
- * in the first several capture results may still be "OFF", and it will become "ON"
- * when the initialization is done.</p>
- * <p>If a camera device supports both this mode and OIS ({@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}),
- * turning both modes on may produce undesirable interaction, so it is recommended not to
- * enable both at the same time.</p>
+ * <p>Switching between different video stabilization modes may take several
+ * frames to initialize, the camera device will report the current mode
+ * in capture result metadata. For example, When "ON" mode is requested,
+ * the video stabilization modes in the first several capture results may
+ * still be "OFF", and it will become "ON" when the initialization is
+ * done.</p>
+ * <p>If a camera device supports both this mode and OIS
+ * ({@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}), turning both modes on may
+ * produce undesirable interaction, so it is recommended not to enable
+ * both at the same time.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_VIDEO_STABILIZATION_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_VIDEO_STABILIZATION_MODE_ON ON}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE
* @see CaptureRequest#SCALER_CROP_REGION
@@ -1106,16 +1351,28 @@
/**
* <p>Operation mode for edge
* enhancement.</p>
- * <p>Edge/sharpness/detail enhancement. OFF means no
- * enhancement will be applied by the camera device.</p>
- * <p>This must be set to one of the modes listed in {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}.</p>
+ * <p>Edge enhancement improves sharpness and details in the captured image. OFF means
+ * no enhancement will be applied by the camera device.</p>
* <p>FAST/HIGH_QUALITY both mean camera device determined enhancement
* will be applied. HIGH_QUALITY mode indicates that the
* camera device will use the highest-quality enhancement algorithms,
* even if it slows down capture rate. FAST means the camera device will
* not slow down capture rate when applying edge enhancement.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #EDGE_MODE_OFF OFF}</li>
+ * <li>{@link #EDGE_MODE_FAST FAST}</li>
+ * <li>{@link #EDGE_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #EDGE_MODE_OFF
* @see #EDGE_MODE_FAST
* @see #EDGE_MODE_HIGH_QUALITY
@@ -1139,6 +1396,13 @@
* <p>When set to TORCH, the flash will be on continuously. This mode can be used
* for use cases such as preview, auto-focus assist, still capture, or video recording.</p>
* <p>The flash status will be reported by {@link CaptureResult#FLASH_STATE android.flash.state} in the capture result metadata.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #FLASH_MODE_OFF OFF}</li>
+ * <li>{@link #FLASH_MODE_SINGLE SINGLE}</li>
+ * <li>{@link #FLASH_MODE_TORCH TORCH}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
@@ -1153,12 +1417,19 @@
new Key<Integer>("android.flash.mode", int.class);
/**
- * <p>Set operational mode for hot pixel correction.</p>
- * <p>Valid modes for this camera device are listed in
- * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}.</p>
+ * <p>Operational mode for hot pixel correction.</p>
* <p>Hotpixel correction interpolates out, or otherwise removes, pixels
- * that do not accurately encode the incoming light (i.e. pixels that
- * are stuck at an arbitrary value).</p>
+ * that do not accurately measure the incoming light (i.e. pixels that
+ * are stuck at an arbitrary value or are oversensitive).</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #HOT_PIXEL_MODE_OFF OFF}</li>
+ * <li>{@link #HOT_PIXEL_MODE_FAST FAST}</li>
+ * <li>{@link #HOT_PIXEL_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES
* @see #HOT_PIXEL_MODE_OFF
@@ -1171,6 +1442,10 @@
/**
* <p>A location object to use when generating image GPS metadata.</p>
+ * <p>Setting a location object in a request will include the GPS coordinates of the location
+ * into any JPEG images captured based on the request. These coordinates can then be
+ * viewed by anyone who receives the JPEG image.</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
@SyntheticKey
@@ -1179,7 +1454,10 @@
/**
* <p>GPS coordinates to include in output JPEG
- * EXIF</p>
+ * EXIF.</p>
+ * <p><b>Range of valid values:</b><br>
+ * (-180 - 180], [-90,90], [-inf, inf]</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<double[]> JPEG_GPS_COORDINATES =
@@ -1187,7 +1465,9 @@
/**
* <p>32 characters describing GPS algorithm to
- * include in EXIF</p>
+ * include in EXIF.</p>
+ * <p><b>Units</b>: UTF-8 null-terminated string</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<String> JPEG_GPS_PROCESSING_METHOD =
@@ -1195,15 +1475,49 @@
/**
* <p>Time GPS fix was made to include in
- * EXIF</p>
+ * EXIF.</p>
+ * <p><b>Units</b>: UTC in seconds since January 1, 1970</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<Long> JPEG_GPS_TIMESTAMP =
new Key<Long>("android.jpeg.gpsTimestamp", long.class);
/**
- * <p>Orientation of JPEG image to
- * write</p>
+ * <p>The orientation for a JPEG image.</p>
+ * <p>The clockwise rotation angle in degrees, relative to the orientation
+ * to the camera, that the JPEG picture needs to be rotated by, to be viewed
+ * upright.</p>
+ * <p>Camera devices may either encode this value into the JPEG EXIF header, or
+ * rotate the image data to match this orientation.</p>
+ * <p>Note that this orientation is relative to the orientation of the camera sensor, given
+ * by {@link CameraCharacteristics#SENSOR_ORIENTATION android.sensor.orientation}.</p>
+ * <p>To translate from the device orientation given by the Android sensor APIs, the following
+ * sample code may be used:</p>
+ * <pre><code>private int getJpegOrientation(CameraCharacteristics c, int deviceOrientation) {
+ * if (deviceOrientation == android.view.OrientationEventListener.ORIENTATION_UNKNOWN) return 0;
+ * int sensorOrientation = c.get(CameraCharacteristics.SENSOR_ORIENTATION);
+ *
+ * // Round device orientation to a multiple of 90
+ * deviceOrientation = (deviceOrientation + 45) / 90 * 90;
+ *
+ * // Reverse device orientation for front-facing cameras
+ * boolean facingFront = c.get(CameraCharacteristics.LENS_FACING) == CameraCharacteristics.LENS_FACING_FRONT;
+ * if (facingFront) deviceOrientation = -deviceOrientation;
+ *
+ * // Calculate desired JPEG orientation relative to camera orientation to make
+ * // the image upright relative to the device orientation
+ * int jpegOrientation = (sensorOrientation + deviceOrientation + 360) % 360;
+ *
+ * return jpegOrientation;
+ * }
+ * </code></pre>
+ * <p><b>Units</b>: Degrees in multiples of 90</p>
+ * <p><b>Range of valid values:</b><br>
+ * 0, 90, 180, 270</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#SENSOR_ORIENTATION
*/
@PublicKey
public static final Key<Integer> JPEG_ORIENTATION =
@@ -1213,6 +1527,9 @@
* <p>Compression quality of the final JPEG
* image.</p>
* <p>85-95 is typical usage range.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 1-100; larger is higher quality</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Byte> JPEG_QUALITY =
@@ -1221,6 +1538,9 @@
/**
* <p>Compression quality of JPEG
* thumbnail.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 1-100; larger is higher quality</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Byte> JPEG_THUMBNAIL_QUALITY =
@@ -1230,25 +1550,29 @@
* <p>Resolution of embedded JPEG thumbnail.</p>
* <p>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail,
* but the captured JPEG will still be a valid image.</p>
- * <p>When a jpeg image capture is issued, the thumbnail size selected should have
- * the same aspect ratio as the jpeg image.</p>
+ * <p>For best results, when issuing a request for a JPEG image, the thumbnail size selected
+ * should have the same aspect ratio as the main JPEG output.</p>
* <p>If the thumbnail image aspect ratio differs from the JPEG primary image aspect
* ratio, the camera device creates the thumbnail by cropping it from the primary image.
* For example, if the primary image has 4:3 aspect ratio, the thumbnail image has
* 16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to
* generate the thumbnail image. The thumbnail image will always have a smaller Field
* Of View (FOV) than the primary image when aspect ratios differ.</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES android.jpeg.availableThumbnailSizes}</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES
*/
@PublicKey
public static final Key<android.util.Size> JPEG_THUMBNAIL_SIZE =
new Key<android.util.Size>("android.jpeg.thumbnailSize", android.util.Size.class);
/**
- * <p>The ratio of lens focal length to the effective
- * aperture diameter.</p>
- * <p>This will only be supported on the camera devices that
- * have variable aperture lens. The aperture value can only be
- * one of the values listed in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}.</p>
+ * <p>The desired lens aperture size, as a ratio of lens focal length to the
+ * effective aperture diameter.</p>
+ * <p>Setting this value is only supported on the camera devices that have a variable
+ * aperture lens.</p>
* <p>When this is supported and {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is OFF,
* this can be set along with {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
* {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}
@@ -1261,8 +1585,16 @@
* the ON modes, this will be overridden by the camera device
* auto-exposure algorithm, the overridden values are then provided
* back to the user in the corresponding result.</p>
+ * <p><b>Units</b>: The f-number (f/N)</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
* @see CaptureResult#LENS_STATE
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
@@ -1274,10 +1606,8 @@
new Key<Float>("android.lens.aperture", float.class);
/**
- * <p>State of lens neutral density filter(s).</p>
- * <p>This will not be supported on most camera devices. On devices
- * where this is supported, this may only be set to one of the
- * values included in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}.</p>
+ * <p>The desired setting for the lens neutral density filter(s).</p>
+ * <p>This control will not be supported on most camera devices.</p>
* <p>Lens filters are typically used to lower the amount of light the
* sensor is exposed to (measured in steps of EV). As used here, an EV
* step is the standard logarithmic representation, which are
@@ -1289,7 +1619,15 @@
* <p>It may take several frames before the lens filter density changes
* to the requested value. While the filter density is still changing,
* {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
+ * <p><b>Units</b>: Exposure Value (EV)</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES
* @see CaptureResult#LENS_STATE
*/
@@ -1298,7 +1636,7 @@
new Key<Float>("android.lens.filterDensity", float.class);
/**
- * <p>The current lens focal length; used for optical zoom.</p>
+ * <p>The desired lens focal length; used for optical zoom.</p>
* <p>This setting controls the physical focal length of the camera
* device's lens. Changing the focal length changes the field of
* view of the camera device, and is usually used for optical zoom.</p>
@@ -1307,10 +1645,15 @@
* frames before the lens can change to the requested focal length.
* While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will
* be set to MOVING.</p>
- * <p>This is expected not to be supported on most devices.</p>
+ * <p>Optical zoom will not be supported on most devices.</p>
+ * <p><b>Units</b>: Millimeters</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#LENS_APERTURE
* @see CaptureRequest#LENS_FOCUS_DISTANCE
+ * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS
* @see CaptureResult#LENS_STATE
*/
@PublicKey
@@ -1318,16 +1661,30 @@
new Key<Float>("android.lens.focalLength", float.class);
/**
- * <p>Distance to plane of sharpest focus,
+ * <p>Desired distance to plane of sharpest focus,
* measured from frontmost surface of the lens.</p>
- * <p>0 means infinity focus. Used value will be clamped
- * to [0, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}].</p>
+ * <p>This control can be used for setting manual focus, on devices that support
+ * the MANUAL_SENSOR capability and have a variable-focus lens (see
+ * {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}).</p>
+ * <p>A value of <code>0.0f</code> means infinity focus. The value set will be clamped to
+ * <code>[0.0f, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}]</code>.</p>
* <p>Like {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}, this setting won't be applied
* instantaneously, and it may take several frames before the lens
* can move to the requested focus distance. While the lens is still moving,
* {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
+ * <p>LEGACY devices support at most setting this to <code>0.0f</code>
+ * for infinity focus.</p>
+ * <p><b>Units</b>: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 0</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#LENS_FOCAL_LENGTH
+ * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
* @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
* @see CaptureResult#LENS_STATE
*/
@@ -1349,14 +1706,26 @@
* capture result metadata. For example, When "ON" mode is requested, the
* optical stabilization modes in the first several capture results may still
* be "OFF", and it will become "ON" when the initialization is done.</p>
- * <p>If a camera device supports both OIS and EIS ({@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}),
- * turning both modes on may produce undesirable interaction, so it is recommended not
- * to enable both at the same time.</p>
+ * <p>If a camera device supports both OIS and digital image stabilization
+ * ({@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}), turning both modes on may produce undesirable
+ * interaction, so it is recommended not to enable both at the same time.</p>
* <p>Not all devices will support OIS; see
* {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for
* available controls.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LENS_OPTICAL_STABILIZATION_MODE_OFF OFF}</li>
+ * <li>{@link #LENS_OPTICAL_STABILIZATION_MODE_ON ON}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION
* @see #LENS_OPTICAL_STABILIZATION_MODE_OFF
* @see #LENS_OPTICAL_STABILIZATION_MODE_ON
@@ -1367,16 +1736,28 @@
/**
* <p>Mode of operation for the noise reduction algorithm.</p>
- * <p>Noise filtering control. OFF means no noise reduction
- * will be applied by the camera device.</p>
- * <p>This must be set to a valid mode from
- * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.</p>
+ * <p>The noise reduction algorithm attempts to improve image quality by removing
+ * excessive noise added by the capture process, especially in dark conditions.
+ * OFF means no noise reduction will be applied by the camera device.</p>
* <p>FAST/HIGH_QUALITY both mean camera device determined noise filtering
* will be applied. HIGH_QUALITY mode indicates that the camera device
* will use the highest-quality noise filtering algorithms,
* even if it slows down capture rate. FAST means the camera device will not
* slow down capture rate when applying noise filtering.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #NOISE_REDUCTION_MODE_OFF OFF}</li>
+ * <li>{@link #NOISE_REDUCTION_MODE_FAST FAST}</li>
+ * <li>{@link #NOISE_REDUCTION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES
* @see #NOISE_REDUCTION_MODE_OFF
* @see #NOISE_REDUCTION_MODE_FAST
@@ -1390,13 +1771,18 @@
* <p>An application-specified ID for the current
* request. Must be maintained unchanged in output
* frame</p>
+ * <p><b>Units</b>: arbitrary integer assigned by application</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any int</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @hide
*/
public static final Key<Integer> REQUEST_ID =
new Key<Integer>("android.request.id", int.class);
/**
- * <p>The region of the sensor to read out for this capture.</p>
+ * <p>The desired region of the sensor to read out for this capture.</p>
+ * <p>This control can be used to implement digital zoom.</p>
* <p>The crop region coordinate system is based off
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with <code>(0, 0)</code> being the
* top-left corner of the sensor active array.</p>
@@ -1426,6 +1812,9 @@
* for rounding and other hardware requirements; the final
* crop region used will be included in the output capture
* result.</p>
+ * <p><b>Units</b>: Pixel coordinates relative to
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
@@ -1437,8 +1826,23 @@
/**
* <p>Duration each pixel is exposed to
* light.</p>
- * <p>If the sensor can't expose this exact duration, it should shorten the
- * duration exposed to the nearest possible value (rather than expose longer).</p>
+ * <p>If the sensor can't expose this exact duration, it will shorten the
+ * duration exposed to the nearest possible value (rather than expose longer).
+ * The final exposure time used will be available in the output capture result.</p>
+ * <p>This control is only effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} is set to
+ * OFF; otherwise the auto-exposure algorithm will override this value.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE android.sensor.info.exposureTimeRange}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CaptureRequest#CONTROL_AE_MODE
+ * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE
*/
@PublicKey
public static final Key<Long> SENSOR_EXPOSURE_TIME =
@@ -1516,8 +1920,23 @@
* delivered.</p>
* <p>For more details about stalling, see
* StreamConfigurationMap#getOutputStallDuration(int,Size).</p>
+ * <p>This control is only effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} is set to
+ * OFF; otherwise the auto-exposure algorithm will override this value.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * See {@link CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION android.sensor.info.maxFrameDuration},
+ * {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}. The duration
+ * is capped to <code>max(duration, exposureTime + overhead)</code>.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CaptureRequest#CONTROL_AE_MODE
+ * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
+ * @see CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION
*/
@PublicKey
public static final Key<Long> SENSOR_FRAME_DURATION =
@@ -1535,7 +1954,15 @@
* requested, it will reduce the gain to the nearest supported
* value. The final sensitivity used will be available in the
* output capture result.</p>
+ * <p><b>Units</b>: ISO arithmetic units</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE
* @see CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY
*/
@@ -1569,7 +1996,21 @@
* <p>For example, if manual flash is enabled, flash firing should still
* occur (and that the test pattern remain unmodified, since the flash
* would not actually affect it).</p>
+ * <p>Defaults to OFF.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_OFF OFF}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR SOLID_COLOR}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS COLOR_BARS}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS_FADE_TO_GRAY COLOR_BARS_FADE_TO_GRAY}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_PN9 PN9}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_CUSTOM1 CUSTOM1}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES android.sensor.availableTestPatternModes}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ *
+ * @see CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES
* @see #SENSOR_TEST_PATTERN_MODE_OFF
* @see #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR
* @see #SENSOR_TEST_PATTERN_MODE_COLOR_BARS
@@ -1587,30 +2028,41 @@
* <p>When set to OFF mode, no lens shading correction will be applied by the
* camera device, and an identity lens shading map data will be provided
* if <code>{@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON</code>. For example, for lens
- * shading map with size specified as <code>android.lens.info.shadingMapSize = [ 4, 3 ]</code>,
- * the output android.statistics.lensShadingMap for this case will be an identity map
- * shown below:</p>
+ * shading map with size of <code>[ 4, 3 ]</code>,
+ * the output {@link CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP android.statistics.lensShadingCorrectionMap} for this case will be an identity
+ * map shown below:</p>
* <pre><code>[ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ]
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ]
* </code></pre>
- * <p>When set to other modes, lens shading correction will be applied by the
- * camera device. Applications can request lens shading map data by setting
- * {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} to ON, and then the camera device will provide
- * lens shading map data in android.statistics.lensShadingMap, with size specified
- * by android.lens.info.shadingMapSize; the returned shading map data will be the one
- * applied by the camera device for this capture request.</p>
- * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore the reliability
- * of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in
- * AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code> OFF),
- * to get best results, it is recommended that the applications wait for the AE and AWB to
- * be converged before using the returned shading map data.</p>
+ * <p>When set to other modes, lens shading correction will be applied by the camera
+ * device. Applications can request lens shading map data by setting
+ * {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} to ON, and then the camera device will provide lens
+ * shading map data in {@link CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP android.statistics.lensShadingCorrectionMap}; the returned shading map
+ * data will be the one applied by the camera device for this capture request.</p>
+ * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore
+ * the reliability of the map data may be affected by the AE and AWB algorithms. When AE and
+ * AWB are in AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code>
+ * OFF), to get best results, it is recommended that the applications wait for the AE and AWB
+ * to be converged before using the returned shading map data.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SHADING_MODE_OFF OFF}</li>
+ * <li>{@link #SHADING_MODE_FAST FAST}</li>
+ * <li>{@link #SHADING_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AWB_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP
* @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE
* @see #SHADING_MODE_OFF
* @see #SHADING_MODE_FAST
@@ -1621,12 +2073,20 @@
new Key<Integer>("android.shading.mode", int.class);
/**
- * <p>Control for the face detector
+ * <p>Operating mode for the face detector
* unit.</p>
* <p>Whether face detection is enabled, and whether it
* should output just the basic fields or the full set of
- * fields. Value must be one of the
- * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}.</p>
+ * fields.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_OFF OFF}</li>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_SIMPLE SIMPLE}</li>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_FULL FULL}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES
* @see #STATISTICS_FACE_DETECT_MODE_OFF
@@ -1638,10 +2098,12 @@
new Key<Integer>("android.statistics.faceDetectMode", int.class);
/**
- * <p>Operating mode for hotpixel map generation.</p>
- * <p>If set to ON, a hotpixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.
- * If set to OFF, no hotpixel map will be returned.</p>
- * <p>This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}.</p>
+ * <p>Operating mode for hot pixel map generation.</p>
+ * <p>If set to <code>true</code>, a hot pixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.
+ * If set to <code>false</code>, no hot pixel map will be returned.</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CaptureResult#STATISTICS_HOT_PIXEL_MAP
* @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES
@@ -1656,6 +2118,18 @@
* <p>When set to ON,
* android.statistics.lensShadingMap will be provided in
* the output result metadata.</p>
+ * <p>ON is always supported on devices with the RAW capability.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #STATISTICS_LENS_SHADING_MAP_MODE_OFF OFF}</li>
+ * <li>{@link #STATISTICS_LENS_SHADING_MAP_MODE_ON ON}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #STATISTICS_LENS_SHADING_MAP_MODE_OFF
* @see #STATISTICS_LENS_SHADING_MAP_MODE_ON
*/
@@ -1668,7 +2142,12 @@
* channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
* <p>See android.tonemap.curveRed for more details.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_MODE
* @hide
*/
@@ -1680,7 +2159,12 @@
* channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
* <p>See android.tonemap.curveRed for more details.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_MODE
* @hide
*/
@@ -1693,10 +2177,10 @@
* CONTRAST_CURVE.</p>
* <p>Each channel's curve is defined by an array of control points:</p>
* <pre><code>android.tonemap.curveRed =
- * [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
+ * [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
* 2 <= N <= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
- * <p>These are sorted in order of increasing <code>Pin</code>; it is always
- * guaranteed that input values 0.0 and 1.0 are included in the list to
+ * <p>These are sorted in order of increasing <code>Pin</code>; it is
+ * required that input values 0.0 and 1.0 are included in the list to
* define a complete mapping. For input values between control points,
* the camera device must linearly interpolate between the control
* points.</p>
@@ -1717,21 +2201,29 @@
* <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
* <p>Gamma 1/2.2 mapping, with 16 control points:</p>
* <pre><code>android.tonemap.curveRed = [
- * 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812,
- * 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072,
- * 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685,
- * 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ]
+ * 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812,
+ * 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072,
+ * 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685,
+ * 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ]
* </code></pre>
* <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
* <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
* <pre><code>android.tonemap.curveRed = [
- * 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845,
- * 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130,
- * 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721,
- * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ]
+ * 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845,
+ * 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130,
+ * 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721,
+ * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ]
* </code></pre>
* <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
+ * <p><b>Range of valid values:</b><br>
+ * 0-1 on both input and output coordinates, normalized
+ * as a floating-point value such that 0 == black and 1 == white.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
* @see CaptureRequest#TONEMAP_MODE
* @hide
@@ -1747,7 +2239,7 @@
* example. The same logic applies to green and blue channel.
* Each channel's curve is defined by an array of control points:</p>
* <pre><code>curveRed =
- * [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ]
+ * [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ]
* 2 <= N <= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
* <p>These are sorted in order of increasing <code>Pin</code>; it is always
* guaranteed that input values 0.0 and 1.0 are included in the list to
@@ -1771,21 +2263,26 @@
* <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
* <p>Gamma 1/2.2 mapping, with 16 control points:</p>
* <pre><code>curveRed = [
- * (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812),
- * (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072),
- * (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685),
- * (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ]
+ * (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812),
+ * (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072),
+ * (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685),
+ * (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ]
* </code></pre>
* <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
* <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
* <pre><code>curveRed = [
- * (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845),
- * (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130),
- * (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721),
- * (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ]
+ * (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845),
+ * (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130),
+ * (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721),
+ * (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ]
* </code></pre>
* <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
* @see CaptureRequest#TONEMAP_MODE
*/
@@ -1807,8 +2304,6 @@
* tables, selective chroma enhancement, or other non-linear color
* transforms will be disabled when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
- * <p>This must be set to a valid mode in
- * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}.</p>
* <p>When using either FAST or HIGH_QUALITY, the camera device will
* emit its own tonemap curve in {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}.
* These values are always available, and as close as possible to the
@@ -1816,7 +2311,20 @@
* <p>If a request is sent with CONTRAST_CURVE with the camera device's
* provided curve in FAST or HIGH_QUALITY, the image's tonemap will be
* roughly the same.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #TONEMAP_MODE_CONTRAST_CURVE CONTRAST_CURVE}</li>
+ * <li>{@link #TONEMAP_MODE_FAST FAST}</li>
+ * <li>{@link #TONEMAP_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES
* @see CaptureRequest#TONEMAP_CURVE
* @see CaptureRequest#TONEMAP_MODE
@@ -1839,6 +2347,7 @@
* data is stored locally on the device.</p>
* <p>The LED <em>may</em> be off if a trusted application is using the data that
* doesn't violate the above rules.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @hide
*/
public static final Key<Boolean> LED_TRANSMIT =
@@ -1847,9 +2356,9 @@
/**
* <p>Whether black-level compensation is locked
* to its current values, or is free to vary.</p>
- * <p>When set to ON, the values used for black-level
+ * <p>When set to <code>true</code> (ON), the values used for black-level
* compensation will not change until the lock is set to
- * OFF.</p>
+ * <code>false</code> (OFF).</p>
* <p>Since changes to certain capture parameters (such as
* exposure time) may require resetting of black level
* compensation, the camera device must report whether setting
@@ -1882,6 +2391,12 @@
* possible, only overriding the lock to OFF when changes to
* other request parameters require a black level recalculation
* or reset.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<Boolean> BLACK_LEVEL_LOCK =
@@ -1891,4 +2406,6 @@
* End generated code
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/
+
+
}
diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java
index 01276a2..d208649 100644
--- a/core/java/android/hardware/camera2/CaptureResult.java
+++ b/core/java/android/hardware/camera2/CaptureResult.java
@@ -327,7 +327,6 @@
* modify the comment blocks at the start or end.
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/
-
/**
* <p>The mode control selects how the image data is converted from the
* sensor's native color into linear sRGB color.</p>
@@ -369,10 +368,21 @@
* </code></pre>
* <p>Both the input and output value ranges must match. Overflow/underflow
* values are clipped to fit within the range.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX TRANSFORM_MATRIX}</li>
+ * <li>{@link #COLOR_CORRECTION_MODE_FAST FAST}</li>
+ * <li>{@link #COLOR_CORRECTION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_GAINS
* @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
* @see CaptureRequest#CONTROL_AWB_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX
* @see #COLOR_CORRECTION_MODE_FAST
* @see #COLOR_CORRECTION_MODE_HIGH_QUALITY
@@ -393,8 +403,14 @@
* in this matrix result metadata. The transform should keep the magnitude
* of the output color values within <code>[0, 1.0]</code> (assuming input color
* values is within the normalized range <code>[0, 1.0]</code>), or clipping may occur.</p>
+ * <p><b>Units</b>: Unitless scale factors</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<android.hardware.camera2.params.ColorSpaceTransform> COLOR_CORRECTION_TRANSFORM =
@@ -410,8 +426,14 @@
* TRANSFORM_MATRIX.</p>
* <p>The gains in the result metadata are the gains actually
* applied by the camera device to the current frame.</p>
+ * <p><b>Units</b>: Unitless gain factors</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<android.hardware.camera2.params.RggbChannelVector> COLOR_CORRECTION_GAINS =
@@ -419,8 +441,6 @@
/**
* <p>Mode of operation for the chromatic aberration correction algorithm.</p>
- * <p>This must be set to a valid mode from
- * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}.</p>
* <p>Chromatic (color) aberration is caused by the fact that different wavelengths of light
* can not focus on the same point after exiting from the lens. This metadata defines
* the high level control of chromatic aberration correction algorithm, which aims to
@@ -431,6 +451,16 @@
* use the highest-quality aberration correction algorithms, even if it slows down
* capture rate. FAST means the camera device will not slow down capture rate when
* applying aberration correction.</p>
+ * <p>LEGACY devices will always be in FAST mode.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_OFF OFF}</li>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_FAST FAST}</li>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES
* @see #COLOR_CORRECTION_ABERRATION_MODE_OFF
@@ -463,7 +493,7 @@
* options for the antibanding mode. The
* {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes} key contains
* the available modes for a given camera device.</p>
- * <p>The default mode is AUTO, which must be supported by all
+ * <p>The default mode is AUTO, which is supported by all
* camera devices.</p>
* <p>If manual exposure control is enabled (by setting
* {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} to OFF),
@@ -471,6 +501,16 @@
* ensure it selects exposure times that do not cause banding
* issues. The {@link CaptureResult#STATISTICS_SCENE_FLICKER android.statistics.sceneFlicker} key can assist
* the application in this.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_50HZ 50HZ}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_60HZ 60HZ}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_AUTO AUTO}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br></p>
+ * <p>{@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES
* @see CaptureRequest#CONTROL_AE_MODE
@@ -503,6 +543,10 @@
* state. Once the new exposure target is reached, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} will
* change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or
* FLASH_REQUIRED (if the scene is too dark for still capture).</p>
+ * <p><b>Units</b>: Compensation steps</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE android.control.aeCompensationRange}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE
* @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP
@@ -517,9 +561,11 @@
/**
* <p>Whether auto-exposure (AE) is currently locked to its latest
* calculated values.</p>
- * <p>Note that even when AE is locked, the flash may be
- * fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH / ON_ALWAYS_FLASH /
- * ON_AUTO_FLASH_REDEYE.</p>
+ * <p>When set to <code>true</code> (ON), the AE algorithm is locked to its latest parameters,
+ * and will not change exposure settings until the lock is set to <code>false</code> (OFF).</p>
+ * <p>Note that even when AE is locked, the flash may be fired if
+ * the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH /
+ * ON_ALWAYS_FLASH / ON_AUTO_FLASH_REDEYE.</p>
* <p>When {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation} is changed, even if the AE lock
* is ON, the camera device will still adjust its exposure value.</p>
* <p>If AE precapture is triggered (see {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger})
@@ -528,7 +574,21 @@
* parameters. The flash may be fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}
* is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the
* {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_ALWAYS_FLASH, the scene may become overexposed.</p>
+ * <p>Since the camera device has a pipeline of in-flight requests, the settings that
+ * get locked do not necessarily correspond to the settings that were present in the
+ * latest capture result received from the camera device, since additional captures
+ * and AE updates may have occurred even before the result was sent out. If an
+ * application is switching between automatic and manual control and wishes to eliminate
+ * any flicker during the switch, the following procedure is recommended:</p>
+ * <ol>
+ * <li>Starting in auto-AE mode:</li>
+ * <li>Lock AE</li>
+ * <li>Wait for the first result to be output that has the AE locked</li>
+ * <li>Copy exposure settings from that result into a request, set the request to manual AE</li>
+ * <li>Submit the capture request, proceed to run manual AE as desired.</li>
+ * </ol>
* <p>See {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE lock related state transition details.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION
* @see CaptureRequest#CONTROL_AE_MODE
@@ -562,7 +622,19 @@
* camera device auto-exposure routine for the overridden
* fields for a given capture will be available in its
* CaptureResult.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON ON}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_AUTO_FLASH ON_AUTO_FLASH}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_ALWAYS_FLASH ON_ALWAYS_FLASH}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE ON_AUTO_FLASH_REDEYE}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES android.control.aeAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#FLASH_INFO_AVAILABLE
* @see CaptureRequest#FLASH_MODE
@@ -580,25 +652,35 @@
new Key<Integer>("android.control.aeMode", int.class);
/**
- * <p>List of areas to use for
- * metering.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0.
+ * <p>List of metering areas to use for auto-exposure adjustment.</p>
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of regions supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
* bottom-right pixel in the active pixel array.</p>
- * <p>The weight must range from 0 to 1000, and represents a weight
+ * <p>The weight must be within <code>[0, 1000]</code>, and represents a weight
* for every pixel in the area. This means that a large metering area
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other exposure metering regions, so if only one
+ * region is used, all non-zero weights will have the same effect. A region with 0
+ * weight is ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AE
@@ -610,12 +692,20 @@
new Key<android.hardware.camera2.params.MeteringRectangle[]>("android.control.aeRegions", android.hardware.camera2.params.MeteringRectangle[].class);
/**
- * <p>Range over which fps can be adjusted to
- * maintain exposure.</p>
+ * <p>Range over which the auto-exposure routine can
+ * adjust the capture frame rate to maintain good
+ * exposure.</p>
* <p>Only constrains auto-exposure (AE) algorithm, not
- * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p>
+ * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} and
+ * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}.</p>
+ * <p><b>Units</b>: Frames per second (FPS)</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any of the entries in {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES android.control.aeAvailableTargetFpsRanges}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
+ * @see CaptureRequest#SENSOR_FRAME_DURATION
*/
@PublicKey
public static final Key<android.util.Range<Integer>> CONTROL_AE_TARGET_FPS_RANGE =
@@ -640,8 +730,22 @@
* depends on the current AE mode and state; see
* {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition
* details.</p>
+ * <p>On LEGACY-level devices, the precapture trigger is not supported;
+ * capturing a high-resolution JPEG image will automatically trigger a
+ * precapture sequence before the high-resolution capture, including
+ * potentially firing a pre-capture flash.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE IDLE}</li>
+ * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_START START}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureResult#CONTROL_AE_STATE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE
* @see #CONTROL_AE_PRECAPTURE_TRIGGER_START
*/
@@ -831,12 +935,26 @@
* </tr>
* </tbody>
* </table>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_STATE_INACTIVE INACTIVE}</li>
+ * <li>{@link #CONTROL_AE_STATE_SEARCHING SEARCHING}</li>
+ * <li>{@link #CONTROL_AE_STATE_CONVERGED CONVERGED}</li>
+ * <li>{@link #CONTROL_AE_STATE_LOCKED LOCKED}</li>
+ * <li>{@link #CONTROL_AE_STATE_FLASH_REQUIRED FLASH_REQUIRED}</li>
+ * <li>{@link #CONTROL_AE_STATE_PRECAPTURE PRECAPTURE}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @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 CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #CONTROL_AE_STATE_INACTIVE
* @see #CONTROL_AE_STATE_SEARCHING
* @see #CONTROL_AE_STATE_CONVERGED
@@ -856,7 +974,20 @@
* <p>If the lens is controlled by the camera device auto-focus algorithm,
* the camera device will report the current AF status in {@link CaptureResult#CONTROL_AF_STATE android.control.afState}
* in result metadata.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AF_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AF_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_AF_MODE_MACRO MACRO}</li>
+ * <li>{@link #CONTROL_AF_MODE_CONTINUOUS_VIDEO CONTINUOUS_VIDEO}</li>
+ * <li>{@link #CONTROL_AF_MODE_CONTINUOUS_PICTURE CONTINUOUS_PICTURE}</li>
+ * <li>{@link #CONTROL_AF_MODE_EDOF EDOF}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES android.control.afAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES
* @see CaptureResult#CONTROL_AF_STATE
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
@@ -872,25 +1003,35 @@
new Key<Integer>("android.control.afMode", int.class);
/**
- * <p>List of areas to use for focus
- * estimation.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0.
+ * <p>List of metering areas to use for auto-focus.</p>
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of focus areas supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
* bottom-right pixel in the active pixel array.</p>
- * <p>The weight must range from 0 to 1000, and represents a weight
+ * <p>The weight must be within <code>[0, 1000]</code>, and represents a weight
* for every pixel in the area. This means that a large metering area
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other metering regions, so if only one region
+ * is used, all non-zero weights will have the same effect. A region with 0 weight is
+ * ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AF
@@ -914,6 +1055,13 @@
* START for multiple captures in a row means restarting the AF operation over
* and over again.</p>
* <p>See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what the trigger means for each AF mode.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AF_TRIGGER_IDLE IDLE}</li>
+ * <li>{@link #CONTROL_AF_TRIGGER_START START}</li>
+ * <li>{@link #CONTROL_AF_TRIGGER_CANCEL CANCEL}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureResult#CONTROL_AF_STATE
* @see #CONTROL_AF_TRIGGER_IDLE
@@ -1306,6 +1454,17 @@
* </tr>
* </tbody>
* </table>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AF_STATE_INACTIVE INACTIVE}</li>
+ * <li>{@link #CONTROL_AF_STATE_PASSIVE_SCAN PASSIVE_SCAN}</li>
+ * <li>{@link #CONTROL_AF_STATE_PASSIVE_FOCUSED PASSIVE_FOCUSED}</li>
+ * <li>{@link #CONTROL_AF_STATE_ACTIVE_SCAN ACTIVE_SCAN}</li>
+ * <li>{@link #CONTROL_AF_STATE_FOCUSED_LOCKED FOCUSED_LOCKED}</li>
+ * <li>{@link #CONTROL_AF_STATE_NOT_FOCUSED_LOCKED NOT_FOCUSED_LOCKED}</li>
+ * <li>{@link #CONTROL_AF_STATE_PASSIVE_UNFOCUSED PASSIVE_UNFOCUSED}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AF_MODE
* @see CaptureRequest#CONTROL_MODE
@@ -1325,9 +1484,26 @@
/**
* <p>Whether auto-white balance (AWB) is currently locked to its
* latest calculated values.</p>
+ * <p>When set to <code>true</code> (ON), the AWB algorithm is locked to its latest parameters,
+ * and will not change color balance settings until the lock is set to <code>false</code> (OFF).</p>
+ * <p>Since the camera device has a pipeline of in-flight requests, the settings that
+ * get locked do not necessarily correspond to the settings that were present in the
+ * latest capture result received from the camera device, since additional captures
+ * and AWB updates may have occurred even before the result was sent out. If an
+ * application is switching between automatic and manual control and wishes to eliminate
+ * any flicker during the switch, the following procedure is recommended:</p>
+ * <ol>
+ * <li>Starting in auto-AWB mode:</li>
+ * <li>Lock AWB</li>
+ * <li>Wait for the first result to be output that has the AWB locked</li>
+ * <li>Copy AWB settings from that result into a request, set the request to manual AWB</li>
+ * <li>Submit the capture request, proceed to run manual AWB as desired.</li>
+ * </ol>
* <p>Note that AWB lock is only meaningful when
* {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} is in the AUTO mode; in other modes,
* AWB is already fixed to a specific setting.</p>
+ * <p>Some LEGACY devices may not support ON; the value is then overridden to OFF.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AWB_MODE
*/
@@ -1355,10 +1531,26 @@
* {@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} are ignored.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AWB_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AWB_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_AWB_MODE_INCANDESCENT INCANDESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_FLUORESCENT FLUORESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_WARM_FLUORESCENT WARM_FLUORESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_DAYLIGHT DAYLIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_CLOUDY_DAYLIGHT CLOUDY_DAYLIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_TWILIGHT TWILIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_SHADE SHADE}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AWB_AVAILABLE_MODES android.control.awbAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#COLOR_CORRECTION_GAINS
* @see CaptureRequest#COLOR_CORRECTION_MODE
* @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
+ * @see CameraCharacteristics#CONTROL_AWB_AVAILABLE_MODES
* @see CaptureRequest#CONTROL_MODE
* @see #CONTROL_AWB_MODE_OFF
* @see #CONTROL_AWB_MODE_AUTO
@@ -1375,10 +1567,12 @@
new Key<Integer>("android.control.awbMode", int.class);
/**
- * <p>List of areas to use for illuminant
+ * <p>List of metering areas to use for auto-white-balance illuminant
* estimation.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0.
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of regions supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
@@ -1389,11 +1583,20 @@
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other white balance metering regions, so if
+ * only one region is used, all non-zero weights will have the same effect. A region with
+ * 0 weight is ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AWB
@@ -1413,7 +1616,18 @@
* <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF</code> and any 3A routine is active.</p>
* <p>ZERO_SHUTTER_LAG will be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
* contains ZSL. MANUAL will be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
- * contains MANUAL_SENSOR.</p>
+ * contains MANUAL_SENSOR. Other intent values are always supported.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_CUSTOM CUSTOM}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_PREVIEW PREVIEW}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_STILL_CAPTURE STILL_CAPTURE}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_VIDEO_RECORD VIDEO_RECORD}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT VIDEO_SNAPSHOT}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_ZERO_SHUTTER_LAG ZERO_SHUTTER_LAG}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_MANUAL MANUAL}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
@@ -1546,11 +1760,23 @@
* </tr>
* </tbody>
* </table>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AWB_STATE_INACTIVE INACTIVE}</li>
+ * <li>{@link #CONTROL_AWB_STATE_SEARCHING SEARCHING}</li>
+ * <li>{@link #CONTROL_AWB_STATE_CONVERGED CONVERGED}</li>
+ * <li>{@link #CONTROL_AWB_STATE_LOCKED LOCKED}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AWB_LOCK
* @see CaptureRequest#CONTROL_AWB_MODE
* @see CaptureRequest#CONTROL_MODE
* @see CaptureRequest#CONTROL_SCENE_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #CONTROL_AWB_STATE_INACTIVE
* @see #CONTROL_AWB_STATE_SEARCHING
* @see #CONTROL_AWB_STATE_CONVERGED
@@ -1568,10 +1794,23 @@
* implementor of the camera device, and should not be
* depended on to be consistent (or present) across all
* devices.</p>
- * <p>A color effect will only be applied if
- * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_EFFECT_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_MONO MONO}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_NEGATIVE NEGATIVE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_SOLARIZE SOLARIZE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_SEPIA SEPIA}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_POSTERIZE POSTERIZE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_WHITEBOARD WHITEBOARD}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_BLACKBOARD BLACKBOARD}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_AQUA AQUA}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS android.control.availableEffects}</p>
+ * <p>This key is available on all devices.</p>
*
- * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS
* @see #CONTROL_EFFECT_MODE_OFF
* @see #CONTROL_EFFECT_MODE_MONO
* @see #CONTROL_EFFECT_MODE_NEGATIVE
@@ -1587,9 +1826,9 @@
new Key<Integer>("android.control.effectMode", int.class);
/**
- * <p>Overall mode of 3A control
+ * <p>Overall mode of 3A (auto-exposure, auto-white-balance, auto-focus) control
* routines.</p>
- * <p>High-level 3A control. When set to OFF, all 3A control
+ * <p>This is a top-level 3A control switch. When set to OFF, all 3A control
* by the camera device is disabled. The application must set the fields for
* capture parameters itself.</p>
* <p>When set to AUTO, the individual algorithm controls in
@@ -1604,6 +1843,18 @@
* update, as if this frame is never captured. This mode can be used in the scenario
* where the application doesn't want a 3A manual control capture to affect
* the subsequent auto 3A capture results.</p>
+ * <p>LEGACY mode devices will only support AUTO and USE_SCENE_MODE modes.
+ * LIMITED mode devices will only support OFF and OFF_KEEP_STATE if they
+ * support the MANUAL_SENSOR and MANUAL_POST_PROCSESING capabilities.
+ * FULL mode devices will always support OFF and OFF_KEEP_STATE.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_MODE_USE_SCENE_MODE USE_SCENE_MODE}</li>
+ * <li>{@link #CONTROL_MODE_OFF_KEEP_STATE OFF_KEEP_STATE}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AF_MODE
* @see #CONTROL_MODE_OFF
@@ -1616,18 +1867,41 @@
new Key<Integer>("android.control.mode", int.class);
/**
- * <p>A camera mode optimized for conditions typical in a particular
- * capture setting.</p>
+ * <p>Control for which scene mode is currently active.</p>
+ * <p>Scene modes are custom camera modes optimized for a certain set of conditions and
+ * capture settings.</p>
* <p>This is the mode that that is active when
* <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code>. Aside from FACE_PRIORITY,
* these modes will disable {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode},
- * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.
- * The scene modes available for a given camera device are listed in
- * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes}.</p>
+ * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.</p>
* <p>The interpretation and implementation of these scene modes is left
* to the implementor of the camera device. Their behavior will not be
* consistent across all devices, and any given device may only implement
* a subset of these modes.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_SCENE_MODE_DISABLED DISABLED}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_FACE_PRIORITY FACE_PRIORITY}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_ACTION ACTION}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_PORTRAIT PORTRAIT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_LANDSCAPE LANDSCAPE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_NIGHT NIGHT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_NIGHT_PORTRAIT NIGHT_PORTRAIT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_THEATRE THEATRE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_BEACH BEACH}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SNOW SNOW}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SUNSET SUNSET}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_STEADYPHOTO STEADYPHOTO}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_FIREWORKS FIREWORKS}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SPORTS SPORTS}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_PARTY PARTY}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_CANDLELIGHT CANDLELIGHT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_BARCODE BARCODE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AF_MODE
@@ -1660,18 +1934,26 @@
/**
* <p>Whether video stabilization is
* active.</p>
- * <p>Video stabilization automatically translates and scales images from the camera
- * in order to stabilize motion between consecutive frames.</p>
+ * <p>Video stabilization automatically translates and scales images from
+ * the camera in order to stabilize motion between consecutive frames.</p>
* <p>If enabled, video stabilization can modify the
* {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream stabilized.</p>
- * <p>Switching between different video stabilization modes may take several frames
- * to initialize, the camera device will report the current mode in capture result
- * metadata. For example, When "ON" mode is requested, the video stabilization modes
- * in the first several capture results may still be "OFF", and it will become "ON"
- * when the initialization is done.</p>
- * <p>If a camera device supports both this mode and OIS ({@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}),
- * turning both modes on may produce undesirable interaction, so it is recommended not to
- * enable both at the same time.</p>
+ * <p>Switching between different video stabilization modes may take several
+ * frames to initialize, the camera device will report the current mode
+ * in capture result metadata. For example, When "ON" mode is requested,
+ * the video stabilization modes in the first several capture results may
+ * still be "OFF", and it will become "ON" when the initialization is
+ * done.</p>
+ * <p>If a camera device supports both this mode and OIS
+ * ({@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}), turning both modes on may
+ * produce undesirable interaction, so it is recommended not to enable
+ * both at the same time.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_VIDEO_STABILIZATION_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_VIDEO_STABILIZATION_MODE_ON ON}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE
* @see CaptureRequest#SCALER_CROP_REGION
@@ -1685,16 +1967,28 @@
/**
* <p>Operation mode for edge
* enhancement.</p>
- * <p>Edge/sharpness/detail enhancement. OFF means no
- * enhancement will be applied by the camera device.</p>
- * <p>This must be set to one of the modes listed in {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}.</p>
+ * <p>Edge enhancement improves sharpness and details in the captured image. OFF means
+ * no enhancement will be applied by the camera device.</p>
* <p>FAST/HIGH_QUALITY both mean camera device determined enhancement
* will be applied. HIGH_QUALITY mode indicates that the
* camera device will use the highest-quality enhancement algorithms,
* even if it slows down capture rate. FAST means the camera device will
* not slow down capture rate when applying edge enhancement.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #EDGE_MODE_OFF OFF}</li>
+ * <li>{@link #EDGE_MODE_FAST FAST}</li>
+ * <li>{@link #EDGE_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #EDGE_MODE_OFF
* @see #EDGE_MODE_FAST
* @see #EDGE_MODE_HIGH_QUALITY
@@ -1718,6 +2012,13 @@
* <p>When set to TORCH, the flash will be on continuously. This mode can be used
* for use cases such as preview, auto-focus assist, still capture, or video recording.</p>
* <p>The flash status will be reported by {@link CaptureResult#FLASH_STATE android.flash.state} in the capture result metadata.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #FLASH_MODE_OFF OFF}</li>
+ * <li>{@link #FLASH_MODE_SINGLE SINGLE}</li>
+ * <li>{@link #FLASH_MODE_TORCH TORCH}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
@@ -1737,8 +2038,33 @@
* <p>When the camera device doesn't have flash unit
* (i.e. <code>{@link CameraCharacteristics#FLASH_INFO_AVAILABLE android.flash.info.available} == false</code>), this state will always be UNAVAILABLE.
* Other states indicate the current flash status.</p>
+ * <p>In certain conditions, this will be available on LEGACY devices:</p>
+ * <ul>
+ * <li>Flash-less cameras always return UNAVAILABLE.</li>
+ * <li>Using {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>==</code> ON_ALWAYS_FLASH
+ * will always return FIRED.</li>
+ * <li>Using {@link CaptureRequest#FLASH_MODE android.flash.mode} <code>==</code> TORCH
+ * will always return FIRED.</li>
+ * </ul>
+ * <p>In all other conditions the state will not be available on
+ * LEGACY devices (i.e. it will be <code>null</code>).</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #FLASH_STATE_UNAVAILABLE UNAVAILABLE}</li>
+ * <li>{@link #FLASH_STATE_CHARGING CHARGING}</li>
+ * <li>{@link #FLASH_STATE_READY READY}</li>
+ * <li>{@link #FLASH_STATE_FIRED FIRED}</li>
+ * <li>{@link #FLASH_STATE_PARTIAL PARTIAL}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CaptureRequest#CONTROL_AE_MODE
* @see CameraCharacteristics#FLASH_INFO_AVAILABLE
+ * @see CaptureRequest#FLASH_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #FLASH_STATE_UNAVAILABLE
* @see #FLASH_STATE_CHARGING
* @see #FLASH_STATE_READY
@@ -1750,12 +2076,19 @@
new Key<Integer>("android.flash.state", int.class);
/**
- * <p>Set operational mode for hot pixel correction.</p>
- * <p>Valid modes for this camera device are listed in
- * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}.</p>
+ * <p>Operational mode for hot pixel correction.</p>
* <p>Hotpixel correction interpolates out, or otherwise removes, pixels
- * that do not accurately encode the incoming light (i.e. pixels that
- * are stuck at an arbitrary value).</p>
+ * that do not accurately measure the incoming light (i.e. pixels that
+ * are stuck at an arbitrary value or are oversensitive).</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #HOT_PIXEL_MODE_OFF OFF}</li>
+ * <li>{@link #HOT_PIXEL_MODE_FAST FAST}</li>
+ * <li>{@link #HOT_PIXEL_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES
* @see #HOT_PIXEL_MODE_OFF
@@ -1768,6 +2101,10 @@
/**
* <p>A location object to use when generating image GPS metadata.</p>
+ * <p>Setting a location object in a request will include the GPS coordinates of the location
+ * into any JPEG images captured based on the request. These coordinates can then be
+ * viewed by anyone who receives the JPEG image.</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
@SyntheticKey
@@ -1776,7 +2113,10 @@
/**
* <p>GPS coordinates to include in output JPEG
- * EXIF</p>
+ * EXIF.</p>
+ * <p><b>Range of valid values:</b><br>
+ * (-180 - 180], [-90,90], [-inf, inf]</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<double[]> JPEG_GPS_COORDINATES =
@@ -1784,7 +2124,9 @@
/**
* <p>32 characters describing GPS algorithm to
- * include in EXIF</p>
+ * include in EXIF.</p>
+ * <p><b>Units</b>: UTF-8 null-terminated string</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<String> JPEG_GPS_PROCESSING_METHOD =
@@ -1792,15 +2134,49 @@
/**
* <p>Time GPS fix was made to include in
- * EXIF</p>
+ * EXIF.</p>
+ * <p><b>Units</b>: UTC in seconds since January 1, 1970</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<Long> JPEG_GPS_TIMESTAMP =
new Key<Long>("android.jpeg.gpsTimestamp", long.class);
/**
- * <p>Orientation of JPEG image to
- * write</p>
+ * <p>The orientation for a JPEG image.</p>
+ * <p>The clockwise rotation angle in degrees, relative to the orientation
+ * to the camera, that the JPEG picture needs to be rotated by, to be viewed
+ * upright.</p>
+ * <p>Camera devices may either encode this value into the JPEG EXIF header, or
+ * rotate the image data to match this orientation.</p>
+ * <p>Note that this orientation is relative to the orientation of the camera sensor, given
+ * by {@link CameraCharacteristics#SENSOR_ORIENTATION android.sensor.orientation}.</p>
+ * <p>To translate from the device orientation given by the Android sensor APIs, the following
+ * sample code may be used:</p>
+ * <pre><code>private int getJpegOrientation(CameraCharacteristics c, int deviceOrientation) {
+ * if (deviceOrientation == android.view.OrientationEventListener.ORIENTATION_UNKNOWN) return 0;
+ * int sensorOrientation = c.get(CameraCharacteristics.SENSOR_ORIENTATION);
+ *
+ * // Round device orientation to a multiple of 90
+ * deviceOrientation = (deviceOrientation + 45) / 90 * 90;
+ *
+ * // Reverse device orientation for front-facing cameras
+ * boolean facingFront = c.get(CameraCharacteristics.LENS_FACING) == CameraCharacteristics.LENS_FACING_FRONT;
+ * if (facingFront) deviceOrientation = -deviceOrientation;
+ *
+ * // Calculate desired JPEG orientation relative to camera orientation to make
+ * // the image upright relative to the device orientation
+ * int jpegOrientation = (sensorOrientation + deviceOrientation + 360) % 360;
+ *
+ * return jpegOrientation;
+ * }
+ * </code></pre>
+ * <p><b>Units</b>: Degrees in multiples of 90</p>
+ * <p><b>Range of valid values:</b><br>
+ * 0, 90, 180, 270</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#SENSOR_ORIENTATION
*/
@PublicKey
public static final Key<Integer> JPEG_ORIENTATION =
@@ -1810,6 +2186,9 @@
* <p>Compression quality of the final JPEG
* image.</p>
* <p>85-95 is typical usage range.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 1-100; larger is higher quality</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Byte> JPEG_QUALITY =
@@ -1818,6 +2197,9 @@
/**
* <p>Compression quality of JPEG
* thumbnail.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 1-100; larger is higher quality</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Byte> JPEG_THUMBNAIL_QUALITY =
@@ -1827,25 +2209,29 @@
* <p>Resolution of embedded JPEG thumbnail.</p>
* <p>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail,
* but the captured JPEG will still be a valid image.</p>
- * <p>When a jpeg image capture is issued, the thumbnail size selected should have
- * the same aspect ratio as the jpeg image.</p>
+ * <p>For best results, when issuing a request for a JPEG image, the thumbnail size selected
+ * should have the same aspect ratio as the main JPEG output.</p>
* <p>If the thumbnail image aspect ratio differs from the JPEG primary image aspect
* ratio, the camera device creates the thumbnail by cropping it from the primary image.
* For example, if the primary image has 4:3 aspect ratio, the thumbnail image has
* 16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to
* generate the thumbnail image. The thumbnail image will always have a smaller Field
* Of View (FOV) than the primary image when aspect ratios differ.</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES android.jpeg.availableThumbnailSizes}</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES
*/
@PublicKey
public static final Key<android.util.Size> JPEG_THUMBNAIL_SIZE =
new Key<android.util.Size>("android.jpeg.thumbnailSize", android.util.Size.class);
/**
- * <p>The ratio of lens focal length to the effective
- * aperture diameter.</p>
- * <p>This will only be supported on the camera devices that
- * have variable aperture lens. The aperture value can only be
- * one of the values listed in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}.</p>
+ * <p>The desired lens aperture size, as a ratio of lens focal length to the
+ * effective aperture diameter.</p>
+ * <p>Setting this value is only supported on the camera devices that have a variable
+ * aperture lens.</p>
* <p>When this is supported and {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is OFF,
* this can be set along with {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
* {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}
@@ -1858,8 +2244,16 @@
* the ON modes, this will be overridden by the camera device
* auto-exposure algorithm, the overridden values are then provided
* back to the user in the corresponding result.</p>
+ * <p><b>Units</b>: The f-number (f/N)</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
* @see CaptureResult#LENS_STATE
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
@@ -1871,10 +2265,8 @@
new Key<Float>("android.lens.aperture", float.class);
/**
- * <p>State of lens neutral density filter(s).</p>
- * <p>This will not be supported on most camera devices. On devices
- * where this is supported, this may only be set to one of the
- * values included in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}.</p>
+ * <p>The desired setting for the lens neutral density filter(s).</p>
+ * <p>This control will not be supported on most camera devices.</p>
* <p>Lens filters are typically used to lower the amount of light the
* sensor is exposed to (measured in steps of EV). As used here, an EV
* step is the standard logarithmic representation, which are
@@ -1886,7 +2278,15 @@
* <p>It may take several frames before the lens filter density changes
* to the requested value. While the filter density is still changing,
* {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
+ * <p><b>Units</b>: Exposure Value (EV)</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES
* @see CaptureResult#LENS_STATE
*/
@@ -1895,7 +2295,7 @@
new Key<Float>("android.lens.filterDensity", float.class);
/**
- * <p>The current lens focal length; used for optical zoom.</p>
+ * <p>The desired lens focal length; used for optical zoom.</p>
* <p>This setting controls the physical focal length of the camera
* device's lens. Changing the focal length changes the field of
* view of the camera device, and is usually used for optical zoom.</p>
@@ -1904,10 +2304,15 @@
* frames before the lens can change to the requested focal length.
* While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will
* be set to MOVING.</p>
- * <p>This is expected not to be supported on most devices.</p>
+ * <p>Optical zoom will not be supported on most devices.</p>
+ * <p><b>Units</b>: Millimeters</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#LENS_APERTURE
* @see CaptureRequest#LENS_FOCUS_DISTANCE
+ * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS
* @see CaptureResult#LENS_STATE
*/
@PublicKey
@@ -1915,9 +2320,19 @@
new Key<Float>("android.lens.focalLength", float.class);
/**
- * <p>Distance to plane of sharpest focus,
+ * <p>Desired distance to plane of sharpest focus,
* measured from frontmost surface of the lens.</p>
* <p>Should be zero for fixed-focus cameras</p>
+ * <p><b>Units</b>: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 0</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
*/
@PublicKey
public static final Key<Float> LENS_FOCUS_DISTANCE =
@@ -1928,6 +2343,17 @@
* sharp focus (depth of field).</p>
* <p>If variable focus not supported, can still report
* fixed depth of field range</p>
+ * <p><b>Units</b>: A pair of focus distances in diopters: (near,
+ * far); see {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details.</p>
+ * <p><b>Range of valid values:</b><br>
+ * >=0</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
*/
@PublicKey
public static final Key<android.util.Pair<Float,Float>> LENS_FOCUS_RANGE =
@@ -1947,14 +2373,26 @@
* capture result metadata. For example, When "ON" mode is requested, the
* optical stabilization modes in the first several capture results may still
* be "OFF", and it will become "ON" when the initialization is done.</p>
- * <p>If a camera device supports both OIS and EIS ({@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}),
- * turning both modes on may produce undesirable interaction, so it is recommended not
- * to enable both at the same time.</p>
+ * <p>If a camera device supports both OIS and digital image stabilization
+ * ({@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}), turning both modes on may produce undesirable
+ * interaction, so it is recommended not to enable both at the same time.</p>
* <p>Not all devices will support OIS; see
* {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for
* available controls.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LENS_OPTICAL_STABILIZATION_MODE_OFF OFF}</li>
+ * <li>{@link #LENS_OPTICAL_STABILIZATION_MODE_ON ON}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION
* @see #LENS_OPTICAL_STABILIZATION_MODE_OFF
* @see #LENS_OPTICAL_STABILIZATION_MODE_ON
@@ -1984,7 +2422,17 @@
* <p>Then this state will always be STATIONARY.</p>
* <p>When the state is MOVING, it indicates that at least one of the lens parameters
* is changing.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LENS_STATE_STATIONARY STATIONARY}</li>
+ * <li>{@link #LENS_STATE_MOVING MOVING}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#LENS_APERTURE
* @see CaptureRequest#LENS_FILTER_DENSITY
* @see CaptureRequest#LENS_FOCAL_LENGTH
@@ -2002,16 +2450,28 @@
/**
* <p>Mode of operation for the noise reduction algorithm.</p>
- * <p>Noise filtering control. OFF means no noise reduction
- * will be applied by the camera device.</p>
- * <p>This must be set to a valid mode from
- * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.</p>
+ * <p>The noise reduction algorithm attempts to improve image quality by removing
+ * excessive noise added by the capture process, especially in dark conditions.
+ * OFF means no noise reduction will be applied by the camera device.</p>
* <p>FAST/HIGH_QUALITY both mean camera device determined noise filtering
* will be applied. HIGH_QUALITY mode indicates that the camera device
* will use the highest-quality noise filtering algorithms,
* even if it slows down capture rate. FAST means the camera device will not
* slow down capture rate when applying noise filtering.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #NOISE_REDUCTION_MODE_OFF OFF}</li>
+ * <li>{@link #NOISE_REDUCTION_MODE_FAST FAST}</li>
+ * <li>{@link #NOISE_REDUCTION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES
* @see #NOISE_REDUCTION_MODE_OFF
* @see #NOISE_REDUCTION_MODE_FAST
@@ -2035,6 +2495,8 @@
* in any order relative to other frames, but all PARTIAL buffers for a given
* capture must arrive before the FINAL buffer for that capture. This entry may
* only be used by the camera device if quirks.usePartialResult is set to 1.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Optional. Default value is FINAL.</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
@@ -2048,6 +2510,10 @@
* increases with every new result (that is, each new result has a unique
* frameCount value).</p>
* <p>Reset on release()</p>
+ * <p><b>Units</b>: count of frames</p>
+ * <p><b>Range of valid values:</b><br>
+ * > 0</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
*/
@@ -2059,6 +2525,10 @@
* <p>An application-specified ID for the current
* request. Must be maintained unchanged in output
* frame</p>
+ * <p><b>Units</b>: arbitrary integer assigned by application</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any int</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @hide
*/
public static final Key<Integer> REQUEST_ID =
@@ -2072,6 +2542,9 @@
* what streams are configured, the data may undergo less processing,
* and some pipeline stages skipped.</p>
* <p>See {@link CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH android.request.pipelineMaxDepth} for more details.</p>
+ * <p><b>Range of valid values:</b><br>
+ * <= {@link CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH android.request.pipelineMaxDepth}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH
*/
@@ -2080,7 +2553,8 @@
new Key<Byte>("android.request.pipelineDepth", byte.class);
/**
- * <p>The region of the sensor to read out for this capture.</p>
+ * <p>The desired region of the sensor to read out for this capture.</p>
+ * <p>This control can be used to implement digital zoom.</p>
* <p>The crop region coordinate system is based off
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with <code>(0, 0)</code> being the
* top-left corner of the sensor active array.</p>
@@ -2110,6 +2584,9 @@
* for rounding and other hardware requirements; the final
* crop region used will be included in the output capture
* result.</p>
+ * <p><b>Units</b>: Pixel coordinates relative to
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
@@ -2121,8 +2598,23 @@
/**
* <p>Duration each pixel is exposed to
* light.</p>
- * <p>If the sensor can't expose this exact duration, it should shorten the
- * duration exposed to the nearest possible value (rather than expose longer).</p>
+ * <p>If the sensor can't expose this exact duration, it will shorten the
+ * duration exposed to the nearest possible value (rather than expose longer).
+ * The final exposure time used will be available in the output capture result.</p>
+ * <p>This control is only effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} is set to
+ * OFF; otherwise the auto-exposure algorithm will override this value.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE android.sensor.info.exposureTimeRange}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CaptureRequest#CONTROL_AE_MODE
+ * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE
*/
@PublicKey
public static final Key<Long> SENSOR_EXPOSURE_TIME =
@@ -2200,8 +2692,23 @@
* delivered.</p>
* <p>For more details about stalling, see
* StreamConfigurationMap#getOutputStallDuration(int,Size).</p>
+ * <p>This control is only effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} is set to
+ * OFF; otherwise the auto-exposure algorithm will override this value.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * See {@link CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION android.sensor.info.maxFrameDuration},
+ * {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}. The duration
+ * is capped to <code>max(duration, exposureTime + overhead)</code>.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CaptureRequest#CONTROL_AE_MODE
+ * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
+ * @see CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION
*/
@PublicKey
public static final Key<Long> SENSOR_FRAME_DURATION =
@@ -2219,7 +2726,15 @@
* requested, it will reduce the gain to the nearest supported
* value. The final sensitivity used will be available in the
* output capture result.</p>
+ * <p><b>Units</b>: ISO arithmetic units</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE
* @see CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY
*/
@@ -2243,6 +2758,10 @@
* android.os.SystemClock#elapsedRealtimeNanos(), and they can be
* compared to other timestamps from other subsystems that are using
* that base.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * > 0</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_TIMESTAMP_SOURCE
*/
@@ -2267,10 +2786,10 @@
/**
* <p>Noise model coefficients for each CFA mosaic channel.</p>
- * <p>This tag contains two noise model coefficients for each CFA channel
+ * <p>This key contains two noise model coefficients for each CFA channel
* corresponding to the sensor amplification (S) and sensor readout
* noise (O). These are given as pairs of coefficients for each channel
- * in the same order as channels listed for the CFA layout tag
+ * in the same order as channels listed for the CFA layout key
* (see {@link CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT android.sensor.info.colorFilterArrangement}). This is
* represented as an array of Pair<Double, Double>, where
* the first member of the Pair at index n is the S coefficient and the
@@ -2324,6 +2843,8 @@
* <li>R > 1.20 will require strong software correction to produce
* a usuable image (>20% divergence).</li>
* </ul>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>>= 0</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*/
@PublicKey
@@ -2356,7 +2877,21 @@
* <p>For example, if manual flash is enabled, flash firing should still
* occur (and that the test pattern remain unmodified, since the flash
* would not actually affect it).</p>
+ * <p>Defaults to OFF.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_OFF OFF}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR SOLID_COLOR}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS COLOR_BARS}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS_FADE_TO_GRAY COLOR_BARS_FADE_TO_GRAY}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_PN9 PN9}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_CUSTOM1 CUSTOM1}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES android.sensor.availableTestPatternModes}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ *
+ * @see CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES
* @see #SENSOR_TEST_PATTERN_MODE_OFF
* @see #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR
* @see #SENSOR_TEST_PATTERN_MODE_COLOR_BARS
@@ -2371,12 +2906,22 @@
/**
* <p>Duration between the start of first row exposure
* and the start of last row exposure.</p>
- * <p>This is the exposure time skew (in the unit of nanosecond) between the first and
- * last row exposure start times. The first row and the last row are the first
- * and last rows inside of the {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</p>
+ * <p>This is the exposure time skew between the first and last
+ * row exposure start times. The first row and the last row are
+ * the first and last rows inside of the
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</p>
* <p>For typical camera sensors that use rolling shutters, this is also equivalent
* to the frame readout time.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 0 and <
+ * StreamConfigurationMap#getOutputMinFrameDuration(int, Size).</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
*/
@PublicKey
@@ -2389,30 +2934,41 @@
* <p>When set to OFF mode, no lens shading correction will be applied by the
* camera device, and an identity lens shading map data will be provided
* if <code>{@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON</code>. For example, for lens
- * shading map with size specified as <code>android.lens.info.shadingMapSize = [ 4, 3 ]</code>,
- * the output android.statistics.lensShadingMap for this case will be an identity map
- * shown below:</p>
+ * shading map with size of <code>[ 4, 3 ]</code>,
+ * the output {@link CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP android.statistics.lensShadingCorrectionMap} for this case will be an identity
+ * map shown below:</p>
* <pre><code>[ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ]
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ]
* </code></pre>
- * <p>When set to other modes, lens shading correction will be applied by the
- * camera device. Applications can request lens shading map data by setting
- * {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} to ON, and then the camera device will provide
- * lens shading map data in android.statistics.lensShadingMap, with size specified
- * by android.lens.info.shadingMapSize; the returned shading map data will be the one
- * applied by the camera device for this capture request.</p>
- * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore the reliability
- * of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in
- * AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code> OFF),
- * to get best results, it is recommended that the applications wait for the AE and AWB to
- * be converged before using the returned shading map data.</p>
+ * <p>When set to other modes, lens shading correction will be applied by the camera
+ * device. Applications can request lens shading map data by setting
+ * {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} to ON, and then the camera device will provide lens
+ * shading map data in {@link CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP android.statistics.lensShadingCorrectionMap}; the returned shading map
+ * data will be the one applied by the camera device for this capture request.</p>
+ * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore
+ * the reliability of the map data may be affected by the AE and AWB algorithms. When AE and
+ * AWB are in AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code>
+ * OFF), to get best results, it is recommended that the applications wait for the AE and AWB
+ * to be converged before using the returned shading map data.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SHADING_MODE_OFF OFF}</li>
+ * <li>{@link #SHADING_MODE_FAST FAST}</li>
+ * <li>{@link #SHADING_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AWB_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP
* @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE
* @see #SHADING_MODE_OFF
* @see #SHADING_MODE_FAST
@@ -2423,12 +2979,20 @@
new Key<Integer>("android.shading.mode", int.class);
/**
- * <p>Control for the face detector
+ * <p>Operating mode for the face detector
* unit.</p>
* <p>Whether face detection is enabled, and whether it
* should output just the basic fields or the full set of
- * fields. Value must be one of the
- * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}.</p>
+ * fields.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_OFF OFF}</li>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_SIMPLE SIMPLE}</li>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_FULL FULL}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES
* @see #STATISTICS_FACE_DETECT_MODE_OFF
@@ -2444,7 +3008,8 @@
* <p>Each detected face is given a unique ID that is valid for as long as the face is visible
* to the camera device. A face that leaves the field of view and later returns may be
* assigned a new ID.</p>
- * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL</p>
+ * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL
+ * This key is available on all devices.</p>
*
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
* @hide
@@ -2457,7 +3022,8 @@
* faces.</p>
* <p>The coordinate system is that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with
* <code>(0, 0)</code> being the top-left pixel of the active array.</p>
- * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL</p>
+ * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL
+ * This key is available on all devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
@@ -2471,7 +3037,8 @@
* faces.</p>
* <p>The coordinate system is that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with
* <code>(0, 0)</code> being the top-left pixel of the active array.</p>
- * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF</p>
+ * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF
+ * This key is available on all devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
@@ -2484,6 +3051,9 @@
* <p>List of the face confidence scores for
* detected faces</p>
* <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 1-100</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
* @hide
@@ -2493,8 +3063,9 @@
/**
* <p>List of the faces detected through camera face detection
- * in this result.</p>
+ * in this capture.</p>
* <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} <code>!=</code> OFF.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
*/
@@ -2528,11 +3099,11 @@
* <pre><code>width,height = [ 4, 3 ]
* values =
* [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2,
- * 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3,
- * 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2,
- * 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2,
- * 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ]
+ * 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3,
+ * 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2,
+ * 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2,
+ * 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ]
* </code></pre>
* <p>The low-resolution scaling map images for each channel are
* (displayed using nearest-neighbor interpolation):</p>
@@ -2543,8 +3114,15 @@
* <p>As a visualization only, inverting the full-color map to recover an
* image of a gray wall (using bicubic interpolation for visual quality) as captured by the sensor gives:</p>
* <p><img alt="Image of a uniform white wall (inverse shading map)" src="../../../../images/camera2/metadata/android.statistics.lensShadingMap/inv_shading.png" /></p>
+ * <p><b>Range of valid values:</b><br>
+ * Each gain factor is >= 1</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<android.hardware.camera2.params.LensShadingMap> STATISTICS_LENS_SHADING_CORRECTION_MAP =
@@ -2576,11 +3154,11 @@
* <pre><code>android.lens.info.shadingMapSize = [ 4, 3 ]
* android.statistics.lensShadingMap =
* [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2,
- * 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3,
- * 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2,
- * 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2,
- * 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ]
+ * 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3,
+ * 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2,
+ * 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2,
+ * 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ]
* </code></pre>
* <p>The low-resolution scaling map images for each channel are
* (displayed using nearest-neighbor interpolation):</p>
@@ -2591,8 +3169,15 @@
* <p>As a visualization only, inverting the full-color map to recover an
* image of a gray wall (using bicubic interpolation for visual quality) as captured by the sensor gives:</p>
* <p><img alt="Image of a uniform white wall (inverse shading map)" src="../../../../images/camera2/metadata/android.statistics.lensShadingMap/inv_shading.png" /></p>
+ * <p><b>Range of valid values:</b><br>
+ * Each gain factor is >= 1</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<float[]> STATISTICS_LENS_SHADING_MAP =
@@ -2659,10 +3244,21 @@
* into this metadata field. See
* {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} for more details.</p>
* <p>Reports NONE if there doesn't appear to be flickering illumination.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #STATISTICS_SCENE_FLICKER_NONE NONE}</li>
+ * <li>{@link #STATISTICS_SCENE_FLICKER_50HZ 50HZ}</li>
+ * <li>{@link #STATISTICS_SCENE_FLICKER_60HZ 60HZ}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AE_ANTIBANDING_MODE
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #STATISTICS_SCENE_FLICKER_NONE
* @see #STATISTICS_SCENE_FLICKER_50HZ
* @see #STATISTICS_SCENE_FLICKER_60HZ
@@ -2672,10 +3268,12 @@
new Key<Integer>("android.statistics.sceneFlicker", int.class);
/**
- * <p>Operating mode for hotpixel map generation.</p>
- * <p>If set to ON, a hotpixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.
- * If set to OFF, no hotpixel map will be returned.</p>
- * <p>This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}.</p>
+ * <p>Operating mode for hot pixel map generation.</p>
+ * <p>If set to <code>true</code>, a hot pixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.
+ * If set to <code>false</code>, no hot pixel map will be returned.</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CaptureResult#STATISTICS_HOT_PIXEL_MAP
* @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES
@@ -2692,6 +3290,11 @@
* height dimensions are given in {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.
* This may include hot pixels that lie outside of the active array
* bounds given by {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>n <= number of pixels on the sensor.
+ * The <code>(x, y)</code> coordinates must be bounded by
+ * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
* @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE
@@ -2706,6 +3309,18 @@
* <p>When set to ON,
* android.statistics.lensShadingMap will be provided in
* the output result metadata.</p>
+ * <p>ON is always supported on devices with the RAW capability.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #STATISTICS_LENS_SHADING_MAP_MODE_OFF OFF}</li>
+ * <li>{@link #STATISTICS_LENS_SHADING_MAP_MODE_ON ON}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #STATISTICS_LENS_SHADING_MAP_MODE_OFF
* @see #STATISTICS_LENS_SHADING_MAP_MODE_ON
*/
@@ -2718,7 +3333,12 @@
* channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
* <p>See android.tonemap.curveRed for more details.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_MODE
* @hide
*/
@@ -2730,7 +3350,12 @@
* channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
* <p>See android.tonemap.curveRed for more details.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_MODE
* @hide
*/
@@ -2743,10 +3368,10 @@
* CONTRAST_CURVE.</p>
* <p>Each channel's curve is defined by an array of control points:</p>
* <pre><code>android.tonemap.curveRed =
- * [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
+ * [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
* 2 <= N <= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
- * <p>These are sorted in order of increasing <code>Pin</code>; it is always
- * guaranteed that input values 0.0 and 1.0 are included in the list to
+ * <p>These are sorted in order of increasing <code>Pin</code>; it is
+ * required that input values 0.0 and 1.0 are included in the list to
* define a complete mapping. For input values between control points,
* the camera device must linearly interpolate between the control
* points.</p>
@@ -2767,21 +3392,29 @@
* <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
* <p>Gamma 1/2.2 mapping, with 16 control points:</p>
* <pre><code>android.tonemap.curveRed = [
- * 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812,
- * 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072,
- * 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685,
- * 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ]
+ * 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812,
+ * 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072,
+ * 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685,
+ * 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ]
* </code></pre>
* <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
* <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
* <pre><code>android.tonemap.curveRed = [
- * 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845,
- * 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130,
- * 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721,
- * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ]
+ * 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845,
+ * 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130,
+ * 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721,
+ * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ]
* </code></pre>
* <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
+ * <p><b>Range of valid values:</b><br>
+ * 0-1 on both input and output coordinates, normalized
+ * as a floating-point value such that 0 == black and 1 == white.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
* @see CaptureRequest#TONEMAP_MODE
* @hide
@@ -2797,7 +3430,7 @@
* example. The same logic applies to green and blue channel.
* Each channel's curve is defined by an array of control points:</p>
* <pre><code>curveRed =
- * [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ]
+ * [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ]
* 2 <= N <= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
* <p>These are sorted in order of increasing <code>Pin</code>; it is always
* guaranteed that input values 0.0 and 1.0 are included in the list to
@@ -2821,21 +3454,26 @@
* <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
* <p>Gamma 1/2.2 mapping, with 16 control points:</p>
* <pre><code>curveRed = [
- * (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812),
- * (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072),
- * (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685),
- * (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ]
+ * (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812),
+ * (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072),
+ * (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685),
+ * (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ]
* </code></pre>
* <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
* <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
* <pre><code>curveRed = [
- * (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845),
- * (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130),
- * (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721),
- * (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ]
+ * (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845),
+ * (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130),
+ * (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721),
+ * (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ]
* </code></pre>
* <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
* @see CaptureRequest#TONEMAP_MODE
*/
@@ -2857,8 +3495,6 @@
* tables, selective chroma enhancement, or other non-linear color
* transforms will be disabled when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
- * <p>This must be set to a valid mode in
- * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}.</p>
* <p>When using either FAST or HIGH_QUALITY, the camera device will
* emit its own tonemap curve in {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}.
* These values are always available, and as close as possible to the
@@ -2866,7 +3502,20 @@
* <p>If a request is sent with CONTRAST_CURVE with the camera device's
* provided curve in FAST or HIGH_QUALITY, the image's tonemap will be
* roughly the same.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #TONEMAP_MODE_CONTRAST_CURVE CONTRAST_CURVE}</li>
+ * <li>{@link #TONEMAP_MODE_FAST FAST}</li>
+ * <li>{@link #TONEMAP_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES
* @see CaptureRequest#TONEMAP_CURVE
* @see CaptureRequest#TONEMAP_MODE
@@ -2889,6 +3538,7 @@
* data is stored locally on the device.</p>
* <p>The LED <em>may</em> be off if a trusted application is using the data that
* doesn't violate the above rules.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @hide
*/
public static final Key<Boolean> LED_TRANSMIT =
@@ -2901,8 +3551,13 @@
* ON if {@link CaptureRequest#BLACK_LEVEL_LOCK android.blackLevel.lock} was ON in the capture request, unless
* a change in other capture settings forced the camera device to
* perform a black level reset.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#BLACK_LEVEL_LOCK
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<Boolean> BLACK_LEVEL_LOCK =
@@ -2960,6 +3615,15 @@
* <p>In other words, results for this current request and up to
* {@link CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH android.request.pipelineMaxDepth} prior requests may have their
* android.sync.frameNumber change to CONVERGING.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SYNC_FRAME_NUMBER_CONVERGING CONVERGING}</li>
+ * <li>{@link #SYNC_FRAME_NUMBER_UNKNOWN UNKNOWN}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * Either a non-negative value corresponding to a
+ * <code>frame_number</code>, or one of the two enums (CONVERGING / UNKNOWN).</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH
* @see #SYNC_FRAME_NUMBER_CONVERGING
@@ -2973,4 +3637,6 @@
* End generated code
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/
+
+
}