Camera: Update streamConfigurationMap doc for jpeg size change
Because camera framework filters out smaller JPEG sizes based on media
performance class level, update the developer doc to reflect that.
Previously only the ndk_public doc was updated.
Also fix the html link generation for nested classes.
Test: Build
Bug: 235804659
Change-Id: I9795de1484803521bc1a24fbb4a57e27b71143f1
diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 7e4e7b8..f4898bc 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -19990,10 +19990,11 @@
<tr class="entry_cont">
<td class="entry_details" colspan="6">
<p>This is a subset of <a href="#static_android.request.availableRequestKeys">android.<wbr/>request.<wbr/>available<wbr/>Request<wbr/>Keys</a> which contains a list
-of keys that can be overridden using <a href="https://developer.android.com/reference/CaptureRequest/Builder.html#setPhysicalCameraKey">Builder#setPhysicalCameraKey</a>.<wbr/>
+of keys that can be overridden using
+<a href="https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder.html#setPhysicalCameraKey">Builder#setPhysicalCameraKey</a>.<wbr/>
The respective value of such request key can be obtained by calling
-<a href="https://developer.android.com/reference/CaptureRequest/Builder.html#getPhysicalCameraKey">Builder#getPhysicalCameraKey</a>.<wbr/> Capture requests that contain
-individual physical device requests must be built via
+<a href="https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder.html#getPhysicalCameraKey">Builder#getPhysicalCameraKey</a>.<wbr/>
+Capture requests that contain individual physical device requests must be built via
<a href="https://developer.android.com/reference/android/hardware/camera2/CameraDevice.html#createCaptureRequest(int,">Set)</a>.<wbr/></p>
</td>
</tr>
@@ -22154,7 +22155,7 @@
</table>
<p>For applications targeting SDK version 31 or newer,<wbr/> if the mobile device declares to be
media performance class 12 or higher by setting
-<a href="https://developer.android.com/reference/android/os/Build/VERSION_CODES/MEDIA_PERFORMANCE_CLASS.html">MEDIA_<wbr/>PERFORMANCE_<wbr/>CLASS</a> to be 31 or larger,<wbr/>
+<a href="https://developer.android.com/reference/android/os/Build.VERSION.html#MEDIA_PERFORMANCE_CLASS">VERSION#MEDIA_<wbr/>PERFORMANCE_<wbr/>CLASS</a> to be 31 or larger,<wbr/>
the primary camera devices (first rear/<wbr/>front camera in the camera ID list) will not
support JPEG sizes smaller than 1080p.<wbr/> If the application configures a JPEG stream
smaller than 1080p,<wbr/> the camera device will round up the JPEG image size to at least
@@ -22228,7 +22229,7 @@
</table>
<p>For applications targeting SDK version 31 or newer,<wbr/> if the mobile device doesn't declare
to be media performance class 12 or better by setting
-<a href="https://developer.android.com/reference/android/os/Build/VERSION_CODES/MEDIA_PERFORMANCE_CLASS.html">MEDIA_<wbr/>PERFORMANCE_<wbr/>CLASS</a> to be 31 or larger,<wbr/>
+<a href="https://developer.android.com/reference/android/os/Build.VERSION.html#MEDIA_PERFORMANCE_CLASS">VERSION#MEDIA_<wbr/>PERFORMANCE_<wbr/>CLASS</a> to be 31 or larger,<wbr/>
or if the camera device isn't a primary rear/<wbr/>front camera,<wbr/> the minimum required output
stream configurations are the same as for applications targeting SDK version older than
31.<wbr/></p>
@@ -22281,7 +22282,7 @@
<li>1080p (1920 x 1080)</li>
</ul>
<p>Note that for primary cameras (first rear/<wbr/>front facing camera in the camera ID list)
-on a device with <a href="https://developer.android.com/reference/android/os/Build/VERSION_CODES/MEDIA_PERFORMANCE_CLASS.html">MEDIA_<wbr/>PERFORMANCE_<wbr/>CLASS</a> set to
+on a device with <a href="https://developer.android.com/reference/android/os/Build.VERSION.html#MEDIA_PERFORMANCE_CLASS">VERSION#MEDIA_<wbr/>PERFORMANCE_<wbr/>CLASS</a> set to
31 or larger,<wbr/> camera framework filters out JPEG sizes smaller than 1080p depending on
applications' targetSdkLevel.<wbr/> The camera HAL must still support the smaller JPEG sizes
to maintain backward compatibility.<wbr/></p>
@@ -22547,9 +22548,27 @@
can provide.<wbr/></p>
<p>Please reference the documentation for the image data destination to
check if it limits the maximum size for image data.<wbr/></p>
-<p>The following table describes the minimum required output stream
-configurations based on the hardware level
-(<a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a>):</p>
+<p>For applications targeting SDK version older than 31,<wbr/> the following table
+describes the minimum required output stream configurations based on the
+hardware level (<a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a>):
+Format |<wbr/> Size |<wbr/> Hardware Level |<wbr/> Notes
+:-------------------------------------------------:|<wbr/>:--------------------------------------------:|<wbr/>:--------------:|<wbr/>:--------------:
+<a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#JPEG">ImageFormat#JPEG</a> |<wbr/> <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> (*1) |<wbr/> Any |<wbr/>
+<a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#JPEG">ImageFormat#JPEG</a> |<wbr/> 1920x1080 (1080p) |<wbr/> Any |<wbr/> if 1080p <= activeArraySize
+<a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#JPEG">ImageFormat#JPEG</a> |<wbr/> 1280x720 (720p) |<wbr/> Any |<wbr/> if 720p <= activeArraySize
+<a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#JPEG">ImageFormat#JPEG</a> |<wbr/> 640x480 (480p) |<wbr/> Any |<wbr/> if 480p <= activeArraySize
+<a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#JPEG">ImageFormat#JPEG</a> |<wbr/> 320x240 (240p) |<wbr/> Any |<wbr/> if 240p <= activeArraySize
+<a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#YUV_420_888">Image<wbr/>Format#YUV_<wbr/>420_<wbr/>888</a> |<wbr/> all output sizes available for JPEG |<wbr/> FULL |<wbr/>
+<a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#YUV_420_888">Image<wbr/>Format#YUV_<wbr/>420_<wbr/>888</a> |<wbr/> all output sizes available for JPEG,<wbr/> up to the maximum video size |<wbr/> LIMITED |<wbr/>
+<a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#PRIVATE">ImageFormat#PRIVATE</a> |<wbr/> same as YUV_<wbr/>420_<wbr/>888 |<wbr/> Any |<wbr/></p>
+<p>For applications targeting SDK version 31 or newer,<wbr/> if the mobile device declares to be
+media performance class 12 or higher by setting
+<a href="https://developer.android.com/reference/android/os/Build.VERSION.html#MEDIA_PERFORMANCE_CLASS">VERSION#MEDIA_<wbr/>PERFORMANCE_<wbr/>CLASS</a> to be 31 or larger,<wbr/>
+the primary camera devices (first rear/<wbr/>front camera in the camera ID list) will not
+support JPEG sizes smaller than 1080p.<wbr/> If the application configures a JPEG stream
+smaller than 1080p,<wbr/> the camera device will round up the JPEG image size to at least
+1080p.<wbr/> The requirements for IMPLEMENTATION_<wbr/>DEFINED and YUV_<wbr/>420_<wbr/>888 stay the same.<wbr/>
+This new minimum required output stream configurations are illustrated by the table below:</p>
<table>
<thead>
<tr>
@@ -22573,32 +22592,38 @@
<td align="center">if 1080p <= activeArraySize</td>
</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 (720p)</td>
-<td align="center">Any</td>
-<td align="center">if 720p <= activeArraySize</td>
-</tr>
-<tr>
-<td align="center"><a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#JPEG">ImageFormat#JPEG</a></td>
-<td align="center">640x480 (480p)</td>
-<td align="center">Any</td>
-<td align="center">if 480p <= activeArraySize</td>
-</tr>
-<tr>
-<td align="center"><a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#JPEG">ImageFormat#JPEG</a></td>
-<td align="center">320x240 (240p)</td>
-<td align="center">Any</td>
-<td align="center">if 240p <= activeArraySize</td>
-</tr>
-<tr>
<td align="center"><a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#YUV_420_888">Image<wbr/>Format#YUV_<wbr/>420_<wbr/>888</a></td>
-<td align="center">all output sizes available for JPEG</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">FULL</td>
<td align="center"></td>
</tr>
<tr>
<td align="center"><a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#YUV_420_888">Image<wbr/>Format#YUV_<wbr/>420_<wbr/>888</a></td>
-<td align="center">all output sizes available for JPEG,<wbr/> up to the maximum video size</td>
+<td align="center">1920x1080 (1080p)</td>
+<td align="center">FULL</td>
+<td align="center">if 1080p <= activeArraySize</td>
+</tr>
+<tr>
+<td align="center"><a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#YUV_420_888">Image<wbr/>Format#YUV_<wbr/>420_<wbr/>888</a></td>
+<td align="center">1280x720 (720)</td>
+<td align="center">FULL</td>
+<td align="center">if 720p <= activeArraySize</td>
+</tr>
+<tr>
+<td align="center"><a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#YUV_420_888">Image<wbr/>Format#YUV_<wbr/>420_<wbr/>888</a></td>
+<td align="center">640x480 (480p)</td>
+<td align="center">FULL</td>
+<td align="center">if 480p <= activeArraySize</td>
+</tr>
+<tr>
+<td align="center"><a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#YUV_420_888">Image<wbr/>Format#YUV_<wbr/>420_<wbr/>888</a></td>
+<td align="center">320x240 (240p)</td>
+<td align="center">FULL</td>
+<td align="center">if 240p <= activeArraySize</td>
+</tr>
+<tr>
+<td align="center"><a href="https://developer.android.com/reference/android/graphics/ImageFormat.html#YUV_420_888">Image<wbr/>Format#YUV_<wbr/>420_<wbr/>888</a></td>
+<td align="center">all output sizes available for FULL hardware level,<wbr/> up to the maximum video size</td>
<td align="center">LIMITED</td>
<td align="center"></td>
</tr>
@@ -22610,6 +22635,12 @@
</tr>
</tbody>
</table>
+<p>For applications targeting SDK version 31 or newer,<wbr/> if the mobile device doesn't declare
+to be media performance class 12 or better by setting
+<a href="https://developer.android.com/reference/android/os/Build.VERSION.html#MEDIA_PERFORMANCE_CLASS">VERSION#MEDIA_<wbr/>PERFORMANCE_<wbr/>CLASS</a> to be 31 or larger,<wbr/>
+or if the camera device isn't a primary rear/<wbr/>front camera,<wbr/> the minimum required output
+stream configurations are the same as for applications targeting SDK version older than
+31.<wbr/></p>
<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>
@@ -22666,6 +22697,10 @@
<li>720p (1280 x 720)</li>
<li>1080p (1920 x 1080)</li>
</ul>
+<p>Note that for Performance Class 12 or higher primary cameras (first rear/<wbr/>front facing
+camera in the camera ID list),<wbr/> camera framework filters out JPEG sizes smaller than
+1080p depending on applications' targetSdkLevel.<wbr/> The camera HAL must still support the
+smaller JPEG sizes to maintain backward comopatibility.<wbr/></p>
<p>For LIMITED capability devices
(<code><a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a> == LIMITED</code>),<wbr/>
the HAL only has to list up to the maximum video size
@@ -34064,7 +34099,7 @@
fire the flash for flash power metering during precapture,<wbr/> and then fire the flash
for the final capture,<wbr/> if a flash is available on the device and the AE mode is set to
enable the flash.<wbr/></p>
-<p>Devices that initially shipped with Android version <a href="https://developer.android.com/reference/android/os/Build/VERSION_CODES.html#Q">Q</a> or newer will not include any LEGACY-level devices.<wbr/></p></span>
+<p>Devices that initially shipped with Android version <a href="https://developer.android.com/reference/android/os/Build.VERSION_CODES.html#Q">Q</a> or newer will not include any LEGACY-level devices.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">3 (v3.2)</span>
diff --git a/camera/docs/html.mako b/camera/docs/html.mako
index aaca5db..992af79 100644
--- a/camera/docs/html.mako
+++ b/camera/docs/html.mako
@@ -134,6 +134,10 @@
else:
target = target + '.html'
+ # Work around html links with inner classes.
+ target = target.replace('CaptureRequest/Builder', 'CaptureRequest.Builder')
+ target = target.replace('Build/VERSION', 'Build.VERSION')
+
return '<a href="https://developer.android.com/reference/%s">%s</a>' % (target, shortname)
# Render as markdown, and do HTML-doc-specific rewrites
diff --git a/camera/docs/metadata_definitions.xml b/camera/docs/metadata_definitions.xml
index d8ca022..bd23135 100644
--- a/camera/docs/metadata_definitions.xml
+++ b/camera/docs/metadata_definitions.xml
@@ -6650,10 +6650,11 @@
physical devices backing a logical multi-camera.</description>
<details>
This is a subset of android.request.availableRequestKeys which contains a list
- of keys that can be overridden using {@link CaptureRequest.Builder#setPhysicalCameraKey}.
+ of keys that can be overridden using
+ {@link android.hardware.camera2.CaptureRequest.Builder#setPhysicalCameraKey}.
The respective value of such request key can be obtained by calling
- {@link CaptureRequest.Builder#getPhysicalCameraKey}. Capture requests that contain
- individual physical device requests must be built via
+ {@link android.hardware.camera2.CaptureRequest.Builder#getPhysicalCameraKey}.
+ Capture requests that contain individual physical device requests must be built via
{@link android.hardware.camera2.CameraDevice#createCaptureRequest(int, Set)}.
</details>
<hal_details>
@@ -7451,7 +7452,7 @@
For applications targeting SDK version 31 or newer, if the mobile device declares to be
media performance class 12 or higher by setting
- {@link android.os.Build.VERSION_CODES.MEDIA_PERFORMANCE_CLASS} to be 31 or larger,
+ {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger,
the primary camera devices (first rear/front camera in the camera ID list) will not
support JPEG sizes smaller than 1080p. If the application configures a JPEG stream
smaller than 1080p, the camera device will round up the JPEG image size to at least
@@ -7472,7 +7473,7 @@
For applications targeting SDK version 31 or newer, if the mobile device doesn't declare
to be media performance class 12 or better by setting
- {@link android.os.Build.VERSION_CODES.MEDIA_PERFORMANCE_CLASS} to be 31 or larger,
+ {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger,
or if the camera device isn't a primary rear/front camera, the minimum required output
stream configurations are the same as for applications targeting SDK version older than
31.
@@ -7526,7 +7527,7 @@
* 1080p (1920 x 1080)
Note that for primary cameras (first rear/front facing camera in the camera ID list)
- on a device with {@link android.os.Build.VERSION_CODES.MEDIA_PERFORMANCE_CLASS} set to
+ on a device with {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} set to
31 or larger, camera framework filters out JPEG sizes smaller than 1080p depending on
applications' targetSdkLevel. The camera HAL must still support the smaller JPEG sizes
to maintain backward compatibility.
@@ -7673,10 +7674,9 @@
Please reference the documentation for the image data destination to
check if it limits the maximum size for image data.
- The following table describes the minimum required output stream
- configurations based on the hardware level
- (android.info.supportedHardwareLevel):
-
+ For applications targeting SDK version older than 31, the following table
+ describes the minimum required output stream configurations based on the
+ hardware level (android.info.supportedHardwareLevel):
Format | Size | Hardware Level | Notes
:-------------------------------------------------:|:--------------------------------------------:|:--------------:|:--------------:
{@link android.graphics.ImageFormat#JPEG} | android.sensor.info.activeArraySize (*1) | Any |
@@ -7688,6 +7688,34 @@
{@link android.graphics.ImageFormat#YUV_420_888} | all output sizes available for JPEG, up to the maximum video size | LIMITED |
{@link android.graphics.ImageFormat#PRIVATE} | same as YUV_420_888 | Any |
+ For applications targeting SDK version 31 or newer, if the mobile device declares to be
+ media performance class 12 or higher by setting
+ {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger,
+ the primary camera devices (first rear/front camera in the camera ID list) will not
+ support JPEG sizes smaller than 1080p. If the application configures a JPEG stream
+ smaller than 1080p, the camera device will round up the JPEG image size to at least
+ 1080p. The requirements for IMPLEMENTATION_DEFINED and YUV_420_888 stay the same.
+ This new minimum required output stream configurations are illustrated by the table below:
+
+ Format | Size | Hardware Level | Notes
+ :-------------------------------------------------:|:--------------------------------------------:|:--------------:|:--------------:
+ {@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#YUV_420_888} | android.sensor.info.activeArraySize | FULL |
+ {@link android.graphics.ImageFormat#YUV_420_888} | 1920x1080 (1080p) | FULL | if 1080p <= activeArraySize
+ {@link android.graphics.ImageFormat#YUV_420_888} | 1280x720 (720) | FULL | if 720p <= activeArraySize
+ {@link android.graphics.ImageFormat#YUV_420_888} | 640x480 (480p) | FULL | if 480p <= activeArraySize
+ {@link android.graphics.ImageFormat#YUV_420_888} | 320x240 (240p) | FULL | if 240p <= activeArraySize
+ {@link android.graphics.ImageFormat#YUV_420_888} | all output sizes available for FULL hardware level, up to the maximum video size | LIMITED |
+ {@link android.graphics.ImageFormat#PRIVATE} | same as YUV_420_888 | Any |
+
+ For applications targeting SDK version 31 or newer, if the mobile device doesn't declare
+ to be media performance class 12 or better by setting
+ {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger,
+ or if the camera device isn't a primary rear/front camera, the minimum required output
+ stream configurations are the same as for applications targeting SDK version older than
+ 31.
+
Refer to android.request.availableCapabilities and {@link
android.hardware.camera2.CameraDevice#createCaptureSession} for additional mandatory
stream configurations on a per-capability basis.
@@ -7747,6 +7775,11 @@
* 720p (1280 x 720)
* 1080p (1920 x 1080)
+ Note that for Performance Class 12 or higher primary cameras (first rear/front facing
+ camera in the camera ID list), camera framework filters out JPEG sizes smaller than
+ 1080p depending on applications' targetSdkLevel. The camera HAL must still support the
+ smaller JPEG sizes to maintain backward comopatibility.
+
For LIMITED capability devices
(`android.info.supportedHardwareLevel == LIMITED`),
the HAL only has to list up to the maximum video size
diff --git a/camera/docs/metadata_helpers.py b/camera/docs/metadata_helpers.py
index e3034f3..bd586df 100644
--- a/camera/docs/metadata_helpers.py
+++ b/camera/docs/metadata_helpers.py
@@ -943,6 +943,10 @@
else:
target = target + '.html'
+ # Work around html links with inner classes.
+ target = target.replace('CaptureRequest/Builder', 'CaptureRequest.Builder')
+ target = target.replace('Build/VERSION', 'Build.VERSION')
+
return '<a href="https://developer.android.com/reference/%s">%s</a>' % (target, shortname)
ndktext = filter_links(ndktext, ndkdoc_link_filter)
