Camera: document expected thumbnail size in capture result
Bug: 21880406
Change-Id: I05a3f9731715a5906a13ba5f8647c887df73b6a7
diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index e3e1c07..f8cecb2 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -10386,6 +10386,18 @@
16:9 aspect ratio,<wbr/> the primary image will be cropped vertically (letterbox) to
generate the thumbnail image.<wbr/> The thumbnail image will always have a smaller Field
Of View (FOV) than the primary image when aspect ratios differ.<wbr/></p>
+<p>When an <a href="#controls_android.jpeg.orientation">android.<wbr/>jpeg.<wbr/>orientation</a> of non-zero degree is requested,<wbr/>
+the camera device will handle thumbnail rotation in one of the following ways:</p>
+<ul>
+<li>Set the <a href="https://developer.android.com/reference/android/media/ExifInterface.html#TAG_ORIENTATION">EXIF orientation flag</a>
+ and keep jpeg and thumbnail image data unrotated.<wbr/></li>
+<li>Rotate the jpeg and thumbnail image data and not set
+ <a href="https://developer.android.com/reference/android/media/ExifInterface.html#TAG_ORIENTATION">EXIF orientation flag</a>.<wbr/> In this
+ case,<wbr/> LIMITED or FULL hardware level devices will report rotated thumnail size in
+ capture result,<wbr/> so the width and height will be interchanged if 90 or 270 degree
+ orientation is requested.<wbr/> LEGACY device will always report unrotated thumbnail
+ size.<wbr/></li>
+</ul>
</td>
</tr>
@@ -11043,6 +11055,18 @@
16:9 aspect ratio,<wbr/> the primary image will be cropped vertically (letterbox) to
generate the thumbnail image.<wbr/> The thumbnail image will always have a smaller Field
Of View (FOV) than the primary image when aspect ratios differ.<wbr/></p>
+<p>When an <a href="#controls_android.jpeg.orientation">android.<wbr/>jpeg.<wbr/>orientation</a> of non-zero degree is requested,<wbr/>
+the camera device will handle thumbnail rotation in one of the following ways:</p>
+<ul>
+<li>Set the <a href="https://developer.android.com/reference/android/media/ExifInterface.html#TAG_ORIENTATION">EXIF orientation flag</a>
+ and keep jpeg and thumbnail image data unrotated.<wbr/></li>
+<li>Rotate the jpeg and thumbnail image data and not set
+ <a href="https://developer.android.com/reference/android/media/ExifInterface.html#TAG_ORIENTATION">EXIF orientation flag</a>.<wbr/> In this
+ case,<wbr/> LIMITED or FULL hardware level devices will report rotated thumnail size in
+ capture result,<wbr/> so the width and height will be interchanged if 90 or 270 degree
+ orientation is requested.<wbr/> LEGACY device will always report unrotated thumbnail
+ size.<wbr/></li>
+</ul>
</td>
</tr>
diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index 2bac770..bd880e8 100644
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -3061,6 +3061,18 @@
16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to
generate the thumbnail image. The thumbnail image will always have a smaller Field
Of View (FOV) than the primary image when aspect ratios differ.
+
+ When an android.jpeg.orientation of non-zero degree is requested,
+ the camera device will handle thumbnail rotation in one of the following ways:
+
+ * Set the {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag}
+ and keep jpeg and thumbnail image data unrotated.
+ * Rotate the jpeg and thumbnail image data and not set
+ {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag}. In this
+ case, LIMITED or FULL hardware level devices will report rotated thumnail size in
+ capture result, so the width and height will be interchanged if 90 or 270 degree
+ orientation is requested. LEGACY device will always report unrotated thumbnail
+ size.
</details>
<hal_details>
The HAL must not squeeze or stretch the downscaled primary image to generate thumbnail.