Image/Reader/Writer: address API review comments (d99dc329) · Commits · e / os / android_frameworks_base

api/current.txt

+3 −6

Original line number	Diff line number	Diff line
		@@ -15230,7 +15230,6 @@ package android.media {
		method public abstract android.media.Image.Plane[] getPlanes();
		method public abstract long getTimestamp();
		method public abstract int getWidth();
		method public boolean isOpaque();
		method public void setCropRect(android.graphics.Rect);
		method public void setTimestamp(long);
		}
		@@ -15250,9 +15249,7 @@ package android.media {
		method public int getMaxImages();
		method public android.view.Surface getSurface();
		method public int getWidth();
		method public boolean isOpaque();
		method public static android.media.ImageReader newInstance(int, int, int, int);
		method public static android.media.ImageReader newOpaqueInstance(int, int, int);
		method public void setOnImageAvailableListener(android.media.ImageReader.OnImageAvailableListener, android.os.Handler);
		}

		@@ -15267,11 +15264,11 @@ package android.media {
		method public int getMaxImages();
		method public static android.media.ImageWriter newInstance(android.view.Surface, int);
		method public void queueInputImage(android.media.Image);
		method public void setImageListener(android.media.ImageWriter.ImageListener, android.os.Handler);
		method public void setOnImageReleasedListener(android.media.ImageWriter.OnImageReleasedListener, android.os.Handler);
		}

		public static abstract interface ImageWriter.ImageListener {
		method public abstract void onInputImageReleased(android.media.ImageWriter);
		public static abstract interface ImageWriter.OnImageReleasedListener {
		method public abstract void onImageReleased(android.media.ImageWriter);
		}

		public class JetPlayer {

api/system-current.txt

+3 −6

Original line number	Diff line number	Diff line
		@@ -16467,7 +16467,6 @@ package android.media {
		method public abstract android.media.Image.Plane[] getPlanes();
		method public abstract long getTimestamp();
		method public abstract int getWidth();
		method public boolean isOpaque();
		method public void setCropRect(android.graphics.Rect);
		method public void setTimestamp(long);
		}
		@@ -16487,9 +16486,7 @@ package android.media {
		method public int getMaxImages();
		method public android.view.Surface getSurface();
		method public int getWidth();
		method public boolean isOpaque();
		method public static android.media.ImageReader newInstance(int, int, int, int);
		method public static android.media.ImageReader newOpaqueInstance(int, int, int);
		method public void setOnImageAvailableListener(android.media.ImageReader.OnImageAvailableListener, android.os.Handler);
		}

		@@ -16504,11 +16501,11 @@ package android.media {
		method public int getMaxImages();
		method public static android.media.ImageWriter newInstance(android.view.Surface, int);
		method public void queueInputImage(android.media.Image);
		method public void setImageListener(android.media.ImageWriter.ImageListener, android.os.Handler);
		method public void setOnImageReleasedListener(android.media.ImageWriter.OnImageReleasedListener, android.os.Handler);
		}

		public static abstract interface ImageWriter.ImageListener {
		method public abstract void onInputImageReleased(android.media.ImageWriter);
		public static abstract interface ImageWriter.OnImageReleasedListener {
		method public abstract void onImageReleased(android.media.ImageWriter);
		}

		public class JetPlayer {

media/java/android/media/Image.java

+16 −23

Original line number	Diff line number	Diff line
		@@ -163,10 +163,12 @@ public abstract class Image implements AutoCloseable {
		* Get the timestamp associated with this frame.
		* <p>
		* The timestamp is measured in nanoseconds, and is normally monotonically
		* increasing. However, the behavior of the timestamp depends on the source
		* of this image. See {@link android.hardware.Camera Camera},
		* {@link android.hardware.camera2.CameraDevice CameraDevice}, {@link MediaPlayer} and
		* {@link MediaCodec} for more details.
		* increasing. The timestamps for the images from different sources may have
		* different timebases therefore may not be comparable. The specific meaning and
		* timebase of the timestamp depend on the source providing images. See
		* {@link android.hardware.Camera Camera},
		* {@link android.hardware.camera2.CameraDevice CameraDevice},
		* {@link MediaPlayer} and {@link MediaCodec} for more details.
		* </p>
		*/
		public abstract long getTimestamp();
		@@ -175,9 +177,11 @@ public abstract class Image implements AutoCloseable {
		* Set the timestamp associated with this frame.
		* <p>
		* The timestamp is measured in nanoseconds, and is normally monotonically
		* increasing. However, the behavior of the timestamp depends on
		* the destination of this image. See {@link android.hardware.Camera Camera}
		* , {@link android.hardware.camera2.CameraDevice CameraDevice},
		* increasing. The timestamps for the images from different sources may have
		* different timebases therefore may not be comparable. The specific meaning and
		* timebase of the timestamp depend on the source providing images. See
		* {@link android.hardware.Camera Camera},
		* {@link android.hardware.camera2.CameraDevice CameraDevice},
		* {@link MediaPlayer} and {@link MediaCodec} for more details.
		* </p>
		* <p>
		@@ -195,18 +199,6 @@ public abstract class Image implements AutoCloseable {
		return;
		}

		/**
		* <p>Check if the image is opaque.</p>
		*
		* <p>The pixel data of opaque images are not accessible to the application,
		* and therefore {@link #getPlanes} will return an empty array for an opaque image.
		* </p>
		*/
		public boolean isOpaque() {
		throwISEIfImageIsInvalid();
		return false;
		}

		private Rect mCropRect;

		/**
		@@ -243,10 +235,11 @@ public abstract class Image implements AutoCloseable {

		/**
		* Get the array of pixel planes for this Image. The number of planes is
		* determined by the format of the Image. The application will get an
		* empty array if the image is opaque because the opaque image pixel data
		* is not directly accessible. The application can check if an image is
		* opaque by calling {@link Image#isOpaque}.
		* determined by the format of the Image. The application will get an empty
		* array if the image format is {@link android.graphics.ImageFormat#PRIVATE
		* PRIVATE}, because the image pixel data is not directly accessible. The
		* application can check the image format by calling
		* {@link Image#getFormat()}.
		*/
		public abstract Plane[] getPlanes();

media/java/android/media/ImageReader.java

+26 −80

Original line number	Diff line number	Diff line
		@@ -67,77 +67,46 @@ public class ImageReader implements AutoCloseable {
		*/
		private static final int ACQUIRE_MAX_IMAGES = 2;

		/**
		* <p>Create a new reader for images of the desired size and format.</p>
		*
		* <p>The {@code maxImages} parameter determines the maximum number of {@link Image}
		* objects that can be be acquired from the {@code ImageReader}
		* simultaneously. Requesting more buffers will use up more memory, so it is
		* important to use only the minimum number necessary for the use case.</p>
		*
		* <p>The valid sizes and formats depend on the source of the image
		* data.</p>
		*
		* @param width
		* The default width in pixels of the Images that this reader will produce.
		* @param height
		* The default height in pixels of the Images that this reader will produce.
		* @param format
		* The format of the Image that this reader will produce. This
		* must be one of the {@link android.graphics.ImageFormat} or
		* {@link android.graphics.PixelFormat} constants. Note that
		* not all formats is supported, like ImageFormat.NV21.
		* @param maxImages
		* The maximum number of images the user will want to
		* access simultaneously. This should be as small as possible to limit
		* memory use. Once maxImages Images are obtained by the user, one of them
		* has to be released before a new Image will become available for access
		* through {@link #acquireLatestImage()} or {@link #acquireNextImage()}.
		* Must be greater than 0.
		*
		* @see Image
		*/
		public static ImageReader newInstance(int width, int height, int format, int maxImages) {
		if (format == ImageFormat.PRIVATE) {
		throw new IllegalArgumentException("To obtain an opaque ImageReader, please use"
		+ " newOpaqueInstance rather than newInstance");
		}
		return new ImageReader(width, height, format, maxImages);
		}

		/**
		* <p>
		* Create a new opaque reader for images of the desired size.
		* </p>
		* <p>
		* An opaque {@link ImageReader} produces images that are not directly
		* accessible by the application. The application can still acquire images
		* from an opaque image reader, and send them to the
		* {@link android.hardware.camera2.CameraDevice camera} for reprocessing via
		* {@link ImageWriter} interface. However, the {@link Image#getPlanes()
		* getPlanes()} will return an empty array for opaque images. The
		* application can check if an existing reader is an opaque reader by
		* calling {@link #isOpaque()}.
		* Create a new reader for images of the desired size and format.
		* </p>
		* <p>
		* The {@code maxImages} parameter determines the maximum number of
		* {@link Image} objects that can be be acquired from the
		* {@code ImageReader} simultaneously. Requesting more buffers will use up
		* more memory, so it is important to use only the minimum number necessary.
		* more memory, so it is important to use only the minimum number necessary
		* for the use case.
		* </p>
		* <p>
		* The valid sizes and formats depend on the source of the image data.
		* </p>
		* <p>
		* Opaque ImageReaders are more efficient to use when application access to
		* image data is not necessary, compared to ImageReaders using a non-opaque
		* format such as {@link ImageFormat#YUV_420_888 YUV_420_888}.
		* If the {@code format} is {@link ImageFormat#PRIVATE PRIVATE}, the created
		* {@link ImageReader} will produce images that are not directly accessible
		* by the application. The application can still acquire images from this
		* {@link ImageReader}, and send them to the
		* {@link android.hardware.camera2.CameraDevice camera} for reprocessing via
		* {@link ImageWriter} interface. However, the {@link Image#getPlanes()
		* getPlanes()} will return an empty array for {@link ImageFormat#PRIVATE
		* PRIVATE} format images. The application can check if an existing reader's
		* format by calling {@link #getImageFormat()}.
		* </p>
		* <p>
		* {@link ImageFormat#PRIVATE PRIVATE} format {@link ImageReader
		* ImageReaders} are more efficient to use when application access to image
		* data is not necessary, compared to ImageReaders using other format such
		* as {@link ImageFormat#YUV_420_888 YUV_420_888}.
		* </p>
		*
		* @param width The default width in pixels of the Images that this reader
		* will produce.
		* @param height The default height in pixels of the Images that this reader
		* will produce.
		* @param format The format of the Image that this reader will produce. This
		* must be one of the {@link android.graphics.ImageFormat} or
		* {@link android.graphics.PixelFormat} constants. Note that not
		* all formats are supported, like ImageFormat.NV21.
		* @param maxImages The maximum number of images the user will want to
		* access simultaneously. This should be as small as possible to
		* limit memory use. Once maxImages Images are obtained by the
		@@ -147,8 +116,8 @@ public class ImageReader implements AutoCloseable {
		* Must be greater than 0.
		* @see Image
		*/
		public static ImageReader newOpaqueInstance(int width, int height, int maxImages) {
		return new ImageReader(width, height, ImageFormat.PRIVATE, maxImages);
		public static ImageReader newInstance(int width, int height, int format, int maxImages) {
		return new ImageReader(width, height, format, maxImages);
		}

		/**
		@@ -247,23 +216,6 @@ public class ImageReader implements AutoCloseable {
		return mMaxImages;
		}

		/**
		* <p>
		* Check if the {@link ImageReader} is an opaque reader.
		* </p>
		* <p>
		* An opaque image reader produces opaque images, see {@link Image#isOpaque}
		* for more details.
		* </p>
		*
		* @return true if the ImageReader is opaque.
		* @see Image#isOpaque
		* @see ImageReader#newOpaqueInstance
		*/
		public boolean isOpaque() {
		return mFormat == ImageFormat.PRIVATE;
		}

		/**
		* <p>Get a {@link Surface} that can be used to produce {@link Image Images} for this
		* {@code ImageReader}.</p>
		@@ -540,11 +492,11 @@ public class ImageReader implements AutoCloseable {
		* </p>
		* <p>
		* This method can be used to achieve zero buffer copy for use cases like
		* {@link android.hardware.camera2.CameraDevice Camera2 API} OPAQUE and YUV
		* {@link android.hardware.camera2.CameraDevice Camera2 API} PRIVATE and YUV
		* reprocessing, where the application can select an output image from
		* {@link ImageReader} and transfer this image directly to
		* {@link ImageWriter}, where this image can be consumed by camera directly.
		* For OPAQUE reprocessing, this is the only way to send input buffers to
		* For PRIVATE reprocessing, this is the only way to send input buffers to
		* the {@link android.hardware.camera2.CameraDevice camera} for
		* reprocessing.
		* </p>
		@@ -745,12 +697,6 @@ public class ImageReader implements AutoCloseable {
		return mPlanes.clone();
		}

		@Override
		public boolean isOpaque() {
		throwISEIfImageIsInvalid();
		return mFormat == ImageFormat.PRIVATE;
		}

		@Override
		protected final void finalize() throws Throwable {
		try {

media/java/android/media/ImageUtils.java

+9 −7

Original line number	Diff line number	Diff line
		@@ -57,7 +57,7 @@ class ImageUtils {
		case ImageFormat.RAW_SENSOR:
		case ImageFormat.RAW10:
		return 1;
		case PixelFormat.OPAQUE:
		case ImageFormat.PRIVATE:
		return 0;
		default:
		throw new UnsupportedOperationException(
		@@ -70,10 +70,11 @@ class ImageUtils {
		* Copy source image data to destination Image.
		* </p>
		* <p>
		* Only support the copy between two non-opaque images with same properties
		* (format, size, etc.). The data from the source image will be copied to
		* the byteBuffers from the destination Image starting from position zero,
		* and the destination image will be rewound to zero after copy is done.
		* Only support the copy between two non-{@link ImageFormat#PRIVATE PRIVATE} format
		* images with same properties (format, size, etc.). The data from the
		* source image will be copied to the byteBuffers from the destination Image
		* starting from position zero, and the destination image will be rewound to
		* zero after copy is done.
		* </p>
		*
		* @param src The source image to be copied from.
		@@ -88,8 +89,9 @@ class ImageUtils {
		if (src.getFormat() != dst.getFormat()) {
		throw new IllegalArgumentException("Src and dst images should have the same format");
		}
		if (src.isOpaque() \|\| dst.isOpaque()) {
		throw new IllegalArgumentException("Opaque image is not copyable");
		if (src.getFormat() == ImageFormat.PRIVATE \|\|
		dst.getFormat() == ImageFormat.PRIVATE) {
		throw new IllegalArgumentException("PRIVATE format images are not copyable");
		}
		if (!(dst.getOwner() instanceof ImageWriter)) {
		throw new IllegalArgumentException("Destination image is not from ImageWriter. Only"