From 951516358e2841d2425f610bcd0175d9960135d2 Mon Sep 17 00:00:00 2001
From: Eino-Ville Talvala <etalvala@google.com>
Date: Wed, 2 May 2012 16:21:18 -0700
Subject: 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
---
 graphics/java/android/graphics/ImageFormat.java | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

(limited to 'graphics/java')

diff --git a/graphics/java/android/graphics/ImageFormat.java b/graphics/java/android/graphics/ImageFormat.java
index b3a8fd7ba87c..f6b747a0af83 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;
-- 
cgit v1.2.3-59-g8ed1b