am 163a3ae7: Merge "Update docs for YV12 format and camera preview callbacks." into jb-dev (b239d1a9) · Commits · e / os / android_frameworks_base

core/java/android/hardware/Camera.java

+57 −13

Original line number	Diff line number	Diff line
		@@ -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);

graphics/java/android/graphics/ImageFormat.java

+14 −2

Original line number	Diff line number	Diff line
		@@ -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;