Merge "Camera: Improve documentation for 3A regions" into tm-dev am: 98dbbf702f

Original change: https://googleplex-android-review.googlesource.com/c/platform/system/media/+/17453434

Change-Id: If31845f4f0473f5aaa41af9826a1541f8dd8ab0e
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>

2 files changed, 75 insertions, 0 deletions

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 933e0d86..9b58f62e 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -2849,6 +2849,14 @@ capture result metadata,<wbr/> the camera device will ignore the sections outsid
 region and output only the intersection rectangle as the metering region in the result
 metadata.<wbr/>  If the region is entirely outside the crop region,<wbr/> it will be ignored and
 not reported in the result metadata.<wbr/></p>
+<p>When setting the AE metering regions,<wbr/> the application must consider the additional
+crop resulted from the aspect ratio differences between the preview stream and
+<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a>.<wbr/> For example,<wbr/> if the <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> is the full
+active array size with 4:3 aspect ratio,<wbr/> and the preview stream is 16:9,<wbr/>
+the boundary of AE regions will be [0,<wbr/> y_<wbr/>crop] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height - 2 * y_<wbr/>crop] rather than [0,<wbr/> 0] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height],<wbr/> where y_<wbr/>crop is the additional crop due to aspect ratio
+mismatch.<wbr/></p>
 <p>Starting from API level 30,<wbr/> the coordinate system of activeArraySize or
 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view,<wbr/> not
 pre-zoom field of view.<wbr/> This means that the same aeRegions values at different
@@ -3348,6 +3356,14 @@ capture result metadata,<wbr/> the camera device will ignore the sections outsid
 region and output only the intersection rectangle as the metering region in the result
 metadata.<wbr/> If the region is entirely outside the crop region,<wbr/> it will be ignored and
 not reported in the result metadata.<wbr/></p>
+<p>When setting the AF metering regions,<wbr/> the application must consider the additional
+crop resulted from the aspect ratio differences between the preview stream and
+<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a>.<wbr/> For example,<wbr/> if the <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> is the full
+active array size with 4:3 aspect ratio,<wbr/> and the preview stream is 16:9,<wbr/>
+the boundary of AF regions will be [0,<wbr/> y_<wbr/>crop] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height - 2 * y_<wbr/>crop] rather than [0,<wbr/> 0] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height],<wbr/> where y_<wbr/>crop is the additional crop due to aspect ratio
+mismatch.<wbr/></p>
 <p>Starting from API level 30,<wbr/> the coordinate system of activeArraySize or
 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view,<wbr/> not
 pre-zoom field of view.<wbr/> This means that the same afRegions values at different
@@ -3844,6 +3860,14 @@ capture result metadata,<wbr/> the camera device will ignore the sections outsid
 region and output only the intersection rectangle as the metering region in the result
 metadata.<wbr/>  If the region is entirely outside the crop region,<wbr/> it will be ignored and
 not reported in the result metadata.<wbr/></p>
+<p>When setting the AWB metering regions,<wbr/> the application must consider the additional
+crop resulted from the aspect ratio differences between the preview stream and
+<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a>.<wbr/> For example,<wbr/> if the <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> is the full
+active array size with 4:3 aspect ratio,<wbr/> and the preview stream is 16:9,<wbr/>
+the boundary of AWB regions will be [0,<wbr/> y_<wbr/>crop] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height - 2 * y_<wbr/>crop] rather than [0,<wbr/> 0] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height],<wbr/> where y_<wbr/>crop is the additional crop due to aspect ratio
+mismatch.<wbr/></p>
 <p>Starting from API level 30,<wbr/> the coordinate system of activeArraySize or
 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view,<wbr/> not
 pre-zoom field of view.<wbr/> This means that the same awbRegions values at different
@@ -7702,6 +7726,14 @@ capture result metadata,<wbr/> the camera device will ignore the sections outsid
 region and output only the intersection rectangle as the metering region in the result
 metadata.<wbr/>  If the region is entirely outside the crop region,<wbr/> it will be ignored and
 not reported in the result metadata.<wbr/></p>
+<p>When setting the AE metering regions,<wbr/> the application must consider the additional
+crop resulted from the aspect ratio differences between the preview stream and
+<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a>.<wbr/> For example,<wbr/> if the <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> is the full
+active array size with 4:3 aspect ratio,<wbr/> and the preview stream is 16:9,<wbr/>
+the boundary of AE regions will be [0,<wbr/> y_<wbr/>crop] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height - 2 * y_<wbr/>crop] rather than [0,<wbr/> 0] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height],<wbr/> where y_<wbr/>crop is the additional crop due to aspect ratio
+mismatch.<wbr/></p>
 <p>Starting from API level 30,<wbr/> the coordinate system of activeArraySize or
 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view,<wbr/> not
 pre-zoom field of view.<wbr/> This means that the same aeRegions values at different
@@ -8508,6 +8540,14 @@ capture result metadata,<wbr/> the camera device will ignore the sections outsid
 region and output only the intersection rectangle as the metering region in the result
 metadata.<wbr/> If the region is entirely outside the crop region,<wbr/> it will be ignored and
 not reported in the result metadata.<wbr/></p>
+<p>When setting the AF metering regions,<wbr/> the application must consider the additional
+crop resulted from the aspect ratio differences between the preview stream and
+<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a>.<wbr/> For example,<wbr/> if the <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> is the full
+active array size with 4:3 aspect ratio,<wbr/> and the preview stream is 16:9,<wbr/>
+the boundary of AF regions will be [0,<wbr/> y_<wbr/>crop] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height - 2 * y_<wbr/>crop] rather than [0,<wbr/> 0] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height],<wbr/> where y_<wbr/>crop is the additional crop due to aspect ratio
+mismatch.<wbr/></p>
 <p>Starting from API level 30,<wbr/> the coordinate system of activeArraySize or
 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view,<wbr/> not
 pre-zoom field of view.<wbr/> This means that the same afRegions values at different
@@ -9550,6 +9590,14 @@ capture result metadata,<wbr/> the camera device will ignore the sections outsid
 region and output only the intersection rectangle as the metering region in the result
 metadata.<wbr/>  If the region is entirely outside the crop region,<wbr/> it will be ignored and
 not reported in the result metadata.<wbr/></p>
+<p>When setting the AWB metering regions,<wbr/> the application must consider the additional
+crop resulted from the aspect ratio differences between the preview stream and
+<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a>.<wbr/> For example,<wbr/> if the <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> is the full
+active array size with 4:3 aspect ratio,<wbr/> and the preview stream is 16:9,<wbr/>
+the boundary of AWB regions will be [0,<wbr/> y_<wbr/>crop] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height - 2 * y_<wbr/>crop] rather than [0,<wbr/> 0] and
+[active_<wbr/>width,<wbr/> active_<wbr/>height],<wbr/> where y_<wbr/>crop is the additional crop due to aspect ratio
+mismatch.<wbr/></p>
 <p>Starting from API level 30,<wbr/> the coordinate system of activeArraySize or
 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view,<wbr/> not
 pre-zoom field of view.<wbr/> This means that the same awbRegions values at different
diff --git a/camera/docs/metadata_definitions.xml b/camera/docs/metadata_definitions.xml
index 7f93b4a6..ecc439a3 100644
--- a/camera/docs/metadata_definitions.xml
+++ b/camera/docs/metadata_definitions.xml
@@ -762,6 +762,15 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               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
@@ -1087,6 +1096,15 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               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
@@ -1435,6 +1453,15 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               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