Camera2: Update availableThumbnailSizes java doc

Bug: 12135317
Change-Id: I4012ed3e7cd6394c5e964aaeb3381b4932c44b11

3 files changed, 24 insertions, 6 deletions

diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java
index 6f5af9c..ca89cb6 100644
--- a/core/java/android/hardware/camera2/CameraCharacteristics.java
+++ b/core/java/android/hardware/camera2/CameraCharacteristics.java
@@ -205,8 +205,20 @@ public final class CameraCharacteristics extends CameraMetadata {
             new Key<Byte>("android.flash.info.available", byte.class);
 
     /**
-     * <p>Supported resolutions for the JPEG
-     * thumbnail</p>
+     * <p>Supported resolutions for the JPEG thumbnail</p>
+     * <p>Below condiditions must be satisfied for this size list:</p>
+     * <ul>
+     * <li>The sizes must be sorted by increasing pixel area (width x height).
+     * If several resolutions have the same area, they must be sorted by increasing width.</li>
+     * <li>The aspect ratio of the largest thumbnail size must be same as the
+     * aspect ratio of largest size in android.scaler.availableJpegSizes.
+     * The largest size is defined as the size that has the largest pixel area
+     * in a given size list.</li>
+     * <li>Each size in android.scaler.availableJpegSizes must have at least
+     * one corresponding size that has the same aspect ratio in availableThumbnailSizes,
+     * and vice versa.</li>
+     * <li>All non (0, 0) sizes must have non-zero widths and heights.</li>
+     * </ul>
      */
     public static final Key<android.hardware.camera2.Size[]> JPEG_AVAILABLE_THUMBNAIL_SIZES =
             new Key<android.hardware.camera2.Size[]>("android.jpeg.availableThumbnailSizes", android.hardware.camera2.Size[].class);
diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java
index e47567b..0c5ba67 100644
--- a/core/java/android/hardware/camera2/CaptureRequest.java
+++ b/core/java/android/hardware/camera2/CaptureRequest.java
@@ -719,8 +719,11 @@ public final class CaptureRequest extends CameraMetadata implements Parcelable {
             new Key<Byte>("android.jpeg.thumbnailQuality", byte.class);
 
     /**
-     * <p>Resolution of embedded JPEG
-     * thumbnail</p>
+     * <p>Resolution of embedded JPEG thumbnail</p>
+     * <p>When set to (0, 0) value, the JPEG EXIF must not contain thumbnail,
+     * but the captured JPEG must still be a valid image.</p>
+     * <p>When a jpeg image capture is issued, the thumbnail size selected should have
+     * the same aspect ratio as the jpeg image.</p>
      */
     public static final Key<android.hardware.camera2.Size> JPEG_THUMBNAIL_SIZE =
             new Key<android.hardware.camera2.Size>("android.jpeg.thumbnailSize", android.hardware.camera2.Size.class);
diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java
index 6119fa4..a892fbe 100644
--- a/core/java/android/hardware/camera2/CaptureResult.java
+++ b/core/java/android/hardware/camera2/CaptureResult.java
@@ -426,8 +426,11 @@ public final class CaptureResult extends CameraMetadata {
             new Key<Byte>("android.jpeg.thumbnailQuality", byte.class);
 
     /**
-     * <p>Resolution of embedded JPEG
-     * thumbnail</p>
+     * <p>Resolution of embedded JPEG thumbnail</p>
+     * <p>When set to (0, 0) value, the JPEG EXIF must not contain thumbnail,
+     * but the captured JPEG must still be a valid image.</p>
+     * <p>When a jpeg image capture is issued, the thumbnail size selected should have
+     * the same aspect ratio as the jpeg image.</p>
      */
     public static final Key<android.hardware.camera2.Size> JPEG_THUMBNAIL_SIZE =
             new Key<android.hardware.camera2.Size>("android.jpeg.thumbnailSize", android.hardware.camera2.Size.class);