From 83acb78ab6591dbca2cc49405b55ceed5a0382b9 Mon Sep 17 00:00:00 2001 From: Bharatt Kukreja Date: Fri, 2 Sep 2022 22:34:29 +0000 Subject: [PATCH] Camera: Add request settings Override API The new API can be used to speed up applying certain capture request settings. Auto-generated files from changes in metadata_definitions.xml Bug: 239822823 Test: Successful build Change-Id: Idaf38603582e6ce78252d55edb39d56b02b248bb --- core/api/current.txt | 5 ++ .../camera2/CameraCharacteristics.java | 24 ++++++ .../hardware/camera2/CameraMetadata.java | 43 ++++++++++ .../hardware/camera2/CaptureRequest.java | 84 +++++++++++++++++++ .../hardware/camera2/CaptureResult.java | 84 +++++++++++++++++++ 5 files changed, 240 insertions(+) diff --git a/core/api/current.txt b/core/api/current.txt index 18d8fc72a40d8..102deb6659d23 100644 --- a/core/api/current.txt +++ b/core/api/current.txt @@ -17593,6 +17593,7 @@ package android.hardware.camera2 { field @NonNull public static final android.hardware.camera2.CameraCharacteristics.Key CONTROL_AVAILABLE_EXTENDED_SCENE_MODE_CAPABILITIES; field @NonNull public static final android.hardware.camera2.CameraCharacteristics.Key CONTROL_AVAILABLE_MODES; field @NonNull public static final android.hardware.camera2.CameraCharacteristics.Key CONTROL_AVAILABLE_SCENE_MODES; + field @NonNull public static final android.hardware.camera2.CameraCharacteristics.Key CONTROL_AVAILABLE_SETTINGS_OVERRIDES; field @NonNull public static final android.hardware.camera2.CameraCharacteristics.Key CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES; field @NonNull public static final android.hardware.camera2.CameraCharacteristics.Key CONTROL_AWB_AVAILABLE_MODES; field @NonNull public static final android.hardware.camera2.CameraCharacteristics.Key CONTROL_AWB_LOCK_AVAILABLE; @@ -17947,6 +17948,8 @@ package android.hardware.camera2 { field public static final int CONTROL_SCENE_MODE_STEADYPHOTO = 11; // 0xb field public static final int CONTROL_SCENE_MODE_SUNSET = 10; // 0xa field public static final int CONTROL_SCENE_MODE_THEATRE = 7; // 0x7 + field public static final int CONTROL_SETTINGS_OVERRIDE_OFF = 0; // 0x0 + field public static final int CONTROL_SETTINGS_OVERRIDE_ZOOM = 1; // 0x1 field public static final int CONTROL_VIDEO_STABILIZATION_MODE_OFF = 0; // 0x0 field public static final int CONTROL_VIDEO_STABILIZATION_MODE_ON = 1; // 0x1 field public static final int CONTROL_VIDEO_STABILIZATION_MODE_PREVIEW_STABILIZATION = 2; // 0x2 @@ -18145,6 +18148,7 @@ package android.hardware.camera2 { field @NonNull public static final android.hardware.camera2.CaptureRequest.Key CONTROL_MODE; field @NonNull public static final android.hardware.camera2.CaptureRequest.Key CONTROL_POST_RAW_SENSITIVITY_BOOST; field @NonNull public static final android.hardware.camera2.CaptureRequest.Key CONTROL_SCENE_MODE; + field @NonNull public static final android.hardware.camera2.CaptureRequest.Key CONTROL_SETTINGS_OVERRIDE; field @NonNull public static final android.hardware.camera2.CaptureRequest.Key CONTROL_VIDEO_STABILIZATION_MODE; field @NonNull public static final android.hardware.camera2.CaptureRequest.Key CONTROL_ZOOM_RATIO; field @NonNull public static final android.os.Parcelable.Creator CREATOR; @@ -18235,6 +18239,7 @@ package android.hardware.camera2 { field @NonNull public static final android.hardware.camera2.CaptureResult.Key CONTROL_MODE; field @NonNull public static final android.hardware.camera2.CaptureResult.Key CONTROL_POST_RAW_SENSITIVITY_BOOST; field @NonNull public static final android.hardware.camera2.CaptureResult.Key CONTROL_SCENE_MODE; + field @NonNull public static final android.hardware.camera2.CaptureResult.Key CONTROL_SETTINGS_OVERRIDE; field @NonNull public static final android.hardware.camera2.CaptureResult.Key CONTROL_VIDEO_STABILIZATION_MODE; field @NonNull public static final android.hardware.camera2.CaptureResult.Key CONTROL_ZOOM_RATIO; field @NonNull public static final android.hardware.camera2.CaptureResult.Key DISTORTION_CORRECTION_MODE; diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java index f63472680bb03..d3cb59dbb034c 100644 --- a/core/java/android/hardware/camera2/CameraCharacteristics.java +++ b/core/java/android/hardware/camera2/CameraCharacteristics.java @@ -1285,6 +1285,30 @@ public final class CameraCharacteristics extends CameraMetadata CONTROL_AVAILABLE_HIGH_SPEED_VIDEO_CONFIGURATIONS_MAXIMUM_RESOLUTION = new Key("android.control.availableHighSpeedVideoConfigurationsMaximumResolution", android.hardware.camera2.params.HighSpeedVideoConfiguration[].class); + /** + *

List of available settings overrides supported by the camera device that can + * be used to speed up certain controls.

+ *

When not all controls within a CaptureRequest are required to take effect + * at the same time on the outputs, the camera device may apply certain request keys sooner + * to improve latency. This list contains such supported settings overrides. Each settings + * override corresponds to a set of CaptureRequest keys that can be sped up when applying.

+ *

A supported settings override can be passed in via + * {@link android.hardware.camera2.CaptureRequest#CONTROL_SETTINGS_OVERRIDE }, and the + * CaptureRequest keys corresponding to the override are applied as soon as possible, not + * bound by per-frame synchronization. See {@link CaptureRequest#CONTROL_SETTINGS_OVERRIDE android.control.settingsOverride} for the + * CaptureRequest keys for each override.

+ *

OFF is always included in this list.

+ *

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

+ *

Optional - The value for this key may be {@code null} on some devices.

+ * + * @see CaptureRequest#CONTROL_SETTINGS_OVERRIDE + */ + @PublicKey + @NonNull + public static final Key CONTROL_AVAILABLE_SETTINGS_OVERRIDES = + new Key("android.control.availableSettingsOverrides", int[].class); + /** *

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

diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java index 1e1d443687134..545aa8f2e80dd 100644 --- a/core/java/android/hardware/camera2/CameraMetadata.java +++ b/core/java/android/hardware/camera2/CameraMetadata.java @@ -3200,6 +3200,49 @@ public abstract class CameraMetadata { */ public static final int CONTROL_EXTENDED_SCENE_MODE_VENDOR_START = 0x40; + // + // Enumeration values for CaptureRequest#CONTROL_SETTINGS_OVERRIDE + // + + /** + *

No keys are applied sooner than the other keys when applying CaptureRequest + * settings to the camera device. This is the default value.

+ * @see CaptureRequest#CONTROL_SETTINGS_OVERRIDE + */ + public static final int CONTROL_SETTINGS_OVERRIDE_OFF = 0; + + /** + *

Zoom related keys are applied sooner than the other keys in the CaptureRequest. The + * zoom related keys are:

+ *
    + *
  • {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio}
    • + *
  • {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}
    • + *
  • {@link CaptureRequest#CONTROL_AE_REGIONS android.control.aeRegions}
    • + *
  • {@link CaptureRequest#CONTROL_AWB_REGIONS android.control.awbRegions}
    • + *
  • {@link CaptureRequest#CONTROL_AF_REGIONS android.control.afRegions}
    • + *
+ *

Even though {@link CaptureRequest#CONTROL_AE_REGIONS android.control.aeRegions}, {@link CaptureRequest#CONTROL_AWB_REGIONS android.control.awbRegions}, + * and {@link CaptureRequest#CONTROL_AF_REGIONS android.control.afRegions} are not directly zoom related, applications + * typically scale these regions together with {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to have a + * consistent mapping within the current field of view. In this aspect, they are + * related to {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} and {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio}.

+ * + * @see CaptureRequest#CONTROL_AE_REGIONS + * @see CaptureRequest#CONTROL_AF_REGIONS + * @see CaptureRequest#CONTROL_AWB_REGIONS + * @see CaptureRequest#CONTROL_ZOOM_RATIO + * @see CaptureRequest#SCALER_CROP_REGION + * @see CaptureRequest#CONTROL_SETTINGS_OVERRIDE + */ + public static final int CONTROL_SETTINGS_OVERRIDE_ZOOM = 1; + + /** + *

Vendor defined settingsOverride. These depend on vendor implementation.

+ * @see CaptureRequest#CONTROL_SETTINGS_OVERRIDE + * @hide + */ + public static final int CONTROL_SETTINGS_OVERRIDE_VENDOR_START = 0x4000; + // // Enumeration values for CaptureRequest#EDGE_MODE // diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java index c5cf0f695040e..407ea07838de2 100644 --- a/core/java/android/hardware/camera2/CaptureRequest.java +++ b/core/java/android/hardware/camera2/CaptureRequest.java @@ -2428,6 +2428,90 @@ public final class CaptureRequest extends CameraMetadata> public static final Key CONTROL_AWB_REGIONS_SET = new Key("android.control.awbRegionsSet", boolean.class); + /** + *

The desired CaptureRequest settings override with which certain keys are + * applied earlier so that they can take effect sooner.

+ *

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

Possible values:

+ *
    + *
  • {@link #CONTROL_SETTINGS_OVERRIDE_OFF OFF}
    • + *
  • {@link #CONTROL_SETTINGS_OVERRIDE_ZOOM ZOOM}
    • + *
+ * + *

Available values for this device:
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_SETTINGS_OVERRIDES android.control.availableSettingsOverrides}

+ *

Optional - The value for this key may be {@code null} on some devices.

+ *

Limited capability - + * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the + * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key

+ * + * @see CameraCharacteristics#CONTROL_AVAILABLE_SETTINGS_OVERRIDES + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL + * @see #CONTROL_SETTINGS_OVERRIDE_OFF + * @see #CONTROL_SETTINGS_OVERRIDE_ZOOM + */ + @PublicKey + @NonNull + public static final Key CONTROL_SETTINGS_OVERRIDE = + new Key("android.control.settingsOverride", int.class); + /** *

Operation mode for edge * enhancement.

diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java index 1a15596af5667..c4f0cabc5f788 100644 --- a/core/java/android/hardware/camera2/CaptureResult.java +++ b/core/java/android/hardware/camera2/CaptureResult.java @@ -2632,6 +2632,90 @@ public class CaptureResult extends CameraMetadata> { public static final Key CONTROL_ZOOM_RATIO = new Key("android.control.zoomRatio", float.class); + /** + *

The desired CaptureRequest settings override with which certain keys are + * applied earlier so that they can take effect sooner.

+ *

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

Possible values:

+ *
    + *
  • {@link #CONTROL_SETTINGS_OVERRIDE_OFF OFF}
    • + *
  • {@link #CONTROL_SETTINGS_OVERRIDE_ZOOM ZOOM}
    • + *
+ * + *

Available values for this device:
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_SETTINGS_OVERRIDES android.control.availableSettingsOverrides}

+ *

Optional - The value for this key may be {@code null} on some devices.

+ *

Limited capability - + * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the + * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key

+ * + * @see CameraCharacteristics#CONTROL_AVAILABLE_SETTINGS_OVERRIDES + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL + * @see #CONTROL_SETTINGS_OVERRIDE_OFF + * @see #CONTROL_SETTINGS_OVERRIDE_ZOOM + */ + @PublicKey + @NonNull + public static final Key CONTROL_SETTINGS_OVERRIDE = + new Key("android.control.settingsOverride", int.class); + /** *

Operation mode for edge * enhancement.