Summary: Nested Classes | Methods | Inherited Methods | [Expand All]

Added in API level 19

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 or a CameraDevice.

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.

Summary

Nested Classes
class	Image.Plane	A single color plane of image data.

Public Methods
abstract void	close() Free up this frame for reuse.
Rect	getCropRect() Get the crop rectangle associated with this frame.
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.
void	setCropRect(Rect cropRect) Set the crop rectangle associated with this frame.
void	setTimestamp(long timestamp) Set the timestamp associated with this frame.

[Expand]

Inherited Methods

From class java.lang.Object

Object	clone() Creates and returns a copy of this `Object`.
boolean	equals(Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of `Class` that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.
final void	wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait(long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.

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 or write to ByteBuffers returned by an earlier getBuffer() call will have undefined behavior. If the image was obtained from ImageWriter via dequeueInputImage(), after calling this method, any image data filled by the application will be lost and the image will be returned to ImageWriter for reuse. Images given to queueInputImage() are automatically closed.

public Rect getCropRect ()

Added in API level 21

Get the crop rectangle associated with this frame.

The crop rectangle specifies the region of valid pixels in the image, using coordinates in the largest-resolution plane.

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.
`YUV_422_888`	3	A luminance plane followed by the Cb and Cr chroma planes. The chroma planes have half the width and the full height of the luminance plane (4:2:2 subsampling). Each pixel sample in each plane has 8 bits. Each plane has its own row stride and pixel stride.
`YUV_444_888`	3	A luminance plane followed by the Cb and Cr chroma planes. The chroma planes have the same width and height as that of the luminance plane (4:4:4 subsampling). Each pixel sample in each plane has 8 bits. Each plane has its own row stride and pixel stride.
`FLEX_RGB_888`	3	A R (red) plane followed by the G (green) and B (blue) planes. All planes have the same widths and heights. Each pixel sample in each plane has 8 bits. Each plane has its own row stride and pixel stride.
`FLEX_RGBA_8888`	4	A R (red) plane followed by the G (green), B (blue), and A (alpha) planes. All planes have the same widths and heights. Each pixel sample in each plane has 8 bits. Each plane has its own row stride and pixel stride.
`RAW_SENSOR`	1	A single plane of raw sensor image data, with 16 bits per color sample. The details of the layout need to be queried from the source of the raw sensor data, such as `CameraDevice`.

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. The application will get an empty array if the image format is PRIVATE, because the image pixel data is not directly accessible. The application can check the image format by calling getFormat().

public abstract long getTimestamp ()

Added in API level 19

Get the timestamp associated with this frame.

The timestamp is measured in nanoseconds, and is normally monotonically 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 Camera, CameraDevice, MediaPlayer and MediaCodec for more details.

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.

public void setCropRect (Rect cropRect)

Added in API level 21

Set the crop rectangle associated with this frame.

The crop rectangle specifies the region of valid pixels in the image, using coordinates in the largest-resolution plane.

public void setTimestamp (long timestamp)

Added in API level 23

Set the timestamp associated with this frame.

For images dequeued from ImageWriter via dequeueInputImage(), it's up to the application to set the timestamps correctly before sending them back to the ImageWriter, or the timestamp will be generated automatically when queueInputImage() is called.

Parameters

timestamp	The timestamp to be set for this image.

Results

Interfaces

Classes

Exceptions

Image

Class Overview

See Also

Summary

Public Methods

public abstract void close ()

public Rect getCropRect ()

public abstract int getFormat ()

See Also

public abstract int getHeight ()

public abstract Plane[] getPlanes ()

public abstract long getTimestamp ()

public abstract int getWidth ()

public void setCropRect (Rect cropRect)

public void setTimestamp (long timestamp)

Parameters