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
diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java
index eb0a0c6..77f826e 100644
--- a/core/java/android/hardware/Camera.java
+++ b/core/java/android/hardware/Camera.java
@@ -469,6 +469,11 @@
* 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()}.
@@ -609,12 +614,17 @@
* 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
@@ -624,8 +634,8 @@
* 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)
@@ -2270,12 +2280,44 @@
* {@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);
@@ -2293,6 +2335,7 @@
*
* @return the preview format.
* @see android.graphics.ImageFormat
+ * @see #setPreviewFormat
*/
public int getPreviewFormat() {
return pixelFormatForCameraFormat(get(KEY_PREVIEW_FORMAT));
@@ -2306,6 +2349,7 @@
* @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 @@
* </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;