Most visited

Recently visited

Added in API level 19

ImageReader

public class ImageReader
extends Object implements AutoCloseable

java.lang.Object
   ↳ android.media.ImageReader


The ImageReader class allows direct application access to image data rendered into a Surface

Several Android media API classes accept Surface objects as targets to render to, including MediaPlayer, MediaCodec, CameraDevice, ImageWriter and RenderScript Allocations. The image sizes and formats that can be used with each source vary, and should be checked in the documentation for the specific API.

The image data is encapsulated in Image objects, and multiple such objects can be accessed at the same time, up to the number specified by the maxImages constructor parameter. New images sent to an ImageReader through its Surface are queued until accessed through the acquireLatestImage() or acquireNextImage() call. Due to memory limits, an image source will eventually stall or drop Images in trying to render to the Surface if the ImageReader does not obtain and release Images at a rate equal to the production rate.

Summary

Nested classes

interface ImageReader.OnImageAvailableListener

Callback interface for being notified that a new image is available. 

Public methods

Image acquireLatestImage()

Acquire the latest Image from the ImageReader's queue, dropping older images.

Image acquireNextImage()

Acquire the next Image from the ImageReader's queue.

void close()

Free up all the resources associated with this ImageReader.

int getHeight()

The default height of Images, in pixels.

int getImageFormat()

The default image format of Images.

int getMaxImages()

Maximum number of images that can be acquired from the ImageReader by any time (for example, with acquireNextImage()).

Surface getSurface()

Get a Surface that can be used to produce Images for this ImageReader.

int getWidth()

The default width of Images, in pixels.

static ImageReader newInstance(int width, int height, int format, int maxImages)

Create a new reader for images of the desired size and format.

void setOnImageAvailableListener(ImageReader.OnImageAvailableListener listener, Handler handler)

Register a listener to be invoked when a new image becomes available from the ImageReader.

Protected methods

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Inherited methods

From class java.lang.Object
From interface java.lang.AutoCloseable

Public methods

acquireLatestImage

Added in API level 19
Image acquireLatestImage ()

Acquire the latest Image from the ImageReader's queue, dropping older images. Returns null if no new image is available.

This operation will acquire all the images possible from the ImageReader, but close() all images that aren't the latest. This function is recommended to use over acquireNextImage() for most use-cases, as it's more suited for real-time processing.

Note that maxImages should be at least 2 for acquireLatestImage() to be any different than acquireNextImage() - discarding all-but-the-newest Image requires temporarily acquiring two Images at once. Or more generally, calling acquireLatestImage() with less than two images of margin, that is (maxImages - currentAcquiredImages < 2) will not discard as expected.

This operation will fail by throwing an IllegalStateException if maxImages have been acquired with acquireLatestImage() or acquireNextImage(). In particular a sequence of acquireLatestImage() calls greater than getMaxImages() without calling close() in-between will exhaust the underlying queue. At such a time, IllegalStateException will be thrown until more images are released with close().

Returns
Image latest frame of image data, or null if no image data is available.
Throws
IllegalStateException if too many images are currently acquired

acquireNextImage

Added in API level 19
Image acquireNextImage ()

Acquire the next Image from the ImageReader's queue. Returns null if no new image is available.

Warning: Consider using acquireLatestImage() instead, as it will automatically release older images, and allow slower-running processing routines to catch up to the newest frame. Usage of acquireNextImage() is recommended for batch/background processing. Incorrectly using this function can cause images to appear with an ever-increasing delay, followed by a complete stall where no new images seem to appear.

This operation will fail by throwing an IllegalStateException if maxImages have been acquired with acquireNextImage() or acquireLatestImage(). In particular a sequence of acquireNextImage() or acquireLatestImage() calls greater than maxImages without calling close() in-between will exhaust the underlying queue. At such a time, IllegalStateException will be thrown until more images are released with close().

Returns
Image a new frame of image data, or null if no image data is available.
Throws
IllegalStateException if maxImages images are currently acquired

See also:

close

