When auto-white balance (AWB) is enabled with 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 FAST or HIGH_QUALITY is used, the camera device may do additional processing but android.colorCorrection.gains and 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:

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:

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.

HAL must support both FAST and HIGH_QUALITY if color correction control is available on the camera device, but the underlying implementation can be the same for both modes. That is, if the highest quality implementation on the camera device does not slow down capture rate, then FAST and HIGH_QUALITY should generate the same output.

This matrix is either set by the camera device when the request android.colorCorrection.mode is not TRANSFORM_MATRIX, or directly by the application in the request when the android.colorCorrection.mode is TRANSFORM_MATRIX.

In the latter case, the camera device may round the matrix to account for precision issues; the final rounded matrix should be reported back 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.

The valid range of each matrix element varies on different devices, but values within [-1.5, 3.0] are guaranteed not to be clipped.

These per-channel gains are either set by the camera device when the request android.colorCorrection.mode is not TRANSFORM_MATRIX, or directly by the application in the request when the android.colorCorrection.mode is TRANSFORM_MATRIX.

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

The valid range of gains varies on different devices, but gains between [1.0, 3.0] are guaranteed not to be clipped. Even if a given device allows gains below 1.0, this is usually not recommended because this can create color artifacts.

The 4-channel white-balance gains are defined in the order of [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.

If a HAL does not support a separate gain for even/odd green channels, it must use the G_even value, and write G_odd equal to G_even in the output result metadata.

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 minimize the chromatic artifacts that may occur along the object boundaries in an image.

FAST/HIGH_QUALITY both mean that camera device determined aberration correction will be applied. HIGH_QUALITY mode indicates that the camera device will 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.

When auto-white balance (AWB) is enabled with 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 FAST or HIGH_QUALITY is used, the camera device may do additional processing but android.colorCorrection.gains and 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:

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:

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.

HAL must support both FAST and HIGH_QUALITY if color correction control is available on the camera device, but the underlying implementation can be the same for both modes. That is, if the highest quality implementation on the camera device does not slow down capture rate, then FAST and HIGH_QUALITY should generate the same output.

This matrix is either set by the camera device when the request android.colorCorrection.mode is not TRANSFORM_MATRIX, or directly by the application in the request when the android.colorCorrection.mode is TRANSFORM_MATRIX.

In the latter case, the camera device may round the matrix to account for precision issues; the final rounded matrix should be reported back 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.

The valid range of each matrix element varies on different devices, but values within [-1.5, 3.0] are guaranteed not to be clipped.

These per-channel gains are either set by the camera device when the request android.colorCorrection.mode is not TRANSFORM_MATRIX, or directly by the application in the request when the android.colorCorrection.mode is TRANSFORM_MATRIX.

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

The valid range of gains varies on different devices, but gains between [1.0, 3.0] are guaranteed not to be clipped. Even if a given device allows gains below 1.0, this is usually not recommended because this can create color artifacts.

The 4-channel white-balance gains are defined in the order of [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.

If a HAL does not support a separate gain for even/odd green channels, it must use the G_even value, and write G_odd equal to G_even in the output result metadata.

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 minimize the chromatic artifacts that may occur along the object boundaries in an image.

FAST/HIGH_QUALITY both mean that camera device determined aberration correction will be applied. HIGH_QUALITY mode indicates that the camera device will 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 lists the valid modes for android.colorCorrection.aberrationMode. If no aberration correction modes are available for a device, this list will solely include OFF mode. All camera devices will support either OFF or FAST mode.

Camera devices that support the MANUAL_POST_PROCESSING capability will always list OFF mode. This includes all FULL level devices.

LEGACY devices will always only support FAST mode.

HAL must support both FAST and HIGH_QUALITY if chromatic aberration control is available on the camera device, but the underlying implementation can be the same for both modes. That is, if the highest quality implementation on the camera device does not slow down capture rate, then FAST and HIGH_QUALITY will generate the same output.

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 android.control.aeAvailableAntibandingModes key contains the available modes for a given camera device.

AUTO mode is the default if it is available on given camera device. When AUTO mode is not available, the default will be either 50HZ or 60HZ, and both 50HZ and 60HZ will be available.

If manual exposure control is enabled (by setting android.control.aeMode or 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 android.statistics.sceneFlicker key can assist the application in this.

For all capture request templates, this field must be set to AUTO if AUTO mode is available. If AUTO is not available, the default must be either 50HZ or 60HZ, and both 50HZ and 60HZ must be available.

If manual exposure control is enabled (by setting android.control.aeMode or android.control.mode to OFF), then the exposure values provided by the application must not be adjusted for antibanding.

The adjustment is measured as a count of steps, with the step size defined by android.control.aeCompensationStep and the allowed range by android.control.aeCompensationRange.

For example, if the exposure value (EV) step is 0.333, '6' will mean an exposure compensation of +2 EV; -3 will mean an exposure compensation of -1 EV. One EV represents a doubling of image brightness. Note that this control will only be effective if android.control.aeMode != OFF. This control will take effect even when android.control.aeLock == true.

In the event of exposure compensation value being changed, camera device may take several frames to reach the newly requested exposure target. During that time, android.control.aeState field will be in the SEARCHING state. Once the new exposure target is reached, 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).

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 android.control.aeMode is ON_AUTO_FLASH / ON_ALWAYS_FLASH / ON_AUTO_FLASH_REDEYE.

When 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 android.control.aePrecaptureTrigger) when AE is already locked, the camera device will not change the exposure time (android.sensor.exposureTime) and sensitivity (android.sensor.sensitivity) parameters. The flash may be fired if the android.control.aeMode is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the android.control.aeMode is ON_ALWAYS_FLASH, the scene may become overexposed. Similarly, AE precapture trigger CANCEL has no effect when AE is already locked.

When an AE precapture sequence is triggered, AE unlock will not be able to unlock the AE if AE is locked by the camera device internally during precapture metering sequence In other words, submitting requests with AE unlock has no effect for an ongoing precapture metering sequence. Otherwise, the precapture metering sequence will never succeed in a sequence of preview requests where AE lock is always set to false.

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. Lock AE
3. Wait for the first result to be output that has the AE locked
4. Copy exposure settings from that result into a request, set the request to manual AE
5. Submit the capture request, proceed to run manual AE as desired.

See android.control.aeState for AE lock related state transition details.

This control is only effective if android.control.mode is AUTO.

When set to any of the ON modes, the camera device's auto-exposure routine is enabled, overriding the application's selected exposure time, sensor sensitivity, and frame duration (android.sensor.exposureTime, android.sensor.sensitivity, and android.sensor.frameDuration). If one of the FLASH modes is selected, the camera device's flash unit controls are also overridden.

The FLASH modes are only available if the camera device has a flash unit (android.flash.info.available is true).

If flash TORCH mode is desired, this field must be set to ON or OFF, and android.flash.mode set to TORCH.

When set to any of the ON modes, the values chosen by the camera device auto-exposure routine for the overridden fields for a given capture will be available in its CaptureResult.

Not available if 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 android.control.maxRegionsAe.

For devices not supporting android.distortionCorrection.mode control, the coordinate system always follows that of android.sensor.info.activeArraySize, with (0,0) being the top-left pixel in the active pixel array, and (android.sensor.info.activeArraySize.width - 1, android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the active pixel array.

For devices supporting android.distortionCorrection.mode control, the coordinate system depends on the mode being set. When the distortion correction mode is OFF, the coordinate system follows android.sensor.info.preCorrectionActiveArraySize, with (0, 0) being the top-left pixel of the pre-correction active array, and (android.sensor.info.preCorrectionActiveArraySize.width - 1, android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right pixel in the pre-correction active pixel array. When the distortion correction mode is not OFF, the coordinate system follows android.sensor.info.activeArraySize, with (0, 0) being the top-left pixel of the active array, and (android.sensor.info.activeArraySize.width - 1, android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the active pixel array.

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.

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

When setting the AE metering regions, the application must consider the additional crop resulted from the aspect ratio differences between the preview stream and android.scaler.cropRegion. For example, if the android.scaler.cropRegion is the full active array size with 4:3 aspect ratio, and the preview stream is 16:9, the boundary of AE regions will be [0, y_crop] and [active_width, active_height - 2 * y_crop] rather than [0, 0] and [active_width, active_height], where y_crop is the additional crop due to aspect ratio mismatch.

Starting from API level 30, the coordinate system of activeArraySize or preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not pre-zoom field of view. This means that the same aeRegions values at different android.control.zoomRatio represent different parts of the scene. The aeRegions coordinates are relative to the activeArray/preCorrectionActiveArray representing the zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same aeRegions at different android.scaler.cropRegion still represent the same parts of the scene as they do before. See android.control.zoomRatio for details. Whether to use activeArraySize or preCorrectionActiveArraySize still depends on distortion correction mode.

For camera devices with the CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR capability or devices where CameraCharacteristics#getAvailableCaptureRequestKeys lists android.sensor.pixelMode android.sensor.info.activeArraySizeMaximumResolution / android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the coordinate system for requests where android.sensor.pixelMode is set to CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION.

The HAL level representation of MeteringRectangle[] is a int[5 * area_count]. Every five elements represent a metering region of (xmin, ymin, xmax, ymax, weight). The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and ymax. HAL must always report metering regions in the coordinate system of pre-correction active array.

Only constrains auto-exposure (AE) algorithm, not manual control of android.sensor.exposureTime and android.sensor.frameDuration.

Note that the actual achievable max framerate also depends on the minimum frame duration of the output streams. The max frame rate will be min(aeTargetFpsRange.maxFps, 1 / max(individual stream min durations)). For example, if the application sets this key to {60, 60}, but the maximum minFrameDuration among all configured streams is 33ms, the maximum framerate won't be 60fps, but will be 30fps.

To start a CaptureSession with a target FPS range different from the capture request template's default value, the application is strongly recommended to call SessionConfiguration#setSessionParameters with the target fps range before creating the capture session. The aeTargetFpsRange is typically a session parameter. Specifying it at session creation time helps avoid session reconfiguration delays in cases like 60fps or high speed recording.

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 auto-exposure (AE) precapture metering sequence.

When set to CANCEL, the camera device will cancel any active precapture metering trigger, and return to its initial AE state. If a precapture metering sequence is already completed, and the camera device has implicitly locked the AE for subsequent still capture, the CANCEL trigger will unlock the AE and return to its initial AE state.

The precapture sequence should be 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.

When a precapture metering sequence is finished, the camera device may lock the auto-exposure routine internally to be able to accurately expose the subsequent still capture image (android.control.captureIntent == STILL_CAPTURE). For this case, the AE may not resume normal scan if no subsequent still capture is submitted. To ensure that the AE routine restarts normal scan, the application should submit a request with android.control.aeLock == true, followed by a request with android.control.aeLock == false, if the application decides not to submit a still capture request after the precapture sequence completes. Alternatively, for API level 23 or newer devices, the CANCEL can be used to unlock the camera device internally locked AE if the application doesn't submit a still capture request after the AE precapture trigger. Note that, the CANCEL was added in API level 23, and must not be used in devices that have earlier API levels.

The exact effect of auto-exposure (AE) precapture trigger depends on the current AE mode and state; see 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.

Using the precapture trigger and the auto-focus trigger android.control.afTrigger simultaneously is allowed. However, since these triggers often require cooperation between the auto-focus and auto-exposure routines (for example, the may need to be enabled for a focus sweep), the camera device may delay acting on a later trigger until the previous trigger has been fully handled. This may lead to longer intervals between the trigger and changes to android.control.aeState indicating the start of the precapture sequence, for example.

If both the precapture and the auto-focus trigger are activated on the same request, then the camera device will complete them in the optimal order for that device.

The HAL must support triggering the AE precapture trigger while an AF trigger is active (and vice versa), or at the same time as the AF trigger. It is acceptable for the HAL to treat these as two consecutive triggers, for example handling the AF trigger and then the AE trigger. Or the HAL may choose to optimize the case with both triggers fired at once, to minimize the latency for converging both focus and exposure/flash usage.

Only effective if android.control.mode = AUTO and the lens is not fixed focus (i.e. android.lens.info.minimumFocusDistance > 0). Also note that when android.control.aeMode is OFF, the behavior of AF is device dependent. It is recommended to lock AF by using android.control.afTrigger before setting android.control.aeMode to OFF, or set AF mode to OFF when AE is OFF.

If the lens is controlled by the camera device auto-focus algorithm, the camera device will report the current AF status in android.control.afState in result metadata.

When afMode is AUTO or MACRO, the lens must not move until an AF trigger is sent in a request (android.control.afTrigger == START). After an AF trigger, the afState will end up with either FOCUSED_LOCKED or NOT_FOCUSED_LOCKED state (see android.control.afState for detailed state transitions), which indicates that the lens is locked and will not move. If camera movement (e.g. tilting camera) causes the lens to move after the lens is locked, the HAL must compensate this movement appropriately such that the same focal plane remains in focus.

When afMode is one of the continuous auto focus modes, the HAL is free to start a AF scan whenever it's not locked. When the lens is locked after an AF trigger (see android.control.afState for detailed state transitions), the HAL should maintain the same lock behavior as above.

When afMode is OFF, the application controls focus manually. The accuracy of the focus distance control depends on the android.lens.info.focusDistanceCalibration. However, the lens must not move regardless of the camera movement for any focus distance manual control.

To put this in concrete terms, if the camera has lens elements which may move based on camera orientation or motion (e.g. due to gravity), then the HAL must drive the lens to remain in a fixed position invariant to the camera's orientation or motion, for example, by using accelerometer measurements in the lens control logic. This is a typical issue that will arise on camera modules with open-loop VCMs.

Not available if 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 android.control.maxRegionsAf.

For devices not supporting android.distortionCorrection.mode control, the coordinate system always follows that of android.sensor.info.activeArraySize, with (0,0) being the top-left pixel in the active pixel array, and (android.sensor.info.activeArraySize.width - 1, android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the active pixel array.

For devices supporting android.distortionCorrection.mode control, the coordinate system depends on the mode being set. When the distortion correction mode is OFF, the coordinate system follows android.sensor.info.preCorrectionActiveArraySize, with (0, 0) being the top-left pixel of the pre-correction active array, and (android.sensor.info.preCorrectionActiveArraySize.width - 1, android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right pixel in the pre-correction active pixel array. When the distortion correction mode is not OFF, the coordinate system follows android.sensor.info.activeArraySize, with (0, 0) being the top-left pixel of the active array, and (android.sensor.info.activeArraySize.width - 1, android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the active pixel array.

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.

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. The capture result will either be a zero weight region as well, or the region selected by the camera device as the focus area of interest.

If the metering region is outside the used 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.

When setting the AF metering regions, the application must consider the additional crop resulted from the aspect ratio differences between the preview stream and android.scaler.cropRegion. For example, if the android.scaler.cropRegion is the full active array size with 4:3 aspect ratio, and the preview stream is 16:9, the boundary of AF regions will be [0, y_crop] and [active_width, active_height - 2 * y_crop] rather than [0, 0] and [active_width, active_height], where y_crop is the additional crop due to aspect ratio mismatch.

Starting from API level 30, the coordinate system of activeArraySize or preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not pre-zoom field of view. This means that the same afRegions values at different android.control.zoomRatio represent different parts of the scene. The afRegions coordinates are relative to the activeArray/preCorrectionActiveArray representing the zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same afRegions at different android.scaler.cropRegion still represent the same parts of the scene as they do before. See android.control.zoomRatio for details. Whether to use activeArraySize or preCorrectionActiveArraySize still depends on distortion correction mode.

For camera devices with the CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR capability or devices where CameraCharacteristics#getAvailableCaptureRequestKeys lists android.sensor.pixelMode, android.sensor.info.activeArraySizeMaximumResolution / android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the coordinate system for requests where android.sensor.pixelMode is set to CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION.

The HAL level representation of MeteringRectangle[] is a int[5 * area_count]. Every five elements represent a metering region of (xmin, ymin, xmax, ymax, weight). The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and ymax. HAL must always report metering regions in the coordinate system of pre-correction active array.

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.

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 android.control.afState for what the trigger means for each AF mode.

Using the autofocus trigger and the precapture trigger android.control.aePrecaptureTrigger simultaneously is allowed. However, since these triggers often require cooperation between the auto-focus and auto-exposure routines (for example, the may need to be enabled for a focus sweep), the camera device may delay acting on a later trigger until the previous trigger has been fully handled. This may lead to longer intervals between the trigger and changes to android.control.afState, for example.

The HAL must support triggering the AF trigger while an AE precapture trigger is active (and vice versa), or at the same time as the AE trigger. It is acceptable for the HAL to treat these as two consecutive triggers, for example handling the AF trigger and then the AE trigger. Or the HAL may choose to optimize the case with both triggers fired at once, to minimize the latency for converging both focus and exposure/flash usage.

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. Lock AWB
3. Wait for the first result to be output that has the AWB locked
4. Copy AWB settings from that result into a request, set the request to manual AWB
5. Submit the capture request, proceed to run manual AWB as desired.

Note that AWB lock is only meaningful when 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 control is only effective if android.control.mode is AUTO.

When set to the AUTO mode, the camera device's auto-white balance routine is enabled, overriding the application's selected android.colorCorrection.transform, android.colorCorrection.gains and android.colorCorrection.mode. Note that when android.control.aeMode is OFF, the behavior of AWB is device dependent. It is recommended to also set AWB mode to OFF or lock AWB by using android.control.awbLock before setting AE mode to OFF.

When set to the OFF mode, the camera device's auto-white balance routine is disabled. The application manually controls the white balance by android.colorCorrection.transform, android.colorCorrection.gains and 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. The application's values for android.colorCorrection.transform, android.colorCorrection.gains and android.colorCorrection.mode are ignored.

Not available if 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 android.control.maxRegionsAwb.

For devices not supporting android.distortionCorrection.mode control, the coordinate system always follows that of android.sensor.info.activeArraySize, with (0,0) being the top-left pixel in the active pixel array, and (android.sensor.info.activeArraySize.width - 1, android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the active pixel array.

For devices supporting android.distortionCorrection.mode control, the coordinate system depends on the mode being set. When the distortion correction mode is OFF, the coordinate system follows android.sensor.info.preCorrectionActiveArraySize, with (0, 0) being the top-left pixel of the pre-correction active array, and (android.sensor.info.preCorrectionActiveArraySize.width - 1, android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right pixel in the pre-correction active pixel array. When the distortion correction mode is not OFF, the coordinate system follows android.sensor.info.activeArraySize, with (0, 0) being the top-left pixel of the active array, and (android.sensor.info.activeArraySize.width - 1, 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 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.

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

When setting the AWB metering regions, the application must consider the additional crop resulted from the aspect ratio differences between the preview stream and android.scaler.cropRegion. For example, if the android.scaler.cropRegion is the full active array size with 4:3 aspect ratio, and the preview stream is 16:9, the boundary of AWB regions will be [0, y_crop] and [active_width, active_height - 2 * y_crop] rather than [0, 0] and [active_width, active_height], where y_crop is the additional crop due to aspect ratio mismatch.

Starting from API level 30, the coordinate system of activeArraySize or preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not pre-zoom field of view. This means that the same awbRegions values at different android.control.zoomRatio represent different parts of the scene. The awbRegions coordinates are relative to the activeArray/preCorrectionActiveArray representing the zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same awbRegions at different android.scaler.cropRegion still represent the same parts of the scene as they do before. See android.control.zoomRatio for details. Whether to use activeArraySize or preCorrectionActiveArraySize still depends on distortion correction mode.

For camera devices with the CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR capability or devices where CameraCharacteristics#getAvailableCaptureRequestKeys lists android.sensor.pixelMode, android.sensor.info.activeArraySizeMaximumResolution / android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the coordinate system for requests where android.sensor.pixelMode is set to CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION.

The HAL level representation of MeteringRectangle[] is a int[5 * area_count]. Every five elements represent a metering region of (xmin, ymin, xmax, ymax, weight). The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and ymax. HAL must always report metering regions in the coordinate system of pre-correction active array.

This control (except for MANUAL) is only effective if android.control.mode != OFF and any 3A routine is active.

All intents are supported by all devices, except that:

• ZERO_SHUTTER_LAG will be supported if android.request.availableCapabilities contains PRIVATE_REPROCESSING or YUV_REPROCESSING.
• MANUAL will be supported if android.request.availableCapabilities contains MANUAL_SENSOR.
• MOTION_TRACKING will be supported if android.request.availableCapabilities contains MOTION_TRACKING.

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.

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 android.control.* are in effect, such as android.control.afMode.

When set to USE_SCENE_MODE or USE_EXTENDED_SCENE_MODE, the individual controls in android.control.* are mostly disabled, and the camera device implements one of the scene mode or extended scene mode settings (such as ACTION, SUNSET, PARTY, or BOKEH) as it wishes. The camera device scene mode 3A settings are provided by capture results.

When set to OFF_KEEP_STATE, it is similar to OFF mode, the only difference is that this frame will not be used by camera device background 3A statistics 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.

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 android.control.mode == USE_SCENE_MODE. Aside from FACE_PRIORITY, these modes will disable android.control.aeMode, android.control.awbMode, and 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.

HAL implementations that include scene modes are expected to provide the per-scene settings to use for android.control.aeMode, android.control.awbMode, and android.control.afMode in android.control.sceneModeOverrides.

For HIGH_SPEED_VIDEO mode, if it is included in android.control.availableSceneModes, the HAL must list supported video size and fps range in android.control.availableHighSpeedVideoConfigurations. For a given size, e.g. 1280x720, if the HAL has two different sensor configurations for normal streaming mode and high speed streaming, when this scene mode is set/reset in a sequence of capture requests, the HAL may have to switch between different sensor modes. This mode is deprecated in legacy HAL3.3, to support high speed video recording, please implement android.control.availableHighSpeedVideoConfigurations and CONSTRAINED_HIGH_SPEED_VIDEO capability defined in android.request.availableCapabilities.

Video stabilization automatically warps images from the camera in order to stabilize motion between consecutive frames.

If enabled, video stabilization can modify the 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.

In addition, not all recording sizes or frame rates may be supported for stabilization by a device that reports stabilization support. It is guaranteed that an output targeting a MediaRecorder or MediaCodec will be stabilized if the recording resolution is less than or equal to 1920 x 1080 (width less than or equal to 1920, height less than or equal to 1080), and the recording frame rate is less than or equal to 30fps. At other sizes, the CaptureResult android.control.videoStabilizationMode field will return OFF if the recording output is not stabilized, or if there are no output Surface types that can be stabilized.

The application is strongly recommended to call SessionConfiguration#setSessionParameters with the desired video stabilization mode before creating the capture session. Video stabilization mode is a session parameter on many devices. Specifying it at session creation time helps avoid reconfiguration delay caused by difference between the default value and the first CaptureRequest.

If a camera device supports both this mode and OIS (android.lens.opticalStabilizationMode), turning both modes on may produce undesirable interaction, so it is recommended not to enable both at the same time.

If video stabilization is set to "PREVIEW_STABILIZATION", android.lens.opticalStabilizationMode is overridden. The camera sub-system may choose to turn on hardware based image stabilization in addition to software based stabilization if it deems that appropriate. This key may be a part of the available session keys, which camera clients may query via CameraCharacteristics#getAvailableSessionKeys. If this is the case, changing this key over the life-time of a capture session may cause delays / glitches.

When this key is set to "PREVIEW_STABILIZATION", for non-stalling buffers returned without errors, the time interval between notify readout timestamp and when buffers are returned to the camera framework, must be no more than 1 extra frame interval, relative to the case where this key is set to "OFF".

This is in order for look-ahead time period to be short enough for preview to match video recording for real-time usage.

Some camera devices support additional digital sensitivity boosting in the camera processing pipeline after sensor RAW image is captured. Such a boost will be applied to YUV/JPEG format output images but will not have effect on RAW output formats like RAW_SENSOR, RAW10, RAW12 or RAW_OPAQUE.

This key will be null for devices that do not support any RAW format outputs. For devices that do support RAW format outputs, this key will always present, and if a device does not support post RAW sensitivity boost, it will list 100 in this key.

If the camera device cannot apply the exact boost requested, it will reduce the boost to the nearest supported value. The final boost value used will be available in the output capture result.

For devices that support post RAW sensitivity boost, the YUV/JPEG output images of such device will have the total sensitivity of android.sensor.sensitivity * android.control.postRawSensitivityBoost / 100 The sensitivity of RAW format images will always be android.sensor.sensitivity

This control is only effective if android.control.aeMode or android.control.mode is set to OFF; otherwise the auto-exposure algorithm will override this value.

If enableZsl is true, the camera device may enable zero-shutter-lag mode for requests with STILL_CAPTURE capture intent. The camera device may use images captured in the past to produce output images for a zero-shutter-lag request. The result metadata including the android.sensor.timestamp reflects the source frames used to produce output images. Therefore, the contents of the output images and the result metadata may be out of order compared to previous regular requests. enableZsl does not affect requests with other capture intents.

For example, when requests are submitted in the following order: Request A: enableZsl is ON, android.control.captureIntent is PREVIEW Request B: enableZsl is ON, android.control.captureIntent is STILL_CAPTURE

The output images for request B may have contents captured before the output images for request A, and the result metadata for request B may be older than the result metadata for request A.

Note that when enableZsl is true, it is not guaranteed to get output images captured in the past for requests with STILL_CAPTURE capture intent.

For applications targeting SDK versions O and newer, the value of enableZsl in TEMPLATE_STILL_CAPTURE template may be true. The value in other templates is always false if present.

For applications targeting SDK versions older than O, the value of enableZsl in all capture templates is always false if present.

For application-operated ZSL, use CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template.

It is valid for HAL to produce regular output images for requests with STILL_CAPTURE capture intent.

With bokeh mode, the camera device may blur out the parts of scene that are not in focus, creating a bokeh (or shallow depth of field) effect for people or objects.

When set to BOKEH_STILL_CAPTURE mode with STILL_CAPTURE capture intent, due to the extra processing needed for high quality bokeh effect, the stall may be longer than when capture intent is not STILL_CAPTURE.

When set to BOKEH_STILL_CAPTURE mode with PREVIEW capture intent,

• If the camera device has BURST_CAPTURE capability, the frame rate requirement of BURST_CAPTURE must still be met.
• All streams not larger than the maximum streaming dimension for BOKEH_STILL_CAPTURE mode (queried via CameraCharacteristics#CONTROL_AVAILABLE_EXTENDED_SCENE_MODE_CAPABILITIES) will have preview bokeh effect applied.

When set to BOKEH_CONTINUOUS mode, configured streams dimension should not exceed this mode's maximum streaming dimension in order to have bokeh effect applied. Bokeh effect may not be available for streams larger than the maximum streaming dimension.

Switching between different extended scene modes may involve reconfiguration of the camera pipeline, resulting in long latency. The application should check this key against the available session keys queried via CameraCharacteristics#getAvailableSessionKeys.

For a logical multi-camera, bokeh may be implemented by stereo vision from sub-cameras with different field of view. As a result, when bokeh mode is enabled, the camera device may override android.scaler.cropRegion or android.control.zoomRatio, and the field of view may be smaller than when bokeh mode is off.

Instead of using android.scaler.cropRegion for zoom, the application can now choose to use this tag to specify the desired zoom level.

By using this control, the application gains a simpler way to control zoom, which can be a combination of optical and digital zoom. For example, a multi-camera system may contain more than one lens with different focal lengths, and the user can use optical zoom by switching between lenses. Using zoomRatio has benefits in the scenarios below:

• Zooming in from a wide-angle lens to a telephoto lens: A floating-point ratio provides better precision compared to an integer value of android.scaler.cropRegion.
• Zooming out from a wide lens to an ultrawide lens: zoomRatio supports zoom-out whereas android.scaler.cropRegion doesn't.

To illustrate, here are several scenarios of different zoom ratios, crop regions, and output streams, for a hypothetical camera device with an active array of size (2000,1500).

• Camera Configuration:
  • Active array size: 2000x1500 (3 MP, 4:3 aspect ratio)
  • Output stream #1: 640x480 (VGA, 4:3 aspect ratio)
  • Output stream #2: 1280x720 (720p, 16:9 aspect ratio)
• Case #1: 4:3 crop region with 2.0x zoom ratio
  • Zoomed field of view: 1/4 of original field of view
  • Crop region: Rect(0, 0, 2000, 1500) // (left, top, right, bottom) (post zoom)
• 
  • 640x480 stream source area: (0, 0, 2000, 1500) (equal to crop region)
  • 1280x720 stream source area: (0, 187, 2000, 1312) (letterboxed)
• Case #2: 16:9 crop region with 2.0x zoom.
  • Zoomed field of view: 1/4 of original field of view
  • Crop region: Rect(0, 187, 2000, 1312)
  • 
  • 640x480 stream source area: (250, 187, 1750, 1312) (pillarboxed)
  • 1280x720 stream source area: (0, 187, 2000, 1312) (equal to crop region)
• Case #3: 1:1 crop region with 0.5x zoom out to ultrawide lens.
  • Zoomed field of view: 4x of original field of view (switched from wide lens to ultrawide lens)
  • Crop region: Rect(250, 0, 1750, 1500)
  • 
  • 640x480 stream source area: (250, 187, 1750, 1312) (letterboxed)
  • 1280x720 stream source area: (250, 328, 1750, 1172) (letterboxed)

As seen from the graphs above, the coordinate system of cropRegion now changes to the effective after-zoom field-of-view, and is represented by the rectangle of (0, 0, activeArrayWith, activeArrayHeight). The same applies to AE/AWB/AF regions, and faces. This coordinate system change isn't applicable to RAW capture and its related metadata such as intrinsicCalibration and lensShadingMap.

Using the same hypothetical example above, and assuming output stream #1 (640x480) is the viewfinder stream, the application can achieve 2.0x zoom in one of two ways:

• zoomRatio = 2.0, scaler.cropRegion = (0, 0, 2000, 1500)
• zoomRatio = 1.0 (default), scaler.cropRegion = (500, 375, 1500, 1125)

If the application intends to set aeRegions to be top-left quarter of the viewfinder field-of-view, the android.control.aeRegions should be set to (0, 0, 1000, 750) with zoomRatio set to 2.0. Alternatively, the application can set aeRegions to the equivalent region of (500, 375, 1000, 750) for zoomRatio of 1.0. If the application doesn't explicitly set android.control.zoomRatio, its value defaults to 1.0.

One limitation of controlling zoom using zoomRatio is that the android.scaler.cropRegion must only be used for letterboxing or pillarboxing of the sensor active array, and no FREEFORM cropping can be used with android.control.zoomRatio other than 1.0. If android.control.zoomRatio is not 1.0, and android.scaler.cropRegion is set to be windowboxing, the camera framework will override the android.scaler.cropRegion to be the active array.

In the capture request, if the application sets android.control.zoomRatio to a value != 1.0, the android.control.zoomRatio tag in the capture result reflects the effective zoom ratio achieved by the camera device, and the android.scaler.cropRegion adjusts for additional crops that are not zoom related. Otherwise, if the application sets android.control.zoomRatio to 1.0, or does not set it at all, the android.control.zoomRatio tag in the result metadata will also be 1.0.

When the application requests a physical stream for a logical multi-camera, the android.control.zoomRatio in the physical camera result metadata will be 1.0, and the android.scaler.cropRegion tag reflects the amount of zoom and crop done by the physical camera device.

For all capture request templates, this field must be set to 1.0 in order to have consistent field of views between different modes.

This must be set to TRUE by the camera2 java fwk when the camera client sets android.control.afRegions.

This must be set to TRUE by the camera2 java fwk when the camera client sets android.control.aeRegions.

This must be set to TRUE by the camera2 java fwk when the camera client sets android.control.awbRegions.

There are some CaptureRequest keys which can be applied earlier than others when controls within a CaptureRequest aren't required to take effect at the same time. One such example is zoom. Zoom can be applied at a later stage of the camera pipeline. As soon as the camera device receives the CaptureRequest, it can apply the requested zoom value onto an earlier request that's already in the pipeline, thus improves zoom latency.

This key's value in the capture result reflects whether the controls for this capture are overridden "by" a newer request. This means that if a capture request turns on settings override, the capture result of an earlier request will contain the key value of ZOOM. On the other hand, if a capture request has settings override turned on, but all newer requests have it turned off, the key's value in the capture result will be OFF because this capture isn't overridden by a newer capture. In the two examples below, the capture results columns illustrate the settingsOverride values in different scenarios.

Assuming the zoom settings override can speed up by 1 frame, below example illustrates the speed-up at the start of capture session:

Camera session created
Request 1 (zoom=1.0x, override=ZOOM) ->
Request 2 (zoom=1.2x, override=ZOOM) ->
Request 3 (zoom=1.4x, override=ZOOM) ->  Result 1 (zoom=1.2x, override=ZOOM)
Request 4 (zoom=1.6x, override=ZOOM) ->  Result 2 (zoom=1.4x, override=ZOOM)
Request 5 (zoom=1.8x, override=ZOOM) ->  Result 3 (zoom=1.6x, override=ZOOM)
                                     ->  Result 4 (zoom=1.8x, override=ZOOM)
                                     ->  Result 5 (zoom=1.8x, override=OFF)

The application can turn on settings override and use zoom as normal. The example shows that the later zoom values (1.2x, 1.4x, 1.6x, and 1.8x) overwrite the zoom values (1.0x, 1.2x, 1.4x, and 1.8x) of earlier requests (#1, #2, #3, and #4).

The application must make sure the settings override doesn't interfere with user journeys requiring simultaneous application of all controls in CaptureRequest on the requested output targets. For example, if the application takes a still capture using CameraCaptureSession#capture, and the repeating request immediately sets a different zoom value using override, the inflight still capture could have its zoom value overwritten unexpectedly.

So the application is strongly recommended to turn off settingsOverride when taking still/burst captures, and turn it back on when there is only repeating viewfinder request and no inflight still/burst captures.

Below is the example demonstrating the transitions in and out of the settings override:

Request 1 (zoom=1.0x, override=OFF)
Request 2 (zoom=1.2x, override=OFF)
Request 3 (zoom=1.4x, override=ZOOM)  -> Result 1 (zoom=1.0x, override=OFF)
Request 4 (zoom=1.6x, override=ZOOM)  -> Result 2 (zoom=1.4x, override=ZOOM)
Request 5 (zoom=1.8x, override=OFF)   -> Result 3 (zoom=1.6x, override=ZOOM)
                                      -> Result 4 (zoom=1.6x, override=OFF)
                                      -> Result 5 (zoom=1.8x, override=OFF)

This example shows that:

• The application "ramps in" settings override by setting the control to ZOOM. In the example, request #3 enables zoom settings override. Because the camera device can speed up applying zoom by 1 frame, the outputs of request #2 has 1.4x zoom, the value specified in request #3.
• The application "ramps out" of settings override by setting the control to OFF. In the example, request #5 changes the override to OFF. Because request #4's zoom takes effect in result #3, result #4's zoom remains the same until new value takes effect in result #5.

The HAL must set this value to OFF in all of the Capture templates.

Typically the HAL unblocks processCaptureRequest at the same rate as the sensor capture, and the HAL queues the capture settings in its pipeline when processCaptureRequest returns. However, when the settings override is enabled, the HAL can optimize the overridden controls' latency by applying them as soon as processCaptureRequest is called, rather than when it's unblocked.

For devices launching with API level 35 or newer, to avoid regression on zoom smoothness, when zoom settings override is on during pinch zoom (zoom value gradually changes), the zoom effect in the camera output must not become more jittery. More specifically, the variation of zoom pipeline latency must not increase. The latency improvement must be at least 1 frame regardless of zoom in or zoom out.

For devices launched before API level 35, if zoom settings override is on, when zooming in, the HAL must be able to apply the zoom related settings at least 1 frame ahead.

Auto-framing is a special mode provided by the camera device to dynamically crop, zoom or pan the camera feed to try to ensure that the people in a scene occupy a reasonable portion of the viewport. It is primarily designed to support video calling in situations where the user isn't directly in front of the device, especially for wide-angle cameras. android.scaler.cropRegion and android.control.zoomRatio in CaptureResult will be used to denote the coordinates of the auto-framed region. Zoom and video stabilization controls are disabled when auto-framing is enabled. The 3A regions must map the screen coordinates into the scaler crop returned from the capture result instead of using the active array sensor.

While auto-framing is ON, the aspect ratio of the auto-framed region must match the aspect ratio of the configured output stream. When reporting CaptureResult, SCALER_CROP_REGION might not adequately describe the actual sensor pixels. In this case, it is acceptable for the returned parameters to only be an approximation of the image sensor region that is actually used. When auto-framing is turned off, the transition should be immediate, with no panning or zooming to transition to the settings requested by the app. When it is turned on, the transition can be immediate or smooth.

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 with the android.control.aeAntibandingMode control.

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 android.control.aeMode for this camera device.

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.

For devices at the LEGACY level or above:

• For constant-framerate recording, for each normal CamcorderProfile, that is, a CamcorderProfile that has quality in the range [QUALITY_LOW, QUALITY_2160P], if the profile is supported by the device and has videoFrameRate x, this list will always include (x,x).

• Also, a camera device must either not support any CamcorderProfile, or support at least one normal CamcorderProfile that has videoFrameRate x >= 24.

For devices at the LIMITED level or above:

• For devices that advertise NIR color filter arrangement in android.sensor.info.colorFilterArrangement, this list will always include (max, max) where max = the maximum output frame rate of the maximum YUV_420_888 output size.
• For devices advertising any color filter arrangement other than NIR, or devices not advertising color filter arrangement, this list will always include (min, max) and (max, max) where min <= 15 and max = the maximum output frame rate of the maximum YUV_420_888 output size.

HAL must make sure the lower bound and upper bound of each supported targetFpsRange can be reached. For example, if HAL supports an aeTargetFpsRange of (15, 30), when set by the application, the camera must be able to reach 15fps in sufficient dark scenes. This way the application knows the exact range of frame rate it can expect.

This is the unit for android.control.aeExposureCompensation. For example, if this key has a value of 1/2, then a setting of -2 for 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.

This must be less than or equal to 1/2.

Not all the auto-focus modes may be supported by a given camera device. This entry lists the valid modes for android.control.afMode for this camera device.

All LIMITED and FULL mode camera devices will support OFF mode, and all camera devices with adjustable focuser units (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 android.lens.focusDistance to 0.0f).

This list contains the color effect modes that can be applied to 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 will only list OFF.

A color effect will only be applied if 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.

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. Otherwise DISABLED will not be listed.

FACE_PRIORITY is always listed if face detection is supported (i.e.android.statistics.info.maxFaceCount > 0).

OFF will always be listed.

Not all the auto-white-balance modes may be supported by a given camera device. This entry lists the valid modes for android.control.awbMode for this camera device.

All camera devices will support ON mode.

Camera devices that support the MANUAL_POST_PROCESSING capability will always support OFF mode, which enables application control of white balance, by using android.colorCorrection.transform and android.colorCorrection.gains(android.colorCorrection.mode must be set to TRANSFORM_MATRIX). This includes all FULL mode camera devices.

This corresponds to the maximum allowed number of elements in android.control.aeRegions.

This entry is private to the framework. Fill in maxRegions to have this entry be automatically populated.

This corresponds to the maximum allowed number of elements in android.control.awbRegions.

This entry is private to the framework. Fill in maxRegions to have this entry be automatically populated.

This corresponds to the maximum allowed number of elements in android.control.afRegions.

This entry is private to the framework. Fill in maxRegions to have this entry be automatically populated.

When a scene mode is enabled, the camera device is expected to override android.control.aeMode, android.control.awbMode, and android.control.afMode with its preferred settings for that scene mode.

The order of this list matches that of availableSceneModes, with 3 entries for each mode. The overrides listed for FACE_PRIORITY and FACE_PRIORITY_LOW_LIGHT (if supported) are ignored, since for that mode the application-set android.control.aeMode, android.control.awbMode, and android.control.afMode values are used instead, matching the behavior when android.control.mode is set to AUTO. It is recommended that the FACE_PRIORITY and FACE_PRIORITY_LOW_LIGHT (if supported) overrides should be set to 0.

For example, if availableSceneModes contains (FACE_PRIORITY, ACTION, NIGHT), then the camera framework expects sceneModeOverrides to have 9 entries formatted like: (0, 0, 0, ON_AUTO_FLASH, AUTO, CONTINUOUS_PICTURE, ON_AUTO_FLASH, INCANDESCENT, AUTO).

To maintain backward compatibility, this list will be made available in the static metadata of the camera service. The camera service will use these values to set android.control.aeMode, android.control.awbMode, and android.control.afMode when using a scene mode other than FACE_PRIORITY and FACE_PRIORITY_LOW_LIGHT (if supported).

When CONSTRAINED_HIGH_SPEED_VIDEO is supported in android.request.availableCapabilities, this metadata will list the supported high speed video size, fps range and max batch size configurations. All the sizes listed in this configuration will be a subset of the sizes reported by StreamConfigurationMap#getOutputSizes for processed non-stalling formats.

For the high speed video use case, the application must select the video size and fps range from this metadata to configure the recording and preview streams and setup the recording requests. For example, if the application intends to do high speed recording, it can select the maximum size reported by this metadata to configure output streams. Once the size is selected, application can filter this metadata by selected size and get the supported fps ranges, and use these fps ranges to setup the recording requests. Note that for the use case of multiple output streams, application must select one unique size from this metadata to use (e.g., preview and recording streams must have the same size). Otherwise, the high speed capture session creation will fail.

The min and max fps will be multiple times of 30fps.

High speed video streaming extends significant performance pressure to camera hardware, to achieve efficient high speed streaming, the camera device may have to aggregate multiple frames together and send to camera device for processing where the request controls are same for all the frames in this batch. Max batch size indicates the max possible number of frames the camera device will group together for this high speed stream configuration. This max batch size will be used to generate a high speed recording request list by CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList. The max batch size for each configuration will satisfy below conditions:

• Each max batch size will be a divisor of its corresponding fps_max / 30. For example, if max_fps is 300, max batch size will only be 1, 2, 5, or 10.
• The camera device may choose smaller internal batch size for each configuration, but the actual batch size will be a divisor of max batch size. For example, if the max batch size is 8, the actual batch size used by camera device will only be 1, 2, 4, or 8.
• The max batch size in each configuration entry must be no larger than 32.

The camera device doesn't have to support batch mode to achieve high speed video recording, in such case, batch_size_max will be reported as 1 in each configuration entry.

This fps ranges in this configuration list can only be used to create requests that are submitted to a high speed camera capture session created by CameraDevice#createConstrainedHighSpeedCaptureSession. The fps ranges reported in this metadata must not be used to setup capture requests for normal capture session, or it will cause request error.

All the sizes listed in this configuration will be a subset of the sizes reported by android.scaler.availableStreamConfigurations for processed non-stalling output formats. Note that for all high speed video configurations, HAL must be able to support a minimum of two streams, though the application might choose to configure just one stream.

The HAL may support multiple sensor modes for high speed outputs, for example, 120fps sensor mode and 120fps recording, 240fps sensor mode for 240fps recording. The application usually starts preview first, then starts recording. To avoid sensor mode switch caused stutter when starting recording as much as possible, the application may want to ensure the same sensor mode is used for preview and recording. Therefore, The HAL must advertise the variable fps range [30, fps_max] for each fixed fps range in this configuration list. For example, if the HAL advertises [120, 120] and [240, 240], the HAL must also advertise [30, 120] and [30, 240] for each configuration. In doing so, if the application intends to do 120fps recording, it can select [30, 120] to start preview, and [120, 120] to start recording. For these variable fps ranges, it's up to the HAL to decide the actual fps values that are suitable for smooth preview streaming. If the HAL sees different max_fps values that fall into different sensor modes in a sequence of requests, the HAL must switch the sensor mode as quick as possible to minimize the mode switch caused stutter.

HAL can also support 60fps preview during high speed recording session by advertising [60, max_fps] for preview and [max_fps, max_fps] for recording. However, HAL must not advertise both 30fps preview and 60fps preview for the same recording frame rate.

Starting from AIDL ICameraDevice V2, camera HAL must report the valid batch_size_max. The field will actually be used to generate a high speed recording request list.