From 4b8cd6b44cf800cf5dd88e5afbcff4968398779d Mon Sep 17 00:00:00 2001 From: Igor Murashkin Date: Thu, 2 Oct 2014 16:00:52 -0700 Subject: camera2: Update docs only for legacy devices Bug: 17788234 Change-Id: Ie88f3750cc06d889c6750f2099598d53ccb601b7 --- .../hardware/camera2/CameraCharacteristics.java | 180 +++++++++++++++- .../android/hardware/camera2/CameraMetadata.java | 6 + .../android/hardware/camera2/CaptureRequest.java | 163 ++++++++++++++- .../android/hardware/camera2/CaptureResult.java | 232 ++++++++++++++++++++- 4 files changed, 560 insertions(+), 21 deletions(-) diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java index 55ca4865b409..54f7e37a4228 100644 --- a/core/java/android/hardware/camera2/CameraCharacteristics.java +++ b/core/java/android/hardware/camera2/CameraCharacteristics.java @@ -318,6 +318,8 @@ public final class CameraCharacteristics extends CameraMetadata *

For FULL capability device ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL), OFF must be * included.

+ *

LEGACY devices will always only support FAST mode.

+ *

This key is available on all devices.

* * @see CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL @@ -333,6 +335,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

This key is available on all devices.

*/ @PublicKey public static final Key CONTROL_AE_AVAILABLE_ANTIBANDING_MODES = @@ -345,12 +348,15 @@ public final class CameraCharacteristics extends CameraMetadata - *

All camera devices support ON, and all camera devices with - * flash units support ON_AUTO_FLASH and - * ON_ALWAYS_FLASH.

+ *

All camera devices support ON, and all camera devices with flash + * units support ON_AUTO_FLASH and ON_ALWAYS_FLASH.

*

FULL mode camera devices always support OFF mode, * which enables application control of camera exposure time, * sensitivity, and frame duration.

+ *

LEGACY mode camera devices never support OFF mode. + * LIMITED mode devices support OFF if they support the MANUAL_SENSOR + * capability.

+ *

This key is available on all devices.

* * @see CaptureRequest#CONTROL_AE_MODE */ @@ -361,6 +367,7 @@ public final class CameraCharacteristics extends CameraMetadataList of frame rate ranges supported by the * auto-exposure (AE) algorithm/hardware

+ *

This key is available on all devices.

*/ @PublicKey public static final Key[]> CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES = @@ -370,6 +377,7 @@ public final class CameraCharacteristics extends CameraMetadataMaximum and minimum exposure compensation * setting, in counts of * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep}.

+ *

This key is available on all devices.

* * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP */ @@ -380,6 +388,7 @@ public final class CameraCharacteristics extends CameraMetadataSmallest step by which exposure compensation * can be changed

+ *

This key is available on all devices.

*/ @PublicKey public static final Key CONTROL_AE_COMPENSATION_STEP = @@ -394,8 +403,13 @@ public final class CameraCharacteristics extends CameraMetadataAll LIMITED and FULL mode camera devices will support OFF mode, and all * camera devices with adjustable focuser units * ({@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} > 0) will support AUTO mode.

+ *

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 + * 0.0f).

+ *

This key is available on all devices.

* * @see CaptureRequest#CONTROL_AF_MODE + * @see CaptureRequest#LENS_FOCUS_DISTANCE * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE */ @PublicKey @@ -414,6 +428,7 @@ public final class CameraCharacteristics extends CameraMetadata *

A color effect will only be applied if * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.

+ *

This key is available on all devices.

* * @see CaptureRequest#CONTROL_EFFECT_MODE * @see CaptureRequest#CONTROL_MODE @@ -430,6 +445,7 @@ public final class CameraCharacteristics extends CameraMetadata[DISABLED].

+ *

This key is available on all devices.

* * @see CaptureRequest#CONTROL_SCENE_MODE */ @@ -440,6 +456,7 @@ public final class CameraCharacteristics extends CameraMetadataList of video stabilization modes that can * be supported

+ *

This key is available on all devices.

*/ @PublicKey public static final Key CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES = @@ -455,6 +472,7 @@ public final class CameraCharacteristics extends CameraMetadataFULL 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).

+ *

This key is available on all devices.

* * @see CaptureRequest#COLOR_CORRECTION_GAINS * @see CaptureRequest#COLOR_CORRECTION_MODE @@ -471,6 +489,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

This key is available on all devices.

* * @see CaptureRequest#CONTROL_AE_REGIONS * @see CaptureRequest#CONTROL_AF_REGIONS @@ -485,6 +504,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

This key is available on all devices.

* * @see CaptureRequest#CONTROL_AE_REGIONS */ @@ -498,6 +518,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

This key is available on all devices.

* * @see CaptureRequest#CONTROL_AWB_REGIONS */ @@ -511,6 +532,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

This key is available on all devices.

* * @see CaptureRequest#CONTROL_AF_REGIONS */ @@ -541,9 +563,14 @@ public final class CameraCharacteristics extends CameraMetadata + *

Optional - This value may be {@code null} on some devices.

+ *

Limited capability - + * 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

* * @see CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES * @see CaptureRequest#CONTROL_SCENE_MODE + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @hide */ public static final Key CONTROL_AVAILABLE_HIGH_SPEED_VIDEO_CONFIGURATIONS = @@ -553,8 +580,13 @@ public final class CameraCharacteristics extends CameraMetadataThe set of edge enhancement modes supported by this camera device.

*

