Merge "Camera: clarify largest JPEG dimension expectation" into mnc-dev
diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 82be3f4..09e5731 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -17500,7 +17500,7 @@
<tbody>
<tr>
<td align="center"><a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#JPEG">ImageFormat#JPEG</a></td>
-<td align="center"><a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></td>
+<td align="center"><a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> (*1)</td>
<td align="center">Any</td>
<td align="center"></td>
</tr>
@@ -17512,7 +17512,7 @@
</tr>
<tr>
<td align="center"><a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#JPEG">ImageFormat#JPEG</a></td>
-<td align="center">1280x720 (720)</td>
+<td align="center">1280x720 (720p)</td>
<td align="center">Any</td>
<td align="center">if 720p <= activeArraySize</td>
</tr>
@@ -17550,6 +17550,22 @@
</table>
<p>Refer to <a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a> and <a href="https://developer.android.com/reference/android/hardware/camera2/CameraDevice.html#createCaptureSession">CameraDevice#createCaptureSession</a> for additional mandatory
stream configurations on a per-capability basis.<wbr/></p>
+<p>*1: For JPEG format,<wbr/> the sizes may be restricted by below conditions:</p>
+<ul>
+<li>The HAL may choose the aspect ratio of each Jpeg size to be one of well known ones
+(e.<wbr/>g.<wbr/> 4:3,<wbr/> 16:9,<wbr/> 3:2 etc.<wbr/>).<wbr/> If the sensor maximum resolution
+(defined by <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>) has an aspect ratio other than these,<wbr/>
+it does not have to be included in the supported JPEG sizes.<wbr/></li>
+<li>Some hardware JPEG encoders may have pixel boundary alignment requirements,<wbr/> such as
+the dimensions being a multiple of 16.<wbr/>
+Therefore,<wbr/> the maximum JPEG size may be smaller than sensor maximum resolution.<wbr/>
+However,<wbr/> the largest JPEG size will be as close as possible to the sensor maximum
+resolution given above constraints.<wbr/> It is required that after aspect ratio adjustments,<wbr/>
+additional size reduction due to other issues must be less than 3% in area.<wbr/> For example,<wbr/>
+if the sensor maximum resolution is 3280x2464,<wbr/> if the maximum JPEG size has aspect
+ratio 4:3,<wbr/> and the JPEG encoder alignment requirement is 16,<wbr/> the maximum JPEG size will be
+3264x2448.<wbr/></li>
+</ul>
</td>
</tr>
diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index 17efce2..5c2256c 100644
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -5652,9 +5652,9 @@
Format | Size | Hardware Level | Notes
:-------------------------------------------------:|:--------------------------------------------:|:--------------:|:--------------:
- {@link android.graphics.ImageFormat#JPEG} | android.sensor.info.activeArraySize | Any |
+ {@link android.graphics.ImageFormat#JPEG} | android.sensor.info.activeArraySize (*1) | Any |
{@link android.graphics.ImageFormat#JPEG} | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize
- {@link android.graphics.ImageFormat#JPEG} | 1280x720 (720) | Any | if 720p <= activeArraySize
+ {@link android.graphics.ImageFormat#JPEG} | 1280x720 (720p) | Any | if 720p <= activeArraySize
{@link android.graphics.ImageFormat#JPEG} | 640x480 (480p) | Any | if 480p <= activeArraySize
{@link android.graphics.ImageFormat#JPEG} | 320x240 (240p) | Any | if 240p <= activeArraySize
{@link android.graphics.ImageFormat#YUV_420_888} | all output sizes available for JPEG | FULL |
@@ -5664,6 +5664,22 @@
Refer to android.request.availableCapabilities and {@link
android.hardware.camera2.CameraDevice#createCaptureSession} for additional mandatory
stream configurations on a per-capability basis.
+
+ *1: For JPEG format, the sizes may be restricted by below conditions:
+
+ * The HAL may choose the aspect ratio of each Jpeg size to be one of well known ones
+ (e.g. 4:3, 16:9, 3:2 etc.). If the sensor maximum resolution
+ (defined by android.sensor.info.activeArraySize) has an aspect ratio other than these,
+ it does not have to be included in the supported JPEG sizes.
+ * Some hardware JPEG encoders may have pixel boundary alignment requirements, such as
+ the dimensions being a multiple of 16.
+ Therefore, the maximum JPEG size may be smaller than sensor maximum resolution.
+ However, the largest JPEG size will be as close as possible to the sensor maximum
+ resolution given above constraints. It is required that after aspect ratio adjustments,
+ additional size reduction due to other issues must be less than 3% in area. For example,
+ if the sensor maximum resolution is 3280x2464, if the maximum JPEG size has aspect
+ ratio 4:3, and the JPEG encoder alignment requirement is 16, the maximum JPEG size will be
+ 3264x2448.
</details>
<hal_details>
Do not set this property directly