Camera: update coordinate semantics w.r.t. distortion correction
Also fix a NDK doucment error on semantics of face rectangle.
Test: Compile
Bug: 109666939
Change-Id: I79c48d3a24b3dccb49720d9bcd0fdce978602139
diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 36a6967..9387ad7 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -2606,12 +2606,15 @@
</td>
<td class="entry_units">
- Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
+ Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size or
+ android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size depending on
+ distortion correction capability and mode
</td>
<td class="entry_range">
<p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> or <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>
+depending on distortion correction capability and mode</p>
</td>
<td class="entry_hal_version">
@@ -2634,11 +2637,26 @@
Otherwise will always be present.<wbr/></p>
<p>The maximum number of regions supported by the device is determined by the value
of <a href="#static_android.control.maxRegionsAe">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Ae</a>.<wbr/></p>
-<p>The coordinate system is based on the active pixel array,<wbr/>
-with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
+<p>For devices not supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system always follows that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with (0,<wbr/>0) being
+the top-left pixel in the active pixel array,<wbr/> and
(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the
-bottom-right pixel in the active pixel array.<wbr/></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
+<p>For devices supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system depends on the mode being set.<wbr/>
+When the distortion correction mode is OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the pre-correction active array,<wbr/> and
+(<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right
+pixel in the pre-correction active pixel array.<wbr/>
+When the distortion correction mode is not OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the active array,<wbr/> and
+(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
<p>The weight must be within <code>[0,<wbr/> 1000]</code>,<wbr/> and represents a weight
for every pixel in the area.<wbr/> This means that a large metering area
with the same weight as a smaller area will have more effect in
@@ -2667,7 +2685,9 @@
Every five elements represent a metering region of
(xmin,<wbr/> ymin,<wbr/> xmax,<wbr/> ymax,<wbr/> weight).<wbr/>
The rectangle is defined to be inclusive on xmin and ymin,<wbr/> but
-exclusive on xmax and ymax.<wbr/></p>
+exclusive on xmax and ymax.<wbr/>
+HAL must always report metering regions in the coordinate system of pre-correction
+active array.<wbr/></p>
</td>
</tr>
@@ -3067,12 +3087,15 @@
</td>
<td class="entry_units">
- Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
+ Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size or
+ android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size depending on
+ distortion correction capability and mode
</td>
<td class="entry_range">
<p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> or <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>
+depending on distortion correction capability and mode</p>
</td>
<td class="entry_hal_version">
@@ -3095,11 +3118,26 @@
Otherwise will always be present.<wbr/></p>
<p>The maximum number of focus areas supported by the device is determined by the value
of <a href="#static_android.control.maxRegionsAf">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Af</a>.<wbr/></p>
-<p>The coordinate system is based on the active pixel array,<wbr/>
-with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
+<p>For devices not supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system always follows that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with (0,<wbr/>0) being
+the top-left pixel in the active pixel array,<wbr/> and
(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the
-bottom-right pixel in the active pixel array.<wbr/></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
+<p>For devices supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system depends on the mode being set.<wbr/>
+When the distortion correction mode is OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the pre-correction active array,<wbr/> and
+(<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right
+pixel in the pre-correction active pixel array.<wbr/>
+When the distortion correction mode is not OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the active array,<wbr/> and
+(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
<p>The weight must be within <code>[0,<wbr/> 1000]</code>,<wbr/> and represents a weight
for every pixel in the area.<wbr/> This means that a large metering area
with the same weight as a smaller area will have more effect in
@@ -3129,7 +3167,9 @@
Every five elements represent a metering region of
(xmin,<wbr/> ymin,<wbr/> xmax,<wbr/> ymax,<wbr/> weight).<wbr/>
The rectangle is defined to be inclusive on xmin and ymin,<wbr/> but
-exclusive on xmax and ymax.<wbr/></p>
+exclusive on xmax and ymax.<wbr/>
+HAL must always report metering regions in the coordinate system of pre-correction
+active array.<wbr/></p>
</td>
</tr>
@@ -3528,12 +3568,15 @@
</td>
<td class="entry_units">
- Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
+ Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size or
+ android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size depending on
+ distortion correction capability and mode
</td>
<td class="entry_range">
<p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> or <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>
+depending on distortion correction capability and mode</p>
</td>
<td class="entry_hal_version">
@@ -3556,11 +3599,26 @@
Otherwise will always be present.<wbr/></p>
<p>The maximum number of regions supported by the device is determined by the value
of <a href="#static_android.control.maxRegionsAwb">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Awb</a>.<wbr/></p>
-<p>The coordinate system is based on the active pixel array,<wbr/>
-with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
+<p>For devices not supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system always follows that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with (0,<wbr/>0) being
+the top-left pixel in the active pixel array,<wbr/> and
(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the
-bottom-right pixel in the active pixel array.<wbr/></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
+<p>For devices supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system depends on the mode being set.<wbr/>
+When the distortion correction mode is OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the pre-correction active array,<wbr/> and
+(<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right
+pixel in the pre-correction active pixel array.<wbr/>
+When the distortion correction mode is not OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the active array,<wbr/> and
+(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
<p>The weight must range from 0 to 1000,<wbr/> and represents a weight
for every pixel in the area.<wbr/> This means that a large metering area
with the same weight as a smaller area will have more effect in
@@ -3589,7 +3647,9 @@
Every five elements represent a metering region of
(xmin,<wbr/> ymin,<wbr/> xmax,<wbr/> ymax,<wbr/> weight).<wbr/>
The rectangle is defined to be inclusive on xmin and ymin,<wbr/> but
-exclusive on xmax and ymax.<wbr/></p>
+exclusive on xmax and ymax.<wbr/>
+HAL must always report metering regions in the coordinate system of pre-correction
+active array.<wbr/></p>
</td>
</tr>
@@ -6505,12 +6565,15 @@
</td>
<td class="entry_units">
- Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
+ Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size or
+ android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size depending on
+ distortion correction capability and mode
</td>
<td class="entry_range">
<p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> or <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>
+depending on distortion correction capability and mode</p>
</td>
<td class="entry_hal_version">
@@ -6533,11 +6596,26 @@
Otherwise will always be present.<wbr/></p>
<p>The maximum number of regions supported by the device is determined by the value
of <a href="#static_android.control.maxRegionsAe">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Ae</a>.<wbr/></p>
-<p>The coordinate system is based on the active pixel array,<wbr/>
-with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
+<p>For devices not supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system always follows that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with (0,<wbr/>0) being
+the top-left pixel in the active pixel array,<wbr/> and
(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the
-bottom-right pixel in the active pixel array.<wbr/></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
+<p>For devices supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system depends on the mode being set.<wbr/>
+When the distortion correction mode is OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the pre-correction active array,<wbr/> and
+(<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right
+pixel in the pre-correction active pixel array.<wbr/>
+When the distortion correction mode is not OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the active array,<wbr/> and
+(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
<p>The weight must be within <code>[0,<wbr/> 1000]</code>,<wbr/> and represents a weight
for every pixel in the area.<wbr/> This means that a large metering area
with the same weight as a smaller area will have more effect in
@@ -6566,7 +6644,9 @@
Every five elements represent a metering region of
(xmin,<wbr/> ymin,<wbr/> xmax,<wbr/> ymax,<wbr/> weight).<wbr/>
The rectangle is defined to be inclusive on xmin and ymin,<wbr/> but
-exclusive on xmax and ymax.<wbr/></p>
+exclusive on xmax and ymax.<wbr/>
+HAL must always report metering regions in the coordinate system of pre-correction
+active array.<wbr/></p>
</td>
</tr>
@@ -7273,12 +7353,15 @@
</td>
<td class="entry_units">
- Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
+ Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size or
+ android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size depending on
+ distortion correction capability and mode
</td>
<td class="entry_range">
<p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> or <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>
+depending on distortion correction capability and mode</p>
</td>
<td class="entry_hal_version">
@@ -7301,11 +7384,26 @@
Otherwise will always be present.<wbr/></p>
<p>The maximum number of focus areas supported by the device is determined by the value
of <a href="#static_android.control.maxRegionsAf">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Af</a>.<wbr/></p>
-<p>The coordinate system is based on the active pixel array,<wbr/>
-with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
+<p>For devices not supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system always follows that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with (0,<wbr/>0) being
+the top-left pixel in the active pixel array,<wbr/> and
(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the
-bottom-right pixel in the active pixel array.<wbr/></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
+<p>For devices supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system depends on the mode being set.<wbr/>
+When the distortion correction mode is OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the pre-correction active array,<wbr/> and
+(<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right
+pixel in the pre-correction active pixel array.<wbr/>
+When the distortion correction mode is not OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the active array,<wbr/> and
+(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
<p>The weight must be within <code>[0,<wbr/> 1000]</code>,<wbr/> and represents a weight
for every pixel in the area.<wbr/> This means that a large metering area
with the same weight as a smaller area will have more effect in
@@ -7335,7 +7433,9 @@
Every five elements represent a metering region of
(xmin,<wbr/> ymin,<wbr/> xmax,<wbr/> ymax,<wbr/> weight).<wbr/>
The rectangle is defined to be inclusive on xmin and ymin,<wbr/> but
-exclusive on xmax and ymax.<wbr/></p>
+exclusive on xmax and ymax.<wbr/>
+HAL must always report metering regions in the coordinate system of pre-correction
+active array.<wbr/></p>
</td>
</tr>
@@ -8280,12 +8380,15 @@
</td>
<td class="entry_units">
- Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
+ Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size or
+ android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size depending on
+ distortion correction capability and mode
</td>
<td class="entry_range">
<p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> or <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>
+depending on distortion correction capability and mode</p>
</td>
<td class="entry_hal_version">
@@ -8308,11 +8411,26 @@
Otherwise will always be present.<wbr/></p>
<p>The maximum number of regions supported by the device is determined by the value
of <a href="#static_android.control.maxRegionsAwb">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Awb</a>.<wbr/></p>
-<p>The coordinate system is based on the active pixel array,<wbr/>
-with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
+<p>For devices not supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system always follows that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with (0,<wbr/>0) being
+the top-left pixel in the active pixel array,<wbr/> and
(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the
-bottom-right pixel in the active pixel array.<wbr/></p>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
+<p>For devices supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system depends on the mode being set.<wbr/>
+When the distortion correction mode is OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the pre-correction active array,<wbr/> and
+(<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right
+pixel in the pre-correction active pixel array.<wbr/>
+When the distortion correction mode is not OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the active array,<wbr/> and
+(<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the bottom-right pixel in the
+active pixel array.<wbr/></p>
<p>The weight must range from 0 to 1000,<wbr/> and represents a weight
for every pixel in the area.<wbr/> This means that a large metering area
with the same weight as a smaller area will have more effect in
@@ -8341,7 +8459,9 @@
Every five elements represent a metering region of
(xmin,<wbr/> ymin,<wbr/> xmax,<wbr/> ymax,<wbr/> weight).<wbr/>
The rectangle is defined to be inclusive on xmin and ymin,<wbr/> but
-exclusive on xmax and ymax.<wbr/></p>
+exclusive on xmax and ymax.<wbr/>
+HAL must always report metering regions in the coordinate system of pre-correction
+active array.<wbr/></p>
</td>
</tr>
@@ -11680,9 +11800,9 @@
<tr class="entry_cont">
<td class="entry_details" colspan="6">
<p>The HAL must not squeeze or stretch the downscaled primary image to generate thumbnail.<wbr/>
-The cropping must be done on the primary jpeg image rather than the sensor active array.<wbr/>
-The stream cropping rule specified by "S5.<wbr/> Cropping" in camera3.<wbr/>h doesn't apply to the
-thumbnail image cropping.<wbr/></p>
+The cropping must be done on the primary jpeg image rather than the sensor pre-correction
+active array.<wbr/> The stream cropping rule specified by "S5.<wbr/> Cropping" in camera3.<wbr/>h doesn't
+apply to the thumbnail image cropping.<wbr/></p>
</td>
</tr>
@@ -12397,9 +12517,9 @@
<tr class="entry_cont">
<td class="entry_details" colspan="6">
<p>The HAL must not squeeze or stretch the downscaled primary image to generate thumbnail.<wbr/>
-The cropping must be done on the primary jpeg image rather than the sensor active array.<wbr/>
-The stream cropping rule specified by "S5.<wbr/> Cropping" in camera3.<wbr/>h doesn't apply to the
-thumbnail image cropping.<wbr/></p>
+The cropping must be done on the primary jpeg image rather than the sensor pre-correction
+active array.<wbr/> The stream cropping rule specified by "S5.<wbr/> Cropping" in camera3.<wbr/>h doesn't
+apply to the thumbnail image cropping.<wbr/></p>
</td>
</tr>
@@ -18083,7 +18203,9 @@
<td class="entry_units">
Pixel coordinates relative to
- android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
+ android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size or
+ android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size depending on distortion correction
+ capability and mode
</td>
<td class="entry_range">
@@ -18106,9 +18228,17 @@
<tr class="entry_cont">
<td class="entry_details" colspan="6">
<p>This control can be used to implement digital zoom.<wbr/></p>
-<p>The crop region coordinate system is based off
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with <code>(0,<wbr/> 0)</code> being the
-top-left corner of the sensor active array.<wbr/></p>
+<p>For devices not supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system always follows that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with <code>(0,<wbr/> 0)</code> being
+the top-left pixel of the active array.<wbr/></p>
+<p>For devices supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system depends on the mode being set.<wbr/>
+When the distortion correction mode is OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the pre-correction active array.<wbr/>
+When the distortion correction mode is not OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the active array.<wbr/></p>
<p>Output streams use this rectangle to produce their output,<wbr/>
cropping to a smaller region if necessary to maintain the
stream's aspect ratio,<wbr/> then scaling the sensor input to
@@ -18127,10 +18257,16 @@
outputs will crop horizontally (pillarbox),<wbr/> and 16:9
streams will match exactly.<wbr/> These additional crops will
be centered within the crop region.<wbr/></p>
-<p>The width and height of the crop region cannot
-be set to be smaller than
+<p>If the coordinate system is android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Arrays<wbr/>Size,<wbr/> the width and height
+of the crop region cannot be set to be smaller than
<code>floor( activeArraySize.<wbr/>width /<wbr/> <a href="#static_android.scaler.availableMaxDigitalZoom">android.<wbr/>scaler.<wbr/>available<wbr/>Max<wbr/>Digital<wbr/>Zoom</a> )</code> and
<code>floor( activeArraySize.<wbr/>height /<wbr/> <a href="#static_android.scaler.availableMaxDigitalZoom">android.<wbr/>scaler.<wbr/>available<wbr/>Max<wbr/>Digital<wbr/>Zoom</a> )</code>,<wbr/> respectively.<wbr/></p>
+<p>If the coordinate system is <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> the width
+and height of the crop region cannot be set to be smaller than
+<code>floor( preCorrectionActiveArraySize.<wbr/>width /<wbr/> <a href="#static_android.scaler.availableMaxDigitalZoom">android.<wbr/>scaler.<wbr/>available<wbr/>Max<wbr/>Digital<wbr/>Zoom</a> )</code>
+and
+<code>floor( preCorrectionActiveArraySize.<wbr/>height /<wbr/> <a href="#static_android.scaler.availableMaxDigitalZoom">android.<wbr/>scaler.<wbr/>available<wbr/>Max<wbr/>Digital<wbr/>Zoom</a> )</code>,<wbr/>
+respectively.<wbr/></p>
<p>The camera device may adjust the crop region to account
for rounding and other hardware requirements; the final
crop region used will be included in the output capture
@@ -18152,34 +18288,35 @@
for raw output,<wbr/> where only a few fixed scales may be
possible.<wbr/></p>
<p>For a set of output streams configured,<wbr/> if the sensor output is cropped to a smaller
-size than active array size,<wbr/> the HAL need follow below cropping rules:</p>
+size than pre-correction active array size,<wbr/> the HAL need follow below cropping rules:</p>
<ul>
<li>
-<p>The HAL need handle the cropRegion as if the sensor crop size is the effective active
-array size.<wbr/>More specifically,<wbr/> the HAL must transform the request cropRegion from
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> to the sensor cropped pixel area size in this way:</p>
+<p>The HAL need handle the cropRegion as if the sensor crop size is the effective
+pre-correction active array size.<wbr/> More specifically,<wbr/> the HAL must transform the request
+cropRegion from <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a> to the sensor cropped
+pixel area size in this way:</p>
<ol>
<li>Translate the requested cropRegion w.<wbr/>r.<wbr/>t.,<wbr/> the left top corner of the sensor
cropped pixel area by (tx,<wbr/> ty),<wbr/>
-where <code>ty = sensorCrop.<wbr/>top * (sensorCrop.<wbr/>height /<wbr/> activeArraySize.<wbr/>height)</code>
-and <code>tx = sensorCrop.<wbr/>left * (sensorCrop.<wbr/>width /<wbr/> activeArraySize.<wbr/>width)</code>.<wbr/> The
-(sensorCrop.<wbr/>top,<wbr/> sensorCrop.<wbr/>left) is the coordinate based off the
+where <code>ty = sensorCrop.<wbr/>top * (sensorCrop.<wbr/>height /<wbr/> preCorrectionActiveArraySize.<wbr/>height)</code>
+and <code>tx = sensorCrop.<wbr/>left * (sensorCrop.<wbr/>width /<wbr/> preCorrectionActiveArraySize.<wbr/>width)</code>.<wbr/>
+The (sensorCrop.<wbr/>top,<wbr/> sensorCrop.<wbr/>left) is the coordinate based off the
<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/></li>
<li>Scale the width and height of requested cropRegion with scaling factor of
-sensor<wbr/>Crop.<wbr/>width/<wbr/>active<wbr/>Array<wbr/>Size.<wbr/>width and sensor<wbr/>Crop.<wbr/>height/<wbr/>active<wbr/>Array<wbr/>Size.<wbr/>height
+sensor<wbr/>Crop.<wbr/>width/<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size.<wbr/>width and sensor<wbr/>Crop.<wbr/>height/<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size.<wbr/>height
respectively.<wbr/>
Once this new cropRegion is calculated,<wbr/> the HAL must use this region to crop the image
-with regard to the sensor crop size (effective active array size).<wbr/> The HAL still need
-follow the general cropping rule for this new cropRegion and effective active
-array size.<wbr/></li>
+with regard to the sensor crop size (effective pre-correction active array size).<wbr/> The
+HAL still need follow the general cropping rule for this new cropRegion and effective
+pre-correction active array size.<wbr/></li>
</ol>
</li>
<li>
-<p>The HAL must report the cropRegion with regard to <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>
-The HAL need convert the new cropRegion generated above w.<wbr/>r.<wbr/>t.,<wbr/> full active array size.<wbr/>
-The reported cropRegion may be slightly different with the requested cropRegion since
-the HAL may adjust the crop region to account for rounding,<wbr/> conversion error,<wbr/> or other
-hardware limitations.<wbr/></p>
+<p>The HAL must report the cropRegion with regard to <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>
+The HAL need convert the new cropRegion generated above w.<wbr/>r.<wbr/>t.,<wbr/> full pre-correction
+active array size.<wbr/> The reported cropRegion may be slightly different with the requested
+cropRegion since the HAL may adjust the crop region to account for rounding,<wbr/> conversion
+error,<wbr/> or other hardware limitations.<wbr/></p>
</li>
</ul>
<p>HAL2.<wbr/>x uses only (x,<wbr/> y,<wbr/> width)</p>
@@ -19683,7 +19820,9 @@
<td class="entry_units">
Pixel coordinates relative to
- android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
+ android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size or
+ android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size depending on distortion correction
+ capability and mode
</td>
<td class="entry_range">
@@ -19706,9 +19845,17 @@
<tr class="entry_cont">
<td class="entry_details" colspan="6">
<p>This control can be used to implement digital zoom.<wbr/></p>
-<p>The crop region coordinate system is based off
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with <code>(0,<wbr/> 0)</code> being the
-top-left corner of the sensor active array.<wbr/></p>
+<p>For devices not supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system always follows that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with <code>(0,<wbr/> 0)</code> being
+the top-left pixel of the active array.<wbr/></p>
+<p>For devices supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system depends on the mode being set.<wbr/>
+When the distortion correction mode is OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the pre-correction active array.<wbr/>
+When the distortion correction mode is not OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the active array.<wbr/></p>
<p>Output streams use this rectangle to produce their output,<wbr/>
cropping to a smaller region if necessary to maintain the
stream's aspect ratio,<wbr/> then scaling the sensor input to
@@ -19727,10 +19874,16 @@
outputs will crop horizontally (pillarbox),<wbr/> and 16:9
streams will match exactly.<wbr/> These additional crops will
be centered within the crop region.<wbr/></p>
-<p>The width and height of the crop region cannot
-be set to be smaller than
+<p>If the coordinate system is android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Arrays<wbr/>Size,<wbr/> the width and height
+of the crop region cannot be set to be smaller than
<code>floor( activeArraySize.<wbr/>width /<wbr/> <a href="#static_android.scaler.availableMaxDigitalZoom">android.<wbr/>scaler.<wbr/>available<wbr/>Max<wbr/>Digital<wbr/>Zoom</a> )</code> and
<code>floor( activeArraySize.<wbr/>height /<wbr/> <a href="#static_android.scaler.availableMaxDigitalZoom">android.<wbr/>scaler.<wbr/>available<wbr/>Max<wbr/>Digital<wbr/>Zoom</a> )</code>,<wbr/> respectively.<wbr/></p>
+<p>If the coordinate system is <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> the width
+and height of the crop region cannot be set to be smaller than
+<code>floor( preCorrectionActiveArraySize.<wbr/>width /<wbr/> <a href="#static_android.scaler.availableMaxDigitalZoom">android.<wbr/>scaler.<wbr/>available<wbr/>Max<wbr/>Digital<wbr/>Zoom</a> )</code>
+and
+<code>floor( preCorrectionActiveArraySize.<wbr/>height /<wbr/> <a href="#static_android.scaler.availableMaxDigitalZoom">android.<wbr/>scaler.<wbr/>available<wbr/>Max<wbr/>Digital<wbr/>Zoom</a> )</code>,<wbr/>
+respectively.<wbr/></p>
<p>The camera device may adjust the crop region to account
for rounding and other hardware requirements; the final
crop region used will be included in the output capture
@@ -19752,34 +19905,35 @@
for raw output,<wbr/> where only a few fixed scales may be
possible.<wbr/></p>
<p>For a set of output streams configured,<wbr/> if the sensor output is cropped to a smaller
-size than active array size,<wbr/> the HAL need follow below cropping rules:</p>
+size than pre-correction active array size,<wbr/> the HAL need follow below cropping rules:</p>
<ul>
<li>
-<p>The HAL need handle the cropRegion as if the sensor crop size is the effective active
-array size.<wbr/>More specifically,<wbr/> the HAL must transform the request cropRegion from
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> to the sensor cropped pixel area size in this way:</p>
+<p>The HAL need handle the cropRegion as if the sensor crop size is the effective
+pre-correction active array size.<wbr/> More specifically,<wbr/> the HAL must transform the request
+cropRegion from <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a> to the sensor cropped
+pixel area size in this way:</p>
<ol>
<li>Translate the requested cropRegion w.<wbr/>r.<wbr/>t.,<wbr/> the left top corner of the sensor
cropped pixel area by (tx,<wbr/> ty),<wbr/>
-where <code>ty = sensorCrop.<wbr/>top * (sensorCrop.<wbr/>height /<wbr/> activeArraySize.<wbr/>height)</code>
-and <code>tx = sensorCrop.<wbr/>left * (sensorCrop.<wbr/>width /<wbr/> activeArraySize.<wbr/>width)</code>.<wbr/> The
-(sensorCrop.<wbr/>top,<wbr/> sensorCrop.<wbr/>left) is the coordinate based off the
+where <code>ty = sensorCrop.<wbr/>top * (sensorCrop.<wbr/>height /<wbr/> preCorrectionActiveArraySize.<wbr/>height)</code>
+and <code>tx = sensorCrop.<wbr/>left * (sensorCrop.<wbr/>width /<wbr/> preCorrectionActiveArraySize.<wbr/>width)</code>.<wbr/>
+The (sensorCrop.<wbr/>top,<wbr/> sensorCrop.<wbr/>left) is the coordinate based off the
<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/></li>
<li>Scale the width and height of requested cropRegion with scaling factor of
-sensor<wbr/>Crop.<wbr/>width/<wbr/>active<wbr/>Array<wbr/>Size.<wbr/>width and sensor<wbr/>Crop.<wbr/>height/<wbr/>active<wbr/>Array<wbr/>Size.<wbr/>height
+sensor<wbr/>Crop.<wbr/>width/<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size.<wbr/>width and sensor<wbr/>Crop.<wbr/>height/<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size.<wbr/>height
respectively.<wbr/>
Once this new cropRegion is calculated,<wbr/> the HAL must use this region to crop the image
-with regard to the sensor crop size (effective active array size).<wbr/> The HAL still need
-follow the general cropping rule for this new cropRegion and effective active
-array size.<wbr/></li>
+with regard to the sensor crop size (effective pre-correction active array size).<wbr/> The
+HAL still need follow the general cropping rule for this new cropRegion and effective
+pre-correction active array size.<wbr/></li>
</ol>
</li>
<li>
-<p>The HAL must report the cropRegion with regard to <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>
-The HAL need convert the new cropRegion generated above w.<wbr/>r.<wbr/>t.,<wbr/> full active array size.<wbr/>
-The reported cropRegion may be slightly different with the requested cropRegion since
-the HAL may adjust the crop region to account for rounding,<wbr/> conversion error,<wbr/> or other
-hardware limitations.<wbr/></p>
+<p>The HAL must report the cropRegion with regard to <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/>
+The HAL need convert the new cropRegion generated above w.<wbr/>r.<wbr/>t.,<wbr/> full pre-correction
+active array size.<wbr/> The reported cropRegion may be slightly different with the requested
+cropRegion since the HAL may adjust the crop region to account for rounding,<wbr/> conversion
+error,<wbr/> or other hardware limitations.<wbr/></p>
</li>
</ul>
<p>HAL2.<wbr/>x uses only (x,<wbr/> y,<wbr/> width)</p>
@@ -20401,8 +20555,18 @@
<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a>,<wbr/> is defined relative to the active array rectangle given in
this field,<wbr/> with <code>(0,<wbr/> 0)</code> being the top-left of this rectangle.<wbr/></p>
<p>The active array may be smaller than the full pixel array,<wbr/> since the full array may
-include black calibration pixels or other inactive regions,<wbr/> and geometric correction
-resulting in scaling or cropping may have been applied.<wbr/></p>
+include black calibration pixels or other inactive regions.<wbr/></p>
+<p>For devices that do not support <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the active
+array must be the same as <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/></p>
+<p>For devices that support <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the active array must
+be enclosed by <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/> The difference between
+pre-correction active array and active array accounts for scaling or cropping caused
+by lens geometric distortion correction.<wbr/></p>
+<p>In general,<wbr/> application should always refer to active array size for controls like
+metering regions or crop region.<wbr/> Two exceptions are when the application is dealing with
+RAW image buffers (RAW_<wbr/>SENSOR,<wbr/> RAW10,<wbr/> RAW12 etc),<wbr/> or when application explicitly set
+<a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> to OFF.<wbr/> In these cases,<wbr/> application should refer
+to <a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/></p>
</td>
</tr>
@@ -21157,9 +21321,9 @@
<ol>
<li><a href="#static_android.lens.distortion">android.<wbr/>lens.<wbr/>distortion</a>.<wbr/></li>
</ol>
-<p>If all of the geometric distortion fields are no-ops,<wbr/> this rectangle will be the same
-as the post-distortion-corrected rectangle given in
-<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/></p>
+<p>If the camera device doesn't support geometric distortion correction,<wbr/> or all of the
+geometric distortion fields are no-ops,<wbr/> this rectangle will be the same as the
+post-distortion-corrected rectangle given in <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/></p>
<p>This rectangle is defined relative to the full pixel array; (0,<wbr/>0) is the top-left of
the full pixel array,<wbr/> and the size of the full pixel array is given by
<a href="#static_android.sensor.info.pixelArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pixel<wbr/>Array<wbr/>Size</a>.<wbr/></p>
@@ -25090,7 +25254,7 @@
<tr class="entry" id="dynamic_android.statistics.faceLandmarks">
<td class="entry_name
- " rowspan="3">
+ " rowspan="5">
android.<wbr/>statistics.<wbr/>face<wbr/>Landmarks
</td>
<td class="entry_type">
@@ -25138,12 +25302,30 @@
</tr>
<tr class="entry_cont">
<td class="entry_details" colspan="6">
- <p>The coordinate system is that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+ <p>For devices not supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system always follows that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with <code>(0,<wbr/> 0)</code> being
+the top-left pixel of the active array.<wbr/></p>
+<p>For devices supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system depends on the mode being set.<wbr/>
+When the distortion correction mode is OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the pre-correction active array.<wbr/>
+When the distortion correction mode is not OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
<code>(0,<wbr/> 0)</code> being the top-left pixel of the active array.<wbr/></p>
<p>Only available if <a href="#controls_android.statistics.faceDetectMode">android.<wbr/>statistics.<wbr/>face<wbr/>Detect<wbr/>Mode</a> == FULL</p>
</td>
</tr>
+ <tr class="entries_header">
+ <th class="th_details" colspan="6">HAL Implementation Details</th>
+ </tr>
+ <tr class="entry_cont">
+ <td class="entry_details" colspan="6">
+ <p>HAL must always report face landmarks in the coordinate system of pre-correction
+active array.<wbr/></p>
+ </td>
+ </tr>
<tr class="entry_spacer"><td class="entry_spacer" colspan="7"></td></tr>
<!-- end of entry -->
@@ -25151,7 +25333,7 @@
<tr class="entry" id="dynamic_android.statistics.faceRectangles">
<td class="entry_name
- " rowspan="3">
+ " rowspan="5">
android.<wbr/>statistics.<wbr/>face<wbr/>Rectangles
</td>
<td class="entry_type">
@@ -25199,12 +25381,30 @@
</tr>
<tr class="entry_cont">
<td class="entry_details" colspan="6">
- <p>The coordinate system is that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+ <p>For devices not supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system always follows that of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with <code>(0,<wbr/> 0)</code> being
+the top-left pixel of the active array.<wbr/></p>
+<p>For devices supporting <a href="#controls_android.distortionCorrection.mode">android.<wbr/>distortion<wbr/>Correction.<wbr/>mode</a> control,<wbr/> the coordinate
+system depends on the mode being set.<wbr/>
+When the distortion correction mode is OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>,<wbr/> with
+<code>(0,<wbr/> 0)</code> being the top-left pixel of the pre-correction active array.<wbr/>
+When the distortion correction mode is not OFF,<wbr/> the coordinate system follows
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with
<code>(0,<wbr/> 0)</code> being the top-left pixel of the active array.<wbr/></p>
<p>Only available if <a href="#controls_android.statistics.faceDetectMode">android.<wbr/>statistics.<wbr/>face<wbr/>Detect<wbr/>Mode</a> != OFF</p>
</td>
</tr>
+ <tr class="entries_header">
+ <th class="th_details" colspan="6">HAL Implementation Details</th>
+ </tr>
+ <tr class="entry_cont">
+ <td class="entry_details" colspan="6">
+ <p>HAL must always report face rectangles in the coordinate system of pre-correction
+active array.<wbr/></p>
+ </td>
+ </tr>
<tr class="entry_spacer"><td class="entry_spacer" colspan="7"></td></tr>
<!-- end of entry -->
@@ -29956,15 +30156,14 @@
any correction at all would slow down capture rate.<wbr/> Every output stream will have a
similar amount of enhancement applied.<wbr/></p>
<p>The correction only applies to processed outputs such as YUV,<wbr/> JPEG,<wbr/> or DEPTH16; it is not
-applied to any RAW output.<wbr/> Metadata coordinates such as face rectangles or metering
+applied to any RAW output.<wbr/> Metadata coordinates such as face rectangles or metering
regions are also not affected by correction.<wbr/></p>
-<p>Applications enabling distortion correction need to pay extra attention when converting
-image coordinates between corrected output buffers and the sensor array.<wbr/> For example,<wbr/> if
-the app supports tap-to-focus and enables correction,<wbr/> it then has to apply the distortion
-model described in <a href="#static_android.lens.distortion">android.<wbr/>lens.<wbr/>distortion</a> to the image buffer tap coordinates to properly
-calculate the tap position on the sensor active array to be used with
-<a href="#controls_android.control.afRegions">android.<wbr/>control.<wbr/>af<wbr/>Regions</a>.<wbr/> The same applies in reverse to detected face rectangles if
-they need to be drawn on top of the corrected output buffers.<wbr/></p>
+<p>This control will be on by default on devices that support this control.<wbr/> Applications
+disabling distortion correction need to pay extra attention with the coordinate system of
+metering regions,<wbr/> crop region,<wbr/> and face rectangles.<wbr/> When distortion correction is OFF,<wbr/>
+metadata coordinates follow the coordinate system of
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/> When distortion is not OFF,<wbr/> metadata
+coordinates follow the coordinate system of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/></p>
</td>
</tr>
@@ -30170,15 +30369,14 @@
any correction at all would slow down capture rate.<wbr/> Every output stream will have a
similar amount of enhancement applied.<wbr/></p>
<p>The correction only applies to processed outputs such as YUV,<wbr/> JPEG,<wbr/> or DEPTH16; it is not
-applied to any RAW output.<wbr/> Metadata coordinates such as face rectangles or metering
+applied to any RAW output.<wbr/> Metadata coordinates such as face rectangles or metering
regions are also not affected by correction.<wbr/></p>
-<p>Applications enabling distortion correction need to pay extra attention when converting
-image coordinates between corrected output buffers and the sensor array.<wbr/> For example,<wbr/> if
-the app supports tap-to-focus and enables correction,<wbr/> it then has to apply the distortion
-model described in <a href="#static_android.lens.distortion">android.<wbr/>lens.<wbr/>distortion</a> to the image buffer tap coordinates to properly
-calculate the tap position on the sensor active array to be used with
-<a href="#controls_android.control.afRegions">android.<wbr/>control.<wbr/>af<wbr/>Regions</a>.<wbr/> The same applies in reverse to detected face rectangles if
-they need to be drawn on top of the corrected output buffers.<wbr/></p>
+<p>This control will be on by default on devices that support this control.<wbr/> Applications
+disabling distortion correction need to pay extra attention with the coordinate system of
+metering regions,<wbr/> crop region,<wbr/> and face rectangles.<wbr/> When distortion correction is OFF,<wbr/>
+metadata coordinates follow the coordinate system of
+<a href="#static_android.sensor.info.preCorrectionActiveArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pre<wbr/>Correction<wbr/>Active<wbr/>Array<wbr/>Size</a>.<wbr/> When distortion is not OFF,<wbr/> metadata
+coordinates follow the coordinate system of <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/></p>
</td>
</tr>
diff --git a/camera/docs/metadata_definitions.xml b/camera/docs/metadata_definitions.xml
index 6059fa0..e288c57 100644
--- a/camera/docs/metadata_definitions.xml
+++ b/camera/docs/metadata_definitions.xml
@@ -686,9 +686,12 @@
<size>area_count</size>
</array>
<description>List of metering areas to use for auto-exposure adjustment.</description>
- <units>Pixel coordinates within android.sensor.info.activeArraySize</units>
+ <units>Pixel coordinates within android.sensor.info.activeArraySize or
+ android.sensor.info.preCorrectionActiveArraySize depending on
+ distortion correction capability and mode</units>
<range>Coordinates must be between `[(0,0), (width, height))` of
- android.sensor.info.activeArraySize</range>
+ android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize
+ depending on distortion correction capability and mode</range>
<details>
Not available if android.control.maxRegionsAe is 0.
Otherwise will always be present.
@@ -696,11 +699,27 @@
The maximum number of regions supported by the device is determined by the value
of android.control.maxRegionsAe.
- The coordinate system is based on the active pixel array,
- with (0,0) being the top-left pixel in the active pixel array, and
+ 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.
+ 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
@@ -734,6 +753,8 @@
(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.
</hal_details>
<tag id="BC" />
</entry>
@@ -969,9 +990,12 @@
<size>area_count</size>
</array>
<description>List of metering areas to use for auto-focus.</description>
- <units>Pixel coordinates within android.sensor.info.activeArraySize</units>
+ <units>Pixel coordinates within android.sensor.info.activeArraySize or
+ android.sensor.info.preCorrectionActiveArraySize depending on
+ distortion correction capability and mode</units>
<range>Coordinates must be between `[(0,0), (width, height))` of
- android.sensor.info.activeArraySize</range>
+ android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize
+ depending on distortion correction capability and mode</range>
<details>
Not available if android.control.maxRegionsAf is 0.
Otherwise will always be present.
@@ -979,11 +1003,28 @@
The maximum number of focus areas supported by the device is determined by the value
of android.control.maxRegionsAf.
- The coordinate system is based on the active pixel array,
- with (0,0) being the top-left pixel in the active pixel array, and
+
+ 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.
+ 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
@@ -1018,6 +1059,8 @@
(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.
</hal_details>
<tag id="BC" />
</entry>
@@ -1279,9 +1322,12 @@
</array>
<description>List of metering areas to use for auto-white-balance illuminant
estimation.</description>
- <units>Pixel coordinates within android.sensor.info.activeArraySize</units>
+ <units>Pixel coordinates within android.sensor.info.activeArraySize or
+ android.sensor.info.preCorrectionActiveArraySize depending on
+ distortion correction capability and mode</units>
<range>Coordinates must be between `[(0,0), (width, height))` of
- android.sensor.info.activeArraySize</range>
+ android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize
+ depending on distortion correction capability and mode</range>
<details>
Not available if android.control.maxRegionsAwb is 0.
Otherwise will always be present.
@@ -1289,11 +1335,27 @@
The maximum number of regions supported by the device is determined by the value
of android.control.maxRegionsAwb.
- The coordinate system is based on the active pixel array,
- with (0,0) being the top-left pixel in the active pixel array, and
+ 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.
+ 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
@@ -1327,6 +1389,8 @@
(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.
</hal_details>
<tag id="BC" />
</entry>
@@ -3410,9 +3474,9 @@
</details>
<hal_details>
The HAL must not squeeze or stretch the downscaled primary image to generate thumbnail.
- The cropping must be done on the primary jpeg image rather than the sensor active array.
- The stream cropping rule specified by "S5. Cropping" in camera3.h doesn't apply to the
- thumbnail image cropping.
+ The cropping must be done on the primary jpeg image rather than the sensor pre-correction
+ active array. The stream cropping rule specified by "S5. Cropping" in camera3.h doesn't
+ apply to the thumbnail image cropping.
</hal_details>
<tag id="BC" />
</entry>
@@ -5577,13 +5641,24 @@
</array>
<description>The desired region of the sensor to read out for this capture.</description>
<units>Pixel coordinates relative to
- android.sensor.info.activeArraySize</units>
+ android.sensor.info.activeArraySize or
+ android.sensor.info.preCorrectionActiveArraySize depending on distortion correction
+ capability and mode</units>
<details>
This control can be used to implement digital zoom.
- The crop region coordinate system is based off
- android.sensor.info.activeArraySize, with `(0, 0)` being the
- top-left corner of the sensor active array.
+ 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 of the active 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.
+ 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.
Output streams use this rectangle to produce their output,
cropping to a smaller region if necessary to maintain the
@@ -5608,11 +5683,18 @@
streams will match exactly. These additional crops will
be centered within the crop region.
- The width and height of the crop region cannot
- be set to be smaller than
+ If the coordinate system is android.sensor.info.activeArraysSize, the width and height
+ of the crop region cannot be set to be smaller than
`floor( activeArraySize.width / android.scaler.availableMaxDigitalZoom )` and
`floor( activeArraySize.height / android.scaler.availableMaxDigitalZoom )`, respectively.
+ If the coordinate system is android.sensor.info.preCorrectionActiveArraySize, the width
+ and height of the crop region cannot be set to be smaller than
+ `floor( preCorrectionActiveArraySize.width / android.scaler.availableMaxDigitalZoom )`
+ and
+ `floor( preCorrectionActiveArraySize.height / android.scaler.availableMaxDigitalZoom )`,
+ respectively.
+
The camera device may adjust the crop region to account
for rounding and other hardware requirements; the final
crop region used will be included in the output capture
@@ -5632,30 +5714,31 @@
possible.
For a set of output streams configured, if the sensor output is cropped to a smaller
- size than active array size, the HAL need follow below cropping rules:
+ size than pre-correction active array size, the HAL need follow below cropping rules:
- * The HAL need handle the cropRegion as if the sensor crop size is the effective active
- array size.More specifically, the HAL must transform the request cropRegion from
- android.sensor.info.activeArraySize to the sensor cropped pixel area size in this way:
+ * The HAL need handle the cropRegion as if the sensor crop size is the effective
+ pre-correction active array size. More specifically, the HAL must transform the request
+ cropRegion from android.sensor.info.preCorrectionActiveArraySize to the sensor cropped
+ pixel area size in this way:
1. Translate the requested cropRegion w.r.t., the left top corner of the sensor
cropped pixel area by (tx, ty),
- where `ty = sensorCrop.top * (sensorCrop.height / activeArraySize.height)`
- and `tx = sensorCrop.left * (sensorCrop.width / activeArraySize.width)`. The
- (sensorCrop.top, sensorCrop.left) is the coordinate based off the
+ where `ty = sensorCrop.top * (sensorCrop.height / preCorrectionActiveArraySize.height)`
+ and `tx = sensorCrop.left * (sensorCrop.width / preCorrectionActiveArraySize.width)`.
+ The (sensorCrop.top, sensorCrop.left) is the coordinate based off the
android.sensor.info.activeArraySize.
2. Scale the width and height of requested cropRegion with scaling factor of
- sensorCrop.width/activeArraySize.width and sensorCrop.height/activeArraySize.height
+ sensorCrop.width/preCorrectionActiveArraySize.width and sensorCrop.height/preCorrectionActiveArraySize.height
respectively.
Once this new cropRegion is calculated, the HAL must use this region to crop the image
- with regard to the sensor crop size (effective active array size). The HAL still need
- follow the general cropping rule for this new cropRegion and effective active
- array size.
+ with regard to the sensor crop size (effective pre-correction active array size). The
+ HAL still need follow the general cropping rule for this new cropRegion and effective
+ pre-correction active array size.
- * The HAL must report the cropRegion with regard to android.sensor.info.activeArraySize.
- The HAL need convert the new cropRegion generated above w.r.t., full active array size.
- The reported cropRegion may be slightly different with the requested cropRegion since
- the HAL may adjust the crop region to account for rounding, conversion error, or other
- hardware limitations.
+ * The HAL must report the cropRegion with regard to android.sensor.info.preCorrectionActiveArraySize.
+ The HAL need convert the new cropRegion generated above w.r.t., full pre-correction
+ active array size. The reported cropRegion may be slightly different with the requested
+ cropRegion since the HAL may adjust the crop region to account for rounding, conversion
+ error, or other hardware limitations.
HAL2.x uses only (x, y, width)
</hal_details>
@@ -6517,8 +6600,21 @@
this field, with `(0, 0)` being the top-left of this rectangle.
The active array may be smaller than the full pixel array, since the full array may
- include black calibration pixels or other inactive regions, and geometric correction
- resulting in scaling or cropping may have been applied.
+ include black calibration pixels or other inactive regions.
+
+ For devices that do not support android.distortionCorrection.mode control, the active
+ array must be the same as android.sensor.info.preCorrectionActiveArraySize.
+
+ For devices that support android.distortionCorrection.mode control, the active array must
+ be enclosed by android.sensor.info.preCorrectionActiveArraySize. The difference between
+ pre-correction active array and active array accounts for scaling or cropping caused
+ by lens geometric distortion correction.
+
+ In general, application should always refer to active array size for controls like
+ metering regions or crop region. Two exceptions are when the application is dealing with
+ RAW image buffers (RAW_SENSOR, RAW10, RAW12 etc), or when application explicitly set
+ android.distortionCorrection.mode to OFF. In these cases, application should refer
+ to android.sensor.info.preCorrectionActiveArraySize.
</details>
<ndk_details>
The data representation is `int[4]`, which maps to `(left, top, width, height)`.
@@ -6810,9 +6906,9 @@
1. android.lens.distortion.
- If all of the geometric distortion fields are no-ops, this rectangle will be the same
- as the post-distortion-corrected rectangle given in
- android.sensor.info.activeArraySize.
+ If the camera device doesn't support geometric distortion correction, or all of the
+ geometric distortion fields are no-ops, this rectangle will be the same as the
+ post-distortion-corrected rectangle given in android.sensor.info.activeArraySize.
This rectangle is defined relative to the full pixel array; (0,0) is the top-left of
the full pixel array, and the size of the full pixel array is given by
@@ -8063,10 +8159,24 @@
<description>List of landmarks for detected
faces.</description>
<details>
- The coordinate system is that of android.sensor.info.activeArraySize, with
+ 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 of the active 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.
+ 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.
Only available if android.statistics.faceDetectMode == FULL</details>
+ <hal_details>
+ HAL must always report face landmarks in the coordinate system of pre-correction
+ active array.
+ </hal_details>
<tag id="BC" />
</entry>
<entry name="faceRectangles" type="int32" visibility="ndk_public"
@@ -8079,13 +8189,27 @@
<description>List of the bounding rectangles for detected
faces.</description>
<details>
- The coordinate system is that of android.sensor.info.activeArraySize, with
+ 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 of the active 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.
+ 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.
Only available if android.statistics.faceDetectMode != OFF</details>
<ndk_details>
- The data representation is `int[4]`, which maps to `(left, top, width, height)`.
+ The data representation is `int[4]`, which maps to `(left, top, right, bottom)`.
</ndk_details>
+ <hal_details>
+ HAL must always report face rectangles in the coordinate system of pre-correction
+ active array.
+ </hal_details>
<tag id="BC" />
</entry>
<entry name="faceScores" type="byte" visibility="ndk_public"
@@ -9740,16 +9864,15 @@
similar amount of enhancement applied.
The correction only applies to processed outputs such as YUV, JPEG, or DEPTH16; it is not
- applied to any RAW output. Metadata coordinates such as face rectangles or metering
+ applied to any RAW output. Metadata coordinates such as face rectangles or metering
regions are also not affected by correction.
- Applications enabling distortion correction need to pay extra attention when converting
- image coordinates between corrected output buffers and the sensor array. For example, if
- the app supports tap-to-focus and enables correction, it then has to apply the distortion
- model described in android.lens.distortion to the image buffer tap coordinates to properly
- calculate the tap position on the sensor active array to be used with
- android.control.afRegions. The same applies in reverse to detected face rectangles if
- they need to be drawn on top of the corrected output buffers.
+ This control will be on by default on devices that support this control. Applications
+ disabling distortion correction need to pay extra attention with the coordinate system of
+ metering regions, crop region, and face rectangles. When distortion correction is OFF,
+ metadata coordinates follow the coordinate system of
+ android.sensor.info.preCorrectionActiveArraySize. When distortion is not OFF, metadata
+ coordinates follow the coordinate system of android.sensor.info.activeArraySize.
</details>
</entry>
</controls>