This tag lists the valid modes for {@link CaptureRequest#EDGE_MODE android.edge.mode}.

*

Full-capability camera devices must always support OFF and FAST.

+ *

Optional - This value may be {@code null} on some devices.

+ *

Full capability - + * 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

* * @see CaptureRequest#EDGE_MODE + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key EDGE_AVAILABLE_EDGE_MODES = @@ -564,7 +596,8 @@ public final class CameraCharacteristics extends CameraMetadataWhether this camera device has a * flash.

*

If no flash, none of the flash controls do - * anything. All other metadata should return 0.

+ * anything. All other metadata should return 0. + * This key is available on all devices.

*/ @PublicKey public static final Key FLASH_INFO_AVAILABLE = @@ -575,6 +608,7 @@ public final class CameraCharacteristics extends CameraMetadata *

This tag lists valid modes for {@link CaptureRequest#HOT_PIXEL_MODE android.hotPixel.mode}.

*

FULL mode camera devices will always support FAST.

+ *

Optional - This value may be {@code null} on some devices.

* * @see CaptureRequest#HOT_PIXEL_MODE */ @@ -595,7 +629,8 @@ public final class CameraCharacteristics extends CameraMetadataEach 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. - *
  • All non (0, 0) sizes will have non-zero widths and heights.
    • + *
  • All non (0, 0) sizes will have non-zero widths and heights. + * This key is available on all devices.
    • * */ @PublicKey @@ -609,6 +644,12 @@ public final class CameraCharacteristics extends CameraMetadata *

    If the camera device supports variable apertures, the aperture value * in this list will be sorted in ascending order.

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Full capability - + * 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

    + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key LENS_INFO_AVAILABLE_APERTURES = @@ -621,7 +662,12 @@ public final class CameraCharacteristics extends CameraMetadata + *

    Optional - This value may be {@code null} on some devices.

    + *

    Full capability - + * 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

    * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#LENS_FILTER_DENSITY */ @PublicKey @@ -635,6 +681,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

    This key is available on all devices.

    * * @see CaptureRequest#LENS_FOCAL_LENGTH */ @@ -648,7 +695,12 @@ public final class CameraCharacteristics extends CameraMetadata *

    If OIS is not implemented for a given camera device, this will * contain only OFF.

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Limited capability - + * 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

    * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE */ @PublicKey @@ -660,7 +712,11 @@ public final class CameraCharacteristics extends CameraMetadataIf 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.

    *

    Optional - This value may be {@code null} on some devices.

    + *

    Limited capability - + * 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

    * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION */ @PublicKey @@ -673,6 +729,11 @@ public final class CameraCharacteristics extends CameraMetadataIf the lens is fixed-focus, this should be * 0.

    *

    Optional - This value may be {@code null} on some devices.

    + *

    Limited capability - + * 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

    + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key LENS_INFO_MINIMUM_FOCUS_DISTANCE = @@ -682,6 +743,12 @@ public final class CameraCharacteristics extends CameraMetadataDimensions of lens shading map.

    *

    The map should be on the order of 30-40 rows and columns, and * must be smaller than 64x64.

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Full capability - + * 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

    + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @hide */ public static final Key LENS_INFO_SHADING_MAP_SIZE = @@ -693,7 +760,12 @@ public final class CameraCharacteristics extends CameraMetadata + *

    Optional - This value may be {@code null} on some devices.

    + *

    Limited capability - + * 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

    * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#LENS_FOCUS_DISTANCE * @see CaptureResult#LENS_FOCUS_RANGE * @see CameraCharacteristics#LENS_INFO_HYPERFOCAL_DISTANCE @@ -709,6 +781,7 @@ public final class CameraCharacteristics extends CameraMetadataDirection the camera faces relative to * device screen.

    + *

    This key is available on all devices.

    * @see #LENS_FACING_FRONT * @see #LENS_FACING_BACK */ @@ -720,7 +793,13 @@ public final class CameraCharacteristics extends CameraMetadataThe set of noise reduction modes supported by this camera device.

    *

    This tag lists the valid modes for {@link CaptureRequest#NOISE_REDUCTION_MODE android.noiseReduction.mode}.

    *

    Full-capability camera devices must always support OFF and FAST.

    + *

    Legacy-capability camera devices will only support FAST mode.

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Limited capability - + * 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

    * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#NOISE_REDUCTION_MODE */ @PublicKey @@ -765,6 +844,7 @@ public final class CameraCharacteristics extends CameraMetadataProcessed (but not-stalling): any non-RAW format without a stall duration. * Typically ImageFormat#YUV_420_888, ImageFormat#NV21, ImageFormat#YV12. * + *

    This key is available on all devices.

    * @hide */ public static final Key REQUEST_MAX_NUM_OUTPUT_STREAMS = @@ -786,7 +866,11 @@ public final class CameraCharacteristics extends CameraMetadataImageFormat#RAW10 *
  • Opaque RAW
    • * + *

    LEGACY mode devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == LEGACY) + * never support raw streams.

    + *

    This key is available on all devices.

    * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP */ @PublicKey @@ -814,6 +898,8 @@ public final class CameraCharacteristics extends CameraMetadata *

    For full guarantees, query StreamConfigurationMap#getOutputStallDuration with * a processed format -- it will return 0 for a non-stalling stream.

    + *

    LEGACY devices will support up to 3 processing/non-stalling streams.

    + *

    This key is available on all devices.

    * * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP */ @@ -836,6 +922,8 @@ public final class CameraCharacteristics extends CameraMetadataJPEG format (ImageFormat#JPEG)

    *

    For full guarantees, query StreamConfigurationMap#getOutputStallDuration with * a processed format -- it will return a non-0 value for a stalling stream.

    + *

    LEGACY devices will support up to 1 processing/stalling stream.

    + *

    This key is available on all devices.

    * * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP */ @@ -856,6 +944,12 @@ public final class CameraCharacteristics extends CameraMetadataFor 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.

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Full capability - + * 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

    + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @hide */ public static final Key REQUEST_MAX_NUM_INPUT_STREAMS = @@ -876,6 +970,7 @@ public final class CameraCharacteristics extends CameraMetadataA pipeline depth of X stages is equivalent to a pipeline latency of * X frame intervals.

    *

    This value will be 8 or less.

    + *

    This key is available on all devices.

    * * @see CaptureResult#REQUEST_PIPELINE_DEPTH */ @@ -924,6 +1019,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    Other capabilities may be available on either FULL or LIMITED * devices, but the application should query this field to be sure.

    + *

    This key is available on all devices.

    * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see #REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE @@ -945,6 +1041,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

    This key is available on all devices.

    * * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @hide @@ -969,6 +1066,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

    This key is available on all devices.

    * * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE @@ -984,6 +1082,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

    This key is available on all devices.

    * @hide */ public static final Key REQUEST_AVAILABLE_CHARACTERISTICS_KEYS = @@ -994,6 +1093,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    All camera devices will support JPEG and YUV_420_888 formats.

    *

    When set to YUV_420_888, application can access the YUV420 data directly.

    + *

    Optional - This value may be {@code null} on some devices.

    * @deprecated * @hide */ @@ -1010,6 +1110,7 @@ public final class CameraCharacteristics extends CameraMetadataWhen multiple streams are configured, the minimum * frame duration will be >= max(individual stream min * durations)

    + *

    Optional - This value may be {@code null} on some devices.

    * @deprecated * @hide */ @@ -1021,6 +1122,7 @@ public final class CameraCharacteristics extends CameraMetadataThe JPEG resolutions that are supported by this camera device.

    *

    The resolutions are listed as (width, height) pairs. All camera devices will support * sensor maximum resolution (defined by {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}).

    + *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE * @deprecated @@ -1040,6 +1142,7 @@ public final class CameraCharacteristics extends CameraMetadataCrop 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.

    + *

    This key is available on all devices.

    */ @PublicKey public static final Key SCALER_AVAILABLE_MAX_DIGITAL_ZOOM = @@ -1054,6 +1157,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    When multiple streams are configured, the minimum frame duration will * be >= max(individual stream min durations).

    + *

    Optional - This value may be {@code null} on some devices.

    * @deprecated * @hide */ @@ -1075,6 +1179,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    Please reference the documentation for the image data destination to * check if it limits the maximum size for image data.

    + *

    Optional - This value may be {@code null} on some devices.

    * @deprecated * @hide */ @@ -1133,6 +1238,12 @@ public final class CameraCharacteristics extends CameraMetadataAttempting to configure an input stream with output streams not * listed as available in this map is not valid.

    *

    TODO: typedef to ReprocessFormatMap

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Full capability - + * 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

    + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @hide */ public static final Key SCALER_AVAILABLE_INPUT_OUTPUT_FORMATS_MAP = @@ -1220,6 +1331,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    Refer to {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} for additional * mandatory stream configurations on a per-capability basis.

    + *

    This key is available on all devices.

    * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES @@ -1244,6 +1356,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    (Keep in sync with * StreamConfigurationMap#getOutputMinFrameDuration)

    + *

    This key is available on all devices.

    * * @see CaptureRequest#SENSOR_FRAME_DURATION * @hide @@ -1309,6 +1422,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    (Keep up to date with * StreamConfigurationMap#getOutputStallDuration(int, Size) )

    + *

    This key is available on all devices.

    * * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @see CaptureRequest#SENSOR_FRAME_DURATION @@ -1396,6 +1510,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    Refer to {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} for additional * mandatory stream configurations on a per-capability basis.

    + *

    This key is available on all devices.

    * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES @@ -1417,7 +1532,8 @@ public final class CameraCharacteristics extends CameraMetadata *

    FULL capability devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL) will support - * FREEFORM cropping.

    + * FREEFORM cropping. LEGACY capability devices will only support CENTER_ONLY cropping.

    + *

    This key is available on all devices.

    * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#SCALER_CROP_REGION @@ -1433,7 +1549,8 @@ public final class CameraCharacteristics extends CameraMetadataArea of raw data which corresponds to only * active pixels.

    *

    It is smaller or equal to - * sensor full pixel array, which could include the black calibration pixels.

    + * sensor full pixel array, which could include the black calibration pixels. + * This key is available on all devices.

    */ @PublicKey public static final Key SENSOR_INFO_ACTIVE_ARRAY_SIZE = @@ -1445,7 +1562,12 @@ public final class CameraCharacteristics extends CameraMetadata *

    The values are the standard ISO sensitivity values, * as defined in ISO 12232:2006.

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Full capability - + * 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

    * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#SENSOR_SENSITIVITY */ @PublicKey @@ -1456,6 +1578,12 @@ public final class CameraCharacteristics extends CameraMetadataThe arrangement of color filters on sensor; * represents the colors in the top-left 2x2 section of * the sensor, in reading order.

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Full capability - + * 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

    + * + * @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 @@ -1472,6 +1600,10 @@ public final class CameraCharacteristics extends CameraMetadataThe min value will be <= 100e3 (100 us). For FULL * capability devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL), * max will be >= 100e6 (100ms)

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Full capability - + * 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

    * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#SENSOR_EXPOSURE_TIME @@ -1493,6 +1625,10 @@ public final class CameraCharacteristics extends CameraMetadata *

    For FULL capability devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL), * max will be >= 100e6 (100ms).

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Full capability - + * 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

    * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#SENSOR_FRAME_DURATION @@ -1506,6 +1642,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    This is the physical size of the sensor pixel * array defined by {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.

    + *

    This key is available on all devices.

    * * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE */ @@ -1523,6 +1660,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

    This key is available on all devices.

    * * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE @@ -1543,6 +1681,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#SENSOR_BLACK_LEVEL_PATTERN */ @@ -1556,6 +1695,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    This characteristic defines the source for the timestamps, and therefore whether they * can be compared against other system time sources/timestamps.

    + *

    This key is available on all devices.

    * @see #SENSOR_INFO_TIMESTAMP_SOURCE_UNKNOWN * @see #SENSOR_INFO_TIMESTAMP_SOURCE_REALTIME */ @@ -1577,6 +1717,7 @@ public final class CameraCharacteristics extends CameraMetadataSome 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.

    + *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM1 * @see CameraCharacteristics#SENSOR_COLOR_TRANSFORM1 @@ -1617,6 +1758,7 @@ public final class CameraCharacteristics extends CameraMetadataIf this tag 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.

    + *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM2 * @see CameraCharacteristics#SENSOR_COLOR_TRANSFORM2 @@ -1804,6 +1946,7 @@ public final class CameraCharacteristics extends CameraMetadata + *

    This key is available on all devices.

    */ @PublicKey public static final Key SENSOR_ORIENTATION = @@ -1830,6 +1973,7 @@ public final class CameraCharacteristics extends CameraMetadataFULL means the device additionally supports the * android.statistics.faceIds and * android.statistics.faceLandmarks outputs.

    + *

    This key is available on all devices.

    */ @PublicKey public static final Key STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES = @@ -1838,6 +1982,7 @@ public final class CameraCharacteristics extends CameraMetadataThe maximum number of simultaneously detectable * faces.

    + *

    This key is available on all devices.

    */ @PublicKey public static final Key STATISTICS_INFO_MAX_FACE_COUNT = @@ -1849,6 +1994,8 @@ public final class CameraCharacteristics extends CameraMetadataIf 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.

    + *

    Required on devices with the RAW capability.

    + *

    Optional - This value may be {@code null} on some devices.

    * * @see CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE */ @@ -1866,7 +2013,12 @@ public final class CameraCharacteristics extends CameraMetadataThe 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.

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Full capability - + * 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

    * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#TONEMAP_CURVE */ @PublicKey @@ -1878,7 +2030,12 @@ public final class CameraCharacteristics extends CameraMetadataThis tag lists the valid modes for {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode}.

    *

    Full-capability camera devices must always support CONTRAST_CURVE and * FAST.

    + *

    Optional - This value may be {@code null} on some devices.

    + *

    Full capability - + * 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

    * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#TONEMAP_MODE */ @PublicKey @@ -1887,6 +2044,7 @@ public final class CameraCharacteristics extends CameraMetadataA list of camera LEDs that are available on this system.

    + *

    Optional - This value may be {@code null} on some devices.

    * @see #LED_AVAILABLE_LEDS_TRANSMIT * @hide */ @@ -1895,7 +2053,7 @@ public final class CameraCharacteristics extends CameraMetadataGenerally classifies the overall set of the camera device functionality.

    - *

    Camera devices will come in two flavors: LIMITED and FULL.

    + *

    Camera devices will come in three flavors: LEGACY, LIMITED and FULL.

    *

    A FULL device has the most support possible and will support below capabilities:

    *
      *
    • 30fps at maximum resolution (== sensor resolution) is preferred, more than 20fps is required.
      • @@ -1912,6 +2070,9 @@ public final class CameraCharacteristics extends CameraMetadata *

      A LEGACY device does not support per-frame control, manual sensor control, manual * post-processing, arbitrary cropping regions, and has relaxed performance constraints.

      + *

      Each higher level supports everything the lower level supports + * in this order: FULL > LIMITED > LEGACY.

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @see CameraCharacteristics#REQUEST_MAX_NUM_OUTPUT_PROC @@ -1959,6 +2120,7 @@ public final class CameraCharacteristics extends CameraMetadataSince result4 has a frameNumber == 4 and * android.sync.frameNumber == 2, the distance is clearly * 4 - 2 = 2.

      + *

      This key is available on all devices.

      * @see #SYNC_MAX_LATENCY_PER_FRAME_CONTROL * @see #SYNC_MAX_LATENCY_UNKNOWN */ @@ -1970,4 +2132,6 @@ public final class CameraCharacteristics extends CameraMetadata { * {@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.

      + *

      LEGACY devices do not support the OFF mode and will + * override attempts to use this value to ON.

      * * @see CaptureRequest#SENSOR_EXPOSURE_TIME * @see CaptureRequest#SENSOR_FRAME_DURATION @@ -1577,6 +1579,8 @@ public abstract class CameraMetadata { /** *

      Turn on custom high dynamic range (HDR) mode.

      + *

      This is intended for LEGACY mode devices only; + * HAL3+ camera devices should not implement this mode.

      * @see CaptureRequest#CONTROL_SCENE_MODE * @hide */ @@ -2064,6 +2068,8 @@ public abstract class CameraMetadata { * and may restart scanning at any time.

      *

      Only used by CONTINUOUS_* AF modes. This is a transient state, the camera * device may skip reporting this state in capture result.

      + *

      LEGACY camera devices do not support this state. When a passive + * scan has finished, it will always go to PASSIVE_FOCUSED.

      * @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 93eb3def1a68..e65e6277251e 100644 --- a/core/java/android/hardware/camera2/CaptureRequest.java +++ b/core/java/android/hardware/camera2/CaptureRequest.java @@ -518,10 +518,15 @@ public final class CaptureRequest extends CameraMetadata> * *

      Both the input and output value ranges must match. Overflow/underflow * values are clipped to fit within the range.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @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 +547,13 @@ public final class CaptureRequest extends CameraMetadata> * in this matrix result metadata. The transform should keep the magnitude * of the output color values within [0, 1.0] (assuming input color * values is within the normalized range [0, 1.0]), or clipping may occur.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @see CaptureRequest#COLOR_CORRECTION_MODE + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key COLOR_CORRECTION_TRANSFORM = @@ -559,8 +569,13 @@ public final class CaptureRequest extends CameraMetadata> * TRANSFORM_MATRIX.

      *

      The gains in the result metadata are the gains actually * applied by the camera device to the current frame.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @see CaptureRequest#COLOR_CORRECTION_MODE + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key COLOR_CORRECTION_GAINS = @@ -580,6 +595,8 @@ public final class CaptureRequest extends CameraMetadata> * 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.

      + *

      LEGACY devices will always be in FAST mode.

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES * @see #COLOR_CORRECTION_ABERRATION_MODE_OFF @@ -620,6 +637,7 @@ public final class CaptureRequest extends CameraMetadata> * 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.

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES * @see CaptureRequest#CONTROL_AE_MODE @@ -652,6 +670,7 @@ public final class CaptureRequest extends CameraMetadata> * 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).

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP @@ -678,6 +697,7 @@ public final class CaptureRequest extends CameraMetadata> * 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.

      *

      See {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE lock related state transition details.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION * @see CaptureRequest#CONTROL_AE_MODE @@ -711,6 +731,7 @@ public final class CaptureRequest extends CameraMetadata> * camera device auto-exposure routine for the overridden * fields for a given capture will be available in its * CaptureResult.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_MODE * @see CameraCharacteristics#FLASH_INFO_AVAILABLE @@ -762,7 +783,8 @@ public final class CaptureRequest extends CameraMetadata> *

      Range over which fps can be adjusted to * maintain exposure.

      *

      Only constrains auto-exposure (AE) algorithm, not - * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}

      + * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} + * This key is available on all devices.

      * * @see CaptureRequest#SENSOR_EXPOSURE_TIME */ @@ -789,8 +811,13 @@ public final class CaptureRequest extends CameraMetadata> * depends on the current AE mode and state; see * {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition * details.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Limited capability - + * 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

      * * @see CaptureResult#CONTROL_AE_STATE + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE * @see #CONTROL_AE_PRECAPTURE_TRIGGER_START */ @@ -805,7 +832,8 @@ public final class CaptureRequest extends CameraMetadata> * (i.e. {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} > 0).

      *

      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.

      + * in result metadata. + * This key is available on all devices.

      * * @see CaptureResult#CONTROL_AF_STATE * @see CaptureRequest#CONTROL_MODE @@ -864,6 +892,7 @@ public final class CaptureRequest extends CameraMetadata> * START for multiple captures in a row means restarting the AF operation over * and over again.

      *

      See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what the trigger means for each AF mode.

      + *

      This key is available on all devices.

      * * @see CaptureResult#CONTROL_AF_STATE * @see #CONTROL_AF_TRIGGER_IDLE @@ -880,6 +909,8 @@ public final class CaptureRequest extends CameraMetadata> *

      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.

      + *

      Some LEGACY devices may not support ON; the value is then overridden to OFF.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AWB_MODE */ @@ -907,6 +938,7 @@ public final class CaptureRequest extends CameraMetadata> * {@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.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#COLOR_CORRECTION_GAINS * @see CaptureRequest#COLOR_CORRECTION_MODE @@ -965,7 +997,8 @@ public final class CaptureRequest extends CameraMetadata> * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF and any 3A routine is active.

      *

      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.

      + * contains MANUAL_SENSOR. + * This key is available on all devices.

      * * @see CaptureRequest#CONTROL_MODE * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES @@ -991,6 +1024,7 @@ public final class CaptureRequest extends CameraMetadata> * devices.

      *

      A color effect will only be applied if * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_MODE * @see #CONTROL_EFFECT_MODE_OFF @@ -1025,6 +1059,10 @@ public final class CaptureRequest extends CameraMetadata> * 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.

      + *

      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 capability.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AF_MODE * @see #CONTROL_MODE_OFF @@ -1049,6 +1087,7 @@ public final class CaptureRequest extends CameraMetadata> * 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.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AE_MODE * @see CaptureRequest#CONTROL_AF_MODE @@ -1093,6 +1132,9 @@ public final class CaptureRequest extends CameraMetadata> *

      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.

      + *

      Some LEGACY camera devices will not support changing video stabilization + * mode; in this case the value will always override to OFF.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE * @see CaptureRequest#SCALER_CROP_REGION @@ -1114,8 +1156,13 @@ public final class CaptureRequest extends CameraMetadata> * 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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @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 +1186,7 @@ public final class CaptureRequest extends CameraMetadata> *

      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.

      *

      The flash status will be reported by {@link CaptureResult#FLASH_STATE android.flash.state} in the capture result metadata.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AE_MODE * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER @@ -1159,6 +1207,7 @@ public final class CaptureRequest extends CameraMetadata> *

      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).

      + *

      Optional - This value may be {@code null} on some devices.

      * * @see CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES * @see #HOT_PIXEL_MODE_OFF @@ -1171,6 +1220,7 @@ public final class CaptureRequest extends CameraMetadata> /** *

      A location object to use when generating image GPS metadata.

      + *

      This key is available on all devices.

      */ @PublicKey @SyntheticKey @@ -1180,6 +1230,7 @@ public final class CaptureRequest extends CameraMetadata> /** *

      GPS coordinates to include in output JPEG * EXIF

      + *

      This key is available on all devices.

      * @hide */ public static final Key JPEG_GPS_COORDINATES = @@ -1188,6 +1239,7 @@ public final class CaptureRequest extends CameraMetadata> /** *

      32 characters describing GPS algorithm to * include in EXIF

      + *

      This key is available on all devices.

      * @hide */ public static final Key JPEG_GPS_PROCESSING_METHOD = @@ -1196,6 +1248,7 @@ public final class CaptureRequest extends CameraMetadata> /** *

      Time GPS fix was made to include in * EXIF

      + *

      This key is available on all devices.

      * @hide */ public static final Key JPEG_GPS_TIMESTAMP = @@ -1204,6 +1257,7 @@ public final class CaptureRequest extends CameraMetadata> /** *

      Orientation of JPEG image to * write

      + *

      This key is available on all devices.

      */ @PublicKey public static final Key JPEG_ORIENTATION = @@ -1213,6 +1267,7 @@ public final class CaptureRequest extends CameraMetadata> *

      Compression quality of the final JPEG * image.

      *

      85-95 is typical usage range.

      + *

      This key is available on all devices.

      */ @PublicKey public static final Key JPEG_QUALITY = @@ -1221,6 +1276,7 @@ public final class CaptureRequest extends CameraMetadata> /** *

      Compression quality of JPEG * thumbnail.

      + *

      This key is available on all devices.

      */ @PublicKey public static final Key JPEG_THUMBNAIL_QUALITY = @@ -1238,6 +1294,7 @@ public final class CaptureRequest extends CameraMetadata> * 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.

      + *

      This key is available on all devices.

      */ @PublicKey public static final Key JPEG_THUMBNAIL_SIZE = @@ -1261,8 +1318,13 @@ public final class CaptureRequest extends CameraMetadata> * 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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @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 @@ -1289,7 +1351,12 @@ public final class CaptureRequest extends CameraMetadata> *

      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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES * @see CaptureResult#LENS_STATE */ @@ -1308,6 +1375,7 @@ public final class CaptureRequest extends CameraMetadata> * While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will * be set to MOVING.

      *

      This is expected not to be supported on most devices.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#LENS_APERTURE * @see CaptureRequest#LENS_FOCUS_DISTANCE @@ -1320,13 +1388,20 @@ public final class CaptureRequest extends CameraMetadata> /** *

      Distance to plane of sharpest focus, * measured from frontmost surface of the lens.

      - *

      0 means infinity focus. Used value will be clamped - * to [0, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}].

      + *

      0.0f means infinity focus. Used value will be clamped + * to [0.0f, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}].

      *

      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.

      + *

      LEGACY devices support at most setting this to 0.0f + * for infinity focus.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#LENS_FOCAL_LENGTH * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE * @see CaptureResult#LENS_STATE @@ -1355,8 +1430,13 @@ public final class CaptureRequest extends CameraMetadata> *

      Not all devices will support OIS; see * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for * available controls.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Limited capability - + * 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

      * * @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 @@ -1376,7 +1456,12 @@ public final class CaptureRequest extends CameraMetadata> * 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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @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,6 +1475,7 @@ public final class CaptureRequest extends CameraMetadata> *

      An application-specified ID for the current * request. Must be maintained unchanged in output * frame

      + *

      Optional - This value may be {@code null} on some devices.

      * @hide */ public static final Key REQUEST_ID = @@ -1426,6 +1512,7 @@ public final class CaptureRequest extends CameraMetadata> * for rounding and other hardware requirements; the final * crop region used will be included in the output capture * result.

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE @@ -1439,6 +1526,12 @@ public final class CaptureRequest extends CameraMetadata> * light.

      *

      If the sensor can't expose this exact duration, it should shorten the * duration exposed to the nearest possible value (rather than expose longer).

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key SENSOR_EXPOSURE_TIME = @@ -1516,7 +1609,12 @@ public final class CaptureRequest extends CameraMetadata> * delivered.

      *

      For more details about stalling, see * StreamConfigurationMap#getOutputStallDuration(int,Size).

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP */ @PublicKey @@ -1535,7 +1633,12 @@ public final class CaptureRequest extends CameraMetadata> * requested, it will reduce the gain to the nearest supported * value. The final sensitivity used will be available in the * output capture result.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE * @see CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY */ @@ -1608,9 +1711,14 @@ public final class CaptureRequest extends CameraMetadata> * AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} != OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != 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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @see CaptureRequest#CONTROL_AE_MODE * @see CaptureRequest#CONTROL_AWB_MODE + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE * @see #SHADING_MODE_OFF * @see #SHADING_MODE_FAST @@ -1626,7 +1734,8 @@ public final class CaptureRequest extends CameraMetadata> *

      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}.

      + * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}. + * This key is available on all devices.

      * * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES * @see #STATISTICS_FACE_DETECT_MODE_OFF @@ -1642,6 +1751,7 @@ public final class CaptureRequest extends CameraMetadata> *

      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.

      *

      This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}.

      + *

      Optional - This value may be {@code null} on some devices.

      * * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES @@ -1656,6 +1766,13 @@ public final class CaptureRequest extends CameraMetadata> *

      When set to ON, * android.statistics.lensShadingMap will be provided in * the output result metadata.

      + *

      Required for devices with the RAW capability.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see #STATISTICS_LENS_SHADING_MAP_MODE_OFF * @see #STATISTICS_LENS_SHADING_MAP_MODE_ON */ @@ -1668,7 +1785,12 @@ public final class CaptureRequest extends CameraMetadata> * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is * CONTRAST_CURVE.

      *

      See android.tonemap.curveRed for more details.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#TONEMAP_MODE * @hide */ @@ -1680,7 +1802,12 @@ public final class CaptureRequest extends CameraMetadata> * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is * CONTRAST_CURVE.

      *

      See android.tonemap.curveRed for more details.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#TONEMAP_MODE * @hide */ @@ -1731,7 +1858,12 @@ public final class CaptureRequest extends CameraMetadata> * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ] * *

      sRGB tonemapping curve

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS * @see CaptureRequest#TONEMAP_MODE * @hide @@ -1785,7 +1917,12 @@ public final class CaptureRequest extends CameraMetadata> * (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ] * *

      sRGB tonemapping curve

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS * @see CaptureRequest#TONEMAP_MODE */ @@ -1816,7 +1953,12 @@ public final class CaptureRequest extends CameraMetadata> *

      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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES * @see CaptureRequest#TONEMAP_CURVE * @see CaptureRequest#TONEMAP_MODE @@ -1839,6 +1981,7 @@ public final class CaptureRequest extends CameraMetadata> * data is stored locally on the device.

      *

      The LED may be off if a trusted application is using the data that * doesn't violate the above rules.

      + *

      Optional - This value may be {@code null} on some devices.

      * @hide */ public static final Key LED_TRANSMIT = @@ -1882,6 +2025,12 @@ public final class CaptureRequest extends CameraMetadata> * possible, only overriding the lock to OFF when changes to * other request parameters require a black level recalculation * or reset.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key BLACK_LEVEL_LOCK = @@ -1891,4 +2040,6 @@ public final class CaptureRequest extends CameraMetadata> * End generated code *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/ + + } diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java index 01276a28e320..fc1baf2a6014 100644 --- a/core/java/android/hardware/camera2/CaptureResult.java +++ b/core/java/android/hardware/camera2/CaptureResult.java @@ -369,10 +369,15 @@ public class CaptureResult extends CameraMetadata> { * *

      Both the input and output value ranges must match. Overflow/underflow * values are clipped to fit within the range.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @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 +398,13 @@ public class CaptureResult extends CameraMetadata> { * in this matrix result metadata. The transform should keep the magnitude * of the output color values within [0, 1.0] (assuming input color * values is within the normalized range [0, 1.0]), or clipping may occur.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @see CaptureRequest#COLOR_CORRECTION_MODE + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key COLOR_CORRECTION_TRANSFORM = @@ -410,8 +420,13 @@ public class CaptureResult extends CameraMetadata> { * TRANSFORM_MATRIX.

      *

      The gains in the result metadata are the gains actually * applied by the camera device to the current frame.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @see CaptureRequest#COLOR_CORRECTION_MODE + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key COLOR_CORRECTION_GAINS = @@ -431,6 +446,8 @@ public class CaptureResult extends CameraMetadata> { * 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.

      + *

      LEGACY devices will always be in FAST mode.

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES * @see #COLOR_CORRECTION_ABERRATION_MODE_OFF @@ -471,6 +488,7 @@ public class CaptureResult extends CameraMetadata> { * 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.

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES * @see CaptureRequest#CONTROL_AE_MODE @@ -503,6 +521,7 @@ public class CaptureResult extends CameraMetadata> { * 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).

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP @@ -529,6 +548,7 @@ public class CaptureResult extends CameraMetadata> { * 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.

      *

      See {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE lock related state transition details.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION * @see CaptureRequest#CONTROL_AE_MODE @@ -562,6 +582,7 @@ public class CaptureResult extends CameraMetadata> { * camera device auto-exposure routine for the overridden * fields for a given capture will be available in its * CaptureResult.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_MODE * @see CameraCharacteristics#FLASH_INFO_AVAILABLE @@ -613,7 +634,8 @@ public class CaptureResult extends CameraMetadata> { *

      Range over which fps can be adjusted to * maintain exposure.

      *

      Only constrains auto-exposure (AE) algorithm, not - * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}

      + * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} + * This key is available on all devices.

      * * @see CaptureRequest#SENSOR_EXPOSURE_TIME */ @@ -640,8 +662,13 @@ public class CaptureResult extends CameraMetadata> { * depends on the current AE mode and state; see * {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition * details.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Limited capability - + * 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

      * * @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 +858,17 @@ public class CaptureResult extends CameraMetadata> { * * * + *

      Optional - This value may be {@code null} on some devices.

      + *

      Limited capability - + * 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

      * * @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 @@ -855,7 +887,8 @@ public class CaptureResult extends CameraMetadata> { * (i.e. {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} > 0).

      *

      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.

      + * in result metadata. + * This key is available on all devices.

      * * @see CaptureResult#CONTROL_AF_STATE * @see CaptureRequest#CONTROL_MODE @@ -914,6 +947,7 @@ public class CaptureResult extends CameraMetadata> { * START for multiple captures in a row means restarting the AF operation over * and over again.

      *

      See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what the trigger means for each AF mode.

      + *

      This key is available on all devices.

      * * @see CaptureResult#CONTROL_AF_STATE * @see #CONTROL_AF_TRIGGER_IDLE @@ -1306,6 +1340,7 @@ public class CaptureResult extends CameraMetadata> { * * * + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AF_MODE * @see CaptureRequest#CONTROL_MODE @@ -1328,6 +1363,8 @@ public class CaptureResult extends CameraMetadata> { *

      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.

      + *

      Some LEGACY devices may not support ON; the value is then overridden to OFF.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AWB_MODE */ @@ -1355,6 +1392,7 @@ public class CaptureResult extends CameraMetadata> { * {@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.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#COLOR_CORRECTION_GAINS * @see CaptureRequest#COLOR_CORRECTION_MODE @@ -1413,7 +1451,8 @@ public class CaptureResult extends CameraMetadata> { * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF and any 3A routine is active.

      *

      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.

      + * contains MANUAL_SENSOR. + * This key is available on all devices.

      * * @see CaptureRequest#CONTROL_MODE * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES @@ -1546,11 +1585,16 @@ public class CaptureResult extends CameraMetadata> { * * * + *

      Optional - This value may be {@code null} on some devices.

      + *

      Limited capability - + * 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

      * * @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 @@ -1570,6 +1614,7 @@ public class CaptureResult extends CameraMetadata> { * devices.

      *

      A color effect will only be applied if * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_MODE * @see #CONTROL_EFFECT_MODE_OFF @@ -1604,6 +1649,10 @@ public class CaptureResult extends CameraMetadata> { * 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.

      + *

      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 capability.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AF_MODE * @see #CONTROL_MODE_OFF @@ -1628,6 +1677,7 @@ public class CaptureResult extends CameraMetadata> { * 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.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AE_MODE * @see CaptureRequest#CONTROL_AF_MODE @@ -1672,6 +1722,9 @@ public class CaptureResult extends CameraMetadata> { *

      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.

      + *

      Some LEGACY camera devices will not support changing video stabilization + * mode; in this case the value will always override to OFF.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE * @see CaptureRequest#SCALER_CROP_REGION @@ -1693,8 +1746,13 @@ public class CaptureResult extends CameraMetadata> { * 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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @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 +1776,7 @@ public class CaptureResult extends CameraMetadata> { *

      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.

      *

      The flash status will be reported by {@link CaptureResult#FLASH_STATE android.flash.state} in the capture result metadata.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AE_MODE * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER @@ -1737,8 +1796,25 @@ public class CaptureResult extends CameraMetadata> { *

      When the camera device doesn't have flash unit * (i.e. {@link CameraCharacteristics#FLASH_INFO_AVAILABLE android.flash.info.available} == false), this state will always be UNAVAILABLE. * Other states indicate the current flash status.

      + *

      In certain conditions, this will be available on LEGACY devices:

      + *
        + *
      • Flash-less cameras always return UNAVAILABLE.
        • + *
      • Using {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} == ON_ALWAYS_FLASH + * will always return FIRED.
        • + *
      • Using {@link CaptureRequest#FLASH_MODE android.flash.mode} == TORCH + * will always return FIRED.
        • + *
      + *

      In all other conditions the state will not be available on + * LEGACY devices (i.e. it will be null).

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Limited capability - + * 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

      * + * @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 @@ -1756,6 +1832,7 @@ public class CaptureResult extends CameraMetadata> { *

      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).

      + *

      Optional - This value may be {@code null} on some devices.

      * * @see CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES * @see #HOT_PIXEL_MODE_OFF @@ -1768,6 +1845,7 @@ public class CaptureResult extends CameraMetadata> { /** *

      A location object to use when generating image GPS metadata.

      + *

      This key is available on all devices.

      */ @PublicKey @SyntheticKey @@ -1777,6 +1855,7 @@ public class CaptureResult extends CameraMetadata> { /** *

      GPS coordinates to include in output JPEG * EXIF

      + *

      This key is available on all devices.

      * @hide */ public static final Key JPEG_GPS_COORDINATES = @@ -1785,6 +1864,7 @@ public class CaptureResult extends CameraMetadata> { /** *

      32 characters describing GPS algorithm to * include in EXIF

      + *

      This key is available on all devices.

      * @hide */ public static final Key JPEG_GPS_PROCESSING_METHOD = @@ -1793,6 +1873,7 @@ public class CaptureResult extends CameraMetadata> { /** *

      Time GPS fix was made to include in * EXIF

      + *

      This key is available on all devices.

      * @hide */ public static final Key JPEG_GPS_TIMESTAMP = @@ -1801,6 +1882,7 @@ public class CaptureResult extends CameraMetadata> { /** *

      Orientation of JPEG image to * write

      + *

      This key is available on all devices.

      */ @PublicKey public static final Key JPEG_ORIENTATION = @@ -1810,6 +1892,7 @@ public class CaptureResult extends CameraMetadata> { *

      Compression quality of the final JPEG * image.

      *

      85-95 is typical usage range.

      + *

      This key is available on all devices.

      */ @PublicKey public static final Key JPEG_QUALITY = @@ -1818,6 +1901,7 @@ public class CaptureResult extends CameraMetadata> { /** *

      Compression quality of JPEG * thumbnail.

      + *

      This key is available on all devices.

      */ @PublicKey public static final Key JPEG_THUMBNAIL_QUALITY = @@ -1835,6 +1919,7 @@ public class CaptureResult extends CameraMetadata> { * 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.

      + *

      This key is available on all devices.

      */ @PublicKey public static final Key JPEG_THUMBNAIL_SIZE = @@ -1858,8 +1943,13 @@ public class CaptureResult extends CameraMetadata> { * 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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @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 @@ -1886,7 +1976,12 @@ public class CaptureResult extends CameraMetadata> { *

      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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES * @see CaptureResult#LENS_STATE */ @@ -1905,6 +2000,7 @@ public class CaptureResult extends CameraMetadata> { * While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will * be set to MOVING.

      *

      This is expected not to be supported on most devices.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#LENS_APERTURE * @see CaptureRequest#LENS_FOCUS_DISTANCE @@ -1918,6 +2014,12 @@ public class CaptureResult extends CameraMetadata> { *

      Distance to plane of sharpest focus, * measured from frontmost surface of the lens.

      *

      Should be zero for fixed-focus cameras

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key LENS_FOCUS_DISTANCE = @@ -1928,6 +2030,12 @@ public class CaptureResult extends CameraMetadata> { * sharp focus (depth of field).

      *

      If variable focus not supported, can still report * fixed depth of field range

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Limited capability - + * 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

      + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key> LENS_FOCUS_RANGE = @@ -1953,8 +2061,13 @@ public class CaptureResult extends CameraMetadata> { *

      Not all devices will support OIS; see * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for * available controls.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Limited capability - + * 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

      * * @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 +2097,12 @@ public class CaptureResult extends CameraMetadata> { *

      Then this state will always be STATIONARY.

      *

      When the state is MOVING, it indicates that at least one of the lens parameters * is changing.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Limited capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#LENS_APERTURE * @see CaptureRequest#LENS_FILTER_DENSITY * @see CaptureRequest#LENS_FOCAL_LENGTH @@ -2011,7 +2129,12 @@ public class CaptureResult extends CameraMetadata> { * 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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES * @see #NOISE_REDUCTION_MODE_OFF * @see #NOISE_REDUCTION_MODE_FAST @@ -2048,6 +2171,7 @@ public class CaptureResult extends CameraMetadata> { * increases with every new result (that is, each new result has a unique * frameCount value).

      *

      Reset on release()

      + *

      Optional - This value may be {@code null} on some devices.

      * @deprecated * @hide */ @@ -2059,6 +2183,7 @@ public class CaptureResult extends CameraMetadata> { *

      An application-specified ID for the current * request. Must be maintained unchanged in output * frame

      + *

      Optional - This value may be {@code null} on some devices.

      * @hide */ public static final Key REQUEST_ID = @@ -2072,6 +2197,7 @@ public class CaptureResult extends CameraMetadata> { * what streams are configured, the data may undergo less processing, * and some pipeline stages skipped.

      *

      See {@link CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH android.request.pipelineMaxDepth} for more details.

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH */ @@ -2110,6 +2236,7 @@ public class CaptureResult extends CameraMetadata> { * for rounding and other hardware requirements; the final * crop region used will be included in the output capture * result.

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE @@ -2123,6 +2250,12 @@ public class CaptureResult extends CameraMetadata> { * light.

      *

      If the sensor can't expose this exact duration, it should shorten the * duration exposed to the nearest possible value (rather than expose longer).

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key SENSOR_EXPOSURE_TIME = @@ -2200,7 +2333,12 @@ public class CaptureResult extends CameraMetadata> { * delivered.

      *

      For more details about stalling, see * StreamConfigurationMap#getOutputStallDuration(int,Size).

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP */ @PublicKey @@ -2219,7 +2357,12 @@ public class CaptureResult extends CameraMetadata> { * requested, it will reduce the gain to the nearest supported * value. The final sensitivity used will be available in the * output capture result.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE * @see CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY */ @@ -2243,6 +2386,7 @@ public class CaptureResult extends CameraMetadata> { * android.os.SystemClock#elapsedRealtimeNanos(), and they can be * compared to other timestamps from other subsystems that are using * that base.

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#SENSOR_INFO_TIMESTAMP_SOURCE */ @@ -2376,7 +2520,12 @@ public class CaptureResult extends CameraMetadata> { * and last rows inside of the {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.

      *

      For typical camera sensors that use rolling shutters, this is also equivalent * to the frame readout time.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Limited capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE */ @PublicKey @@ -2410,9 +2559,14 @@ public class CaptureResult extends CameraMetadata> { * AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} != OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != 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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @see CaptureRequest#CONTROL_AE_MODE * @see CaptureRequest#CONTROL_AWB_MODE + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE * @see #SHADING_MODE_OFF * @see #SHADING_MODE_FAST @@ -2428,7 +2582,8 @@ public class CaptureResult extends CameraMetadata> { *

      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}.

      + * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}. + * This key is available on all devices.

      * * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES * @see #STATISTICS_FACE_DETECT_MODE_OFF @@ -2444,7 +2599,8 @@ public class CaptureResult extends CameraMetadata> { *

      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.

      - *

      Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL

      + *

      Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL + * This key is available on all devices.

      * * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE * @hide @@ -2457,7 +2613,8 @@ public class CaptureResult extends CameraMetadata> { * faces.

      *

      The coordinate system is that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with * (0, 0) being the top-left pixel of the active array.

      - *

      Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL

      + *

      Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL + * This key is available on all devices.

      * * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE @@ -2471,7 +2628,8 @@ public class CaptureResult extends CameraMetadata> { * faces.

      *

      The coordinate system is that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with * (0, 0) being the top-left pixel of the active array.

      - *

      Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF

      + *

      Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF + * This key is available on all devices.

      * * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE @@ -2484,6 +2642,7 @@ public class CaptureResult extends CameraMetadata> { *

      List of the face confidence scores for * detected faces

      *

      Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE * @hide @@ -2495,6 +2654,7 @@ public class CaptureResult extends CameraMetadata> { *

      List of the faces detected through camera face detection * in this result.

      *

      Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF.

      + *

      This key is available on all devices.

      * * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE */ @@ -2543,8 +2703,13 @@ public class CaptureResult extends CameraMetadata> { *

      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:

      *

      Image of a uniform white wall (inverse shading map)

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @see CaptureRequest#COLOR_CORRECTION_MODE + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key STATISTICS_LENS_SHADING_CORRECTION_MAP = @@ -2591,8 +2756,13 @@ public class CaptureResult extends CameraMetadata> { *

      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:

      *

      Image of a uniform white wall (inverse shading map)

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @see CaptureRequest#COLOR_CORRECTION_MODE + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @hide */ public static final Key STATISTICS_LENS_SHADING_MAP = @@ -2659,10 +2829,15 @@ public class CaptureResult extends CameraMetadata> { * into this metadata field. See * {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} for more details.

      *

      Reports NONE if there doesn't appear to be flickering illumination.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @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 @@ -2676,6 +2851,7 @@ public class CaptureResult extends CameraMetadata> { *

      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.

      *

      This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}.

      + *

      Optional - This value may be {@code null} on some devices.

      * * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES @@ -2692,6 +2868,7 @@ public class CaptureResult extends CameraMetadata> { * 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}.

      + *

      Optional - This value may be {@code null} on some devices.

      * * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE @@ -2706,6 +2883,13 @@ public class CaptureResult extends CameraMetadata> { *

      When set to ON, * android.statistics.lensShadingMap will be provided in * the output result metadata.

      + *

      Required for devices with the RAW capability.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see #STATISTICS_LENS_SHADING_MAP_MODE_OFF * @see #STATISTICS_LENS_SHADING_MAP_MODE_ON */ @@ -2718,7 +2902,12 @@ public class CaptureResult extends CameraMetadata> { * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is * CONTRAST_CURVE.

      *

      See android.tonemap.curveRed for more details.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#TONEMAP_MODE * @hide */ @@ -2730,7 +2919,12 @@ public class CaptureResult extends CameraMetadata> { * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is * CONTRAST_CURVE.

      *

      See android.tonemap.curveRed for more details.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CaptureRequest#TONEMAP_MODE * @hide */ @@ -2781,7 +2975,12 @@ public class CaptureResult extends CameraMetadata> { * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ] * *

      sRGB tonemapping curve

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS * @see CaptureRequest#TONEMAP_MODE * @hide @@ -2835,7 +3034,12 @@ public class CaptureResult extends CameraMetadata> { * (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ] * *

      sRGB tonemapping curve

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS * @see CaptureRequest#TONEMAP_MODE */ @@ -2866,7 +3070,12 @@ public class CaptureResult extends CameraMetadata> { *

      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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES * @see CaptureRequest#TONEMAP_CURVE * @see CaptureRequest#TONEMAP_MODE @@ -2889,6 +3098,7 @@ public class CaptureResult extends CameraMetadata> { * data is stored locally on the device.

      *

      The LED may be off if a trusted application is using the data that * doesn't violate the above rules.

      + *

      Optional - This value may be {@code null} on some devices.

      * @hide */ public static final Key LED_TRANSMIT = @@ -2901,8 +3111,13 @@ public class CaptureResult extends CameraMetadata> { * 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.

      + *

      Optional - This value may be {@code null} on some devices.

      + *

      Full capability - + * 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

      * * @see CaptureRequest#BLACK_LEVEL_LOCK + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey public static final Key BLACK_LEVEL_LOCK = @@ -2960,6 +3175,7 @@ public class CaptureResult extends CameraMetadata> { *

      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.

      + *

      This key is available on all devices.

      * * @see CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH * @see #SYNC_FRAME_NUMBER_CONVERGING @@ -2973,4 +3189,6 @@ public class CaptureResult extends CameraMetadata> { * End generated code *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/ + + } -- cgit v1.2.3-59-g8ed1b From fd3e2892f29ded5a25a0a064275b282ce93ed258 Mon Sep 17 00:00:00 2001 From: Eino-Ville Talvala Date: Mon, 6 Oct 2014 10:23:55 -0700 Subject: Camera2: Docs cleanup, especially units and range - Add entries for units and range into javadoc - Fix up existing units entries and add new ones - Fix up range entries to be consistent for enums - Add range entries where it makes sense - Minor fix to javadoc gen to allow for code indentation - Lots of edits for consistency, especially to available* entries. Bug: 16525650 Change-Id: Id09663d897ec98122073e6e13719731ec0de4dad --- .../hardware/camera2/CameraCharacteristics.java | 564 +++++++++++---- .../android/hardware/camera2/CameraMetadata.java | 29 +- .../android/hardware/camera2/CaptureRequest.java | 674 ++++++++++++++---- .../android/hardware/camera2/CaptureResult.java | 784 ++++++++++++++++----- 4 files changed, 1557 insertions(+), 494 deletions(-) diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java index 54f7e37a4228..fb3eaffe339b 100644 --- a/core/java/android/hardware/camera2/CameraCharacteristics.java +++ b/core/java/android/hardware/camera2/CameraCharacteristics.java @@ -310,15 +310,17 @@ public final class CameraCharacteristics extends CameraMetadataThe set of aberration correction modes supported by this camera device.

      - *

      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 + *

      List of aberration correction modes for {@link CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE android.colorCorrection.aberrationMode} that are + * supported by this camera device.

      + *

      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.

      - *

      For FULL capability device ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL), OFF must be - * included.

      + *

      For FULL capability device ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL), OFF is + * always included.

      *

      LEGACY devices will always only support FAST mode.

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE android.colorCorrection.aberrationMode}

      *

      This key is available on all devices.

      * * @see CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE @@ -329,21 +331,27 @@ public final class CameraCharacteristics extends CameraMetadata("android.colorCorrection.availableAberrationModes", int[].class); /** - *

      The set of auto-exposure antibanding modes that are + *

      List of auto-exposure antibanding modes for {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} that are * supported by this camera device.

      *

      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.

      + * for this camera device with the + * {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} control. This list + * always includes AUTO.

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode}

      *

      This key is available on all devices.

      + * + * @see CaptureRequest#CONTROL_AE_ANTIBANDING_MODE */ @PublicKey public static final Key CONTROL_AE_AVAILABLE_ANTIBANDING_MODES = new Key("android.control.aeAvailableAntibandingModes", int[].class); /** - *

      The set of auto-exposure modes that are supported by this - * camera device.

      + *

      List of auto-exposure modes for {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} that are supported by this camera + * device.

      *

      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 @@ -356,6 +364,8 @@ public final class CameraCharacteristics extends CameraMetadataLEGACY mode camera devices never support OFF mode. * LIMITED mode devices support OFF if they support the MANUAL_SENSOR * capability.

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}

      *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AE_MODE @@ -365,38 +375,55 @@ public final class CameraCharacteristics extends CameraMetadata("android.control.aeAvailableModes", int[].class); /** - *

      List of frame rate ranges supported by the - * auto-exposure (AE) algorithm/hardware

      + *

      List of frame rate ranges for {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE android.control.aeTargetFpsRange} supported by + * this camera device.

      + *

      For devices at the LIMITED level or above, this list will include at least (30, 30) for + * constant-framerate recording.

      + *

      Units: Frames per second (FPS)

      *

      This key is available on all devices.

      + * + * @see CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE */ @PublicKey public static final Key[]> CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES = new Key[]>("android.control.aeAvailableTargetFpsRanges", new TypeReference[]>() {{ }}); /** - *

      Maximum and minimum exposure compensation - * setting, in counts of - * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep}.

      + *

      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.

      + *

      Range of valid values:

      + *

      Min.exposure compensation * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep} <= -2 EV

      + *

      Max.exposure compensation * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep} >= 2 EV

      *

      This key is available on all devices.

      * * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP + * @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION */ @PublicKey public static final Key> CONTROL_AE_COMPENSATION_RANGE = new Key>("android.control.aeCompensationRange", new TypeReference>() {{ }}); /** - *

      Smallest step by which exposure compensation - * can be changed

      + *

      Smallest step by which the exposure compensation + * can be changed.

      + *

      This is the unit for {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation}. For example, if this key has + * a value of 1/2, then a setting of -2 for {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation} means + * that the target EV offset for the auto-exposure routine is -1 EV.

      + *

      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.

      + *

      Units: Exposure Value (EV)

      *

      This key is available on all devices.

      + * + * @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION */ @PublicKey public static final Key CONTROL_AE_COMPENSATION_STEP = new Key("android.control.aeCompensationStep", Rational.class); /** - *

      List of auto-focus (AF) modes that can be - * selected with {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}.

      + *

      List of auto-focus (AF) modes for {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} that are + * supported by this camera device.

      *

      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.

      @@ -406,6 +433,8 @@ public final class CameraCharacteristics extends CameraMetadataLEGACY devices will support OFF mode only if they support * focusing to infinity (by also setting {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} to * 0.0f).

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}

      *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AF_MODE @@ -417,17 +446,19 @@ public final class CameraCharacteristics extends CameraMetadata("android.control.afAvailableModes", int[].class); /** - *

      List containing the subset of color effects - * specified in {@link CaptureRequest#CONTROL_EFFECT_MODE android.control.effectMode} that is supported by - * this device.

      + *

      List of color effects for {@link CaptureRequest#CONTROL_EFFECT_MODE android.control.effectMode} that are supported by this camera + * device.

      *

      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.

      + * If no color effect modes are available for a device, this will only list + * OFF.

      *

      A color effect will only be applied if - * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.

      + * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF. OFF is always included in this list.

      + *

      This control has no effect on the operation of other control routines such + * as auto-exposure, white balance, or focus.

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#CONTROL_EFFECT_MODE android.control.effectMode}

      *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_EFFECT_MODE @@ -438,40 +469,55 @@ public final class CameraCharacteristics extends CameraMetadata("android.control.availableEffects", int[].class); /** - *

      List containing a subset of scene modes - * specified in {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode}.

      + *

      List of scene modes for {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} that are supported by this camera + * device.

      *

      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 [DISABLED].

      + * to be consistent across all devices.

      + *

      If no scene modes are supported by the camera device, this + * will be set to DISABLED. Otherwise DISABLED will not be listed.

      + *

      FACE_PRIORITY is always listed if face detection is + * supported (i.e.{@link CameraCharacteristics#STATISTICS_INFO_MAX_FACE_COUNT android.statistics.info.maxFaceCount} > + * 0).

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode}

      *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_SCENE_MODE + * @see CameraCharacteristics#STATISTICS_INFO_MAX_FACE_COUNT */ @PublicKey public static final Key CONTROL_AVAILABLE_SCENE_MODES = new Key("android.control.availableSceneModes", int[].class); /** - *

      List of video stabilization modes that can - * be supported

      + *

      List of video stabilization modes for {@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode} + * that are supported by this camera device.

      + *

      OFF will always be listed.

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}

      *

      This key is available on all devices.

      + * + * @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE */ @PublicKey public static final Key CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES = new Key("android.control.availableVideoStabilizationModes", int[].class); /** - *

      The set of auto-white-balance modes ({@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}) - * that are supported by this camera device.

      + *

      List of auto-white-balance modes for {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} that are supported by this + * camera device.

      *

      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.

      *

      All camera devices will support ON mode.

      - *

      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).

      + *

      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.

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}

      *

      This key is available on all devices.

      * * @see CaptureRequest#COLOR_CORRECTION_GAINS @@ -489,6 +535,10 @@ public final class CameraCharacteristics extends CameraMetadata + *

      Range of valid values:

      + *

      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: + * (AE, AWB, AF).

      *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AE_REGIONS @@ -500,10 +550,13 @@ public final class CameraCharacteristics extends CameraMetadata("android.control.maxRegions", int[].class); /** - *

      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 + *

      The maximum number of metering regions that can be used by the auto-exposure (AE) + * routine.

      + *

      This corresponds to the the maximum allowed number of elements in * {@link CaptureRequest#CONTROL_AE_REGIONS android.control.aeRegions}.

      + *

      Range of valid values:
      + * Value will be >= 0. For FULL-capability devices, this + * value will be >= 1.

      *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AE_REGIONS @@ -514,10 +567,12 @@ public final class CameraCharacteristics extends CameraMetadata("android.control.maxRegionsAe", int.class); /** - *

      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 + *

      The maximum number of metering regions that can be used by the auto-white balance (AWB) + * routine.

      + *

      This corresponds to the the maximum allowed number of elements in * {@link CaptureRequest#CONTROL_AWB_REGIONS android.control.awbRegions}.

      + *

      Range of valid values:
      + * Value will be >= 0.

      *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AWB_REGIONS @@ -528,10 +583,12 @@ public final class CameraCharacteristics extends CameraMetadata("android.control.maxRegionsAwb", int.class); /** - *

      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 + *

      The maximum number of metering regions that can be used by the auto-focus (AF) routine.

      + *

      This corresponds to the the maximum allowed number of elements in * {@link CaptureRequest#CONTROL_AF_REGIONS android.control.afRegions}.

      + *

      Range of valid values:
      + * Value will be >= 0. For FULL-capability devices, this + * value will be >= 1.

      *

      This key is available on all devices.

      * * @see CaptureRequest#CONTROL_AF_REGIONS @@ -563,6 +620,8 @@ public final class CameraCharacteristics extends CameraMetadata + *

      Range of valid values:

      + *

      For each configuration, the fps_max >= 60fps.

      *

      Optional - This value may be {@code null} on some devices.

      *

      Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -577,9 +636,11 @@ public final class CameraCharacteristics extends CameraMetadata("android.control.availableHighSpeedVideoConfigurations", android.hardware.camera2.params.HighSpeedVideoConfiguration[].class); /** - *

      The set of edge enhancement modes supported by this camera device.

      - *

      This tag lists the valid modes for {@link CaptureRequest#EDGE_MODE android.edge.mode}.

      - *

      Full-capability camera devices must always support OFF and FAST.

      + *

      List of edge enhancement modes for {@link CaptureRequest#EDGE_MODE android.edge.mode} that are supported by this camera + * device.

      + *

      Full-capability camera devices must always support OFF; all devices will list FAST.

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#EDGE_MODE android.edge.mode}

      *

      Optional - This value may be {@code null} on some devices.

      *

      Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -594,9 +655,10 @@ public final class CameraCharacteristics extends CameraMetadataWhether this camera device has a - * flash.

      - *

      If no flash, none of the flash controls do - * anything. All other metadata should return 0. + * flash unit.

      + *

      Will be false if no flash is available.

      + *

      If there is no flash unit, none of the flash controls do + * anything. * This key is available on all devices.

      */ @PublicKey @@ -604,10 +666,11 @@ public final class CameraCharacteristics extends CameraMetadata("android.flash.info.available", boolean.class); /** - *

      The set of hot pixel correction modes that are supported by this + *

      List of hot pixel correction modes for {@link CaptureRequest#HOT_PIXEL_MODE android.hotPixel.mode} that are supported by this * camera device.

      - *

      This tag lists valid modes for {@link CaptureRequest#HOT_PIXEL_MODE android.hotPixel.mode}.

      *

      FULL mode camera devices will always support FAST.

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#HOT_PIXEL_MODE android.hotPixel.mode}

      *

      Optional - This value may be {@code null} on some devices.

      * * @see CaptureRequest#HOT_PIXEL_MODE @@ -617,7 +680,10 @@ public final class CameraCharacteristics extends CameraMetadata("android.hotPixel.availableHotPixelModes", int[].class); /** - *

      Supported resolutions for the JPEG thumbnail.

      + *

      List of JPEG thumbnail sizes for {@link CaptureRequest#JPEG_THUMBNAIL_SIZE android.jpeg.thumbnailSize} supported by this + * camera device.

      + *

      This list will include at least one non-zero resolution, plus (0,0) for indicating no + * thumbnail should be generated.

      *

      Below condiditions will be satisfied for this size list:

      *
        *
      • The sizes will be sorted by increasing pixel area (width x height). @@ -629,39 +695,45 @@ public final class CameraCharacteristics extends CameraMetadataEach 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.
        • - *
      • All non (0, 0) sizes will have non-zero widths and heights. + *
      • All non-(0, 0) sizes will have non-zero widths and heights. * This key is available on all devices.
        • *
      + * + * @see CaptureRequest#JPEG_THUMBNAIL_SIZE */ @PublicKey public static final Key JPEG_AVAILABLE_THUMBNAIL_SIZES = new Key("android.jpeg.availableThumbnailSizes", android.util.Size[].class); /** - *

      List of supported aperture - * values.

      - *

      If the camera device doesn't support variable apertures, - * listed value will be the fixed aperture.

      - *

      If the camera device supports variable apertures, the aperture value + *

      List of aperture size values for {@link CaptureRequest#LENS_APERTURE android.lens.aperture} that are + * supported by this camera device.

      + *

      If the camera device doesn't support a variable lens aperture, + * this list will contain only one value, which is the fixed aperture size.

      + *

      If the camera device supports a variable aperture, the aperture values * in this list will be sorted in ascending order.

      + *

      Units: The aperture f-number

      *

      Optional - This value may be {@code null} on some devices.

      *

      Full capability - * 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

      * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL + * @see CaptureRequest#LENS_APERTURE */ @PublicKey public static final Key LENS_INFO_AVAILABLE_APERTURES = new Key("android.lens.info.availableApertures", float[].class); /** - *

      List of supported neutral density filter values for - * {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity}.

      - *

      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.

      + *

      List of neutral density filter values for + * {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity} that are supported by this camera device.

      + *

      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.

      + *

      Units: Exposure value (EV)

      + *

      Range of valid values:

      + *

      Values are >= 0

      *

      Optional - This value may be {@code null} on some devices.

      *

      Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -675,12 +747,15 @@ public final class CameraCharacteristics extends CameraMetadata("android.lens.info.availableFilterDensities", float[].class); /** - *

      The available focal lengths for this device for use with - * {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}.

      - *

      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.

      + *

      List of focal lengths for {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength} that are supported by this camera + * device.

      + *

      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.

      + *

      Units: Millimeters

      + *

      Range of valid values:

      + *

      Values are > 0

      *

      This key is available on all devices.

      * * @see CaptureRequest#LENS_FOCAL_LENGTH @@ -690,11 +765,12 @@ public final class CameraCharacteristics extends CameraMetadata("android.lens.info.availableFocalLengths", float[].class); /** - *

      List containing a subset of the optical image - * stabilization (OIS) modes specified in - * {@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}.

      - *

      If OIS is not implemented for a given camera device, this will + *

      List of optical image stabilization (OIS) modes for + * {@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode} that are supported by this camera device.

      + *

      If OIS is not supported by a given camera device, this list will * contain only OFF.

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}

      *

      Optional - This value may be {@code null} on some devices.

      *

      Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -708,9 +784,13 @@ public final class CameraCharacteristics extends CameraMetadata("android.lens.info.availableOpticalStabilization", int[].class); /** - *

      Optional. Hyperfocal distance for this lens.

      + *

      Hyperfocal distance for this lens.

      *

      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.

      + *

      Units: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details

      + *

      Range of valid values:
      + * If lens is fixed focus, >= 0. If lens has focuser unit, the value is + * within (0.0f, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}]

      *

      Optional - This value may be {@code null} on some devices.

      *

      Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -718,6 +798,7 @@ public final class CameraCharacteristics extends CameraMetadata LENS_INFO_HYPERFOCAL_DISTANCE = @@ -725,15 +806,19 @@ public final class CameraCharacteristics extends CameraMetadataShortest distance from frontmost surface - * of the lens that can be focused correctly.

      - *

      If the lens is fixed-focus, this should be + * of the lens that can be brought into sharp focus.

      + *

      If the lens is fixed-focus, this will be * 0.

      + *

      Units: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details

      + *

      Range of valid values:
      + * >= 0

      *

      Optional - This value may be {@code null} on some devices.

      *

      Limited capability - * 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

      * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL + * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION */ @PublicKey public static final Key LENS_INFO_MINIMUM_FOCUS_DISTANCE = @@ -743,6 +828,8 @@ public final class CameraCharacteristics extends CameraMetadataDimensions of lens shading map.

      *

      The map should be on the order of 30-40 rows and columns, and * must be smaller than 64x64.

      + *

      Range of valid values:
      + * Both values >= 1

      *

      Optional - This value may be {@code null} on some devices.

      *

      Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -760,6 +847,21 @@ public final class CameraCharacteristics extends CameraMetadata + *

      APPROXIMATE and CALIBRATED devices report the focus metadata in + * units of diopters (1/meter), so 0.0f 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.

      + *

      UNCALIBRATED devices do not use units that are directly comparable + * to any real physical measurement, but 0.0f still represents farthest + * focus, and {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} represents the + * nearest focus the device can achieve.

      + *

      Possible values: + *

        + *
      • {@link #LENS_INFO_FOCUS_DISTANCE_CALIBRATION_UNCALIBRATED UNCALIBRATED}
        • + *
      • {@link #LENS_INFO_FOCUS_DISTANCE_CALIBRATION_APPROXIMATE APPROXIMATE}
        • + *
      • {@link #LENS_INFO_FOCUS_DISTANCE_CALIBRATION_CALIBRATED CALIBRATED}
        • + *

      *

      Optional - This value may be {@code null} on some devices.

      *

      Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -781,6 +883,11 @@ public final class CameraCharacteristics extends CameraMetadataDirection the camera faces relative to * device screen.

      + *

      Possible values: + *

        + *
      • {@link #LENS_FACING_FRONT FRONT}
        • + *
      • {@link #LENS_FACING_BACK BACK}
        • + *

      *

      This key is available on all devices.

      * @see #LENS_FACING_FRONT * @see #LENS_FACING_BACK @@ -790,10 +897,12 @@ public final class CameraCharacteristics extends CameraMetadata("android.lens.facing", int.class); /** - *

      The set of noise reduction modes supported by this camera device.

      - *

      This tag lists the valid modes for {@link CaptureRequest#NOISE_REDUCTION_MODE android.noiseReduction.mode}.

      - *

      Full-capability camera devices must always support OFF and FAST.

      + *

      List of noise reduction modes for {@link CaptureRequest#NOISE_REDUCTION_MODE android.noiseReduction.mode} that are supported + * by this camera device.

      + *

      Full-capability camera devices will always support OFF and FAST.

      *

      Legacy-capability camera devices will only support FAST mode.

      + *

      Range of valid values:
      + * Any value listed in {@link CaptureRequest#NOISE_REDUCTION_MODE android.noiseReduction.mode}

      *

      Optional - This value may be {@code null} on some devices.

      *

      Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -844,7 +953,15 @@ public final class CameraCharacteristics extends CameraMetadataProcessed (but not-stalling): any non-RAW format without a stall duration. * Typically ImageFormat#YUV_420_888, ImageFormat#NV21, ImageFormat#YV12. *

    + *

    Range of valid values:

    + *

    For processed (and stalling) format streams, >= 1.

    + *

    For Raw format (either stalling or non-stalling) streams, >= 0.

    + *

    For processed (but not stalling) format streams, >= 3 + * for FULL mode devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL); + * >= 2 for LIMITED mode devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == LIMITED).

    *

    This key is available on all devices.

    + * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @hide */ public static final Key REQUEST_MAX_NUM_OUTPUT_STREAMS = @@ -868,6 +985,8 @@ public final class CameraCharacteristics extends CameraMetadata *

    LEGACY mode devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == LEGACY) * never support raw streams.

    + *

    Range of valid values:

    + *

    >= 0

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL @@ -898,9 +1017,14 @@ public final class CameraCharacteristics extends CameraMetadata *

    For full guarantees, query StreamConfigurationMap#getOutputStallDuration with * a processed format -- it will return 0 for a non-stalling stream.

    - *

    LEGACY devices will support up to 3 processing/non-stalling streams.

    + *

    LEGACY devices will support at least 2 processing/non-stalling streams.

    + *

    Range of valid values:

    + *

    >= 3 + * for FULL mode devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL); + * >= 2 for LIMITED mode devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == LIMITED).

    *

    This key is available on all devices.

    * + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP */ @PublicKey @@ -919,10 +1043,12 @@ public final class CameraCharacteristics extends CameraMetadataRAW and supported format provided by {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}.

    *

    A processed and stalling format is defined as any non-RAW format with a stallDurations > 0. - * Typically only the JPEG format (ImageFormat#JPEG)

    + * Typically only the JPEG format (ImageFormat#JPEG) is a stalling format.

    *

    For full guarantees, query StreamConfigurationMap#getOutputStallDuration with * a processed format -- it will return a non-0 value for a stalling stream.

    *

    LEGACY devices will support up to 1 processing/stalling stream.

    + *

    Range of valid values:

    + *

    >= 1

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP @@ -944,6 +1070,8 @@ public final class CameraCharacteristics extends CameraMetadataFor 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.

    + *

    Range of valid values:

    + *

    0 or 1.

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -993,6 +1121,8 @@ public final class CameraCharacteristics extends CameraMetadata + *

    Range of valid values:
    + * >= 1

    *

    Optional - This value may be {@code null} on some devices.

    */ @PublicKey @@ -1000,7 +1130,7 @@ public final class CameraCharacteristics extends CameraMetadata("android.request.partialResultCount", int.class); /** - *

    List of capabilities that the camera device + *

    List of capabilities that this camera device * advertises as fully supporting.

    *

    A capability is a contract that the camera device makes in order * to be able to satisfy one or more use cases.

    @@ -1018,7 +1148,14 @@ public final class CameraCharacteristics extends CameraMetadataMANUAL_POST_PROCESSING * *

    Other capabilities may be available on either FULL or LIMITED - * devices, but the application should query this field to be sure.

    + * devices, but the application should query this key to be sure.

    + *

    Possible values: + *

      + *
    • {@link #REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE BACKWARD_COMPATIBLE}
      • + *
    • {@link #REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR MANUAL_SENSOR}
      • + *
    • {@link #REQUEST_AVAILABLE_CAPABILITIES_MANUAL_POST_PROCESSING MANUAL_POST_PROCESSING}
      • + *
    • {@link #REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}
      • + *

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL @@ -1054,13 +1191,13 @@ public final class CameraCharacteristics extends CameraMetadata *

    Attempting to get a key from a CaptureResult that is not * listed here will always return a null value. Getting a key from - * a CaptureResult that is listed here must never return a null + * a CaptureResult that is listed here will generally never return a null * value.

    *

    The following keys may return null unless they are enabled:

    *
      *
    • android.statistics.lensShadingMap (non-null iff {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON)
      • *
    - *

    (Those sometimes-null keys should nevertheless be listed here + *

    (Those sometimes-null keys will nevertheless be listed here * if they are available.)

    *

    This field can be used to query the feature set of a camera device * at a more granular level than capabilities. This is especially @@ -1110,6 +1247,9 @@ public final class CameraCharacteristics extends CameraMetadataWhen multiple streams are configured, the minimum * frame duration will be >= max(individual stream min * durations)

    + *

    Units: Nanoseconds

    + *

    Range of valid values:
    + * TODO: Remove property.

    *

    Optional - This value may be {@code null} on some devices.

    * @deprecated * @hide @@ -1122,6 +1262,8 @@ public final class CameraCharacteristics extends CameraMetadataThe JPEG resolutions that are supported by this camera device.

    *

    The resolutions are listed as (width, height) pairs. All camera devices will support * sensor maximum resolution (defined by {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}).

    + *

    Range of valid values:
    + * TODO: Remove property.

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE @@ -1135,14 +1277,19 @@ public final class CameraCharacteristics extends CameraMetadataThe maximum ratio between both active area width * and crop region width, and active area height and - * crop region height.

    + * crop region height, for {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}.

    *

    This represents the maximum amount of zooming possible by * the camera device, or equivalently, the minimum cropping * window size.

    *

    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.

    + *

    Units: Zoom scale factor

    + *

    Range of valid values:
    + * >=1

    *

    This key is available on all devices.

    + * + * @see CaptureRequest#SCALER_CROP_REGION */ @PublicKey public static final Key SCALER_AVAILABLE_MAX_DIGITAL_ZOOM = @@ -1157,6 +1304,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    When multiple streams are configured, the minimum frame duration will * be >= max(individual stream min durations).

    + *

    Units: Nanoseconds

    *

    Optional - This value may be {@code null} on some devices.

    * @deprecated * @hide @@ -1356,6 +1504,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    (Keep in sync with * StreamConfigurationMap#getOutputMinFrameDuration)

    + *

    Units: (format, width, height, ns) x n

    *

    This key is available on all devices.

    * * @see CaptureRequest#SENSOR_FRAME_DURATION @@ -1422,6 +1571,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    (Keep up to date with * StreamConfigurationMap#getOutputStallDuration(int, Size) )

    + *

    Units: (format, width, height, ns) x n

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES @@ -1533,6 +1683,11 @@ public final class CameraCharacteristics extends CameraMetadata *

    FULL capability devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL) will support * FREEFORM cropping. LEGACY capability devices will only support CENTER_ONLY cropping.

    + *

    Possible values: + *

      + *
    • {@link #SCALER_CROPPING_TYPE_CENTER_ONLY CENTER_ONLY}
      • + *
    • {@link #SCALER_CROPPING_TYPE_FREEFORM FREEFORM}
      • + *

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL @@ -1546,22 +1701,35 @@ public final class CameraCharacteristics extends CameraMetadata("android.scaler.croppingType", int.class); /** - *

    Area of raw data which corresponds to only + *

    The area of the image sensor which corresponds to * active pixels.

    - *

    It is smaller or equal to - * sensor full pixel array, which could include the black calibration pixels. - * This key is available on all devices.

    + *

    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.

    + *

    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}.

    + *

    Most other keys listing pixel coordinates have their coordinate systems based on the + * active array, with (0, 0) being the top-left of the active array rectangle.

    + *

    The active array may be smaller than the full pixel array, since the full array may + * include black calibration pixels or other inactive regions.

    + *

    Units: Pixel coordinates on the image sensor

    + *

    Range of valid values:

    + *

    This key is available on all devices.

    + * + * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE */ @PublicKey public static final Key SENSOR_INFO_ACTIVE_ARRAY_SIZE = new Key("android.sensor.info.activeArraySize", android.graphics.Rect.class); /** - *

    Range of valid sensitivities.

    - *

    The minimum and maximum valid values for the - * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} control.

    + *

    Range of sensitivities for {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} supported by this + * camera device.

    *

    The values are the standard ISO sensitivity values, * as defined in ISO 12232:2006.

    + *

    Range of valid values:
    + * Min <= 100, Max >= 800

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1578,6 +1746,14 @@ public final class CameraCharacteristics extends CameraMetadataThe arrangement of color filters on sensor; * represents the colors in the top-left 2x2 section of * the sensor, in reading order.

    + *

    Possible values: + *

      + *
    • {@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGGB RGGB}
      • + *
    • {@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GRBG GRBG}
      • + *
    • {@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GBRG GBRG}
      • + *
    • {@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_BGGR BGGR}
      • + *
    • {@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGB RGB}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1595,11 +1771,13 @@ public final class CameraCharacteristics extends CameraMetadata("android.sensor.info.colorFilterArrangement", int.class); /** - *

    Range of valid exposure - * times used by {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}.

    - *

    The min value will be <= 100e3 (100 us). For FULL + *

    The range of image exposure times for {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} supported + * by this camera device.

    + *

    Units: Nanoseconds

    + *

    Range of valid values:
    + * 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)

    + * the maximum exposure time will be greater than 100ms.

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1613,18 +1791,17 @@ public final class CameraCharacteristics extends CameraMetadata>("android.sensor.info.exposureTimeRange", new TypeReference>() {{ }}); /** - *

    Maximum possible frame duration (minimum frame - * rate).

    - *

    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.

    - *

    Refer to - * StreamConfigurationMap#getOutputMinFrameDuration(int,Size) - * for the minimum frame duration values.

    - *

    For FULL capability devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL), - * max will be >= 100e6 (100ms).

    + *

    The maximum possible frame duration (minimum frame rate) for + * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration} that is supported this 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.

    + *

    Refer to StreamConfigurationMap#getOutputMinFrameDuration(int,Size) for the minimum + * frame duration values.

    + *

    Units: Nanoseconds

    + *

    Range of valid values:
    + * For FULL capability devices + * ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL), at least 100ms.

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1642,6 +1819,7 @@ public final class CameraCharacteristics extends CameraMetadata *

    This is the physical size of the sensor pixel * array defined by {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.

    + *

    Units: Millimeters

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE @@ -1651,7 +1829,7 @@ public final class CameraCharacteristics extends CameraMetadata("android.sensor.info.physicalSize", android.util.SizeF.class); /** - *

    Dimensions of full pixel array, possibly + *

    Dimensions of the full pixel array, possibly * including black calibration pixels.

    *

    The pixel count of the full pixel array, * which covers {@link CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE android.sensor.info.physicalSize} area.

    @@ -1660,6 +1838,10 @@ public final class CameraCharacteristics extends CameraMetadata + *

    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.

    + *

    Units: Pixels

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP @@ -1676,11 +1858,13 @@ public final class CameraCharacteristics extends CameraMetadata + * {@link CameraCharacteristics#SENSOR_BLACK_LEVEL_PATTERN android.sensor.blackLevelPattern} key.

    *

    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).

    + *

    Range of valid values:
    + * > 255 (8-bit output)

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#SENSOR_BLACK_LEVEL_PATTERN @@ -1695,6 +1879,11 @@ public final class CameraCharacteristics extends CameraMetadata *

    This characteristic defines the source for the timestamps, and therefore whether they * can be compared against other system time sources/timestamps.

    + *

    Possible values: + *

      + *
    • {@link #SENSOR_INFO_TIMESTAMP_SOURCE_UNKNOWN UNKNOWN}
      • + *
    • {@link #SENSOR_INFO_TIMESTAMP_SOURCE_REALTIME REALTIME}
      • + *

    *

    This key is available on all devices.

    * @see #SENSOR_INFO_TIMESTAMP_SOURCE_UNKNOWN * @see #SENSOR_INFO_TIMESTAMP_SOURCE_REALTIME @@ -1708,15 +1897,37 @@ public final class CameraCharacteristics extends CameraMetadata - *

    The values in this tag correspond to the values defined for the + *

    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.

    - *

    If this tag is present, then {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM1 android.sensor.colorTransform1}, + *

    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.

    *

    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.

    + *

    Possible values: + *

      + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_DAYLIGHT DAYLIGHT}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_FLUORESCENT FLUORESCENT}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_TUNGSTEN TUNGSTEN}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_FLASH FLASH}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_FINE_WEATHER FINE_WEATHER}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_CLOUDY_WEATHER CLOUDY_WEATHER}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_SHADE SHADE}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_DAYLIGHT_FLUORESCENT DAYLIGHT_FLUORESCENT}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_DAY_WHITE_FLUORESCENT DAY_WHITE_FLUORESCENT}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_COOL_WHITE_FLUORESCENT COOL_WHITE_FLUORESCENT}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_WHITE_FLUORESCENT WHITE_FLUORESCENT}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_STANDARD_A STANDARD_A}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_STANDARD_B STANDARD_B}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_STANDARD_C STANDARD_C}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_D55 D55}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_D65 D65}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_D75 D75}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_D50 D50}
      • + *
    • {@link #SENSOR_REFERENCE_ILLUMINANT1_ISO_STUDIO_TUNGSTEN ISO_STUDIO_TUNGSTEN}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM1 @@ -1752,12 +1963,12 @@ public final class CameraCharacteristics extends CameraMetadata - *

    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.

    - *

    If this tag is present, then {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM2 android.sensor.colorTransform2}, + *

    See {@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT1 android.sensor.referenceIlluminant1} for more details.

    + *

    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.

    + *

    Range of valid values:
    + * Any value listed in {@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT1 android.sensor.referenceIlluminant1}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM2 @@ -1905,13 +2116,15 @@ public final class CameraCharacteristics extends CameraMetadataA fixed black level offset for each of the color filter arrangement * (CFA) mosaic channels.

    - *

    This tag specifies the zero light value for each of the CFA mosaic + *

    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}.

    *

    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.

    + *

    Range of valid values:
    + * >= 0 for each.

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT @@ -1941,11 +2154,14 @@ public final class CameraCharacteristics extends CameraMetadata("android.sensor.maxAnalogSensitivity", int.class); /** - *

    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

    + *

    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.

    + *

    Units: Degrees of clockwise rotation; always a multiple of + * 90

    + *

    Range of valid values:
    + * 0, 90, 180, 270

    *

    This key is available on all devices.

    */ @PublicKey @@ -1953,8 +2169,11 @@ public final class CameraCharacteristics extends CameraMetadata("android.sensor.orientation", int.class); /** - *

    Lists the supported sensor test pattern modes for {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}.

    - *

    Optional. Defaults to [OFF].

    + *

    List of sensor test pattern modes for {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode} + * supported by this camera device.

    + *

    Defaults to OFF, and always includes OFF if defined.

    + *

    Range of valid values:
    + * Any value listed in {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CaptureRequest#SENSOR_TEST_PATTERN_MODE @@ -1964,16 +2183,14 @@ public final class CameraCharacteristics extends CameraMetadata("android.sensor.availableTestPatternModes", int[].class); /** - *

    The face detection modes that are available - * for this camera device.

    + *

    List of face detection modes for {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} that are + * supported by this camera device.

    *

    OFF is always supported.

    - *

    SIMPLE means the device supports the - * android.statistics.faceRectangles and - * android.statistics.faceScores outputs.

    - *

    FULL means the device additionally supports the - * android.statistics.faceIds and - * android.statistics.faceLandmarks outputs.

    + *

    Range of valid values:
    + * Any value listed in {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode}

    *

    This key is available on all devices.

    + * + * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE */ @PublicKey public static final Key STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES = @@ -1982,6 +2199,10 @@ public final class CameraCharacteristics extends CameraMetadataThe maximum number of simultaneously detectable * faces.

    + *

    Range of valid values:
    + * 0 for cameras without available face detection; otherwise: + * >=4 for LIMITED or FULL hwlevel devices or + * >0 for LEGACY devices.

    *

    This key is available on all devices.

    */ @PublicKey @@ -1989,12 +2210,13 @@ public final class CameraCharacteristics extends CameraMetadata("android.statistics.info.maxFaceCount", int.class); /** - *

    The set of hot pixel map output modes supported by this camera device.

    - *

    This tag lists valid output modes for {@link CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE android.statistics.hotPixelMapMode}.

    - *

    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.

    - *

    Required on devices with the RAW capability.

    + *

    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.

    + *

    If no hotpixel map output is available for this camera device, this will contain only + * false.

    + *

    ON is always supported on devices with the RAW capability.

    + *

    Range of valid values:
    + * Any value listed in {@link CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE android.statistics.hotPixelMapMode}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE @@ -2006,10 +2228,9 @@ public final class CameraCharacteristics extends CameraMetadataMaximum number of supported points in the * tonemap curve that can be used for {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}.

    - *

    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.

    + *

    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.

    *

    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.

    @@ -2026,10 +2247,12 @@ public final class CameraCharacteristics extends CameraMetadata("android.tonemap.maxCurvePoints", int.class); /** - *

    The set of tonemapping modes supported by this camera device.

    - *

    This tag lists the valid modes for {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode}.

    - *

    Full-capability camera devices must always support CONTRAST_CURVE and - * FAST.

    + *

    List of tonemapping modes for {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} that are supported by this camera + * device.

    + *

    Camera devices that support the MANUAL_POST_PROCESSING capability will always list + * CONTRAST_CURVE and FAST. This includes all FULL level devices.

    + *

    Range of valid values:
    + * Any value listed in {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -2044,6 +2267,10 @@ public final class CameraCharacteristics extends CameraMetadataA list of camera LEDs that are available on this system.

    + *

    Possible values: + *

      + *
    • {@link #LED_AVAILABLE_LEDS_TRANSMIT TRANSMIT}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    * @see #LED_AVAILABLE_LEDS_TRANSMIT * @hide @@ -2054,7 +2281,7 @@ public final class CameraCharacteristics extends CameraMetadataGenerally classifies the overall set of the camera device functionality.

    *

    Camera devices will come in three flavors: LEGACY, LIMITED and FULL.

    - *

    A FULL device has the most support possible and will support below capabilities:

    + *

    A FULL device will support below capabilities:

    *
      *
    • 30fps at maximum resolution (== sensor resolution) is preferred, more than 20fps is required.
      • *
    • Per frame control ({@link CameraCharacteristics#SYNC_MAX_LATENCY android.sync.maxLatency} == PER_FRAME_CONTROL)
      • @@ -2068,17 +2295,38 @@ public final class CameraCharacteristics extends CameraMetadata *

      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}.

      + *

      Some features are not part of any particular hardware level or capability and must be + * queried separately. These include:

      + *
        + *
      • Calibrated timestamps ({@link CameraCharacteristics#SENSOR_INFO_TIMESTAMP_SOURCE android.sensor.info.timestampSource} == REALTIME)
        • + *
      • Precision lens control ({@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} == CALIBRATED)
        • + *
      • Face detection ({@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes})
        • + *
      • 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})
        • + *
      *

      A LEGACY device does not support per-frame control, manual sensor control, manual * post-processing, arbitrary cropping regions, and has relaxed performance constraints.

      *

      Each higher level supports everything the lower level supports * in this order: FULL > LIMITED > LEGACY.

      + *

      Possible values: + *

        + *
      • {@link #INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}
        • + *
      • {@link #INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}
        • + *
      • {@link #INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}
        • + *

      *

      This key is available on all devices.

      * + * @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 @@ -2120,6 +2368,14 @@ public final class CameraCharacteristics extends CameraMetadataSince result4 has a frameNumber == 4 and * android.sync.frameNumber == 2, the distance is clearly * 4 - 2 = 2.

      + *

      Units: Frame counts

      + *

      Possible values: + *

        + *
      • {@link #SYNC_MAX_LATENCY_PER_FRAME_CONTROL PER_FRAME_CONTROL}
        • + *
      • {@link #SYNC_MAX_LATENCY_UNKNOWN UNKNOWN}
        • + *

      + *

      Available values for this device:
      + * A positive value, PER_FRAME_CONTROL, or UNKNOWN.

      *

      This key is available on all devices.

      * @see #SYNC_MAX_LATENCY_PER_FRAME_CONTROL * @see #SYNC_MAX_LATENCY_UNKNOWN diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java index d3ef07cff564..16df8441b171 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 { *
        *
      • RAW_SENSOR is supported as an output format.
        • *
      • 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}.
        • + * 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}. *
      • All DNG-related optional metadata entries are provided - * by the camera device.
        • + * by the camera device. *
      * * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE @@ -437,13 +437,13 @@ public abstract class CameraMetadata { *
    • At least one input stream can be used.
      • *
    • RAW_OPAQUE is supported as an output/input format
      • *
    • Using RAW_OPAQUE does not cause a frame rate drop - * relative to the sensor's maximum capture rate (at that - * resolution).
      • + * relative to the sensor's maximum capture rate (at that + * resolution). *
    • RAW_OPAQUE will be reprocessable into both YUV_420_888 - * and JPEG formats.
      • + * and JPEG formats. *
    • The maximum available resolution for RAW_OPAQUE streams - * (both input/output) will match the maximum available - * resolution of JPEG streams.
      • + * (both input/output) will match the maximum available + * resolution of JPEG streams. *
    * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @hide @@ -1215,8 +1215,7 @@ public abstract class CameraMetadata { * image while recording video) use case.

    *

    The camera device should take the highest-quality image * possible (given the other settings) without disrupting the - * frame rate of video recording.
    - *

    + * frame rate of video recording.

    * @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT = 4; @@ -1866,8 +1865,6 @@ public abstract class CameraMetadata { /** *

    Return face rectangle and confidence values only.

    - *

    In this mode, only android.statistics.faceRectangles and - * android.statistics.faceScores outputs are valid.

    * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE */ public static final int STATISTICS_FACE_DETECT_MODE_SIMPLE = 1; @@ -1875,11 +1872,7 @@ public abstract class CameraMetadata { /** *

    Return all face * metadata.

    - *

    In this mode, - * android.statistics.faceRectangles, - * android.statistics.faceScores, - * android.statistics.faceIds, and - * android.statistics.faceLandmarks outputs are valid.

    + *

    In this mode, face rectangles, scores, landmarks, and face IDs are all valid.

    * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE */ public static final int STATISTICS_FACE_DETECT_MODE_FULL = 2; diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java index e65e6277251e..6aec72a36762 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> * modify the comment blocks at the start or end. *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/ - /** *

    The mode control selects how the image data is converted from the * sensor's native color into linear sRGB color.

    @@ -518,6 +517,12 @@ public final class CaptureRequest extends CameraMetadata> * *

    Both the input and output value ranges must match. Overflow/underflow * values are clipped to fit within the range.

    + *

    Possible values: + *

      + *
    • {@link #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX TRANSFORM_MATRIX}
      • + *
    • {@link #COLOR_CORRECTION_MODE_FAST FAST}
      • + *
    • {@link #COLOR_CORRECTION_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -547,6 +552,7 @@ public final class CaptureRequest extends CameraMetadata> * in this matrix result metadata. The transform should keep the magnitude * of the output color values within [0, 1.0] (assuming input color * values is within the normalized range [0, 1.0]), or clipping may occur.

    + *

    Units: Unitless scale factors

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -569,6 +575,7 @@ public final class CaptureRequest extends CameraMetadata> * TRANSFORM_MATRIX.

    *

    The gains in the result metadata are the gains actually * applied by the camera device to the current frame.

    + *

    Units: Unitless gain factors

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -583,8 +590,6 @@ public final class CaptureRequest extends CameraMetadata> /** *

    Mode of operation for the chromatic aberration correction algorithm.

    - *

    This must be set to a valid mode from - * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}.

    *

    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 @@ -596,6 +601,14 @@ public final class CaptureRequest extends CameraMetadata> * capture rate. FAST means the camera device will not slow down capture rate when * applying aberration correction.

    *

    LEGACY devices will always be in FAST mode.

    + *

    Possible values: + *

      + *
    • {@link #COLOR_CORRECTION_ABERRATION_MODE_OFF OFF}
      • + *
    • {@link #COLOR_CORRECTION_ABERRATION_MODE_FAST FAST}
      • + *
    • {@link #COLOR_CORRECTION_ABERRATION_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES @@ -629,7 +642,7 @@ public final class CaptureRequest extends CameraMetadata> * 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.

    - *

    The default mode is AUTO, which must be supported by all + *

    The default mode is AUTO, which is supported by all * camera devices.

    *

    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), @@ -637,6 +650,15 @@ public final class CaptureRequest extends CameraMetadata> * 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.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AE_ANTIBANDING_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_AE_ANTIBANDING_MODE_50HZ 50HZ}
      • + *
    • {@link #CONTROL_AE_ANTIBANDING_MODE_60HZ 60HZ}
      • + *
    • {@link #CONTROL_AE_ANTIBANDING_MODE_AUTO AUTO}
      • + *

    + *

    Available values for this device:

    + *

    {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes}

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES @@ -670,6 +692,9 @@ public final class CaptureRequest extends CameraMetadata> * 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).

    + *

    Units: Compensation steps

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE android.control.aeCompensationRange}

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE @@ -685,9 +710,11 @@ public final class CaptureRequest extends CameraMetadata> /** *

    Whether auto-exposure (AE) is currently locked to its latest * calculated values.

    - *

    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.

    + *

    When set to true (ON), the AE algorithm is locked to its latest parameters, + * and will not change exposure settings until the lock is set to false (OFF).

    + *

    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.

    *

    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.

    *

    If AE precapture is triggered (see {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}) @@ -696,6 +723,19 @@ public final class CaptureRequest extends CameraMetadata> * 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.

    + *

    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:

    + *
      + *
    1. Starting in auto-AE mode:
      2. + *
    2. Lock AE
      3. + *
    3. Wait for the first result to be output that has the AE locked
      4. + *
    4. Copy exposure settings from that result into a request, set the request to manual AE
      5. + *
    5. Submit the capture request, proceed to run manual AE as desired.
      6. + *
    *

    See {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE lock related state transition details.

    *

    This key is available on all devices.

    * @@ -731,8 +771,19 @@ public final class CaptureRequest extends CameraMetadata> * camera device auto-exposure routine for the overridden * fields for a given capture will be available in its * CaptureResult.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AE_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_AE_MODE_ON ON}
      • + *
    • {@link #CONTROL_AE_MODE_ON_AUTO_FLASH ON_AUTO_FLASH}
      • + *
    • {@link #CONTROL_AE_MODE_ON_ALWAYS_FLASH ON_ALWAYS_FLASH}
      • + *
    • {@link #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE ON_AUTO_FLASH_REDEYE}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES android.control.aeAvailableModes}

    *

    This key is available on all devices.

    * + * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES * @see CaptureRequest#CONTROL_MODE * @see CameraCharacteristics#FLASH_INFO_AVAILABLE * @see CaptureRequest#FLASH_MODE @@ -750,25 +801,35 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.control.aeMode", int.class); /** - *

    List of areas to use for - * metering.

    - *

    Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0. + *

    List of metering areas to use for auto-exposure adjustment.

    + *

    Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0. * Otherwise will always be present.

    + *

    The maximum number of regions supported by the device is determined by the value + * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe}.

    *

    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.

    - *

    The weight must range from 0 to 1000, and represents a weight + *

    The weight must be within [0, 1000], 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.

    - *

    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.

    + *

    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.

    + *

    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 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.

    + *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + *

    Range of valid values:
    + * Coordinates must be between [(0,0), (width, height)) of + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AE @@ -780,13 +841,20 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.control.aeRegions", android.hardware.camera2.params.MeteringRectangle[].class); /** - *

    Range over which fps can be adjusted to - * maintain exposure.

    + *

    Range over which the auto-exposure routine can + * adjust the capture frame rate to maintain good + * exposure.

    *

    Only constrains auto-exposure (AE) algorithm, not - * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} - * This key is available on all devices.

    + * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} and + * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}.

    + *

    Units: Frames per second (FPS)

    + *

    Range of valid values:
    + * Any of the entries in {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES android.control.aeAvailableTargetFpsRanges}

    + *

    This key is available on all devices.

    * + * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES * @see CaptureRequest#SENSOR_EXPOSURE_TIME + * @see CaptureRequest#SENSOR_FRAME_DURATION */ @PublicKey public static final Key> CONTROL_AE_TARGET_FPS_RANGE = @@ -811,6 +879,15 @@ public final class CaptureRequest extends CameraMetadata> * depends on the current AE mode and state; see * {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition * details.

    + *

    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.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE IDLE}
      • + *
    • {@link #CONTROL_AE_PRECAPTURE_TRIGGER_START START}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -832,9 +909,21 @@ public final class CaptureRequest extends CameraMetadata> * (i.e. {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} > 0).

    *

    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. - * This key is available on all devices.

    + * in result metadata.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AF_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_AF_MODE_AUTO AUTO}
      • + *
    • {@link #CONTROL_AF_MODE_MACRO MACRO}
      • + *
    • {@link #CONTROL_AF_MODE_CONTINUOUS_VIDEO CONTINUOUS_VIDEO}
      • + *
    • {@link #CONTROL_AF_MODE_CONTINUOUS_PICTURE CONTINUOUS_PICTURE}
      • + *
    • {@link #CONTROL_AF_MODE_EDOF EDOF}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES android.control.afAvailableModes}

    + *

    This key is available on all devices.

    * + * @see CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES * @see CaptureResult#CONTROL_AF_STATE * @see CaptureRequest#CONTROL_MODE * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE @@ -850,25 +939,35 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.control.afMode", int.class); /** - *

    List of areas to use for focus - * estimation.

    - *

    Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0. + *

    List of metering areas to use for auto-focus.

    + *

    Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0. * Otherwise will always be present.

    + *

    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}.

    *

    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.

    - *

    The weight must range from 0 to 1000, and represents a weight + *

    The weight must be within [0, 1000], 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.

    - *

    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.

    + *

    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.

    + *

    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 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.

    + *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + *

    Range of valid values:
    + * Coordinates must be between [(0,0), (width, height)) of + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AF @@ -892,6 +991,12 @@ public final class CaptureRequest extends CameraMetadata> * START for multiple captures in a row means restarting the AF operation over * and over again.

    *

    See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what the trigger means for each AF mode.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AF_TRIGGER_IDLE IDLE}
      • + *
    • {@link #CONTROL_AF_TRIGGER_START START}
      • + *
    • {@link #CONTROL_AF_TRIGGER_CANCEL CANCEL}
      • + *

    *

    This key is available on all devices.

    * * @see CaptureResult#CONTROL_AF_STATE @@ -906,6 +1011,21 @@ public final class CaptureRequest extends CameraMetadata> /** *

    Whether auto-white balance (AWB) is currently locked to its * latest calculated values.

    + *

    When set to true (ON), the AWB algorithm is locked to its latest parameters, + * and will not change color balance settings until the lock is set to false (OFF).

    + *

    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:

    + *
      + *
    1. Starting in auto-AWB mode:
      2. + *
    2. Lock AWB
      3. + *
    3. Wait for the first result to be output that has the AWB locked
      4. + *
    4. Copy AWB settings from that result into a request, set the request to manual AWB
      5. + *
    5. Submit the capture request, proceed to run manual AWB as desired.
      6. + *
    *

    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.

    @@ -938,11 +1058,26 @@ public final class CaptureRequest extends CameraMetadata> * {@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.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AWB_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_AWB_MODE_AUTO AUTO}
      • + *
    • {@link #CONTROL_AWB_MODE_INCANDESCENT INCANDESCENT}
      • + *
    • {@link #CONTROL_AWB_MODE_FLUORESCENT FLUORESCENT}
      • + *
    • {@link #CONTROL_AWB_MODE_WARM_FLUORESCENT WARM_FLUORESCENT}
      • + *
    • {@link #CONTROL_AWB_MODE_DAYLIGHT DAYLIGHT}
      • + *
    • {@link #CONTROL_AWB_MODE_CLOUDY_DAYLIGHT CLOUDY_DAYLIGHT}
      • + *
    • {@link #CONTROL_AWB_MODE_TWILIGHT TWILIGHT}
      • + *
    • {@link #CONTROL_AWB_MODE_SHADE SHADE}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#CONTROL_AWB_AVAILABLE_MODES android.control.awbAvailableModes}

    *

    This key is available on all devices.

    * * @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 @@ -959,10 +1094,12 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.control.awbMode", int.class); /** - *

    List of areas to use for illuminant + *

    List of metering areas to use for auto-white-balance illuminant * estimation.

    - *

    Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0. + *

    Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0. * Otherwise will always be present.

    + *

    The maximum number of regions supported by the device is determined by the value + * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb}.

    *

    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, @@ -973,11 +1110,20 @@ public final class CaptureRequest extends CameraMetadata> * 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.

    - *

    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.

    + *

    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.

    + *

    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 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.

    + *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + *

    Range of valid values:
    + * Coordinates must be between [(0,0), (width, height)) of + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AWB @@ -997,8 +1143,18 @@ public final class CaptureRequest extends CameraMetadata> * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF and any 3A routine is active.

    *

    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. - * This key is available on all devices.

    + * contains MANUAL_SENSOR. Other intent values are always supported.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_CAPTURE_INTENT_CUSTOM CUSTOM}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_PREVIEW PREVIEW}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_STILL_CAPTURE STILL_CAPTURE}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_VIDEO_RECORD VIDEO_RECORD}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT VIDEO_SNAPSHOT}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_ZERO_SHUTTER_LAG ZERO_SHUTTER_LAG}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_MANUAL MANUAL}
      • + *

    + *

    This key is available on all devices.

    * * @see CaptureRequest#CONTROL_MODE * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES @@ -1022,11 +1178,23 @@ public final class CaptureRequest extends CameraMetadata> * implementor of the camera device, and should not be * depended on to be consistent (or present) across all * devices.

    - *

    A color effect will only be applied if - * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_EFFECT_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_EFFECT_MODE_MONO MONO}
      • + *
    • {@link #CONTROL_EFFECT_MODE_NEGATIVE NEGATIVE}
      • + *
    • {@link #CONTROL_EFFECT_MODE_SOLARIZE SOLARIZE}
      • + *
    • {@link #CONTROL_EFFECT_MODE_SEPIA SEPIA}
      • + *
    • {@link #CONTROL_EFFECT_MODE_POSTERIZE POSTERIZE}
      • + *
    • {@link #CONTROL_EFFECT_MODE_WHITEBOARD WHITEBOARD}
      • + *
    • {@link #CONTROL_EFFECT_MODE_BLACKBOARD BLACKBOARD}
      • + *
    • {@link #CONTROL_EFFECT_MODE_AQUA AQUA}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS android.control.availableEffects}

    *

    This key is available on all devices.

    * - * @see CaptureRequest#CONTROL_MODE + * @see CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS * @see #CONTROL_EFFECT_MODE_OFF * @see #CONTROL_EFFECT_MODE_MONO * @see #CONTROL_EFFECT_MODE_NEGATIVE @@ -1042,9 +1210,9 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.control.effectMode", int.class); /** - *

    Overall mode of 3A control + *

    Overall mode of 3A (auto-exposure, auto-white-balance, auto-focus) control * routines.

    - *

    High-level 3A control. When set to OFF, all 3A control + *

    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.

    *

    When set to AUTO, the individual algorithm controls in @@ -1061,7 +1229,15 @@ public final class CaptureRequest extends CameraMetadata> * the subsequent auto 3A capture results.

    *

    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 capability.

    + * support the MANUAL_SENSOR and MANUAL_POST_PROCSESING capabilities. + * FULL mode devices will always support OFF and OFF_KEEP_STATE.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_MODE_AUTO AUTO}
      • + *
    • {@link #CONTROL_MODE_USE_SCENE_MODE USE_SCENE_MODE}
      • + *
    • {@link #CONTROL_MODE_OFF_KEEP_STATE OFF_KEEP_STATE}
      • + *

    *

    This key is available on all devices.

    * * @see CaptureRequest#CONTROL_AF_MODE @@ -1075,18 +1251,40 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.control.mode", int.class); /** - *

    A camera mode optimized for conditions typical in a particular - * capture setting.

    + *

    Control for which scene mode is currently active.

    + *

    Scene modes are custom camera modes optimized for a certain set of conditions and + * capture settings.

    *

    This is the mode that that is active when * {@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE. 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}.

    + * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.

    *

    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.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_SCENE_MODE_DISABLED DISABLED}
      • + *
    • {@link #CONTROL_SCENE_MODE_FACE_PRIORITY FACE_PRIORITY}
      • + *
    • {@link #CONTROL_SCENE_MODE_ACTION ACTION}
      • + *
    • {@link #CONTROL_SCENE_MODE_PORTRAIT PORTRAIT}
      • + *
    • {@link #CONTROL_SCENE_MODE_LANDSCAPE LANDSCAPE}
      • + *
    • {@link #CONTROL_SCENE_MODE_NIGHT NIGHT}
      • + *
    • {@link #CONTROL_SCENE_MODE_NIGHT_PORTRAIT NIGHT_PORTRAIT}
      • + *
    • {@link #CONTROL_SCENE_MODE_THEATRE THEATRE}
      • + *
    • {@link #CONTROL_SCENE_MODE_BEACH BEACH}
      • + *
    • {@link #CONTROL_SCENE_MODE_SNOW SNOW}
      • + *
    • {@link #CONTROL_SCENE_MODE_SUNSET SUNSET}
      • + *
    • {@link #CONTROL_SCENE_MODE_STEADYPHOTO STEADYPHOTO}
      • + *
    • {@link #CONTROL_SCENE_MODE_FIREWORKS FIREWORKS}
      • + *
    • {@link #CONTROL_SCENE_MODE_SPORTS SPORTS}
      • + *
    • {@link #CONTROL_SCENE_MODE_PARTY PARTY}
      • + *
    • {@link #CONTROL_SCENE_MODE_CANDLELIGHT CANDLELIGHT}
      • + *
    • {@link #CONTROL_SCENE_MODE_BARCODE BARCODE}
      • + *
    • {@link #CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes}

    *

    This key is available on all devices.

    * * @see CaptureRequest#CONTROL_AE_MODE @@ -1120,20 +1318,25 @@ public final class CaptureRequest extends CameraMetadata> /** *

    Whether video stabilization is * active.

    - *

    Video stabilization automatically translates and scales images from the camera - * in order to stabilize motion between consecutive frames.

    + *

    Video stabilization automatically translates and scales images from + * the camera in order to stabilize motion between consecutive frames.

    *

    If enabled, video stabilization can modify the * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream stabilized.

    - *

    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.

    - *

    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.

    - *

    Some LEGACY camera devices will not support changing video stabilization - * mode; in this case the value will always override to OFF.

    + *

    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.

    + *

    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.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_VIDEO_STABILIZATION_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_VIDEO_STABILIZATION_MODE_ON ON}
      • + *

    *

    This key is available on all devices.

    * * @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE @@ -1148,14 +1351,21 @@ public final class CaptureRequest extends CameraMetadata> /** *

    Operation mode for edge * enhancement.

    - *

    Edge/sharpness/detail enhancement. OFF means no - * enhancement will be applied by the camera device.

    - *

    This must be set to one of the modes listed in {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}.

    + *

    Edge enhancement improves sharpness and details in the captured image. OFF means + * no enhancement will be applied by the camera device.

    *

    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.

    + *

    Possible values: + *

      + *
    • {@link #EDGE_MODE_OFF OFF}
      • + *
    • {@link #EDGE_MODE_FAST FAST}
      • + *
    • {@link #EDGE_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1186,6 +1396,12 @@ public final class CaptureRequest extends CameraMetadata> *

    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.

    *

    The flash status will be reported by {@link CaptureResult#FLASH_STATE android.flash.state} in the capture result metadata.

    + *

    Possible values: + *

      + *
    • {@link #FLASH_MODE_OFF OFF}
      • + *
    • {@link #FLASH_MODE_SINGLE SINGLE}
      • + *
    • {@link #FLASH_MODE_TORCH TORCH}
      • + *

    *

    This key is available on all devices.

    * * @see CaptureRequest#CONTROL_AE_MODE @@ -1201,12 +1417,18 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.flash.mode", int.class); /** - *

    Set operational mode for hot pixel correction.

    - *

    Valid modes for this camera device are listed in - * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}.

    + *

    Operational mode for hot pixel correction.

    *

    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).

    + * that do not accurately measure the incoming light (i.e. pixels that + * are stuck at an arbitrary value or are oversensitive).

    + *

    Possible values: + *

      + *
    • {@link #HOT_PIXEL_MODE_OFF OFF}
      • + *
    • {@link #HOT_PIXEL_MODE_FAST FAST}
      • + *
    • {@link #HOT_PIXEL_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES @@ -1220,6 +1442,9 @@ public final class CaptureRequest extends CameraMetadata> /** *

    A location object to use when generating image GPS metadata.

    + *

    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.

    *

    This key is available on all devices.

    */ @PublicKey @@ -1229,7 +1454,9 @@ public final class CaptureRequest extends CameraMetadata> /** *

    GPS coordinates to include in output JPEG - * EXIF

    + * EXIF.

    + *

    Range of valid values:
    + * (-180 - 180], [-90,90], [-inf, inf]

    *

    This key is available on all devices.

    * @hide */ @@ -1238,7 +1465,8 @@ public final class CaptureRequest extends CameraMetadata> /** *

    32 characters describing GPS algorithm to - * include in EXIF

    + * include in EXIF.

    + *

    Units: UTF-8 null-terminated string

    *

    This key is available on all devices.

    * @hide */ @@ -1247,7 +1475,8 @@ public final class CaptureRequest extends CameraMetadata> /** *

    Time GPS fix was made to include in - * EXIF

    + * EXIF.

    + *

    Units: UTC in seconds since January 1, 1970

    *

    This key is available on all devices.

    * @hide */ @@ -1255,9 +1484,40 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.jpeg.gpsTimestamp", long.class); /** - *

    Orientation of JPEG image to - * write

    + *

    The orientation for a JPEG image.

    + *

    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.

    + *

    Camera devices may either encode this value into the JPEG EXIF header, or + * rotate the image data to match this orientation.

    + *

    Note that this orientation is relative to the orientation of the camera sensor, given + * by {@link CameraCharacteristics#SENSOR_ORIENTATION android.sensor.orientation}.

    + *

    To translate from the device orientation given by the Android sensor APIs, the following + * sample code may be used:

    + * 
    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;
+     * }
+     *
    + *

    Units: Degrees in multiples of 90

    + *

    Range of valid values:
    + * 0, 90, 180, 270

    *

    This key is available on all devices.

    + * + * @see CameraCharacteristics#SENSOR_ORIENTATION */ @PublicKey public static final Key JPEG_ORIENTATION = @@ -1267,6 +1527,8 @@ public final class CaptureRequest extends CameraMetadata> *

    Compression quality of the final JPEG * image.

    *

    85-95 is typical usage range.

    + *

    Range of valid values:
    + * 1-100; larger is higher quality

    *

    This key is available on all devices.

    */ @PublicKey @@ -1276,6 +1538,8 @@ public final class CaptureRequest extends CameraMetadata> /** *

    Compression quality of JPEG * thumbnail.

    + *

    Range of valid values:
    + * 1-100; larger is higher quality

    *

    This key is available on all devices.

    */ @PublicKey @@ -1286,26 +1550,29 @@ public final class CaptureRequest extends CameraMetadata> *

    Resolution of embedded JPEG thumbnail.

    *

    When set to (0, 0) value, the JPEG EXIF will not contain thumbnail, * but the captured JPEG will still be a valid image.

    - *

    When a jpeg image capture is issued, the thumbnail size selected should have - * the same aspect ratio as the jpeg image.

    + *

    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.

    *

    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.

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES android.jpeg.availableThumbnailSizes}

    *

    This key is available on all devices.

    + * + * @see CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES */ @PublicKey public static final Key JPEG_THUMBNAIL_SIZE = new Key("android.jpeg.thumbnailSize", android.util.Size.class); /** - *

    The ratio of lens focal length to the effective - * aperture diameter.

    - *

    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}.

    + *

    The desired lens aperture size, as a ratio of lens focal length to the + * effective aperture diameter.

    + *

    Setting this value is only supported on the camera devices that have a variable + * aperture lens.

    *

    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} @@ -1318,6 +1585,9 @@ public final class CaptureRequest extends CameraMetadata> * 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.

    + *

    Units: The f-number (f/N)

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1336,10 +1606,8 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.lens.aperture", float.class); /** - *

    State of lens neutral density filter(s).

    - *

    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}.

    + *

    The desired setting for the lens neutral density filter(s).

    + *

    This control will not be supported on most camera devices.

    *

    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 @@ -1351,6 +1619,9 @@ public final class CaptureRequest extends CameraMetadata> *

    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.

    + *

    Units: Exposure Value (EV)

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1365,7 +1636,7 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.lens.filterDensity", float.class); /** - *

    The current lens focal length; used for optical zoom.

    + *

    The desired lens focal length; used for optical zoom.

    *

    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.

    @@ -1374,11 +1645,15 @@ public final class CaptureRequest extends CameraMetadata> * 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.

    - *

    This is expected not to be supported on most devices.

    + *

    Optical zoom will not be supported on most devices.

    + *

    Units: Millimeters

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}

    *

    This key is available on all devices.

    * * @see CaptureRequest#LENS_APERTURE * @see CaptureRequest#LENS_FOCUS_DISTANCE + * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS * @see CaptureResult#LENS_STATE */ @PublicKey @@ -1386,16 +1661,22 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.lens.focalLength", float.class); /** - *

    Distance to plane of sharpest focus, + *

    Desired distance to plane of sharpest focus, * measured from frontmost surface of the lens.

    - *

    0.0f means infinity focus. Used value will be clamped - * to [0.0f, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}].

    + *

    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}).

    + *

    A value of 0.0f means infinity focus. The value set will be clamped to + * [0.0f, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}].

    *

    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.

    *

    LEGACY devices support at most setting this to 0.0f * for infinity focus.

    + *

    Units: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details

    + *

    Range of valid values:
    + * >= 0

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1403,6 +1684,7 @@ public final class CaptureRequest extends CameraMetadata> * * @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 */ @@ -1424,12 +1706,19 @@ public final class CaptureRequest extends CameraMetadata> * 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.

    - *

    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.

    + *

    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.

    *

    Not all devices will support OIS; see * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for * available controls.

    + *

    Possible values: + *

      + *
    • {@link #LENS_OPTICAL_STABILIZATION_MODE_OFF OFF}
      • + *
    • {@link #LENS_OPTICAL_STABILIZATION_MODE_ON ON}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -1447,15 +1736,22 @@ public final class CaptureRequest extends CameraMetadata> /** *

    Mode of operation for the noise reduction algorithm.

    - *

    Noise filtering control. OFF means no noise reduction - * will be applied by the camera device.

    - *

    This must be set to a valid mode from - * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.

    + *

    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.

    *

    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.

    + *

    Possible values: + *

      + *
    • {@link #NOISE_REDUCTION_MODE_OFF OFF}
      • + *
    • {@link #NOISE_REDUCTION_MODE_FAST FAST}
      • + *
    • {@link #NOISE_REDUCTION_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1475,6 +1771,9 @@ public final class CaptureRequest extends CameraMetadata> *

    An application-specified ID for the current * request. Must be maintained unchanged in output * frame

    + *

    Units: arbitrary integer assigned by application

    + *

    Range of valid values:
    + * Any int

    *

    Optional - This value may be {@code null} on some devices.

    * @hide */ @@ -1482,7 +1781,8 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.request.id", int.class); /** - *

    The region of the sensor to read out for this capture.

    + *

    The desired region of the sensor to read out for this capture.

    + *

    This control can be used to implement digital zoom.

    *

    The crop region coordinate system is based off * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0, 0) being the * top-left corner of the sensor active array.

    @@ -1512,6 +1812,8 @@ public final class CaptureRequest extends CameraMetadata> * for rounding and other hardware requirements; the final * crop region used will be included in the output capture * result.

    + *

    Units: Pixel coordinates relative to + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM @@ -1524,14 +1826,23 @@ public final class CaptureRequest extends CameraMetadata> /** *

    Duration each pixel is exposed to * light.

    - *

    If the sensor can't expose this exact duration, it should shorten the - * duration exposed to the nearest possible value (rather than expose longer).

    + *

    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.

    + *

    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.

    + *

    Units: Nanoseconds

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE android.sensor.info.exposureTimeRange}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * 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

    * + * @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 SENSOR_EXPOSURE_TIME = @@ -1609,13 +1920,23 @@ public final class CaptureRequest extends CameraMetadata> * delivered.

    *

    For more details about stalling, see * StreamConfigurationMap#getOutputStallDuration(int,Size).

    + *

    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.

    + *

    Units: Nanoseconds

    + *

    Range of valid values:
    + * 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 max(duration, exposureTime + overhead).

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * 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

    * + * @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 SENSOR_FRAME_DURATION = @@ -1633,6 +1954,9 @@ public final class CaptureRequest extends CameraMetadata> * requested, it will reduce the gain to the nearest supported * value. The final sensitivity used will be available in the * output capture result.

    + *

    Units: ISO arithmetic units

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1672,7 +1996,21 @@ public final class CaptureRequest extends CameraMetadata> *

    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).

    + *

    Defaults to OFF.

    + *

    Possible values: + *

      + *
    • {@link #SENSOR_TEST_PATTERN_MODE_OFF OFF}
      • + *
    • {@link #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR SOLID_COLOR}
      • + *
    • {@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS COLOR_BARS}
      • + *
    • {@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS_FADE_TO_GRAY COLOR_BARS_FADE_TO_GRAY}
      • + *
    • {@link #SENSOR_TEST_PATTERN_MODE_PN9 PN9}
      • + *
    • {@link #SENSOR_TEST_PATTERN_MODE_CUSTOM1 CUSTOM1}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES android.sensor.availableTestPatternModes}

    *

    Optional - This value may be {@code null} on some devices.

    + * + * @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 @@ -1690,27 +2028,32 @@ public final class CaptureRequest extends CameraMetadata> *

    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 {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON. For example, for lens - * shading map with size specified as android.lens.info.shadingMapSize = [ 4, 3 ], - * the output android.statistics.lensShadingMap for this case will be an identity map - * shown below:

    + * shading map with size of [ 4, 3 ], + * the output {@link CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP android.statistics.lensShadingCorrectionMap} for this case will be an identity + * map shown below:

    * 
    [ 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-     * 1.0, 1.0, 1.0, 1.0,   1.0, 1.0, 1.0, 1.0,
-     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0 ]
+     *  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+     *  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+     *  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+     *  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+     *  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0 ]
      *
    - *

    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.

    - *

    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} != OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != 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.

    + *

    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.

    + *

    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} != OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != + * 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.

    + *

    Possible values: + *

      + *
    • {@link #SHADING_MODE_OFF OFF}
      • + *
    • {@link #SHADING_MODE_FAST FAST}
      • + *
    • {@link #SHADING_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1719,6 +2062,7 @@ public final class CaptureRequest extends CameraMetadata> * @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 @@ -1729,13 +2073,20 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.shading.mode", int.class); /** - *

    Control for the face detector + *

    Operating mode for the face detector * unit.

    *

    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}. - * This key is available on all devices.

    + * fields.

    + *

    Possible values: + *

      + *
    • {@link #STATISTICS_FACE_DETECT_MODE_OFF OFF}
      • + *
    • {@link #STATISTICS_FACE_DETECT_MODE_SIMPLE SIMPLE}
      • + *
    • {@link #STATISTICS_FACE_DETECT_MODE_FULL FULL}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}

    + *

    This key is available on all devices.

    * * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES * @see #STATISTICS_FACE_DETECT_MODE_OFF @@ -1747,10 +2098,11 @@ public final class CaptureRequest extends CameraMetadata> new Key("android.statistics.faceDetectMode", int.class); /** - *

    Operating mode for hotpixel map generation.

    - *

    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.

    - *

    This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}.

    + *

    Operating mode for hot pixel map generation.

    + *

    If set to true, a hot pixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}. + * If set to false, no hot pixel map will be returned.

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP @@ -1766,7 +2118,12 @@ public final class CaptureRequest extends CameraMetadata> *

    When set to ON, * android.statistics.lensShadingMap will be provided in * the output result metadata.

    - *

    Required for devices with the RAW capability.

    + *

    ON is always supported on devices with the RAW capability.

    + *

    Possible values: + *

      + *
    • {@link #STATISTICS_LENS_SHADING_MAP_MODE_OFF OFF}
      • + *
    • {@link #STATISTICS_LENS_SHADING_MAP_MODE_ON ON}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1820,10 +2177,10 @@ public final class CaptureRequest extends CameraMetadata> * CONTRAST_CURVE.

    *

    Each channel's curve is defined by an array of control points:

    * 
    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}
    - *

    These are sorted in order of increasing Pin; it is always - * guaranteed that input values 0.0 and 1.0 are included in the list to + *

    These are sorted in order of increasing Pin; 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.

    @@ -1844,20 +2201,23 @@ public final class CaptureRequest extends CameraMetadata> *

    Inverting mapping curve

    *

    Gamma 1/2.2 mapping, with 16 control points:

    * 
    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 ]
      *
    *

    Gamma = 1/2.2 tonemapping curve

    *

    Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:

    * 
    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 ]
      *
    *

    sRGB tonemapping curve

    + *

    Range of valid values:
    + * 0-1 on both input and output coordinates, normalized + * as a floating-point value such that 0 == black and 1 == white.

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1879,7 +2239,7 @@ public final class CaptureRequest extends CameraMetadata> * example. The same logic applies to green and blue channel. * Each channel's curve is defined by an array of control points:

    * 
    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}
    *

    These are sorted in order of increasing Pin; it is always * guaranteed that input values 0.0 and 1.0 are included in the list to @@ -1903,18 +2263,18 @@ public final class CaptureRequest extends CameraMetadata> *

    Inverting mapping curve

    *

    Gamma 1/2.2 mapping, with 16 control points:

    * 
    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) ]
      *
    *

    Gamma = 1/2.2 tonemapping curve

    *

    Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:

    * 
    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) ]
      *
    *

    sRGB tonemapping curve

    *

    Optional - This value may be {@code null} on some devices.

    @@ -1944,8 +2304,6 @@ public final class CaptureRequest extends CameraMetadata> * tables, selective chroma enhancement, or other non-linear color * transforms will be disabled when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is * CONTRAST_CURVE.

    - *

    This must be set to a valid mode in - * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}.

    *

    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 @@ -1953,6 +2311,14 @@ public final class CaptureRequest extends CameraMetadata> *

    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.

    + *

    Possible values: + *

      + *
    • {@link #TONEMAP_MODE_CONTRAST_CURVE CONTRAST_CURVE}
      • + *
    • {@link #TONEMAP_MODE_FAST FAST}
      • + *
    • {@link #TONEMAP_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1990,9 +2356,9 @@ public final class CaptureRequest extends CameraMetadata> /** *

    Whether black-level compensation is locked * to its current values, or is free to vary.

    - *

    When set to ON, the values used for black-level + *

    When set to true (ON), the values used for black-level * compensation will not change until the lock is set to - * OFF.

    + * false (OFF).

    *

    Since changes to certain capture parameters (such as * exposure time) may require resetting of black level * compensation, the camera device must report whether setting diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java index fc1baf2a6014..d208649f3edd 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> { * modify the comment blocks at the start or end. *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/ - /** *

    The mode control selects how the image data is converted from the * sensor's native color into linear sRGB color.

    @@ -369,6 +368,12 @@ public class CaptureResult extends CameraMetadata> { * *

    Both the input and output value ranges must match. Overflow/underflow * values are clipped to fit within the range.

    + *

    Possible values: + *

      + *
    • {@link #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX TRANSFORM_MATRIX}
      • + *
    • {@link #COLOR_CORRECTION_MODE_FAST FAST}
      • + *
    • {@link #COLOR_CORRECTION_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -398,6 +403,7 @@ public class CaptureResult extends CameraMetadata> { * in this matrix result metadata. The transform should keep the magnitude * of the output color values within [0, 1.0] (assuming input color * values is within the normalized range [0, 1.0]), or clipping may occur.

    + *

    Units: Unitless scale factors

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -420,6 +426,7 @@ public class CaptureResult extends CameraMetadata> { * TRANSFORM_MATRIX.

    *

    The gains in the result metadata are the gains actually * applied by the camera device to the current frame.

    + *

    Units: Unitless gain factors

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -434,8 +441,6 @@ public class CaptureResult extends CameraMetadata> { /** *

    Mode of operation for the chromatic aberration correction algorithm.

    - *

    This must be set to a valid mode from - * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}.

    *

    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 @@ -447,6 +452,14 @@ public class CaptureResult extends CameraMetadata> { * capture rate. FAST means the camera device will not slow down capture rate when * applying aberration correction.

    *

    LEGACY devices will always be in FAST mode.

    + *

    Possible values: + *

      + *
    • {@link #COLOR_CORRECTION_ABERRATION_MODE_OFF OFF}
      • + *
    • {@link #COLOR_CORRECTION_ABERRATION_MODE_FAST FAST}
      • + *
    • {@link #COLOR_CORRECTION_ABERRATION_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES @@ -480,7 +493,7 @@ public class CaptureResult extends CameraMetadata> { * 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.

    - *

    The default mode is AUTO, which must be supported by all + *

    The default mode is AUTO, which is supported by all * camera devices.

    *

    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), @@ -488,6 +501,15 @@ public class CaptureResult extends CameraMetadata> { * 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.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AE_ANTIBANDING_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_AE_ANTIBANDING_MODE_50HZ 50HZ}
      • + *
    • {@link #CONTROL_AE_ANTIBANDING_MODE_60HZ 60HZ}
      • + *
    • {@link #CONTROL_AE_ANTIBANDING_MODE_AUTO AUTO}
      • + *

    + *

    Available values for this device:

    + *

    {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes}

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES @@ -521,6 +543,9 @@ public class CaptureResult extends CameraMetadata> { * 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).

    + *

    Units: Compensation steps

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE android.control.aeCompensationRange}

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE @@ -536,9 +561,11 @@ public class CaptureResult extends CameraMetadata> { /** *

    Whether auto-exposure (AE) is currently locked to its latest * calculated values.

    - *

    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.

    + *

    When set to true (ON), the AE algorithm is locked to its latest parameters, + * and will not change exposure settings until the lock is set to false (OFF).

    + *

    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.

    *

    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.

    *

    If AE precapture is triggered (see {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}) @@ -547,6 +574,19 @@ public class CaptureResult extends CameraMetadata> { * 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.

    + *

    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:

    + *
      + *
    1. Starting in auto-AE mode:
      2. + *
    2. Lock AE
      3. + *
    3. Wait for the first result to be output that has the AE locked
      4. + *
    4. Copy exposure settings from that result into a request, set the request to manual AE
      5. + *
    5. Submit the capture request, proceed to run manual AE as desired.
      6. + *
    *

    See {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE lock related state transition details.

    *

    This key is available on all devices.

    * @@ -582,8 +622,19 @@ public class CaptureResult extends CameraMetadata> { * camera device auto-exposure routine for the overridden * fields for a given capture will be available in its * CaptureResult.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AE_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_AE_MODE_ON ON}
      • + *
    • {@link #CONTROL_AE_MODE_ON_AUTO_FLASH ON_AUTO_FLASH}
      • + *
    • {@link #CONTROL_AE_MODE_ON_ALWAYS_FLASH ON_ALWAYS_FLASH}
      • + *
    • {@link #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE ON_AUTO_FLASH_REDEYE}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES android.control.aeAvailableModes}

    *

    This key is available on all devices.

    * + * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES * @see CaptureRequest#CONTROL_MODE * @see CameraCharacteristics#FLASH_INFO_AVAILABLE * @see CaptureRequest#FLASH_MODE @@ -601,25 +652,35 @@ public class CaptureResult extends CameraMetadata> { new Key("android.control.aeMode", int.class); /** - *

    List of areas to use for - * metering.

    - *

    Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0. + *

    List of metering areas to use for auto-exposure adjustment.

    + *

    Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0. * Otherwise will always be present.

    + *

    The maximum number of regions supported by the device is determined by the value + * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe}.

    *

    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.

    - *

    The weight must range from 0 to 1000, and represents a weight + *

    The weight must be within [0, 1000], 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.

    - *

    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.

    + *

    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.

    + *

    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 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.

    + *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + *

    Range of valid values:
    + * Coordinates must be between [(0,0), (width, height)) of + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AE @@ -631,13 +692,20 @@ public class CaptureResult extends CameraMetadata> { new Key("android.control.aeRegions", android.hardware.camera2.params.MeteringRectangle[].class); /** - *

    Range over which fps can be adjusted to - * maintain exposure.

    + *

    Range over which the auto-exposure routine can + * adjust the capture frame rate to maintain good + * exposure.

    *

    Only constrains auto-exposure (AE) algorithm, not - * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} - * This key is available on all devices.

    + * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} and + * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}.

    + *

    Units: Frames per second (FPS)

    + *

    Range of valid values:
    + * Any of the entries in {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES android.control.aeAvailableTargetFpsRanges}

    + *

    This key is available on all devices.

    * + * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES * @see CaptureRequest#SENSOR_EXPOSURE_TIME + * @see CaptureRequest#SENSOR_FRAME_DURATION */ @PublicKey public static final Key> CONTROL_AE_TARGET_FPS_RANGE = @@ -662,6 +730,15 @@ public class CaptureResult extends CameraMetadata> { * depends on the current AE mode and state; see * {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition * details.

    + *

    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.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE IDLE}
      • + *
    • {@link #CONTROL_AE_PRECAPTURE_TRIGGER_START START}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -858,6 +935,15 @@ public class CaptureResult extends CameraMetadata> { * * * + *

    Possible values: + *

      + *
    • {@link #CONTROL_AE_STATE_INACTIVE INACTIVE}
      • + *
    • {@link #CONTROL_AE_STATE_SEARCHING SEARCHING}
      • + *
    • {@link #CONTROL_AE_STATE_CONVERGED CONVERGED}
      • + *
    • {@link #CONTROL_AE_STATE_LOCKED LOCKED}
      • + *
    • {@link #CONTROL_AE_STATE_FLASH_REQUIRED FLASH_REQUIRED}
      • + *
    • {@link #CONTROL_AE_STATE_PRECAPTURE PRECAPTURE}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -887,9 +973,21 @@ public class CaptureResult extends CameraMetadata> { * (i.e. {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} > 0).

    *

    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. - * This key is available on all devices.

    + * in result metadata.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AF_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_AF_MODE_AUTO AUTO}
      • + *
    • {@link #CONTROL_AF_MODE_MACRO MACRO}
      • + *
    • {@link #CONTROL_AF_MODE_CONTINUOUS_VIDEO CONTINUOUS_VIDEO}
      • + *
    • {@link #CONTROL_AF_MODE_CONTINUOUS_PICTURE CONTINUOUS_PICTURE}
      • + *
    • {@link #CONTROL_AF_MODE_EDOF EDOF}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES android.control.afAvailableModes}

    + *

    This key is available on all devices.

    * + * @see CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES * @see CaptureResult#CONTROL_AF_STATE * @see CaptureRequest#CONTROL_MODE * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE @@ -905,25 +1003,35 @@ public class CaptureResult extends CameraMetadata> { new Key("android.control.afMode", int.class); /** - *

    List of areas to use for focus - * estimation.

    - *

    Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0. + *

    List of metering areas to use for auto-focus.

    + *

    Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0. * Otherwise will always be present.

    + *

    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}.

    *

    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.

    - *

    The weight must range from 0 to 1000, and represents a weight + *

    The weight must be within [0, 1000], 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.

    - *

    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.

    + *

    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.

    + *

    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 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.

    + *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + *

    Range of valid values:
    + * Coordinates must be between [(0,0), (width, height)) of + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AF @@ -947,6 +1055,12 @@ public class CaptureResult extends CameraMetadata> { * START for multiple captures in a row means restarting the AF operation over * and over again.

    *

    See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what the trigger means for each AF mode.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AF_TRIGGER_IDLE IDLE}
      • + *
    • {@link #CONTROL_AF_TRIGGER_START START}
      • + *
    • {@link #CONTROL_AF_TRIGGER_CANCEL CANCEL}
      • + *

    *

    This key is available on all devices.

    * * @see CaptureResult#CONTROL_AF_STATE @@ -1340,6 +1454,16 @@ public class CaptureResult extends CameraMetadata> { * * * + *

    Possible values: + *

      + *
    • {@link #CONTROL_AF_STATE_INACTIVE INACTIVE}
      • + *
    • {@link #CONTROL_AF_STATE_PASSIVE_SCAN PASSIVE_SCAN}
      • + *
    • {@link #CONTROL_AF_STATE_PASSIVE_FOCUSED PASSIVE_FOCUSED}
      • + *
    • {@link #CONTROL_AF_STATE_ACTIVE_SCAN ACTIVE_SCAN}
      • + *
    • {@link #CONTROL_AF_STATE_FOCUSED_LOCKED FOCUSED_LOCKED}
      • + *
    • {@link #CONTROL_AF_STATE_NOT_FOCUSED_LOCKED NOT_FOCUSED_LOCKED}
      • + *
    • {@link #CONTROL_AF_STATE_PASSIVE_UNFOCUSED PASSIVE_UNFOCUSED}
      • + *

    *

    This key is available on all devices.

    * * @see CaptureRequest#CONTROL_AF_MODE @@ -1360,6 +1484,21 @@ public class CaptureResult extends CameraMetadata> { /** *

    Whether auto-white balance (AWB) is currently locked to its * latest calculated values.

    + *

    When set to true (ON), the AWB algorithm is locked to its latest parameters, + * and will not change color balance settings until the lock is set to false (OFF).

    + *

    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:

    + *
      + *
    1. Starting in auto-AWB mode:
      2. + *
    2. Lock AWB
      3. + *
    3. Wait for the first result to be output that has the AWB locked
      4. + *
    4. Copy AWB settings from that result into a request, set the request to manual AWB
      5. + *
    5. Submit the capture request, proceed to run manual AWB as desired.
      6. + *
    *

    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.

    @@ -1392,11 +1531,26 @@ public class CaptureResult extends CameraMetadata> { * {@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.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_AWB_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_AWB_MODE_AUTO AUTO}
      • + *
    • {@link #CONTROL_AWB_MODE_INCANDESCENT INCANDESCENT}
      • + *
    • {@link #CONTROL_AWB_MODE_FLUORESCENT FLUORESCENT}
      • + *
    • {@link #CONTROL_AWB_MODE_WARM_FLUORESCENT WARM_FLUORESCENT}
      • + *
    • {@link #CONTROL_AWB_MODE_DAYLIGHT DAYLIGHT}
      • + *
    • {@link #CONTROL_AWB_MODE_CLOUDY_DAYLIGHT CLOUDY_DAYLIGHT}
      • + *
    • {@link #CONTROL_AWB_MODE_TWILIGHT TWILIGHT}
      • + *
    • {@link #CONTROL_AWB_MODE_SHADE SHADE}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#CONTROL_AWB_AVAILABLE_MODES android.control.awbAvailableModes}

    *

    This key is available on all devices.

    * * @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 @@ -1413,10 +1567,12 @@ public class CaptureResult extends CameraMetadata> { new Key("android.control.awbMode", int.class); /** - *

    List of areas to use for illuminant + *

    List of metering areas to use for auto-white-balance illuminant * estimation.

    - *

    Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0. + *

    Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0. * Otherwise will always be present.

    + *

    The maximum number of regions supported by the device is determined by the value + * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb}.

    *

    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, @@ -1427,11 +1583,20 @@ public class CaptureResult extends CameraMetadata> { * 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.

    - *

    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.

    + *

    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.

    + *

    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 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.

    + *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + *

    Range of valid values:
    + * Coordinates must be between [(0,0), (width, height)) of + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AWB @@ -1451,8 +1616,18 @@ public class CaptureResult extends CameraMetadata> { * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF and any 3A routine is active.

    *

    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. - * This key is available on all devices.

    + * contains MANUAL_SENSOR. Other intent values are always supported.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_CAPTURE_INTENT_CUSTOM CUSTOM}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_PREVIEW PREVIEW}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_STILL_CAPTURE STILL_CAPTURE}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_VIDEO_RECORD VIDEO_RECORD}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT VIDEO_SNAPSHOT}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_ZERO_SHUTTER_LAG ZERO_SHUTTER_LAG}
      • + *
    • {@link #CONTROL_CAPTURE_INTENT_MANUAL MANUAL}
      • + *

    + *

    This key is available on all devices.

    * * @see CaptureRequest#CONTROL_MODE * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES @@ -1585,6 +1760,13 @@ public class CaptureResult extends CameraMetadata> { * * * + *

    Possible values: + *

      + *
    • {@link #CONTROL_AWB_STATE_INACTIVE INACTIVE}
      • + *
    • {@link #CONTROL_AWB_STATE_SEARCHING SEARCHING}
      • + *
    • {@link #CONTROL_AWB_STATE_CONVERGED CONVERGED}
      • + *
    • {@link #CONTROL_AWB_STATE_LOCKED LOCKED}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -1612,11 +1794,23 @@ public class CaptureResult extends CameraMetadata> { * implementor of the camera device, and should not be * depended on to be consistent (or present) across all * devices.

    - *

    A color effect will only be applied if - * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_EFFECT_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_EFFECT_MODE_MONO MONO}
      • + *
    • {@link #CONTROL_EFFECT_MODE_NEGATIVE NEGATIVE}
      • + *
    • {@link #CONTROL_EFFECT_MODE_SOLARIZE SOLARIZE}
      • + *
    • {@link #CONTROL_EFFECT_MODE_SEPIA SEPIA}
      • + *
    • {@link #CONTROL_EFFECT_MODE_POSTERIZE POSTERIZE}
      • + *
    • {@link #CONTROL_EFFECT_MODE_WHITEBOARD WHITEBOARD}
      • + *
    • {@link #CONTROL_EFFECT_MODE_BLACKBOARD BLACKBOARD}
      • + *
    • {@link #CONTROL_EFFECT_MODE_AQUA AQUA}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS android.control.availableEffects}

    *

    This key is available on all devices.

    * - * @see CaptureRequest#CONTROL_MODE + * @see CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS * @see #CONTROL_EFFECT_MODE_OFF * @see #CONTROL_EFFECT_MODE_MONO * @see #CONTROL_EFFECT_MODE_NEGATIVE @@ -1632,9 +1826,9 @@ public class CaptureResult extends CameraMetadata> { new Key("android.control.effectMode", int.class); /** - *

    Overall mode of 3A control + *

    Overall mode of 3A (auto-exposure, auto-white-balance, auto-focus) control * routines.

    - *

    High-level 3A control. When set to OFF, all 3A control + *

    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.

    *

    When set to AUTO, the individual algorithm controls in @@ -1651,7 +1845,15 @@ public class CaptureResult extends CameraMetadata> { * the subsequent auto 3A capture results.

    *

    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 capability.

    + * support the MANUAL_SENSOR and MANUAL_POST_PROCSESING capabilities. + * FULL mode devices will always support OFF and OFF_KEEP_STATE.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_MODE_AUTO AUTO}
      • + *
    • {@link #CONTROL_MODE_USE_SCENE_MODE USE_SCENE_MODE}
      • + *
    • {@link #CONTROL_MODE_OFF_KEEP_STATE OFF_KEEP_STATE}
      • + *

    *

    This key is available on all devices.

    * * @see CaptureRequest#CONTROL_AF_MODE @@ -1665,18 +1867,40 @@ public class CaptureResult extends CameraMetadata> { new Key("android.control.mode", int.class); /** - *

    A camera mode optimized for conditions typical in a particular - * capture setting.

    + *

    Control for which scene mode is currently active.

    + *

    Scene modes are custom camera modes optimized for a certain set of conditions and + * capture settings.

    *

    This is the mode that that is active when * {@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE. 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}.

    + * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.

    *

    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.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_SCENE_MODE_DISABLED DISABLED}
      • + *
    • {@link #CONTROL_SCENE_MODE_FACE_PRIORITY FACE_PRIORITY}
      • + *
    • {@link #CONTROL_SCENE_MODE_ACTION ACTION}
      • + *
    • {@link #CONTROL_SCENE_MODE_PORTRAIT PORTRAIT}
      • + *
    • {@link #CONTROL_SCENE_MODE_LANDSCAPE LANDSCAPE}
      • + *
    • {@link #CONTROL_SCENE_MODE_NIGHT NIGHT}
      • + *
    • {@link #CONTROL_SCENE_MODE_NIGHT_PORTRAIT NIGHT_PORTRAIT}
      • + *
    • {@link #CONTROL_SCENE_MODE_THEATRE THEATRE}
      • + *
    • {@link #CONTROL_SCENE_MODE_BEACH BEACH}
      • + *
    • {@link #CONTROL_SCENE_MODE_SNOW SNOW}
      • + *
    • {@link #CONTROL_SCENE_MODE_SUNSET SUNSET}
      • + *
    • {@link #CONTROL_SCENE_MODE_STEADYPHOTO STEADYPHOTO}
      • + *
    • {@link #CONTROL_SCENE_MODE_FIREWORKS FIREWORKS}
      • + *
    • {@link #CONTROL_SCENE_MODE_SPORTS SPORTS}
      • + *
    • {@link #CONTROL_SCENE_MODE_PARTY PARTY}
      • + *
    • {@link #CONTROL_SCENE_MODE_CANDLELIGHT CANDLELIGHT}
      • + *
    • {@link #CONTROL_SCENE_MODE_BARCODE BARCODE}
      • + *
    • {@link #CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes}

    *

    This key is available on all devices.

    * * @see CaptureRequest#CONTROL_AE_MODE @@ -1710,20 +1934,25 @@ public class CaptureResult extends CameraMetadata> { /** *

    Whether video stabilization is * active.

    - *

    Video stabilization automatically translates and scales images from the camera - * in order to stabilize motion between consecutive frames.

    + *

    Video stabilization automatically translates and scales images from + * the camera in order to stabilize motion between consecutive frames.

    *

    If enabled, video stabilization can modify the * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream stabilized.

    - *

    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.

    - *

    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.

    - *

    Some LEGACY camera devices will not support changing video stabilization - * mode; in this case the value will always override to OFF.

    + *

    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.

    + *

    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.

    + *

    Possible values: + *

      + *
    • {@link #CONTROL_VIDEO_STABILIZATION_MODE_OFF OFF}
      • + *
    • {@link #CONTROL_VIDEO_STABILIZATION_MODE_ON ON}
      • + *

    *

    This key is available on all devices.

    * * @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE @@ -1738,14 +1967,21 @@ public class CaptureResult extends CameraMetadata> { /** *

    Operation mode for edge * enhancement.

    - *

    Edge/sharpness/detail enhancement. OFF means no - * enhancement will be applied by the camera device.

    - *

    This must be set to one of the modes listed in {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}.

    + *

    Edge enhancement improves sharpness and details in the captured image. OFF means + * no enhancement will be applied by the camera device.

    *

    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.

    + *

    Possible values: + *

      + *
    • {@link #EDGE_MODE_OFF OFF}
      • + *
    • {@link #EDGE_MODE_FAST FAST}
      • + *
    • {@link #EDGE_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1776,6 +2012,12 @@ public class CaptureResult extends CameraMetadata> { *

    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.

    *

    The flash status will be reported by {@link CaptureResult#FLASH_STATE android.flash.state} in the capture result metadata.

    + *

    Possible values: + *

      + *
    • {@link #FLASH_MODE_OFF OFF}
      • + *
    • {@link #FLASH_MODE_SINGLE SINGLE}
      • + *
    • {@link #FLASH_MODE_TORCH TORCH}
      • + *

    *

    This key is available on all devices.

    * * @see CaptureRequest#CONTROL_AE_MODE @@ -1800,12 +2042,20 @@ public class CaptureResult extends CameraMetadata> { *
      *
    • Flash-less cameras always return UNAVAILABLE.
      • *
    • Using {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} == ON_ALWAYS_FLASH - * will always return FIRED.
      • + * will always return FIRED. *
    • Using {@link CaptureRequest#FLASH_MODE android.flash.mode} == TORCH - * will always return FIRED.
      • + * will always return FIRED. *
    *

    In all other conditions the state will not be available on * LEGACY devices (i.e. it will be null).

    + *

    Possible values: + *

      + *
    • {@link #FLASH_STATE_UNAVAILABLE UNAVAILABLE}
      • + *
    • {@link #FLASH_STATE_CHARGING CHARGING}
      • + *
    • {@link #FLASH_STATE_READY READY}
      • + *
    • {@link #FLASH_STATE_FIRED FIRED}
      • + *
    • {@link #FLASH_STATE_PARTIAL PARTIAL}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -1826,12 +2076,18 @@ public class CaptureResult extends CameraMetadata> { new Key("android.flash.state", int.class); /** - *

    Set operational mode for hot pixel correction.

    - *

    Valid modes for this camera device are listed in - * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}.

    + *

    Operational mode for hot pixel correction.

    *

    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).

    + * that do not accurately measure the incoming light (i.e. pixels that + * are stuck at an arbitrary value or are oversensitive).

    + *

    Possible values: + *

      + *
    • {@link #HOT_PIXEL_MODE_OFF OFF}
      • + *
    • {@link #HOT_PIXEL_MODE_FAST FAST}
      • + *
    • {@link #HOT_PIXEL_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES @@ -1845,6 +2101,9 @@ public class CaptureResult extends CameraMetadata> { /** *

    A location object to use when generating image GPS metadata.

    + *

    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.

    *

    This key is available on all devices.

    */ @PublicKey @@ -1854,7 +2113,9 @@ public class CaptureResult extends CameraMetadata> { /** *

    GPS coordinates to include in output JPEG - * EXIF

    + * EXIF.

    + *

    Range of valid values:
    + * (-180 - 180], [-90,90], [-inf, inf]

    *

    This key is available on all devices.

    * @hide */ @@ -1863,7 +2124,8 @@ public class CaptureResult extends CameraMetadata> { /** *

    32 characters describing GPS algorithm to - * include in EXIF

    + * include in EXIF.

    + *

    Units: UTF-8 null-terminated string

    *

    This key is available on all devices.

    * @hide */ @@ -1872,7 +2134,8 @@ public class CaptureResult extends CameraMetadata> { /** *

    Time GPS fix was made to include in - * EXIF

    + * EXIF.

    + *

    Units: UTC in seconds since January 1, 1970

    *

    This key is available on all devices.

    * @hide */ @@ -1880,9 +2143,40 @@ public class CaptureResult extends CameraMetadata> { new Key("android.jpeg.gpsTimestamp", long.class); /** - *

    Orientation of JPEG image to - * write

    + *

    The orientation for a JPEG image.

    + *

    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.

    + *

    Camera devices may either encode this value into the JPEG EXIF header, or + * rotate the image data to match this orientation.

    + *

    Note that this orientation is relative to the orientation of the camera sensor, given + * by {@link CameraCharacteristics#SENSOR_ORIENTATION android.sensor.orientation}.

    + *

    To translate from the device orientation given by the Android sensor APIs, the following + * sample code may be used:

    + * 
    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;
+     * }
+     *
    + *

    Units: Degrees in multiples of 90

    + *

    Range of valid values:
    + * 0, 90, 180, 270

    *

    This key is available on all devices.

    + * + * @see CameraCharacteristics#SENSOR_ORIENTATION */ @PublicKey public static final Key JPEG_ORIENTATION = @@ -1892,6 +2186,8 @@ public class CaptureResult extends CameraMetadata> { *

    Compression quality of the final JPEG * image.

    *

    85-95 is typical usage range.

    + *

    Range of valid values:
    + * 1-100; larger is higher quality

    *

    This key is available on all devices.

    */ @PublicKey @@ -1901,6 +2197,8 @@ public class CaptureResult extends CameraMetadata> { /** *

    Compression quality of JPEG * thumbnail.

    + *

    Range of valid values:
    + * 1-100; larger is higher quality

    *

    This key is available on all devices.

    */ @PublicKey @@ -1911,26 +2209,29 @@ public class CaptureResult extends CameraMetadata> { *

    Resolution of embedded JPEG thumbnail.

    *

    When set to (0, 0) value, the JPEG EXIF will not contain thumbnail, * but the captured JPEG will still be a valid image.

    - *

    When a jpeg image capture is issued, the thumbnail size selected should have - * the same aspect ratio as the jpeg image.

    + *

    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.

    *

    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.

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES android.jpeg.availableThumbnailSizes}

    *

    This key is available on all devices.

    + * + * @see CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES */ @PublicKey public static final Key JPEG_THUMBNAIL_SIZE = new Key("android.jpeg.thumbnailSize", android.util.Size.class); /** - *

    The ratio of lens focal length to the effective - * aperture diameter.

    - *

    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}.

    + *

    The desired lens aperture size, as a ratio of lens focal length to the + * effective aperture diameter.

    + *

    Setting this value is only supported on the camera devices that have a variable + * aperture lens.

    *

    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} @@ -1943,6 +2244,9 @@ public class CaptureResult extends CameraMetadata> { * 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.

    + *

    Units: The f-number (f/N)

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1961,10 +2265,8 @@ public class CaptureResult extends CameraMetadata> { new Key("android.lens.aperture", float.class); /** - *

    State of lens neutral density filter(s).

    - *

    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}.

    + *

    The desired setting for the lens neutral density filter(s).

    + *

    This control will not be supported on most camera devices.

    *

    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 @@ -1976,6 +2278,9 @@ public class CaptureResult extends CameraMetadata> { *

    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.

    + *

    Units: Exposure Value (EV)

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -1990,7 +2295,7 @@ public class CaptureResult extends CameraMetadata> { new Key("android.lens.filterDensity", float.class); /** - *

    The current lens focal length; used for optical zoom.

    + *

    The desired lens focal length; used for optical zoom.

    *

    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.

    @@ -1999,11 +2304,15 @@ public class CaptureResult extends CameraMetadata> { * 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.

    - *

    This is expected not to be supported on most devices.

    + *

    Optical zoom will not be supported on most devices.

    + *

    Units: Millimeters

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}

    *

    This key is available on all devices.

    * * @see CaptureRequest#LENS_APERTURE * @see CaptureRequest#LENS_FOCUS_DISTANCE + * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS * @see CaptureResult#LENS_STATE */ @PublicKey @@ -2011,15 +2320,19 @@ public class CaptureResult extends CameraMetadata> { new Key("android.lens.focalLength", float.class); /** - *

    Distance to plane of sharpest focus, + *

    Desired distance to plane of sharpest focus, * measured from frontmost surface of the lens.

    *

    Should be zero for fixed-focus cameras

    + *

    Units: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details

    + *

    Range of valid values:
    + * >= 0

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * 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

    * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL + * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION */ @PublicKey public static final Key LENS_FOCUS_DISTANCE = @@ -2030,12 +2343,17 @@ public class CaptureResult extends CameraMetadata> { * sharp focus (depth of field).

    *

    If variable focus not supported, can still report * fixed depth of field range

    + *

    Units: A pair of focus distances in diopters: (near, + * far); see {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details.

    + *

    Range of valid values:
    + * >=0

    *

    Optional - This value may be {@code null} on some devices.

    *

    Limited capability - * 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

    * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL + * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION */ @PublicKey public static final Key> LENS_FOCUS_RANGE = @@ -2055,12 +2373,19 @@ public class CaptureResult extends CameraMetadata> { * 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.

    - *

    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.

    + *

    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.

    *

    Not all devices will support OIS; see * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for * available controls.

    + *

    Possible values: + *

      + *
    • {@link #LENS_OPTICAL_STABILIZATION_MODE_OFF OFF}
      • + *
    • {@link #LENS_OPTICAL_STABILIZATION_MODE_ON ON}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -2097,6 +2422,11 @@ public class CaptureResult extends CameraMetadata> { *

    Then this state will always be STATIONARY.

    *

    When the state is MOVING, it indicates that at least one of the lens parameters * is changing.

    + *

    Possible values: + *

      + *
    • {@link #LENS_STATE_STATIONARY STATIONARY}
      • + *
    • {@link #LENS_STATE_MOVING MOVING}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -2120,15 +2450,22 @@ public class CaptureResult extends CameraMetadata> { /** *

    Mode of operation for the noise reduction algorithm.

    - *

    Noise filtering control. OFF means no noise reduction - * will be applied by the camera device.

    - *

    This must be set to a valid mode from - * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.

    + *

    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.

    *

    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.

    + *

    Possible values: + *

      + *
    • {@link #NOISE_REDUCTION_MODE_OFF OFF}
      • + *
    • {@link #NOISE_REDUCTION_MODE_FAST FAST}
      • + *
    • {@link #NOISE_REDUCTION_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -2158,6 +2495,8 @@ public class CaptureResult extends CameraMetadata> { * 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.

    + *

    Range of valid values:
    + * Optional. Default value is FINAL.

    *

    Optional - This value may be {@code null} on some devices.

    * @deprecated * @hide @@ -2171,6 +2510,9 @@ public class CaptureResult extends CameraMetadata> { * increases with every new result (that is, each new result has a unique * frameCount value).

    *

    Reset on release()

    + *

    Units: count of frames

    + *

    Range of valid values:
    + * > 0

    *

    Optional - This value may be {@code null} on some devices.

    * @deprecated * @hide @@ -2183,6 +2525,9 @@ public class CaptureResult extends CameraMetadata> { *

    An application-specified ID for the current * request. Must be maintained unchanged in output * frame

    + *

    Units: arbitrary integer assigned by application

    + *

    Range of valid values:
    + * Any int

    *

    Optional - This value may be {@code null} on some devices.

    * @hide */ @@ -2197,6 +2542,8 @@ public class CaptureResult extends CameraMetadata> { * what streams are configured, the data may undergo less processing, * and some pipeline stages skipped.

    *

    See {@link CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH android.request.pipelineMaxDepth} for more details.

    + *

    Range of valid values:
    + * <= {@link CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH android.request.pipelineMaxDepth}

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH @@ -2206,7 +2553,8 @@ public class CaptureResult extends CameraMetadata> { new Key("android.request.pipelineDepth", byte.class); /** - *

    The region of the sensor to read out for this capture.

    + *

    The desired region of the sensor to read out for this capture.

    + *

    This control can be used to implement digital zoom.

    *

    The crop region coordinate system is based off * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0, 0) being the * top-left corner of the sensor active array.

    @@ -2236,6 +2584,8 @@ public class CaptureResult extends CameraMetadata> { * for rounding and other hardware requirements; the final * crop region used will be included in the output capture * result.

    + *

    Units: Pixel coordinates relative to + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM @@ -2248,14 +2598,23 @@ public class CaptureResult extends CameraMetadata> { /** *

    Duration each pixel is exposed to * light.

    - *

    If the sensor can't expose this exact duration, it should shorten the - * duration exposed to the nearest possible value (rather than expose longer).

    + *

    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.

    + *

    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.

    + *

    Units: Nanoseconds

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE android.sensor.info.exposureTimeRange}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * 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

    * + * @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 SENSOR_EXPOSURE_TIME = @@ -2333,13 +2692,23 @@ public class CaptureResult extends CameraMetadata> { * delivered.

    *

    For more details about stalling, see * StreamConfigurationMap#getOutputStallDuration(int,Size).

    + *

    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.

    + *

    Units: Nanoseconds

    + *

    Range of valid values:
    + * 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 max(duration, exposureTime + overhead).

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * 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

    * + * @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 SENSOR_FRAME_DURATION = @@ -2357,6 +2726,9 @@ public class CaptureResult extends CameraMetadata> { * requested, it will reduce the gain to the nearest supported * value. The final sensitivity used will be available in the * output capture result.

    + *

    Units: ISO arithmetic units

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -2386,6 +2758,9 @@ public class CaptureResult extends CameraMetadata> { * android.os.SystemClock#elapsedRealtimeNanos(), and they can be * compared to other timestamps from other subsystems that are using * that base.

    + *

    Units: Nanoseconds

    + *

    Range of valid values:
    + * > 0

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#SENSOR_INFO_TIMESTAMP_SOURCE @@ -2411,10 +2786,10 @@ public class CaptureResult extends CameraMetadata> { /** *

    Noise model coefficients for each CFA mosaic channel.

    - *

    This tag contains two noise model coefficients for each CFA channel + *

    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 @@ -2468,6 +2843,8 @@ public class CaptureResult extends CameraMetadata> { *

  • R > 1.20 will require strong software correction to produce * a usuable image (>20% divergence).
    • * + *

    Range of valid values:

    + *

    >= 0

    *

    Optional - This value may be {@code null} on some devices.

    */ @PublicKey @@ -2500,7 +2877,21 @@ public class CaptureResult extends CameraMetadata> { *

    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).

    + *

    Defaults to OFF.

    + *

    Possible values: + *

      + *
    • {@link #SENSOR_TEST_PATTERN_MODE_OFF OFF}
      • + *
    • {@link #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR SOLID_COLOR}
      • + *
    • {@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS COLOR_BARS}
      • + *
    • {@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS_FADE_TO_GRAY COLOR_BARS_FADE_TO_GRAY}
      • + *
    • {@link #SENSOR_TEST_PATTERN_MODE_PN9 PN9}
      • + *
    • {@link #SENSOR_TEST_PATTERN_MODE_CUSTOM1 CUSTOM1}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES android.sensor.availableTestPatternModes}

    *

    Optional - This value may be {@code null} on some devices.

    + * + * @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 @@ -2515,11 +2906,16 @@ public class CaptureResult extends CameraMetadata> { /** *

    Duration between the start of first row exposure * and the start of last row exposure.

    - *

    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}.

    + *

    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}.

    *

    For typical camera sensors that use rolling shutters, this is also equivalent * to the frame readout time.

    + *

    Units: Nanoseconds

    + *

    Range of valid values:
    + * >= 0 and < + * StreamConfigurationMap#getOutputMinFrameDuration(int, Size).

    *

    Optional - This value may be {@code null} on some devices.

    *

    Limited capability - * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the @@ -2538,27 +2934,32 @@ public class CaptureResult extends CameraMetadata> { *

    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 {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON. For example, for lens - * shading map with size specified as android.lens.info.shadingMapSize = [ 4, 3 ], - * the output android.statistics.lensShadingMap for this case will be an identity map - * shown below:

    + * shading map with size of [ 4, 3 ], + * the output {@link CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP android.statistics.lensShadingCorrectionMap} for this case will be an identity + * map shown below:

    * 
    [ 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-     * 1.0, 1.0, 1.0, 1.0,   1.0, 1.0, 1.0, 1.0,
-     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0 ]
+     *  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+     *  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+     *  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+     *  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+     *  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0 ]
      *
    - *

    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.

    - *

    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} != OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != 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.

    + *

    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.

    + *

    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} != OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != + * 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.

    + *

    Possible values: + *

      + *
    • {@link #SHADING_MODE_OFF OFF}
      • + *
    • {@link #SHADING_MODE_FAST FAST}
      • + *
    • {@link #SHADING_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -2567,6 +2968,7 @@ public class CaptureResult extends CameraMetadata> { * @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 @@ -2577,13 +2979,20 @@ public class CaptureResult extends CameraMetadata> { new Key("android.shading.mode", int.class); /** - *

    Control for the face detector + *

    Operating mode for the face detector * unit.

    *

    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}. - * This key is available on all devices.

    + * fields.

    + *

    Possible values: + *

      + *
    • {@link #STATISTICS_FACE_DETECT_MODE_OFF OFF}
      • + *
    • {@link #STATISTICS_FACE_DETECT_MODE_SIMPLE SIMPLE}
      • + *
    • {@link #STATISTICS_FACE_DETECT_MODE_FULL FULL}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}

    + *

    This key is available on all devices.

    * * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES * @see #STATISTICS_FACE_DETECT_MODE_OFF @@ -2642,6 +3051,8 @@ public class CaptureResult extends CameraMetadata> { *

    List of the face confidence scores for * detected faces

    *

    Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF.

    + *

    Range of valid values:
    + * 1-100

    *

    This key is available on all devices.

    * * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE @@ -2652,7 +3063,7 @@ public class CaptureResult extends CameraMetadata> { /** *

    List of the faces detected through camera face detection - * in this result.

    + * in this capture.

    *

    Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF.

    *

    This key is available on all devices.

    * @@ -2688,11 +3099,11 @@ public class CaptureResult extends CameraMetadata> { * 
    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 ]
      *
    *

    The low-resolution scaling map images for each channel are * (displayed using nearest-neighbor interpolation):

    @@ -2703,6 +3114,8 @@ public class CaptureResult extends CameraMetadata> { *

    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:

    *

    Image of a uniform white wall (inverse shading map)

    + *

    Range of valid values:
    + * Each gain factor is >= 1

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -2741,11 +3154,11 @@ public class CaptureResult extends CameraMetadata> { * 

    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 ]
      *
    *

    The low-resolution scaling map images for each channel are * (displayed using nearest-neighbor interpolation):

    @@ -2756,6 +3169,8 @@ public class CaptureResult extends CameraMetadata> { *

    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:

    *

    Image of a uniform white wall (inverse shading map)

    + *

    Range of valid values:
    + * Each gain factor is >= 1

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -2829,6 +3244,12 @@ public class CaptureResult extends CameraMetadata> { * into this metadata field. See * {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} for more details.

    *

    Reports NONE if there doesn't appear to be flickering illumination.

    + *

    Possible values: + *

      + *
    • {@link #STATISTICS_SCENE_FLICKER_NONE NONE}
      • + *
    • {@link #STATISTICS_SCENE_FLICKER_50HZ 50HZ}
      • + *
    • {@link #STATISTICS_SCENE_FLICKER_60HZ 60HZ}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -2847,10 +3268,11 @@ public class CaptureResult extends CameraMetadata> { new Key("android.statistics.sceneFlicker", int.class); /** - *

    Operating mode for hotpixel map generation.

    - *

    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.

    - *

    This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}.

    + *

    Operating mode for hot pixel map generation.

    + *

    If set to true, a hot pixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}. + * If set to false, no hot pixel map will be returned.

    + *

    Range of valid values:
    + * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP @@ -2868,6 +3290,10 @@ public class CaptureResult extends CameraMetadata> { * 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}.

    + *

    Range of valid values:

    + *

    n <= number of pixels on the sensor. + * The (x, y) coordinates must be bounded by + * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE @@ -2883,7 +3309,12 @@ public class CaptureResult extends CameraMetadata> { *

    When set to ON, * android.statistics.lensShadingMap will be provided in * the output result metadata.

    - *

    Required for devices with the RAW capability.

    + *

    ON is always supported on devices with the RAW capability.

    + *

    Possible values: + *

      + *
    • {@link #STATISTICS_LENS_SHADING_MAP_MODE_OFF OFF}
      • + *
    • {@link #STATISTICS_LENS_SHADING_MAP_MODE_ON ON}
      • + *

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -2937,10 +3368,10 @@ public class CaptureResult extends CameraMetadata> { * CONTRAST_CURVE.

    *

    Each channel's curve is defined by an array of control points:

    * 
    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}
    - *

    These are sorted in order of increasing Pin; it is always - * guaranteed that input values 0.0 and 1.0 are included in the list to + *

    These are sorted in order of increasing Pin; 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.

    @@ -2961,20 +3392,23 @@ public class CaptureResult extends CameraMetadata> { *

    Inverting mapping curve

    *

    Gamma 1/2.2 mapping, with 16 control points:

    * 
    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 ]
      *
    *

    Gamma = 1/2.2 tonemapping curve

    *

    Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:

    * 
    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 ]
      *
    *

    sRGB tonemapping curve

    + *

    Range of valid values:
    + * 0-1 on both input and output coordinates, normalized + * as a floating-point value such that 0 == black and 1 == white.

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -2996,7 +3430,7 @@ public class CaptureResult extends CameraMetadata> { * example. The same logic applies to green and blue channel. * Each channel's curve is defined by an array of control points:

    * 
    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}
    *

    These are sorted in order of increasing Pin; it is always * guaranteed that input values 0.0 and 1.0 are included in the list to @@ -3020,18 +3454,18 @@ public class CaptureResult extends CameraMetadata> { *

    Inverting mapping curve

    *

    Gamma 1/2.2 mapping, with 16 control points:

    * 
    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) ]
      *
    *

    Gamma = 1/2.2 tonemapping curve

    *

    Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:

    * 
    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) ]
      *
    *

    sRGB tonemapping curve

    *

    Optional - This value may be {@code null} on some devices.

    @@ -3061,8 +3495,6 @@ public class CaptureResult extends CameraMetadata> { * tables, selective chroma enhancement, or other non-linear color * transforms will be disabled when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is * CONTRAST_CURVE.

    - *

    This must be set to a valid mode in - * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}.

    *

    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 @@ -3070,6 +3502,14 @@ public class CaptureResult extends CameraMetadata> { *

    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.

    + *

    Possible values: + *

      + *
    • {@link #TONEMAP_MODE_CONTRAST_CURVE CONTRAST_CURVE}
      • + *
    • {@link #TONEMAP_MODE_FAST FAST}
      • + *
    • {@link #TONEMAP_MODE_HIGH_QUALITY HIGH_QUALITY}
      • + *

    + *

    Available values for this device:
    + * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}

    *

    Optional - This value may be {@code null} on some devices.

    *

    Full capability - * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the @@ -3175,6 +3615,14 @@ public class CaptureResult extends CameraMetadata> { *

    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.

    + *

    Possible values: + *

      + *
    • {@link #SYNC_FRAME_NUMBER_CONVERGING CONVERGING}
      • + *
    • {@link #SYNC_FRAME_NUMBER_UNKNOWN UNKNOWN}
      • + *

    + *

    Available values for this device:
    + * Either a non-negative value corresponding to a + * frame_number, or one of the two enums (CONVERGING / UNKNOWN).

    *

    This key is available on all devices.

    * * @see CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH -- cgit v1.2.3-59-g8ed1b