From 9393a69a5fe3b54e741e3ec161bc1159bd25f8cf Mon Sep 17 00:00:00 2001 From: Shuzhen Wang Date: Mon, 28 Mar 2022 13:05:29 -0700 Subject: [PATCH] Camera: Improve documentation for 3A regions Clarify that 3A regions need to consider additional crop for preview stream due to aspect ratio mismatch. Test: Build Bug: 226939029 Change-Id: I660e83bb4aae088dc231827bd9a075879c573538 --- .../hardware/camera2/CaptureRequest.java | 24 +++++++++++++++++++ .../hardware/camera2/CaptureResult.java | 24 +++++++++++++++++++ 2 files changed, 48 insertions(+) diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java index 5df64e3cca9ec..b25c24d3e6807 100644 --- a/core/java/android/hardware/camera2/CaptureRequest.java +++ b/core/java/android/hardware/camera2/CaptureRequest.java @@ -1382,6 +1382,14 @@ public final class CaptureRequest extends CameraMetadata> * 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 + * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}. For example, if the {@link CaptureRequest#SCALER_CROP_REGION 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 @@ -1604,6 +1612,14 @@ public final class CaptureRequest extends CameraMetadata> * 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 + * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}. For example, if the {@link CaptureRequest#SCALER_CROP_REGION 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 @@ -1818,6 +1834,14 @@ public final class CaptureRequest extends CameraMetadata> * 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 + * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}. For example, if the {@link CaptureRequest#SCALER_CROP_REGION 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 diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java index 60d5e9eba3e05..1faec5b76524c 100644 --- a/core/java/android/hardware/camera2/CaptureResult.java +++ b/core/java/android/hardware/camera2/CaptureResult.java @@ -829,6 +829,14 @@ public class CaptureResult extends CameraMetadata> { * 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 + * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}. For example, if the {@link CaptureRequest#SCALER_CROP_REGION 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 @@ -1301,6 +1309,14 @@ public class CaptureResult extends CameraMetadata> { * 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 + * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}. For example, if the {@link CaptureRequest#SCALER_CROP_REGION 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 @@ -1926,6 +1942,14 @@ public class CaptureResult extends CameraMetadata> { * 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 + * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}. For example, if the {@link CaptureRequest#SCALER_CROP_REGION 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