Merge "Update docs for YV12 format and camera preview callbacks." into jb-dev

2 files changed, 71 insertions, 15 deletions

diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java
index 5ed8dd1..a8308c4 100644
--- a/core/java/android/hardware/Camera.java
+++ b/core/java/android/hardware/Camera.java
@@ -471,6 +471,11 @@ public class Camera {
          * Called as preview frames are displayed.  This callback is invoked
          * on the event thread {@link #open(int)} was called from.
          *
+         * <p>If using the {@link android.graphics.ImageFormat#YV12} format,
+         * refer to the equations in {@link Camera.Parameters#setPreviewFormat}
+         * for the arrangement of the pixel data in the preview callback
+         * buffers.
+         *
          * @param data the contents of the preview frame in the format defined
          *  by {@link android.graphics.ImageFormat}, which can be queried
          *  with {@link android.hardware.Camera.Parameters#getPreviewFormat()}.
@@ -611,12 +616,17 @@ public class Camera {
      * the frame is discarded. Applications should add buffers back when they
      * finish processing the data in them.
      *
-     * <p>The size of the buffer is determined by multiplying the preview
-     * image width, height, and bytes per pixel. The width and height can be
-     * read from {@link Camera.Parameters#getPreviewSize()}. Bytes per pixel
-     * can be computed from
-     * {@link android.graphics.ImageFormat#getBitsPerPixel(int)} / 8,
-     * using the image format from {@link Camera.Parameters#getPreviewFormat()}.
+     * <p>For formats besides YV12, the size of the buffer is determined by
+     * multiplying the preview image width, height, and bytes per pixel. The
+     * width and height can be read from
+     * {@link Camera.Parameters#getPreviewSize()}. Bytes per pixel can be
+     * computed from {@link android.graphics.ImageFormat#getBitsPerPixel(int)} /
+     * 8, using the image format from
+     * {@link Camera.Parameters#getPreviewFormat()}.
+     *
+     * <p>If using the {@link android.graphics.ImageFormat#YV12} format, the
+     * size can be calculated using the equations listed in
+     * {@link Camera.Parameters#setPreviewFormat}.
      *
      * <p>This method is only necessary when
      * {@link #setPreviewCallbackWithBuffer(PreviewCallback)} is used. When
@@ -626,8 +636,8 @@ public class Camera {
      * hold the preview frame data, preview callback will return null and
      * the buffer will be removed from the buffer queue.
      *
-     * @param callbackBuffer the buffer to add to the queue.
-     *     The size should be width * height * bits_per_pixel / 8.
+     * @param callbackBuffer the buffer to add to the queue. The size of the
+     *   buffer must match the values described above.
      * @see #setPreviewCallbackWithBuffer(PreviewCallback)
      */
     public final void addCallbackBuffer(byte[] callbackBuffer)
@@ -2289,12 +2299,44 @@ public class Camera {
          * {@link android.graphics.ImageFormat#NV21}, which
          * uses the NV21 encoding format.</p>
          *
-         * @param pixel_format the desired preview picture format, defined
-         *   by one of the {@link android.graphics.ImageFormat} constants.
-         *   (E.g., <var>ImageFormat.NV21</var> (default),
-         *                      <var>ImageFormat.RGB_565</var>, or
-         *                      <var>ImageFormat.JPEG</var>)
+         * <p>Use {@link Parameters#getSupportedPreviewFormats} to get a list of
+         * the available preview formats.
+         *
+         * <p>It is strongly recommended that either
+         * {@link android.graphics.ImageFormat#NV21} or
+         * {@link android.graphics.ImageFormat#YV12} is used, since
+         * they are supported by all camera devices.</p>
+         *
+         * <p>For YV12, the image buffer that is received is not necessarily
+         * tightly packed, as there may be padding at the end of each row of
+         * pixel data, as described in
+         * {@link android.graphics.ImageFormat#YV12}. For camera callback data,
+         * it can be assumed that the stride of the Y and UV data is the
+         * smallest possible that meets the alignment requirements. That is, if
+         * the preview size is <var>width x height</var>, then the following
+         * equations describe the buffer index for the beginning of row
+         * <var>y</var> for the Y plane and row <var>c</var> for the U and V
+         * planes:
+         *
+         * {@code
+         * <pre>
+         * yStride   = (int) ceil(width / 16.0) * 16;
+         * uvStride  = (int) ceil( (yStride / 2) / 16.0) * 16;
+         * ySize     = yStride * height;
+         * uvSize    = uvStride * height / 2;
+         * yRowIndex = yStride * y;
+         * uRowIndex = ySize + uvSize + uvStride * c;
+         * vRowIndex = ySize + uvStride * c;
+         * size      = ySize + uvSize * 2;</pre>
+         * }
+         *
+         * @param pixel_format the desired preview picture format, defined by
+         *   one of the {@link android.graphics.ImageFormat} constants.  (E.g.,
+         *   <var>ImageFormat.NV21</var> (default), or
+         *   <var>ImageFormat.YV12</var>)
+         *
          * @see android.graphics.ImageFormat
+         * @see android.hardware.Camera.Parameters#getSupportedPreviewFormats
          */
         public void setPreviewFormat(int pixel_format) {
             String s = cameraFormatForPixelFormat(pixel_format);
@@ -2312,6 +2354,7 @@ public class Camera {
          *
          * @return the preview format.
          * @see android.graphics.ImageFormat
+         * @see #setPreviewFormat
          */
         public int getPreviewFormat() {
             return pixelFormatForCameraFormat(get(KEY_PREVIEW_FORMAT));
@@ -2325,6 +2368,7 @@ public class Camera {
          * @return a list of supported preview formats. This method will always
          *         return a list with at least one element.
          * @see android.graphics.ImageFormat
+         * @see #setPreviewFormat
          */
         public List<Integer> getSupportedPreviewFormats() {
             String str = get(KEY_PREVIEW_FORMAT + SUPPORTED_VALUES_SUFFIX);
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;