Added in API level 19
void close ()

Free up all the resources associated with this ImageReader.

After calling this method, this ImageReader can not be used. Calling any methods on this ImageReader and Images previously provided by acquireNextImage() or acquireLatestImage() will result in an IllegalStateException, and attempting to read from ByteBuffers returned by an earlier Plane#getBuffer call will have undefined behavior.

getHeight

Added in API level 19
int getHeight ()

The default height of Images, in pixels.

The height may be overridden by the producer sending buffers to this ImageReader's Surface. If so, the actual height of the images can be found using getHeight().

Returns
int the expected height of an Image

getImageFormat

Added in API level 19
int getImageFormat ()

The default image format of Images.

Some color formats may be overridden by the producer sending buffers to this ImageReader's Surface if the default color format allows. ImageReader guarantees that all Images acquired from ImageReader (for example, with acquireNextImage()) will have a "compatible" format to what was specified in newInstance(int, int, int, int). As of now, each format is only compatible to itself. The actual format of the images can be found using getFormat().

Returns
int the expected format of an Image

See also:

getMaxImages

Added in API level 19
int getMaxImages ()

Maximum number of images that can be acquired from the ImageReader by any time (for example, with acquireNextImage()).

An image is considered acquired after it's returned by a function from ImageReader, and until the Image is closed to release the image back to the ImageReader.

Attempting to acquire more than maxImages concurrently will result in the acquire function throwing a IllegalStateException. Furthermore, while the max number of images have been acquired by the ImageReader user, the producer enqueueing additional images may stall until at least one image has been released.

Returns
int Maximum number of images for this ImageReader.

See also:

getSurface

Added in API level 19
Surface getSurface ()

Get a Surface that can be used to produce Images for this ImageReader.

Until valid image data is rendered into this Surface, the acquireNextImage() method will return null. Only one source can be producing data into this Surface at the same time, although the same Surface can be reused with a different API once the first source is disconnected from the Surface.

Returns
Surface A Surface to use for a drawing target for various APIs.

getWidth

Added in API level 19
int getWidth ()

The default width of Images, in pixels.

The width may be overridden by the producer sending buffers to this ImageReader's Surface. If so, the actual width of the images can be found using getWidth().

Returns
int the expected width of an Image

newInstance

Added in API level 19
ImageReader newInstance (int width, 
                int height, 
                int format, 
                int maxImages)

Create a new reader for images of the desired size and format.

The maxImages parameter determines the maximum number of Image objects that can be be acquired from the 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.

The valid sizes and formats depend on the source of the image data.

If the format is PRIVATE, the created ImageReader will produce images that are not directly accessible by the application. The application can still acquire images from this ImageReader, and send them to the camera for reprocessing via ImageWriter interface. However, the getPlanes() will return an empty array for PRIVATE format images. The application can check if an existing reader's format by calling getImageFormat().

PRIVATE format ImageReaders are more efficient to use when application access to image data is not necessary, compared to ImageReaders using other format such as YUV_420_888.

Parameters
width int: The default width in pixels of the Images that this reader will produce.
height int: The default height in pixels of the Images that this reader will produce.
format int: The format of the Image that this reader will produce. This must be one of the ImageFormat or PixelFormat constants. Note that not all formats are supported, like ImageFormat.NV21.
maxImages int: 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 acquireLatestImage() or acquireNextImage(). Must be greater than 0.
Returns
ImageReader

See also:

setOnImageAvailableListener

Added in API level 19
void setOnImageAvailableListener (ImageReader.OnImageAvailableListener listener, 
                Handler handler)

Register a listener to be invoked when a new image becomes available from the ImageReader.

Parameters
listener ImageReader.OnImageAvailableListener: The listener that will be run.
handler Handler: The handler on which the listener should be invoked, or null if the listener should be invoked on the calling thread's looper.
Throws
IllegalArgumentException If no handler specified and the calling thread has no looper.

Protected methods

finalize

Added in API level 19
void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the JavaTM virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Throws
Throwable

Hooray!