Update docs for YV12 format and camera preview callbacks.

- Define stride for YV12 when using it for preview callbacks

- Include equations for calculating stride and start indexes of Y, U,
  and V planes for YV12.

- Add more cross-references so that equations are easier to find.

Bug: 6330501
Change-Id: I85a78757ec767d08173b9fe714adb715835244b4

1 files changed, 14 insertions, 2 deletions

diff --git a/graphics/java/android/graphics/ImageFormat.java b/graphics/java/android/graphics/ImageFormat.java
index b3a8fd7..f6b747a 100644
--- a/graphics/java/android/graphics/ImageFormat.java
+++ b/graphics/java/android/graphics/ImageFormat.java
@@ -48,14 +48,26 @@ public class ImageFormat {
      * </p>
      *
      * <pre> y_size = stride * height
-     * c_size = ALIGN(stride/2, 16) * height/2
+     * c_stride = ALIGN(stride/2, 16)
+     * c_size = c_stride * height/2
      * size = y_size + c_size * 2
      * cr_offset = y_size
      * cb_offset = y_size + c_size</pre>
      *
-     * This format is guaranteed to be supported for camera preview images since
+     * <p>This format is guaranteed to be supported for camera preview images since
      * API level 12; for earlier API versions, check
      * {@link android.hardware.Camera.Parameters#getSupportedPreviewFormats()}.
+     *
+     * <p>Note that for camera preview callback use (see
+     * {@link android.hardware.Camera#setPreviewCallback}), the
+     * <var>stride</var> value is the smallest possible; that is, it is equal
+     * to:
+     *
+     * <pre>stride = ALIGN(width, 16)</pre>
+     *
+     * @see android.hardware.Camera.Parameters#setPreviewCallback
+     * @see android.hardware.Camera.Parameters#setPreviewFormat
+     * @see android.hardware.Camera.Parameters#getSupportedPreviewFormats
      * </p>
      */
     public static final int YV12 = 0x32315659;