diff options
Diffstat (limited to 'core/java/android/hardware')
4 files changed, 2086 insertions, 484 deletions
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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * {@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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * </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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * </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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * </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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * </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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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 @@ public abstract class CameraMetadata<TKey> { * <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 @@ public abstract class CameraMetadata<TKey> { * <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 @@ public abstract class CameraMetadata<TKey> { * {@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 @@ public abstract class CameraMetadata<TKey> { * 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 @@ public abstract class CameraMetadata<TKey> { /** * <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 @@ public abstract class CameraMetadata<TKey> { /** * <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 @@ public abstract class CameraMetadata<TKey> { /** * <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 @@ public abstract class CameraMetadata<TKey> { * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * </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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * {@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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * </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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * </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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * </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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * {@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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * </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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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> - * - * @see CaptureRequest#CONTROL_MODE + * <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 CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS * @see #CONTROL_EFFECT_MODE_OFF * @see #CONTROL_EFFECT_MODE_MONO * @see #CONTROL_EFFECT_MODE_NEGATIVE @@ -1587,9 +1826,9 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * 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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * End generated code *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/ + + } |