to top
Android APIs
public abstract class

Image

extends Object
implements AutoCloseable
java.lang.Object
   ↳ android.media.Image

Class Overview

A single complete image buffer to use with a media source such as a MediaCodec.

This class allows for efficient direct application access to the pixel data of the Image through one or more ByteBuffers. Each buffer is encapsulated in a Image.Plane that describes the layout of the pixel data in that plane. Due to this direct access, and unlike the Bitmap class, Images are not directly usable as as UI resources.

Since Images are often directly produced or consumed by hardware components, they are a limited resource shared across the system, and should be closed as soon as they are no longer needed.

For example, when using the ImageReader class to read out Images from various media sources, not closing old Image objects will prevent the availability of new Images once the maximum outstanding image count is reached. When this happens, the function acquiring new Images will typically throw an IllegalStateException.

See Also

Summary

Nested Classes
class Image.Plane

A single color plane of image data. 

Public Methods
abstract void close()
Free up this frame for reuse.
abstract int getFormat()
Get the format for this image.
abstract int getHeight()
The height of the image in pixels.
abstract Plane[] getPlanes()
Get the array of pixel planes for this Image.
abstract long getTimestamp()
Get the timestamp associated with this frame.
abstract int getWidth()
The width of the image in pixels.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.lang.AutoCloseable

Public Methods

public abstract void close ()

Added in API level 19

Free up this frame for reuse.

After calling this method, calling any methods on this Image will result in an IllegalStateException, and attempting to read from ByteBuffers returned by an earlier getBuffer() call will have undefined behavior.

public abstract int getFormat ()

Added in API level 19

Get the format for this image. This format determines the number of ByteBuffers needed to represent the image, and the general layout of the pixel data in each in ByteBuffer.

The format is one of the values from ImageFormat. The mapping between the formats and the planes is as follows:

Format Plane count Layout details
JPEG 1 Compressed data, so row and pixel strides are 0. To uncompress, use BitmapFactory#decodeByteArray.
YUV_420_888 3 A luminance plane followed by the Cb and Cr chroma planes. The chroma planes have half the width and height of the luminance plane (4:2:0 subsampling). Each pixel sample in each plane has 8 bits. Each plane has its own row stride and pixel stride.

See Also

public abstract int getHeight ()

Added in API level 19

The height of the image in pixels. For formats where some color channels are subsampled, this is the height of the largest-resolution plane.

public abstract Plane[] getPlanes ()

Added in API level 19

Get the array of pixel planes for this Image. The number of planes is determined by the format of the Image.

public abstract long getTimestamp ()

Added in API level 19

Get the timestamp associated with this frame.

The timestamp is measured in nanoseconds, and is monotonically increasing. However, the zero point and whether the timestamp can be compared against other sources of time or images depend on the source of this image.

public abstract int getWidth ()

Added in API level 19

The width of the image in pixels. For formats where some color channels are subsampled, this is the width of the largest-resolution plane.