Merge "Camera: Revise crop region definition." into jb-mr2-dev

2 files changed, 117 insertions, 36 deletions

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 65d6f006..49b535b6 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -6692,7 +6692,7 @@
                 <span class="entry_type_container">x</span>
 
                 <span class="entry_type_array">
-                  3
+                  4
                 </span>
 
 
@@ -6700,14 +6700,20 @@
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              Top-left corner and width of the output
-          region to select from the active pixel
-          array
+              (x,<wbr> y,<wbr> width,<wbr> height).<wbr>
+<br>
+<br>          A rectangle with the top-level corner of (x,<wbr>y) and size
+          (width,<wbr> height).<wbr> The region of the sensor that is used for
+          output.<wbr> Each stream must use this rectangle to produce its
+          output,<wbr> cropping to a smaller region if necessary to
+          maintain the stream's aspect ratio.<wbr>
+<br>
+<br>          HAL2.<wbr>x uses only (x,<wbr> y,<wbr> width)
             </td>
 
             <td class="entry_units">
-              (x,<wbr>y) of top-left corner,<wbr> width of region in
-          pixels; (0,<wbr>0) is top-left corner of
+              (x,<wbr>y) of top-left corner,<wbr> width and height of region
+          in pixels; (0,<wbr>0) is top-left corner of
           android.<wbr>sensor.<wbr>active<wbr>Pixel<wbr>Array
             </td>
 
@@ -6715,12 +6721,33 @@
             </td>
 
             <td class="entry_notes">
-              [BC - zoom] Height determined based on width and
-          aspect ratio of output stream.<wbr> Negative values for corner
-          are allowed for raw output if full pixel array is larger
-          than active pixel array.<wbr> Width may be rounded to nearest
-          larger supportable width,<wbr> especially for raw output,<wbr>
-          where only a few fixed scales may be possible
+              
+            Any additional per-stream cropping must be done to
+            maximize the final pixel area of the stream.<wbr>
+<br>
+<br>            For example,<wbr> if the crop region is set to a 4:3 aspect
+            ratio,<wbr> then 4:3 streams should use the exact crop
+            region.<wbr> 16:9 streams should further crop vertically
+            (letterbox).<wbr>
+<br>
+<br>            Conversely,<wbr> if the crop region is set to a 16:9,<wbr> then 4:3
+            outputs should crop horizontally (pillarbox),<wbr> and 16:9
+            streams should match exactly.<wbr> These additional crops must
+            be centered within the crop region.<wbr>
+<br>
+<br>            The output streams must maintain square pixels at all
+            times,<wbr> no matter what the relative aspect ratios of the
+            crop region and the stream are.<wbr>  Negative values for
+            corner are allowed for raw output if full pixel array is
+            larger than active pixel array.<wbr> Width and height may be
+            rounded to nearest larger supportable width,<wbr> especially
+            for raw output,<wbr> where only a few fixed scales may be
+            possible.<wbr> The width and height of the crop region cannot
+            be set to be smaller than floor( activePixelArray.<wbr>width /<wbr>
+            android.<wbr>scaler.<wbr>max<wbr>Digital<wbr>Zoom ) and floor(
+            activePixelArray.<wbr>height /<wbr> android.<wbr>scaler.<wbr>max<wbr>Digital<wbr>Zoom),<wbr>
+            respectively.<wbr>
+          
             </td>
 
             <td class="entry_tags">
@@ -7134,7 +7161,7 @@
                 <span class="entry_type_container">x</span>
 
                 <span class="entry_type_array">
-                  3
+                  4
                 </span>
 
 
@@ -7142,14 +7169,20 @@
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              Top-left corner and width of the output
-          region to select from the active pixel
-          array
+              (x,<wbr> y,<wbr> width,<wbr> height).<wbr>
+<br>
+<br>          A rectangle with the top-level corner of (x,<wbr>y) and size
+          (width,<wbr> height).<wbr> The region of the sensor that is used for
+          output.<wbr> Each stream must use this rectangle to produce its
+          output,<wbr> cropping to a smaller region if necessary to
+          maintain the stream's aspect ratio.<wbr>
+<br>
+<br>          HAL2.<wbr>x uses only (x,<wbr> y,<wbr> width)
             </td>
 
             <td class="entry_units">
-              (x,<wbr>y) of top-left corner,<wbr> width of region in
-          pixels; (0,<wbr>0) is top-left corner of
+              (x,<wbr>y) of top-left corner,<wbr> width and height of region
+          in pixels; (0,<wbr>0) is top-left corner of
           android.<wbr>sensor.<wbr>active<wbr>Pixel<wbr>Array
             </td>
 
