The mode control selects how the image data is converted from the + * sensor's native color into linear sRGB color.
+ *When auto-white balance is enabled with {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, this + * control is overridden by the AWB routine. When AWB is disabled, the + * application controls how the color mapping is performed.
+ *We define the expected processing pipeline below. For consistency + * across devices, this is always the case with TRANSFORM_MATRIX.
+ *When either FULL or HIGH_QUALITY is used, the camera device may + * do additional processing but {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} and + * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} will still be provided by the + * camera device (in the results) and be roughly correct.
+ *Switching to TRANSFORM_MATRIX and using the data provided from + * FAST or HIGH_QUALITY will yield a picture with the same white point + * as what was produced by the camera device in the earlier frame.
+ *The expected processing pipeline is as follows:
+ *
The white balance is encoded by two values, a 4-channel white-balance + * gain vector (applied in the Bayer domain), and a 3x3 color transform + * matrix (applied after demosaic).
+ *The 4-channel white-balance gains are defined as:
+ *{@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} = [ R G_even G_odd B ]
+ * where G_even is the gain for green pixels on even rows of the
+ * output, and G_odd is the gain for green pixels on the odd rows.
+ * These may be identical for a given camera device implementation; if
+ * the camera device does not support a separate gain for even/odd green
+ * channels, it will use the G_even value, and write G_odd equal to
+ * G_even in the output result metadata.
The matrices for color transforms are defined as a 9-entry vector:
+ *{@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} = [ I0 I1 I2 I3 I4 I5 I6 I7 I8 ]
+ * which define a transform from input sensor colors, P_in = [ r g b ],
+ * to output linear sRGB, P_out = [ r' g' b' ],
with colors as follows:
+ *r' = I0r + I1g + I2b
+ * g' = I3r + I4g + I5b
+ * b' = I6r + I7g + I8b
+ * Both the input and output value ranges must match. Overflow/underflow + * values are clipped to fit within the range.
+ * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM + * @see CaptureRequest#CONTROL_AWB_MODE + * @see #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX + * @see #COLOR_CORRECTION_MODE_FAST + * @see #COLOR_CORRECTION_MODE_HIGH_QUALITY + */ + public static final KeyA color transform matrix to use to transform * from sensor RGB color space to output linear sRGB color space
@@ -175,6 +227,82 @@ public final class CaptureResult extends CameraMetadata { public static final KeyThe desired setting for the camera device's auto-exposure + * algorithm's antibanding compensation.
+ *Some kinds of lighting fixtures, such as some fluorescent + * lights, flicker at the rate of the power supply frequency + * (60Hz or 50Hz, depending on country). While this is + * typically not noticeable to a person, it can be visible to + * a camera device. If a camera sets its exposure time to the + * wrong value, the flicker may become visible in the + * viewfinder as flicker or in a final captured image, as a + * set of variable-brightness bands across the image.
+ *Therefore, the auto-exposure routines of camera devices + * include antibanding routines that ensure that the chosen + * exposure value will not cause such banding. The choice of + * exposure time depends on the rate of flicker, which the + * camera device can detect automatically, or the expected + * rate can be selected by the application using this + * control.
+ *A given camera device may not support all of the possible + * 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 + * 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), + * then this setting has no effect, and the application must + * 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.
+ * + * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES + * @see CaptureRequest#CONTROL_AE_MODE + * @see CaptureRequest#CONTROL_MODE + * @see CaptureResult#STATISTICS_SCENE_FLICKER + * @see #CONTROL_AE_ANTIBANDING_MODE_OFF + * @see #CONTROL_AE_ANTIBANDING_MODE_50HZ + * @see #CONTROL_AE_ANTIBANDING_MODE_60HZ + * @see #CONTROL_AE_ANTIBANDING_MODE_AUTO + */ + public static final KeyAdjustment to AE target image + * brightness
+ *For example, if EV step is 0.333, '6' will mean an + * exposure compensation of +2 EV; -3 will mean an exposure + * compensation of -1
+ */ + public static final KeyWhether 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.
+ *If AE precapture is triggered (see {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}) + * when AE is already locked, the camera device will not change the exposure time + * ({@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}) and sensitivity ({@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}) + * 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.
+ *See {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE lock related state transition details.
+ * + * @see CaptureRequest#CONTROL_AE_MODE + * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER + * @see CaptureResult#CONTROL_AE_STATE + * @see CaptureRequest#SENSOR_EXPOSURE_TIME + * @see CaptureRequest#SENSOR_SENSITIVITY + */ + public static final KeyThe desired mode for the camera device's * auto-exposure routine.
@@ -236,6 +364,35 @@ public final class CaptureResult extends CameraMetadata { public static final KeyRange over which fps can be adjusted to + * maintain exposure
+ *Only constrains AE algorithm, not manual control + * of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}
+ * + * @see CaptureRequest#SENSOR_EXPOSURE_TIME + */ + public static final KeyWhether the camera device will trigger a precapture + * metering sequence when it processes this request.
+ *This entry is normally set to IDLE, or is not + * included at all in the request settings. When included and + * set to START, the camera device will trigger the autoexposure + * precapture metering sequence.
+ *The effect of 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.
+ * + * @see CaptureResult#CONTROL_AE_STATE + * @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE + * @see #CONTROL_AE_PRECAPTURE_TRIGGER_START + */ + public static final KeyCurrent state of AE algorithm
*Switching between or enabling AE modes ({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}) always
@@ -480,6 +637,24 @@ public final class CaptureResult extends CameraMetadata {
public static final Key Whether the camera device will trigger autofocus for this request. This entry is normally set to IDLE, or is not
+ * included at all in the request settings. When included and set to START, the camera device will trigger the
+ * autofocus algorithm. If autofocus is disabled, this trigger has no effect. 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. Current state of AF algorithm. Switching between or enabling AF modes ({@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}) always
@@ -888,6 +1063,16 @@ public final class CaptureResult extends CameraMetadata {
public static final Key Whether 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. Whether AWB is currently setting the color
* transform fields, and what its illumination target
@@ -947,6 +1132,30 @@ public final class CaptureResult extends CameraMetadata {
public static final Key Information to the camera device 3A (auto-exposure,
+ * auto-focus, auto-white balance) routines about the purpose
+ * of this capture, to help the camera device to decide optimal 3A
+ * strategy. This control (except for MANUAL) is only effective if
+ * 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}
+ * contains MANUAL_SENSOR. Current state of AWB algorithm Switching between or enabling AWB modes ({@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}) always
@@ -1077,6 +1286,31 @@ public final class CaptureResult extends CameraMetadata {
public static final Key A special color effect to apply. When this mode is set, a color effect will be applied
+ * to images produced by the camera device. The interpretation
+ * and implementation of these color effects is left to the
+ * 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. Overall mode of 3A control
* routines. A camera mode optimized for conditions typical in a particular
+ * capture setting. This is the mode that that is active when
+ * 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. Whether video stabilization is
+ * active If enabled, video stabilization can modify the
+ * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream
+ * stabilized Operation mode for edge
* enhancement. A pixel Each color channel is treated as an unsigned 32-bit integer.
+ * The camera device then uses the most significant X bits
+ * that correspond to how many bits are in its Bayer raw sensor
+ * output. For example, a sensor with RAW10 Bayer output would use the
+ * 10 most significant bits from each color channel. Optional - This value may be {@code null} on some devices. When enabled, the sensor sends a test pattern instead of
* doing a real exposure from the camera. Whether the camera device will output the lens
+ * shading map in output result metadata. When set to ON,
+ * {@link CaptureResult#STATISTICS_LENS_SHADING_MAP android.statistics.lensShadingMap} must be provided in
+ * the output result metadata. Tonemapping / contrast / gamma curve for the blue
* channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
{@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF and any 3A routine is active.{@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.[R, G_even, G_odd, B] that supplies the test pattern
+ * when {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode} is SOLID_COLOR.