These properties are fixed for a given CameraDevice, and can be queried * through the {@link CameraManager CameraManager} - * interface in addition to through the CameraDevice interface.
+ * interface with {@link CameraManager#getCameraCharacteristics}. * *{@link CameraCharacteristics} objects are immutable.
* @@ -555,7 +555,7 @@ public final class CameraCharacteristics extends CameraMetadataIf OIS is not implemented for a given camera device, this should + *
If OIS is not implemented for a given camera device, this will * contain only OFF.
* * @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE @@ -612,7 +612,7 @@ public final class CameraCharacteristics extends CameraMetadataThis tag lists the valid modes for {@link CaptureRequest#NOISE_REDUCTION_MODE android.noiseReduction.mode}.
- *Full-capability camera devices must laways support OFF and FAST.
+ *Full-capability camera devices must always support OFF and FAST.
* * @see CaptureRequest#NOISE_REDUCTION_MODE */ @@ -778,18 +778,20 @@ public final class CameraCharacteristics extends CameraMetadataOptional. Defaults to 1. Defines how many sub-components + *
Defines how many sub-components * a result will be composed of.
*In order to combat the pipeline latency, partial results * may be delivered to the application layer from the camera device as * soon as they are available.
- *A value of 1 means that partial results are not supported.
+ *Optional; defaults to 1. A value of 1 means that partial + * results are not supported, and only the final TotalCaptureResult will + * be produced by the camera device.
*A typical use case for this might be: after requesting an * auto-focus (AF) lock the new AF state might be available 50% * of the way through the pipeline. The camera device could * then immediately dispatch this state via a partial result to - * the framework/application layer, and the rest of the - * metadata via later partial results.
+ * the application, and the rest of the metadata via later + * partial results. */ public static final KeyXX: Maybe these should go into {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} - * as a table instead?
*The following capabilities are guaranteed to be available on
* {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL devices:
Other capabilities may be available on either FULL or LIMITED - * devices, but the app. should query this field to be sure.
+ * devices, but the application should query this field to be sure. * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL - * @see #REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE - * @see #REQUEST_AVAILABLE_CAPABILITIES_OPTIONAL * @see #REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR * @see #REQUEST_AVAILABLE_CAPABILITIES_MANUAL_POST_PROCESSING - * @see #REQUEST_AVAILABLE_CAPABILITIES_ZSL * @see #REQUEST_AVAILABLE_CAPABILITIES_DNG */ public static final KeyTODO: This should be used by #getAvailableCaptureRequestKeys.
* * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @hide @@ -863,7 +859,6 @@ public final class CameraCharacteristics extends CameraMetadataTODO: This should be used by #getAvailableCaptureResultKeys.
* * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE @@ -879,7 +874,6 @@ public final class CameraCharacteristics extends CameraMetadataTODO: This should be used by CameraCharacteristics#getKeys.
* @hide */ public static final KeyThe maximum ratio between active area width - * and crop region width, or between active area height and - * crop region height, if the crop region height is larger - * than width
+ *The maximum ratio between both active area width + * and crop region width, and active area height and + * crop region height.
+ *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.
*/ public static final KeyArrangement of color filters on sensor; + *
The arrangement of color filters on sensor; * represents the colors in the top-left 2x2 section of - * the sensor, in reading order
+ * the sensor, in reading order. * @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGGB * @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GRBG * @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GBRG @@ -1666,10 +1665,9 @@ public final class CameraCharacteristics extends CameraMetadataWhich face detection modes are available, - * if any.
- *OFF means face detection is disabled, it must - * be included in the list.
+ *The face detection modes that are available + * for this camera device.
+ *OFF is always supported.
*SIMPLE means the device supports the * android.statistics.faceRectangles and * android.statistics.faceScores outputs.
@@ -1681,8 +1679,8 @@ public final class CameraCharacteristics extends CameraMetadataMaximum number of simultaneously detectable - * faces
+ *The maximum number of simultaneously detectable + * faces.
*/ public static final KeyThis 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 should include both + * only OFF. If the hotpixel map is available, this will include both * the ON and OFF options.
* * @see CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java index 90e5e4e2a61a9..33e19150934fb 100644 --- a/core/java/android/hardware/camera2/CameraMetadata.java +++ b/core/java/android/hardware/camera2/CameraMetadata.java @@ -157,8 +157,8 @@ public abstract class CameraMetadataThe lens focus distance is not accurate, and the units used for - * {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} do not correspond to any physical units. - * Setting the lens to the same focus distance on separate occasions may + * {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} do not correspond to any physical units.
+ *Setting the lens to the same focus distance on separate occasions may
* result in a different real focus distance, depending on factors such
* as the orientation of the device, the age of the focusing mechanism,
* and the device temperature. The focus distance value will still be
@@ -172,20 +172,24 @@ public abstract class CameraMetadata The lens focus distance is measured in diopters. However, setting the lens
- * to the same focus distance on separate occasions may result in a
- * different real focus distance, depending on factors such as the
- * orientation of the device, the age of the focusing mechanism, and
- * the device temperature. The lens focus distance is measured in diopters. However, setting the lens to the same focus distance
+ * on separate occasions may result in a different real
+ * focus distance, depending on factors such as the
+ * orientation of the device, the age of the focusing
+ * mechanism, and the device temperature. The lens focus distance is measured in diopters. The lens mechanism is
- * calibrated so that setting the same focus distance is repeatable on
- * multiple occasions with good accuracy, and the focus distance corresponds
- * to the real physical distance to the plane of best focus. The lens focus distance is measured in diopters, and
+ * is calibrated. The lens mechanism is calibrated so that setting the
+ * same focus distance is repeatable on multiple
+ * occasions with good accuracy, and the focus distance
+ * corresponds to the real physical distance to the plane
+ * of best focus. The camera device faces the same direction as the device's screen. The camera device faces the opposite direction as the device's screen. The full set of features supported by this capability makes
* the camera2 api backwards compatible with the camera1
* (android.hardware.Camera) API. TODO: @hide this. Doesn't really mean anything except
- * act as a catch-all for all the 'base' functionality.
A typical example is all tags marked 'optional'.
- *TODO: @hide. We may not need this if we @hide all the optional - * tags not belonging to a capability.
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES + * @hide */ public static final int REQUEST_AVAILABLE_CAPABILITIES_OPTIONAL = 1; /** *The camera device can be manually controlled (3A algorithms such - * as auto exposure, and auto focus can be bypassed). + * as auto-exposure, and auto-focus can be bypassed). * The camera device supports basic manual control of the sensor image * acquisition related stages. This means the following controls are * guaranteed to be supported:
@@ -257,11 +261,11 @@ public abstract class CameraMetadataIf auto white balance is enabled, then the camera device * will accurately report the values applied by AWB in the result.
- *The camera device will also support everything in MANUAL_SENSOR - * except manual lens control and manual flash control.
*A given camera device may also support additional post-processing * controls, but this capability only covers the above list of controls.
* @@ -340,8 +342,8 @@ public abstract class CameraMetadata@hide this, TODO: remove it when input related APIs are ready.
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES + * @hide */ public static final int REQUEST_AVAILABLE_CAPABILITIES_ZSL = 4; @@ -355,7 +357,7 @@ public abstract class CameraMetadataThe camera device will only support centered crop regions.
+ *The camera device only supports centered crop regions.
* @see CameraCharacteristics#SCALER_CROPPING_TYPE */ public static final int SCALER_CROPPING_TYPE_CENTER_ONLY = 0; /** - *The camera device will support arbitrarily chosen crop regions.
+ *The camera device supports arbitrarily chosen crop regions.
* @see CameraCharacteristics#SCALER_CROPPING_TYPE */ public static final int SCALER_CROPPING_TYPE_FREEFORM = 1; @@ -525,7 +527,7 @@ public abstract class CameraMetadataandroid.led.transmit control is used
+ *android.led.transmit control is used.
* @see CameraCharacteristics#LED_AVAILABLE_LEDS * @hide */ @@ -536,11 +538,14 @@ public abstract class CameraMetadataThis camera device has only limited capabilities.
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ public static final int INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED = 0; /** + *This camera device is capable of supporting advanced imaging + * applications.
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ public static final int INFO_SUPPORTED_HARDWARE_LEVEL_FULL = 1; @@ -550,9 +555,9 @@ public abstract class CameraMetadataEvery frame has the requests immediately applied.
- * (and furthermore for all results,
- * android.sync.frameNumber == android.request.frameCount)
Every frame has the requests immediately applied.
+ *Furthermore for all results,
+ * android.sync.frameNumber == android.request.frameCount
Changing controls over multiple requests one after another will * produce results that have those controls applied atomically * each frame.
@@ -592,8 +597,8 @@ public abstract class CameraMetadataMust not slow down capture rate relative to sensor raw - * output.
+ *Color correction processing must not slow down + * capture rate relative to sensor raw output.
*Advanced white balance adjustments above and beyond * the specified white balance pipeline may be applied.
*If AWB is enabled with Capture rate (relative to sensor raw output)
- * may be reduced by high quality. Color correction processing operates at improved
+ * quality but reduced capture rate (relative to sensor raw
+ * output). Advanced white balance adjustments above and beyond
* the specified white balance pipeline may be applied. If AWB is enabled with The camera device's autoexposure routine is disabled;
- * the application-selected {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
+ * The camera device's autoexposure routine is disabled. The application-selected {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
* {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} and
* {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration} are used by the camera
* device, along with android.flash.* fields, if there's
@@ -674,7 +680,8 @@ public abstract class CameraMetadata The camera device's autoexposure routine is active,
- * with no flash control. The application's values for
+ * with no flash control. The application's values for
* {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
* {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and
* {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration} are ignored. The
@@ -691,10 +698,10 @@ public abstract class CameraMetadata Like ON, except that the camera device also controls
* the camera's flash unit, firing it in low-light
- * conditions. The flash may be fired during a
- * precapture sequence (triggered by
- * {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}) and may be fired
- * for captures for which the
+ * conditions. The flash may be fired during a precapture sequence
+ * (triggered by {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}) and
+ * may be fired for captures for which the
* {@link CaptureRequest#CONTROL_CAPTURE_INTENT android.control.captureIntent} field is set to
* STILL_CAPTURE Like ON, except that the camera device also controls
* the camera's flash unit, always firing it for still
- * captures. The flash may be fired during a precapture
- * sequence (triggered by
- * {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}) and will always
- * be fired for captures for which the
+ * captures. The flash may be fired during a precapture sequence
+ * (triggered by {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}) and
+ * will always be fired for captures for which the
* {@link CaptureRequest#CONTROL_CAPTURE_INTENT android.control.captureIntent} field is set to
* STILL_CAPTURE Like ON_AUTO_FLASH, but with automatic red eye
- * reduction. If deemed necessary by the camera device,
- * a red eye reduction flash will fire during the
- * precapture sequence. If deemed necessary by the camera device, a red eye
+ * reduction flash will fire during the precapture
+ * sequence. The precapture metering sequence will be started
- * by the camera device. The exact effect of the precapture
- * trigger depends on the current AE mode and state. The exact effect of the precapture trigger depends on
+ * the current AE mode and state. The auto-focus routine does not control the lens;
* {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} is controlled by the
- * application Extended depth of field (digital focus). AF
- * trigger is ignored, AF state should always be
+ * Extended depth of field (digital focus) mode. The camera device will produce images with an extended
+ * depth of field automatically; no special focusing
+ * operations need to be done before taking a picture. AF triggers are ignored, and the AF state will always be
* INACTIVE. The camera device's auto white balance routine is disabled;
- * the application-selected color transform matrix
+ * The camera device's auto-white balance routine is disabled. The application-selected color transform matrix
* ({@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}) and gains
* ({@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains}) are used by the camera
* device for manual white balance control. The camera device's auto white balance routine is active;
- * the application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}
- * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. The camera device's auto-white balance routine is active. The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}
+ * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored.
+ * For devices that support the MANUAL_POST_PROCESSING capability, the
+ * values used by the camera device for the transform and gains
+ * will be available in the capture result for this request. The camera device's auto white balance routine is disabled;
+ * The camera device's auto-white balance routine is disabled;
* the camera device uses incandescent light as the assumed scene
- * illumination for white balance. While the exact white balance
- * transforms are up to the camera device, they will approximately
- * match the CIE standard illuminant A.{@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != OFF, then
@@ -606,8 +611,9 @@ public abstract class CameraMetadata{@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != OFF, then
@@ -658,8 +664,8 @@ public abstract class CameraMetadata
While the exact white balance transforms are up to the + * camera device, they will approximately match the CIE + * standard illuminant A.
+ *The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.
+ * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_INCANDESCENT = 2; /** - *The camera device's auto white balance routine is disabled; + *
The camera device's auto-white balance routine is disabled; * the camera device uses fluorescent light as the assumed scene - * illumination for white balance. While the exact white balance - * transforms are up to the camera device, they will approximately - * match the CIE standard illuminant F2.
+ * illumination for white balance. + *While the exact white balance transforms are up to the + * camera device, they will approximately match the CIE + * standard illuminant F2.
+ *The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.
+ * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_FLUORESCENT = 3; /** - *The camera device's auto white balance routine is disabled; + *
The camera device's auto-white balance routine is disabled; * the camera device uses warm fluorescent light as the assumed scene - * illumination for white balance. While the exact white balance - * transforms are up to the camera device, they will approximately - * match the CIE standard illuminant F4.
+ * illumination for white balance. + *While the exact white balance transforms are up to the + * camera device, they will approximately match the CIE + * standard illuminant F4.
+ *The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.
+ * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_WARM_FLUORESCENT = 4; /** - *The camera device's auto white balance routine is disabled; + *
The camera device's auto-white balance routine is disabled; * the camera device uses daylight light as the assumed scene - * illumination for white balance. While the exact white balance - * transforms are up to the camera device, they will approximately - * match the CIE standard illuminant D65.
+ * illumination for white balance. + *While the exact white balance transforms are up to the + * camera device, they will approximately match the CIE + * standard illuminant D65.
+ *The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.
+ * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_DAYLIGHT = 5; /** - *The camera device's auto white balance routine is disabled; + *
The camera device's auto-white balance routine is disabled; * the camera device uses cloudy daylight light as the assumed scene * illumination for white balance.
+ *The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.
+ * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_CLOUDY_DAYLIGHT = 6; /** - *The camera device's auto white balance routine is disabled; + *
The camera device's auto-white balance routine is disabled; * the camera device uses twilight light as the assumed scene * illumination for white balance.
+ *The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.
+ * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_TWILIGHT = 7; /** - *The camera device's auto white balance routine is disabled; + *
The camera device's auto-white balance routine is disabled; * the camera device uses shade light as the assumed scene * illumination for white balance.
+ *The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.
+ * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_SHADE = 8; @@ -966,38 +1041,43 @@ public abstract class CameraMetadataThis request doesn't fall into the other - * categories. Default to preview-like + *
The goal of this request doesn't fall into the other + * categories. The camera device will default to preview-like * behavior.
* @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_CUSTOM = 0; /** - *This request is for a preview-like usecase. The - * precapture trigger may be used to start off a metering - * w/flash sequence
+ *This request is for a preview-like use case.
+ *The precapture trigger may be used to start off a metering + * w/flash sequence.
* @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_PREVIEW = 1; /** *This request is for a still capture-type - * usecase.
+ * use case. + *If the flash unit is under automatic control, it may fire as needed.
* @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_STILL_CAPTURE = 2; /** *This request is for a video recording - * usecase.
+ * use case. * @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_VIDEO_RECORD = 3; /** *This request is for a video snapshot (still - * image while recording video) usecase
+ * 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.
+ *
This request is for a ZSL usecase; the * application will stream full-resolution images and * reprocess one or several later for a final - * capture
+ * capture. * @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_ZERO_SHUTTER_LAG = 5; /** *This request is for manual capture use case where - * the applications want to directly control the capture parameters - * (e.g. {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}, {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} etc.).
+ * the applications want to directly control the capture parameters. + *For example, the application may wish to manually control + * {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}, {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, etc.
* * @see CaptureRequest#SENSOR_EXPOSURE_TIME * @see CaptureRequest#SENSOR_SENSITIVITY @@ -1034,7 +1115,8 @@ public abstract class CameraMetadataA "monocolor" effect where the image is mapped into - * a single color. This will typically be grayscale.
+ * a single color. + *This will typically be grayscale.
* @see CaptureRequest#CONTROL_EFFECT_MODE */ public static final int CONTROL_EFFECT_MODE_MONO = 1; @@ -1094,31 +1176,42 @@ public abstract class CameraMetadataFull application control of pipeline. All 3A - * routines are disabled, no other settings in - * android.control.* have any effect
+ *Full application control of pipeline.
+ *All control by the device's metering and focusing (3A) + * routines is disabled, and no other settings in + * android.control.* have any effect, except that + * {@link CaptureRequest#CONTROL_CAPTURE_INTENT android.control.captureIntent} may be used by the camera + * device to select post-processing values for processing + * blocks that do not allow for manual control, or are not + * exposed by the camera API.
+ *However, the camera device's 3A routines may continue to + * collect statistics and update their internal state so that + * when control is switched to AUTO mode, good control values + * can be immediately applied.
+ * + * @see CaptureRequest#CONTROL_CAPTURE_INTENT * @see CaptureRequest#CONTROL_MODE */ public static final int CONTROL_MODE_OFF = 0; /** - *Use settings for each individual 3A routine. - * Manual control of capture parameters is disabled. All + *
Use settings for each individual 3A routine.
+ *Manual control of capture parameters is disabled. All * controls in android.control.* besides sceneMode take - * effect
+ * effect. * @see CaptureRequest#CONTROL_MODE */ public static final int CONTROL_MODE_AUTO = 1; /** - *Use specific scene mode. Enabling this disables - * control.aeMode, control.awbMode and control.afMode - * controls; the camera device will ignore those settings while - * USE_SCENE_MODE is active (except for FACE_PRIORITY - * scene mode). Other control entries are still active. - * This setting can only be used if scene mode is supported - * (i.e. {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes} contain some modes - * other than DISABLED).
+ *Use a specific scene mode.
+ *Enabling this disables control.aeMode, control.awbMode and + * control.afMode controls; the camera device will ignore + * those settings while USE_SCENE_MODE is active (except for + * FACE_PRIORITY scene mode). Other control entries are still + * active. This setting can only be used if scene mode is + * supported (i.e. {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes} + * contain some modes other than DISABLED).
* * @see CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES * @see CaptureRequest#CONTROL_MODE @@ -1128,7 +1221,12 @@ public abstract class CameraMetadataSame as OFF mode, except that this capture will not be * used by camera device background auto-exposure, auto-white balance and - * auto-focus algorithms to update their statistics.
+ * auto-focus algorithms (3A) to update their statistics. + *Specifically, the 3A routines are locked to the last + * values set from a request with AUTO, OFF, or + * USE_SCENE_MODE, and any statistics or state updates + * collected from manual captures with OFF_KEEP_STATE will be + * discarded by the camera device.
* @see CaptureRequest#CONTROL_MODE */ public static final int CONTROL_MODE_OFF_KEEP_STATE = 3; @@ -1146,8 +1244,9 @@ public abstract class CameraMetadataIf face detection support exists, use face * detection data for auto-focus, auto-white balance, and - * auto-exposure routines. If face detection statistics are - * disabled (i.e. {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} is set to OFF), + * auto-exposure routines.
+ *If face detection statistics are disabled + * (i.e. {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} is set to OFF), * this should still operate correctly (but will not return * face detection statistics to the framework).
*Unlike the other scene modes, {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode},
@@ -1163,8 +1262,8 @@ public abstract class CameraMetadata Optimized for photos of quickly moving objects.
- * Similar to SPORTS. Optimized for photos of quickly moving objects. Similar to SPORTS. Optimized for photos of quickly moving people.
- * Similar to ACTION. Optimized for photos of quickly moving people. Similar to ACTION. Video stabilization is disabled. Video stabilization is enabled. No edge enhancement is applied No edge enhancement is applied. Must not slow down frame rate relative to sensor
+ * Apply edge enhancement at a quality level that does not slow down frame rate relative to sensor
* output Frame rate may be reduced by high
- * quality Apply high-quality edge enhancement, at a cost of reducing output frame rate. No hot pixel correction is applied. The frame rate must not be reduced relative to sensor raw output
* for this option. No hot pixel correction is applied.
- * The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}. The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}. The frame rate must not be reduced relative to sensor raw output
- * for this option. Hot pixel correction is applied.
- * The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}. Hot pixel correction is applied, without reducing frame
+ * rate relative to sensor raw output. The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}. The frame rate may be reduced relative to sensor raw output
- * for this option. A high-quality hot pixel correction is applied.
- * The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}. High-quality hot pixel correction is applied, at a cost
+ * of reducing frame rate relative to sensor raw output. The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}. No noise reduction is applied No noise reduction is applied. Must not slow down frame rate relative to sensor
- * output Noise reduction is applied without reducing frame rate relative to sensor
+ * output. May slow down frame rate to provide highest
- * quality High-quality noise reduction is applied, at the cost of reducing frame rate
+ * relative to sensor output. Default. No test pattern mode is used, and the camera
+ * No test pattern mode is used, and the camera
* device returns captures from the image sensor. This is the default if the key is not set. No lens shading correction is applied No lens shading correction is applied. Must not slow down frame rate relative to sensor raw output Apply lens shading corrections, without slowing
+ * frame rate relative to sensor raw output Frame rate may be reduced by high quality Apply high-quality lens shading correction, at the
+ * cost of reduced frame rate. Do not include face detection statistics in capture
+ * results. Optional Return rectangle and confidence
- * only Return face rectangle and confidence values only. In this mode, only android.statistics.faceRectangles and
+ * android.statistics.faceScores outputs are valid. Optional Return all face
- * metadata Return all face
+ * metadata. In this mode,
+ * android.statistics.faceRectangles,
+ * android.statistics.faceScores,
+ * android.statistics.faceIds, and
+ * android.statistics.faceLandmarks outputs are valid. Do not include a lens shading map in the capture result. Include a lens shading map in the capture result. Advanced gamma mapping and color enhancement may be applied. Should not slow down frame rate relative to raw sensor output. Advanced gamma mapping and color enhancement may be applied, without
+ * reducing frame rate compared to raw sensor output. Advanced gamma mapping and color enhancement may be applied. May slow down frame rate relative to raw sensor output. High-quality gamma mapping and color enhancement will be applied, at
+ * the cost of reduced frame rate compared to raw sensor output. AE is off or recently reset. When a camera device is opened, it starts in
+ * AE is off or recently reset. When a camera device is opened, it starts in
* this state. This is a transient state, the camera device may skip reporting
* this state in capture result. AE doesn't yet have a good set of control values
- * for the current scene. This is a transient state, the camera device may skip
+ * for the current scene. This is a transient state, the camera device may skip
* reporting this state in capture result. AE has been asked to do a precapture sequence
- * (through the {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} START),
- * and is currently executing it. Once PRECAPTURE
- * completes, AE will transition to CONVERGED or
- * FLASH_REQUIRED as appropriate. This is a transient state, the
- * camera device may skip reporting this state in capture result.
Precapture can be triggered through setting + * {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} to START.
+ *Once PRECAPTURE completes, AE will transition to CONVERGED + * or FLASH_REQUIRED as appropriate. This is a transient + * state, the camera device may skip reporting this state in + * capture result.
* * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER * @see CaptureResult#CONTROL_AE_STATE @@ -1654,61 +1769,78 @@ public abstract class CameraMetadataAF off or has not yet tried to scan/been asked - * to scan. When a camera device is opened, it starts in - * this state. This is a transient state, the camera device may - * skip reporting this state in capture result.
+ *AF is off or has not yet tried to scan/been asked + * to scan.
+ *When a camera device is opened, it starts in this + * state. This is a transient state, the camera device may + * skip reporting this state in capture + * result.
* @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_INACTIVE = 0; /** - *if CONTINUOUS_* modes are supported. AF is - * currently doing an AF scan initiated by a continuous - * autofocus mode. This is a transient state, the camera device may - * skip reporting this state in capture result.
+ *AF is currently performing an AF scan initiated the + * camera device in a continuous autofocus mode.
+ *Only used by CONTINUOUS_* AF modes. This is a transient + * state, the camera device may skip reporting this state in + * capture result.
* @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_PASSIVE_SCAN = 1; /** - *if CONTINUOUS_* modes are supported. AF currently - * believes it is in focus, but may restart scanning at - * any time. This is a transient state, the camera device may skip - * reporting this state in capture result.
+ *AF currently believes it is in focus, but 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.
* @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_PASSIVE_FOCUSED = 2; /** - *if AUTO or MACRO modes are supported. AF is doing - * an AF scan because it was triggered by AF trigger. This is a - * transient state, the camera device may skip reporting - * this state in capture result.
+ *AF is performing an AF scan because it was + * triggered by AF trigger.
+ *Only used by AUTO or MACRO AF modes. This is a transient + * state, the camera device may skip reporting this state in + * capture result.
* @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_ACTIVE_SCAN = 3; /** - *if any AF mode besides OFF is supported. AF - * believes it is focused correctly and is - * locked.
+ *AF believes it is focused correctly and has locked + * focus.
+ *This state is reached only after an explicit START AF trigger has been + * sent ({@link CaptureRequest#CONTROL_AF_TRIGGER android.control.afTrigger}), when good focus has been obtained.
+ *The lens will remain stationary until the AF mode ({@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}) is changed or + * a new AF trigger is sent to the camera device ({@link CaptureRequest#CONTROL_AF_TRIGGER android.control.afTrigger}).
+ * + * @see CaptureRequest#CONTROL_AF_MODE + * @see CaptureRequest#CONTROL_AF_TRIGGER * @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_FOCUSED_LOCKED = 4; /** - *if any AF mode besides OFF is supported. AF has - * failed to focus successfully and is - * locked.
+ *AF has failed to focus successfully and has locked + * focus.
+ *This state is reached only after an explicit START AF trigger has been + * sent ({@link CaptureRequest#CONTROL_AF_TRIGGER android.control.afTrigger}), when good focus cannot be obtained.
+ *The lens will remain stationary until the AF mode ({@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}) is changed or + * a new AF trigger is sent to the camera device ({@link CaptureRequest#CONTROL_AF_TRIGGER android.control.afTrigger}).
+ * + * @see CaptureRequest#CONTROL_AF_MODE + * @see CaptureRequest#CONTROL_AF_TRIGGER * @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_NOT_FOCUSED_LOCKED = 5; /** - *if CONTINUOUS_* modes are supported. AF finished a - * passive scan without finding focus, and may restart - * scanning at any time. This is a transient state, the camera + *
AF finished a passive scan without finding focus, + * 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.
* @see CaptureResult#CONTROL_AF_STATE */ @@ -1719,16 +1851,19 @@ public abstract class CameraMetadataAWB is not in auto mode. When a camera device is opened, it - * starts in this state. This is a transient state, the camera device may - * skip reporting this state in capture result.
+ *AWB is not in auto mode, or has not yet started metering.
+ *When a camera device is opened, it starts in this + * state. This is a transient state, the camera device may + * skip reporting this state in capture + * result.
* @see CaptureResult#CONTROL_AWB_STATE */ public static final int CONTROL_AWB_STATE_INACTIVE = 0; /** *AWB doesn't yet have a good set of control - * values for the current scene. This is a transient state, the camera device + * values for the current scene.
+ *This is a transient state, the camera device * may skip reporting this state in capture result.
* @see CaptureResult#CONTROL_AWB_STATE */ @@ -1776,8 +1911,9 @@ public abstract class CameraMetadataFlash partially illuminated this frame. This is usually due to the next - * or previous frame having the flash fire, and the flash spilling into this capture + *
Flash partially illuminated this frame.
+ *This is usually due to the next or previous frame having + * the flash fire, and the flash spilling into this capture * due to hardware limitations.
* @see CaptureResult#FLASH_STATE */ @@ -1800,8 +1936,10 @@ public abstract class CameraMetadataAny of the lens parameters ({@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}, {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance}, - * {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity} or {@link CaptureRequest#LENS_APERTURE android.lens.aperture}) is changing.
+ *One or several of the lens parameters + * ({@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}, {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance}, + * {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity} or {@link CaptureRequest#LENS_APERTURE android.lens.aperture}) is + * currently changing.
* * @see CaptureRequest#LENS_APERTURE * @see CaptureRequest#LENS_FILTER_DENSITY @@ -1816,16 +1954,22 @@ public abstract class CameraMetadataThe camera device does not detect any flickering illumination + * in the current scene.
* @see CaptureResult#STATISTICS_SCENE_FLICKER */ public static final int STATISTICS_SCENE_FLICKER_NONE = 0; /** + *The camera device detects illumination flickering at 50Hz + * in the current scene.
* @see CaptureResult#STATISTICS_SCENE_FLICKER */ public static final int STATISTICS_SCENE_FLICKER_50HZ = 1; /** + *The camera device detects illumination flickering at 60Hz + * in the current scene.
* @see CaptureResult#STATISTICS_SCENE_FLICKER */ public static final int STATISTICS_SCENE_FLICKER_60HZ = 2; @@ -1835,8 +1979,8 @@ public abstract class CameraMetadataThe current result is not yet fully synchronized to any request. - * Synchronization is in progress, and reading metadata from this + *
The current result is not yet fully synchronized to any request.
+ *Synchronization is in progress, and reading metadata from this * result may include a mix of data that have taken effect since the * last synchronization time.
*In some future result, within {@link CameraCharacteristics#SYNC_MAX_LATENCY android.sync.maxLatency} frames,
@@ -1851,10 +1995,10 @@ public abstract class CameraMetadata The current result's synchronization status is unknown. The
- * result may have already converged, or it may be in progress.
- * Reading from this result may include some mix of settings from
- * past requests. The current result's synchronization status is unknown. The result may have already converged, or it may be in
+ * progress. Reading from this result may include some mix
+ * of settings from past requests. After a settings change, the new settings will eventually all
* take effect for the output buffers and results. However, this
* value will not change when that happens. Altering settings
diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java
index 0ff8cce4544ad..bf7bd37c90a20 100644
--- a/core/java/android/hardware/camera2/CaptureRequest.java
+++ b/core/java/android/hardware/camera2/CaptureRequest.java
@@ -733,8 +733,16 @@ public final class CaptureRequest extends CameraMetadata The effect of auto-exposure (AE) precapture trigger depends
- * on the current AE mode and state; see
+ * The precapture sequence should triggered before starting a
+ * high-quality still capture for final metering decisions to
+ * be made, and for firing pre-capture flash pulses to estimate
+ * scene brightness and required final capture flash power, when
+ * the flash is enabled. Normally, this entry should be set to START for only a
+ * single request, and the application should wait until the
+ * sequence completes before starting a new one. The exact effect of auto-exposure (AE) precapture trigger
+ * depends on the current AE mode and state; see
* {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition
* details.
When set to CANCEL, the camera device will cancel any active trigger, * and return to its initial AF state.
- *See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what that means for each AF mode.
+ *Generally, applications should set this entry to START or CANCEL for only a + * single capture, and then return it to IDLE (or not set at all). Specifying + * 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.
* * @see CaptureResult#CONTROL_AF_STATE * @see #CONTROL_AF_TRIGGER_IDLE @@ -813,9 +825,11 @@ public final class CaptureRequest extends CameraMetadataWhether auto-white balance (AWB) is currently locked to its * latest calculated values.
- *Note that AWB lock is only meaningful for AUTO - * mode; in other modes, AWB is already fixed to a specific - * setting.
+ *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.
+ * + * @see CaptureRequest#CONTROL_AWB_MODE */ public static final KeyThis control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is AUTO.
- *When set to the ON mode, the camera device's auto white balance + *
When set to the ON mode, the camera device's auto-white balance * routine is enabled, overriding the application's selected * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} and * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.
- *When set to the OFF mode, the camera device's auto white balance + *
When set to the OFF mode, the camera device's auto-white balance * routine is disabled. The application manually controls the white * balance by {@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}.
- *When set to any other modes, the camera device's auto white balance - * routine is disabled. The camera device uses each particular illumination - * target for white balance adjustment.
+ *When set to any other modes, the camera device's auto-white + * balance routine is disabled. The camera device uses each + * particular illumination target for white balance + * adjustment. The application's values for + * {@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.
* * @see CaptureRequest#COLOR_CORRECTION_GAINS * @see CaptureRequest#COLOR_CORRECTION_MODE @@ -886,8 +904,8 @@ public final class CaptureRequest extends CameraMetadataThis control (except for MANUAL) is only effective if
* {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF and any 3A routine is active.
ZERO_SHUTTER_LAG must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} - * contains ZSL. MANUAL must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} + *
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.
* * @see CaptureRequest#CONTROL_MODE @@ -962,7 +980,9 @@ public final class CaptureRequest extends CameraMetadataThis 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 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
@@ -970,6 +990,7 @@ 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. If enabled, video stabilization can modify the
* {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream
* stabilized Compression quality of the final JPEG
* image. 85-95 is typical usage range 85-95 is typical usage range. Compression quality of JPEG
- * thumbnail
Sets whether the camera device uses optical image stabilization (OIS) * when capturing images.
- *OIS is used to compensate for motion blur due to small movements of - * the camera during capture. Unlike digital image stabilization, OIS makes - * use of mechanical elements to stabilize the camera sensor, and thus - * allows for longer exposure times before camera shake becomes - * apparent.
- *This is not expected to be supported on most devices.
+ *OIS is used to compensate for motion blur due to small + * movements of the camera during capture. Unlike digital image + * stabilization ({@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}), OIS + * makes use of mechanical elements to stabilize the camera + * sensor, and thus allows for longer exposure times before + * camera shake becomes apparent.
+ *Not all devices will support OIS; see + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for + * available controls.
+ * + * @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE + * @see CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION * @see #LENS_OPTICAL_STABILIZATION_MODE_OFF * @see #LENS_OPTICAL_STABILIZATION_MODE_ON */ @@ -1242,16 +1271,15 @@ public final class CaptureRequest extends CameraMetadataMode of operation for the noise reduction. - * algorithm
+ *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 in + *
This must be set to a valid mode from * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.
*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 should not + * even if it slows down capture rate. FAST means the camera device will not * slow down capture rate when applying noise filtering.
* * @see CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES @@ -1435,7 +1463,7 @@ public final class CaptureRequest extends CameraMetadataWhen enabled, the sensor sends a test pattern instead of * doing a real exposure from the camera.
*When a test pattern is enabled, all manual sensor controls specified - * by android.sensor.* should be ignored. All other controls should + * by android.sensor.* will be ignored. All other controls should * work as normal.
*For example, if manual flash is enabled, flash firing should still
* occur (and that the test pattern remain unmodified, since the flash
@@ -1490,7 +1518,7 @@ public final class CaptureRequest extends CameraMetadata State of the face detector
+ * Control for the face detector
* unit. Whether face detection is enabled, and whether it
* should output just the basic fields or the full set of
@@ -1508,7 +1536,7 @@ public final class CaptureRequest extends CameraMetadata 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 should be returned. This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}. Whether the camera device will output the lens
* shading map in output result metadata. When set to ON,
- * android.statistics.lensShadingMap must be provided in
+ * android.statistics.lensShadingMap will be provided in
* the output result metadata.
The effect of auto-exposure (AE) precapture trigger depends - * on the current AE mode and state; see + *
The precapture sequence should triggered before starting a + * high-quality still capture for final metering decisions to + * be made, and for firing pre-capture flash pulses to estimate + * scene brightness and required final capture flash power, when + * the flash is enabled.
+ *Normally, this entry should be set to START for only a + * single request, and the application should wait until the + * sequence completes before starting a new one.
+ *The exact effect of auto-exposure (AE) precapture trigger + * depends on the current AE mode and state; see * {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition * details.
* @@ -592,7 +600,7 @@ public class CaptureResult extends CameraMetadataCurrent state of auto-exposure (AE) algorithm.
+ *Current state of the auto-exposure (AE) algorithm.
*Switching between or enabling AE modes ({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}) always
* resets the AE state to INACTIVE. Similarly, switching between {@link CaptureRequest#CONTROL_MODE android.control.mode},
* or {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} if {@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE resets all
@@ -844,7 +852,11 @@ public class CaptureResult extends CameraMetadata
When set to CANCEL, the camera device will cancel any active trigger, * and return to its initial AF state.
- *See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what that means for each AF mode.
+ *Generally, applications should set this entry to START or CANCEL for only a + * single capture, and then return it to IDLE (or not set at all). Specifying + * 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.
* * @see CaptureResult#CONTROL_AF_STATE * @see #CONTROL_AF_TRIGGER_IDLE @@ -1034,13 +1046,13 @@ public class CaptureResult extends CameraMetadataWhether auto-white balance (AWB) is currently locked to its * latest calculated values.
- *Note that AWB lock is only meaningful for AUTO - * mode; in other modes, AWB is already fixed to a specific - * setting.
+ *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.
+ * + * @see CaptureRequest#CONTROL_AWB_MODE */ public static final KeyThis control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is AUTO.
- *When set to the ON mode, the camera device's auto white balance + *
When set to the ON mode, the camera device's auto-white balance * routine is enabled, overriding the application's selected * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} and * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.
- *When set to the OFF mode, the camera device's auto white balance + *
When set to the OFF mode, the camera device's auto-white balance * routine is disabled. The application manually controls the white * balance by {@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}.
- *When set to any other modes, the camera device's auto white balance - * routine is disabled. The camera device uses each particular illumination - * target for white balance adjustment.
+ *When set to any other modes, the camera device's auto-white + * balance routine is disabled. The camera device uses each + * particular illumination target for white balance + * adjustment. The application's values for + * {@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.
* * @see CaptureRequest#COLOR_CORRECTION_GAINS * @see CaptureRequest#COLOR_CORRECTION_MODE @@ -1327,8 +1345,8 @@ public class CaptureResult extends CameraMetadataThis control (except for MANUAL) is only effective if
* {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF and any 3A routine is active.
ZERO_SHUTTER_LAG must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} - * contains ZSL. MANUAL must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} + *
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.
* * @see CaptureRequest#CONTROL_MODE @@ -1533,7 +1551,9 @@ public class CaptureResult extends CameraMetadataThis 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 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
@@ -1541,6 +1561,7 @@ 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. If enabled, video stabilization can modify the
* {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream
* stabilized Compression quality of the final JPEG
* image. 85-95 is typical usage range 85-95 is typical usage range. Compression quality of JPEG
- * thumbnail
Sets whether the camera device uses optical image stabilization (OIS) * when capturing images.
- *OIS is used to compensate for motion blur due to small movements of - * the camera during capture. Unlike digital image stabilization, OIS makes - * use of mechanical elements to stabilize the camera sensor, and thus - * allows for longer exposure times before camera shake becomes - * apparent.
- *This is not expected to be supported on most devices.
+ *OIS is used to compensate for motion blur due to small + * movements of the camera during capture. Unlike digital image + * stabilization ({@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}), OIS + * makes use of mechanical elements to stabilize the camera + * sensor, and thus allows for longer exposure times before + * camera shake becomes apparent.
+ *Not all devices will support OIS; see + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for + * available controls.
+ * + * @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE + * @see CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION * @see #LENS_OPTICAL_STABILIZATION_MODE_OFF * @see #LENS_OPTICAL_STABILIZATION_MODE_ON */ @@ -1866,16 +1895,15 @@ public class CaptureResult extends CameraMetadataMode of operation for the noise reduction. - * algorithm
+ *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 in + *
This must be set to a valid mode from * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.
*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 should not + * even if it slows down capture rate. FAST means the camera device will not * slow down capture rate when applying noise filtering.
* * @see CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES @@ -2170,7 +2198,7 @@ public class CaptureResult extends CameraMetadataWhen enabled, the sensor sends a test pattern instead of * doing a real exposure from the camera.
*When a test pattern is enabled, all manual sensor controls specified - * by android.sensor.* should be ignored. All other controls should + * by android.sensor.* will be ignored. All other controls should * work as normal.
*For example, if manual flash is enabled, flash firing should still
* occur (and that the test pattern remain unmodified, since the flash
@@ -2225,7 +2253,7 @@ public class CaptureResult extends CameraMetadata State of the face detector
+ * Control for the face detector
* unit. Whether face detection is enabled, and whether it
* should output just the basic fields or the full set of
@@ -2241,9 +2269,13 @@ public class CaptureResult extends CameraMetadata List of unique IDs for detected
- * faces Only available if faceDetectMode == FULL List of unique IDs for detected faces. 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 List of landmarks for detected
- * faces Only available if faceDetectMode == FULL The coordinate system is that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with
+ * Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL List of the bounding rectangles for detected
- * faces Only available if faceDetectMode != OFF(0, 0) being the top-left pixel of the active array.
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
+ * + * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE * @hide */ public static final KeyList of the face confidence scores for * detected faces
- *Only available if faceDetectMode != OFF. The value should be - * meaningful (for example, setting 100 at all times is illegal).
+ *Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF.
+ * + * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE * @hide */ public static final KeyWhen manual exposure control is enabled
- * ({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} == OFF or {@link CaptureRequest#CONTROL_MODE android.control.mode} == OFF),
- * the {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} doesn't do the antibanding, and the
- * application can ensure it selects exposure times that do not cause banding
- * issues by looking into this metadata field. See {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode}
- * for more details.
Report NONE if there doesn't appear to be flickering illumination.
+ * ({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} == OFF or {@link CaptureRequest#CONTROL_MODE android.control.mode} ==
+ * OFF), the {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} doesn't perform
+ * antibanding, and the application can ensure it selects
+ * exposure times that do not cause banding issues by looking
+ * 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.
* * @see CaptureRequest#CONTROL_AE_ANTIBANDING_MODE * @see CaptureRequest#CONTROL_AE_MODE @@ -2455,7 +2499,7 @@ public class CaptureResult extends CameraMetadataOperating 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 should be returned.
+ * 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}.
* * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP @@ -2483,7 +2527,7 @@ public class CaptureResult extends CameraMetadataWhether the camera device will output the lens * shading map in output result metadata.
*When set to ON, - * android.statistics.lensShadingMap must be provided in + * android.statistics.lensShadingMap will be provided in * the output result metadata.
* @see #STATISTICS_LENS_SHADING_MAP_MODE_OFF * @see #STATISTICS_LENS_SHADING_MAP_MODE_ON diff --git a/core/java/android/hardware/camera2/params/StreamConfiguration.java b/core/java/android/hardware/camera2/params/StreamConfiguration.java index dd862b5f5aee3..a6fc10fdcc618 100644 --- a/core/java/android/hardware/camera2/params/StreamConfiguration.java +++ b/core/java/android/hardware/camera2/params/StreamConfiguration.java @@ -30,7 +30,8 @@ import android.util.Size; * Immutable class to store the available stream * {@link CameraCharacteristics#SCALER_AVAILABLE_STREAM_CONFIGURATIONS configurations} to set up * {@link android.view.Surface Surfaces} for creating a {@link CameraCaptureSession capture session} - * with {@link CameraDevice#createCaptureSession}. + * with {@link CameraDevice#createCaptureSession}. + * * *This is the authoritative list for all input/output formats (and sizes respectively * for that format) that are supported by a camera device.