@@ -7157,12 +7190,33 @@
             </td>
 
             <td class="entry_notes">
-              [BC - zoom] Height determined based on width and
-          aspect ratio of output stream.<wbr> Negative values for corner
-          are allowed for raw output if full pixel array is larger
-          than active pixel array.<wbr> Width may be rounded to nearest
-          larger supportable width,<wbr> especially for raw output,<wbr>
-          where only a few fixed scales may be possible
+              
+            Any additional per-stream cropping must be done to
+            maximize the final pixel area of the stream.<wbr>
+<br>
+<br>            For example,<wbr> if the crop region is set to a 4:3 aspect
+            ratio,<wbr> then 4:3 streams should use the exact crop
+            region.<wbr> 16:9 streams should further crop vertically
+            (letterbox).<wbr>
+<br>
+<br>            Conversely,<wbr> if the crop region is set to a 16:9,<wbr> then 4:3
+            outputs should crop horizontally (pillarbox),<wbr> and 16:9
+            streams should match exactly.<wbr> These additional crops must
+            be centered within the crop region.<wbr>
+<br>
+<br>            The output streams must maintain square pixels at all
+            times,<wbr> no matter what the relative aspect ratios of the
+            crop region and the stream are.<wbr>  Negative values for
+            corner are allowed for raw output if full pixel array is
+            larger than active pixel array.<wbr> Width and height may be
+            rounded to nearest larger supportable width,<wbr> especially
+            for raw output,<wbr> where only a few fixed scales may be
+            possible.<wbr> The width and height of the crop region cannot
+            be set to be smaller than floor( activePixelArray.<wbr>width /<wbr>
+            android.<wbr>scaler.<wbr>max<wbr>Digital<wbr>Zoom ) and floor(
+            activePixelArray.<wbr>height /<wbr> android.<wbr>scaler.<wbr>max<wbr>Digital<wbr>Zoom),<wbr>
+            respectively.<wbr>
+          
             </td>
 
             <td class="entry_tags">
diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index a5188cc8..1b9b8629 100644
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -1507,20 +1507,47 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
       <controls>
         <entry name="cropRegion" type="int32" container="array">
           <array>
-            <size>3</size>
+            <size>4</size>
           </array>
-          <description>Top-left corner and width of the output
-          region to select from the active pixel
-          array</description>
-          <units>(x,y) of top-left corner, width of region in
-          pixels; (0,0) is top-left corner of
+          <description>(x, y, width, height).
+
+          A rectangle with the top-level corner of (x,y) and size
+          (width, height). The region of the sensor that is used for
+          output. Each stream must use this rectangle to produce its
+          output, cropping to a smaller region if necessary to
+          maintain the stream's aspect ratio.
+
+          HAL2.x uses only (x, y, width)</description>
+          <units>(x,y) of top-left corner, width and height of region
+          in pixels; (0,0) is top-left corner of
           android.sensor.activePixelArray</units>
-          <notes>[BC - zoom] Height determined based on width and
-          aspect ratio of output stream. Negative values for corner
-          are allowed for raw output if full pixel array is larger
-          than active pixel array. Width may be rounded to nearest
-          larger supportable width, especially for raw output,
-          where only a few fixed scales may be possible</notes>
+          <notes>
+            Any additional per-stream cropping must be done to
+            maximize the final pixel area of the stream.
+
+            For example, if the crop region is set to a 4:3 aspect
+            ratio, then 4:3 streams should use the exact crop
+            region. 16:9 streams should further crop vertically
+            (letterbox).
+
+            Conversely, if the crop region is set to a 16:9, then 4:3
+            outputs should crop horizontally (pillarbox), and 16:9
+            streams should match exactly. These additional crops must
+            be centered within the crop region.
+
+            The output streams must maintain square pixels at all
+            times, no matter what the relative aspect ratios of the
+            crop region and the stream are.  Negative values for
+            corner are allowed for raw output if full pixel array is
+            larger than active pixel array. Width and height may be
+            rounded to nearest larger supportable width, especially
+            for raw output, where only a few fixed scales may be
+            possible. The width and height of the crop region cannot
+            be set to be smaller than floor( activePixelArray.width /
+            android.scaler.maxDigitalZoom ) and floor(
+            activePixelArray.height / android.scaler.maxDigitalZoom),
+            respectively.
+          </notes>
           <tag id="BC" />
         </entry>
       </controls>