Skip to content

Most visited

Recently visited

navigation

Media

Files

file  NdkImage.h
 
file  NdkImageReader.h
 

Data Structures

struct  AImageCropRect
 
struct  AImageReader_ImageListener
 
struct  AImageReader_BufferRemovedListener
 

Typedefs

typedef typedef__BEGIN_DECLS struct AImage AImage
 
typedef struct AImageCropRect AImageCropRect
 
typedef typedef__BEGIN_DECLS struct AImageReader AImageReader
 
typedef void(* AImageReader_ImageCallback) (void *context, AImageReader *reader)
 
typedef struct AImageReader_ImageListener AImageReader_ImageListener
 
typedef void(* AImageReader_BufferRemovedCallback) (void *context, AImageReader *reader, AHardwareBuffer *buffer)
 
typedef struct AImageReader_BufferRemovedListener AImageReader_BufferRemovedListener
 

Enumerations

enum  AIMAGE_FORMATS {
  AIMAGE_FORMAT_RGBA_8888 = 0x1, AIMAGE_FORMAT_RGBX_8888 = 0x2, AIMAGE_FORMAT_RGB_888 = 0x3, AIMAGE_FORMAT_RGB_565 = 0x4,
  AIMAGE_FORMAT_RGBA_FP16 = 0x16, AIMAGE_FORMAT_YUV_420_888 = 0x23, AIMAGE_FORMAT_JPEG = 0x100, AIMAGE_FORMAT_RAW16 = 0x20,
  AIMAGE_FORMAT_RAW_PRIVATE = 0x24, AIMAGE_FORMAT_RAW10 = 0x25, AIMAGE_FORMAT_RAW12 = 0x26, AIMAGE_FORMAT_DEPTH16 = 0x44363159,
  AIMAGE_FORMAT_DEPTH_POINT_CLOUD = 0x101, AIMAGE_FORMAT_PRIVATE = 0x22
}
 

Functions

void AImage_delete (AImage *image)
 
media_status_t AImage_getWidth (const AImage *image, int32_t *width)
 
media_status_t AImage_getHeight (const AImage *image, int32_t *height)
 
media_status_t AImage_getFormat (const AImage *image, int32_t *format)
 
media_status_t AImage_getCropRect (const AImage *image, AImageCropRect *rect)
 
media_status_t AImage_getTimestamp (const AImage *image, int64_t *timestampNs)
 
media_status_t AImage_getNumberOfPlanes (const AImage *image, int32_t *numPlanes)
 
media_status_t AImage_getPlanePixelStride (const AImage *image, int planeIdx, int32_t *pixelStride)
 
media_status_t AImage_getPlaneRowStride (const AImage *image, int planeIdx, int32_t *rowStride)
 
media_status_t AImage_getPlaneData (const AImage *image, int planeIdx, uint8_t **data, int *dataLength)
 
void AImage_deleteAsync (AImage *image, int releaseFenceFd)
 
media_status_t AImage_getHardwareBuffer (const AImage *image, AHardwareBuffer **buffer)
 
media_status_t AImageReader_new (int32_t width, int32_t height, int32_t format, int32_t maxImages, AImageReader **reader)
 
void AImageReader_delete (AImageReader *reader)
 
media_status_t AImageReader_getWindow (AImageReader *reader, ANativeWindow **window)
 
media_status_t AImageReader_getWidth (const AImageReader *reader, int32_t *width)
 
media_status_t AImageReader_getHeight (const AImageReader *reader, int32_t *height)
 
media_status_t AImageReader_getFormat (const AImageReader *reader, int32_t *format)
 
media_status_t AImageReader_getMaxImages (const AImageReader *reader, int32_t *maxImages)
 
media_status_t AImageReader_acquireNextImage (AImageReader *reader, AImage **image)
 
media_status_t AImageReader_acquireLatestImage (AImageReader *reader, AImage **image)
 
media_status_t AImageReader_setImageListener (AImageReader *reader, AImageReader_ImageListener *listener)
 
media_status_t AImageReader_newWithUsage (int32_t width, int32_t height, int32_t format, uint64_t usage, int32_t maxImages, AImageReader **reader)
 
media_status_t AImageReader_acquireNextImageAsync (AImageReader *reader, AImage **image, int *acquireFenceFd)
 
media_status_t AImageReader_acquireLatestImageAsync (AImageReader *reader, AImage **image, int *acquireFenceFd)
 
media_status_t AImageReader_setBufferRemovedListener (AImageReader *reader, AImageReader_BufferRemovedListener *listener)
 

Detailed Description

Typedef Documentation

§ AImage

typedef typedef__BEGIN_DECLS struct AImage AImage

AImage is an opaque type that provides access to image generated by AImageReader.

§ AImageCropRect

Data type describing an cropped rectangle returned by AImage_getCropRect.

Note that the right and bottom coordinates are exclusive, so the width of the rectangle is (right - left) and the height of the rectangle is (bottom - top).

§ AImageReader

typedef typedef__BEGIN_DECLS struct AImageReader AImageReader

AImage is an opaque type that allows direct application access to image data rendered into a ANativeWindow.

§ AImageReader_BufferRemovedCallback

typedef void(* AImageReader_BufferRemovedCallback) (void *context, AImageReader *reader, AHardwareBuffer *buffer)

The definition of AImageReader buffer removed callback.

Parameters
contextThe optional application context provided by user in AImageReader_setBufferRemovedListener.
readerThe AImageReader of interest.
bufferThe AHardwareBuffer that is being removed from this image reader.

§ AImageReader_BufferRemovedListener

§ AImageReader_ImageCallback

typedef void(* AImageReader_ImageCallback) (void *context, AImageReader *reader)

The definition of AImageReader new image available callback.

Parameters
contextThe optional application context provided by user in AImageReader_setImageListener.
sessionThe camera capture session whose state is changing.

§ AImageReader_ImageListener

Enumeration Type Documentation

§ AIMAGE_FORMATS

Enumerator
AIMAGE_FORMAT_RGBA_8888 

32 bits RGBA format, 8 bits for each of the four channels.

Corresponding formats:

  • AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM
  • Vulkan: VK_FORMAT_R8G8B8A8_UNORM
  • OpenGL ES: GL_RGBA8
See also
AImage
AImageReader
AHardwareBuffer
AIMAGE_FORMAT_RGBX_8888 

32 bits RGBX format, 8 bits for each of the four channels.

Corresponding formats:

  • AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM
  • Vulkan: VK_FORMAT_R8G8B8A8_UNORM
  • OpenGL ES: GL_RGBA8
See also
AImage
AImageReader
AHardwareBuffer
AIMAGE_FORMAT_RGB_888 

24 bits RGB format, 8 bits for each of the three channels.

Corresponding formats:

  • AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM
  • Vulkan: VK_FORMAT_R8G8B8_UNORM
  • OpenGL ES: GL_RGB8
See also
AImage
AImageReader
AHardwareBuffer
AIMAGE_FORMAT_RGB_565 

16 bits RGB format, 5 bits for Red channel, 6 bits for Green channel, and 5 bits for Blue channel.

Corresponding formats:

  • AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM
  • Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16
  • OpenGL ES: GL_RGB565
See also
AImage
AImageReader
AHardwareBuffer
AIMAGE_FORMAT_RGBA_FP16 

64 bits RGBA format, 16 bits for each of the four channels.

Corresponding formats:

  • AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT
  • Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT
  • OpenGL ES: GL_RGBA16F
See also
AImage
AImageReader
AHardwareBuffer
AIMAGE_FORMAT_YUV_420_888 

Multi-plane Android YUV 420 format.

This format is a generic YCbCr format, capable of describing any 4:2:0 chroma-subsampled planar or semiplanar buffer (but not fully interleaved), with 8 bits per color sample.

Images in this format are always represented by three separate buffers of data, one for each color plane. Additional information always accompanies the buffers, describing the row stride and the pixel stride for each plane.

The order of planes is guaranteed such that plane #0 is always Y, plane #1 is always U (Cb), and plane #2 is always V (Cr).

The Y-plane is guaranteed not to be interleaved with the U/V planes (in particular, pixel stride is always 1 in AImage_getPlanePixelStride).

The U/V planes are guaranteed to have the same row stride and pixel stride, that is, the return value of AImage_getPlaneRowStride for the U/V plane are guaranteed to be the same, and the return value of AImage_getPlanePixelStride for the U/V plane are also guaranteed to be the same.

For example, the AImage object can provide data in this format from a ACameraDevice through an AImageReader object.

This format is always supported as an output format for the android Camera2 NDK API.

See also
AImage
AImageReader
ACameraDevice
AIMAGE_FORMAT_JPEG 

Compressed JPEG format.

This format is always supported as an output format for the android Camera2 NDK API.

AIMAGE_FORMAT_RAW16 

16 bits per pixel raw camera sensor image format, usually representing a single-channel Bayer-mosaic image.

The layout of the color mosaic, the maximum and minimum encoding values of the raw pixel data, the color space of the image, and all other needed information to interpret a raw sensor image must be queried from the ACameraDevice which produced the image.

AIMAGE_FORMAT_RAW_PRIVATE 

Private raw camera sensor image format, a single channel image with implementation depedent pixel layout.

AIMAGE_FORMAT_RAW_PRIVATE is a format for unprocessed raw image buffers coming from an image sensor. The actual structure of buffers of this format is implementation-dependent.

AIMAGE_FORMAT_RAW10 

Android 10-bit raw format.

This is a single-plane, 10-bit per pixel, densely packed (in each row), unprocessed format, usually representing raw Bayer-pattern images coming from an image sensor.

In an image buffer with this format, starting from the first pixel of each row, each 4 consecutive pixels are packed into 5 bytes (40 bits). Each one of the first 4 bytes contains the top 8 bits of each pixel, The fifth byte contains the 2 least significant bits of the 4 pixels, the exact layout data for each 4 consecutive pixels is illustrated below (Pi[j] stands for the jth bit of the ith pixel):

bit 7 bit 6 bit 5 bit 4 bit 3 bit 2 bit 1 bit 0
Byte 0: P0[9] P0[8] P0[7] P0[6] P0[5] P0[4] P0[3] P0[2]
Byte 1: P1[9] P1[8] P1[7] P1[6] P1[5] P1[4] P1[3] P1[2]
Byte 2: P2[9] P2[8] P2[7] P2[6] P2[5] P2[4] P2[3] P2[2]
Byte 3: P3[9] P3[8] P3[7] P3[6] P3[5] P3[4] P3[3] P3[2]
Byte 4: P3[1] P3[0] P2[1] P2[0] P1[1] P1[0] P0[1] P0[0]

This format assumes

  • a width multiple of 4 pixels
  • an even height
size = row stride * height

where the row stride is in bytes, not pixels.

Since this is a densely packed format, the pixel stride is always 0. The application must use the pixel data layout defined in above table to access each row data. When row stride is equal to (width * (10 / 8)), there will be no padding bytes at the end of each row, the entire image data is densely packed. When stride is larger than (width * (10 / 8)), padding bytes will be present at the end of each row.

For example, the AImage object can provide data in this format from a ACameraDevice (if supported) through a AImageReader object. The number of planes returned by AImage_getNumberOfPlanes will always be 1. The pixel stride is undefined (AImage_getPlanePixelStride will return AMEDIA_ERROR_UNSUPPORTED), and the AImage_getPlaneRowStride described the vertical neighboring pixel distance (in bytes) between adjacent rows.

See also
AImage
AImageReader
ACameraDevice
AIMAGE_FORMAT_RAW12 

Android 12-bit raw format.

This is a single-plane, 12-bit per pixel, densely packed (in each row), unprocessed format, usually representing raw Bayer-pattern images coming from an image sensor.

In an image buffer with this format, starting from the first pixel of each row, each two consecutive pixels are packed into 3 bytes (24 bits). The first and second byte contains the top 8 bits of first and second pixel. The third byte contains the 4 least significant bits of the two pixels, the exact layout data for each two consecutive pixels is illustrated below (Pi[j] stands for the jth bit of the ith pixel):

bit 7 bit 6 bit 5 bit 4 bit 3 bit 2 bit 1 bit 0
Byte 0: P0[11] P0[10] P0[ 9] P0[ 8] P0[ 7] P0[ 6] P0[ 5] P0[ 4]
Byte 1: P1[11] P1[10] P1[ 9] P1[ 8] P1[ 7] P1[ 6] P1[ 5] P1[ 4]
Byte 2: P1[ 3] P1[ 2] P1[ 1] P1[ 0] P0[ 3] P0[ 2] P0[ 1] P0[ 0]

This format assumes

  • a width multiple of 4 pixels
  • an even height
size = row stride * height

where the row stride is in bytes, not pixels.

Since this is a densely packed format, the pixel stride is always 0. The application must use the pixel data layout defined in above table to access each row data. When row stride is equal to (width * (12 / 8)), there will be no padding bytes at the end of each row, the entire image data is densely packed. When stride is larger than (width * (12 / 8)), padding bytes will be present at the end of each row.

For example, the AImage object can provide data in this format from a ACameraDevice (if supported) through a AImageReader object. The number of planes returned by AImage_getNumberOfPlanes will always be 1. The pixel stride is undefined (AImage_getPlanePixelStride will return AMEDIA_ERROR_UNSUPPORTED), and the AImage_getPlaneRowStride described the vertical neighboring pixel distance (in bytes) between adjacent rows.

See also
AImage
AImageReader
ACameraDevice
AIMAGE_FORMAT_DEPTH16 

Android dense depth image format.

Each pixel is 16 bits, representing a depth ranging measurement from a depth camera or similar sensor. The 16-bit sample consists of a confidence value and the actual ranging measurement.

The confidence value is an estimate of correctness for this sample. It is encoded in the 3 most significant bits of the sample, with a value of 0 representing 100% confidence, a value of 1 representing 0% confidence, a value of 2 representing 1/7, a value of 3 representing 2/7, and so on.

As an example, the following sample extracts the range and confidence from the first pixel of a DEPTH16-format AImage, and converts the confidence to a floating-point value between 0 and 1.f inclusive, with 1.f representing maximum confidence:

   uint16_t* data;
   int dataLength;
   AImage_getPlaneData(image, 0, (uint8_t**)&data, &dataLength);
   uint16_t depthSample = data[0];
   uint16_t depthRange = (depthSample & 0x1FFF);
   uint16_t depthConfidence = ((depthSample >> 13) & 0x7);
   float depthPercentage = depthConfidence == 0 ? 1.f : (depthConfidence - 1) / 7.f;

This format assumes

  • an even width
  • an even height
  • a horizontal stride multiple of 16 pixels
 y_size = stride * height 

When produced by a camera, the units for the range are millimeters.

AIMAGE_FORMAT_DEPTH_POINT_CLOUD 

Android sparse depth point cloud format.

A variable-length list of 3D points plus a confidence value, with each point represented by four floats; first the X, Y, Z position coordinates, and then the confidence value.

The number of points is ((size of the buffer in bytes) / 16).

The coordinate system and units of the position values depend on the source of the point cloud data. The confidence value is between 0.f and 1.f, inclusive, with 0 representing 0% confidence and 1.f representing 100% confidence in the measured position values.

As an example, the following code extracts the first depth point in a DEPTH_POINT_CLOUD format AImage:

   float* data;
   int dataLength;
   AImage_getPlaneData(image, 0, (uint8_t**)&data, &dataLength);
   float x = data[0];
   float y = data[1];
   float z = data[2];
   float confidence = data[3];
AIMAGE_FORMAT_PRIVATE 

Android private opaque image format.

The choices of the actual format and pixel data layout are entirely up to the device-specific and framework internal implementations, and may vary depending on use cases even for the same device. Also note that the contents of these buffers are not directly accessible to the application.

When an AImage of this format is obtained from an AImageReader or AImage_getNumberOfPlanes() method will return zero.

Function Documentation

§ AImage_delete()

void AImage_delete ( AImage image)

Return the image back the the system and delete the AImage object from memory.

Do NOT use the image pointer after this method returns. Note that if the parent AImageReader is closed, all the AImage objects acquired from the parent reader will be returned to system. All AImage_* methods except this method will return AMEDIA_ERROR_INVALID_OBJECT. Application still needs to call this method on those AImage objects to fully delete the AImage object from memory.

Parameters
imageThe AImage to be deleted.

§ AImage_deleteAsync()

void AImage_deleteAsync ( AImage image,
int  releaseFenceFd 
)

§ AImage_getCropRect()

media_status_t AImage_getCropRect ( const AImage image,
AImageCropRect rect 
)

Query the cropped rectangle of the input AImage.

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

Parameters
imagethe AImage of interest.
rectthe cropped rectangle of the image will be filled here if the method call succeeeds.
Returns

§ AImage_getFormat()

media_status_t AImage_getFormat ( const AImage image,
int32_t *  format 
)

Query the format of the input AImage.

The format value will be one of AIMAGE_FORMAT_* enum value.

Parameters
imagethe AImage of interest.
formatthe format of the image will be filled here if the method call succeeeds.
Returns

§ AImage_getHardwareBuffer()

media_status_t AImage_getHardwareBuffer ( const AImage image,
AHardwareBuffer **  buffer 
)

Get the hardware buffer handle of the input image intended for GPU and/or hardware access.

Note that no reference on the returned AHardwareBuffer handle is acquired automatically. Once the AImage or the parent AImageReader is deleted, the AHardwareBuffer handle from previous AImage_getHardwareBuffer becomes invalid.

If the caller ever needs to hold on a reference to the AHardwareBuffer handle after the AImage or the parent AImageReader is deleted, it must call AHardwareBuffer_acquire to acquire an extra reference, and call AHardwareBuffer_release once it has finished using it in order to properly deallocate the underlying memory managed by AHardwareBuffer. If the caller has acquired extra reference on an AHardwareBuffer returned from this function, it must also listen to onBufferFreed callback to be notified when the buffer is no longer used by AImageReader.

Parameters
imagethe AImage of interest.
outBufferThe memory area pointed to by buffer will contain the acquired AHardwareBuffer handle.
Returns
See also
AImageReader_ImageCallback

§ AImage_getHeight()

media_status_t AImage_getHeight ( const AImage image,
int32_t *  height 
)

Query the height of the input AImage.

Parameters
imagethe AImage of interest.
heightthe height of the image will be filled here if the method call succeeeds.
Returns

§ AImage_getNumberOfPlanes()

media_status_t AImage_getNumberOfPlanes ( const AImage image,
int32_t *  numPlanes 
)

Query the number of planes of the input AImage.

The number of plane of an AImage is determined by its format, which can be queried by AImage_getFormat method.

Parameters
imagethe AImage of interest.
numPlanesthe number of planes of the image will be filled here if the method call succeeeds.
Returns

§ AImage_getPlaneData()

media_status_t AImage_getPlaneData ( const AImage image,
int  planeIdx,
uint8_t **  data,
int *  dataLength 
)

Get the data pointer of the input image for direct application access.

Note that once the AImage or the parent AImageReader is deleted, the data pointer from previous AImage_getPlaneData call becomes invalid. Do NOT use it after the AImage or the parent AImageReader is deleted.

Parameters
imagethe AImage of interest.
planeIdxthe index of the plane. Must be less than the number of planes of input image.
datathe data pointer of the image will be filled here if the method call succeeeds.
dataLengththe valid length of data will be filled here if the method call succeeeds.
Returns

§ AImage_getPlanePixelStride()

media_status_t AImage_getPlanePixelStride ( const AImage image,
int  planeIdx,
int32_t *  pixelStride 
)

Query the pixel stride of the input AImage.

This is the distance between two consecutive pixel values in a row of pixels. It may be larger than the size of a single pixel to account for interleaved image data or padded formats. Note that pixel stride is undefined for some formats such as AIMAGE_FORMAT_RAW_PRIVATE, and calling this method on images of these formats will cause AMEDIA_ERROR_UNSUPPORTED being returned. For formats where pixel stride is well defined, the pixel stride is always greater than 0.

Parameters
imagethe AImage of interest.
planeIdxthe index of the plane. Must be less than the number of planes of input image.
pixelStridethe pixel stride of the image will be filled here if the method call succeeeds.
Returns

§ AImage_getPlaneRowStride()

media_status_t AImage_getPlaneRowStride ( const AImage image,
int  planeIdx,
int32_t *  rowStride 
)

Query the row stride of the input AImage.

This is the distance between the start of two consecutive rows of pixels in the image. Note that row stried is undefined for some formats such as AIMAGE_FORMAT_RAW_PRIVATE, and calling this method on images of these formats will cause AMEDIA_ERROR_UNSUPPORTED being returned. For formats where row stride is well defined, the row stride is always greater than 0.

Parameters
imagethe AImage of interest.
planeIdxthe index of the plane. Must be less than the number of planes of input image.
rowStridethe row stride of the image will be filled here if the method call succeeeds.
Returns

§ AImage_getTimestamp()

media_status_t AImage_getTimestamp ( const AImage image,
int64_t *  timestampNs 
)

Query the timestamp of the input AImage.

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. For images generated by camera, the timestamp value will match ACAMERA_SENSOR_TIMESTAMP of the ACameraMetadata in ACameraCaptureSession_captureCallbacks#onCaptureStarted and ACameraCaptureSession_captureCallbacks#onCaptureCompleted callback.

Parameters
imagethe AImage of interest.
timestampNsthe timestamp of the image will be filled here if the method call succeeeds.
Returns

§ AImage_getWidth()

media_status_t AImage_getWidth ( const AImage image,
int32_t *  width 
)

Query the width of the input AImage.

Parameters
imagethe AImage of interest.
widththe width of the image will be filled here if the method call succeeeds.
Returns

§ AImageReader_acquireLatestImage()

media_status_t AImageReader_acquireLatestImage ( AImageReader reader,
AImage **  image 
)

Acquire the latest AImage from the image reader's queue, dropping older images.

This operation will acquire all the images possible from the image reader, but AImage_delete all images that aren't the latest. This function is recommended to use over AImageReader_acquireNextImage for most use-cases, as it's more suited for real-time processing.

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

This method will fail if maxImages have been acquired with AImageReader_acquireNextImage or AImageReader_acquireLatestImage. In particular a sequence of AImageReader_acquireNextImage or AImageReader_acquireLatestImage calls greater than maxImages without calling AImage_delete in-between will exhaust the underlying queue. At such a time, AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED will be returned until more images are released with AImage_delete.

Parameters
readerThe image reader of interest.
imagethe acquired AImage will be filled here if the method call succeeeds.
Returns
See also
AImageReader_acquireNextImage

§ AImageReader_acquireLatestImageAsync()

media_status_t AImageReader_acquireLatestImageAsync ( AImageReader reader,
AImage **  image,
int *  acquireFenceFd 
)

Acquire the latest AImage from the image reader's queue asynchronously, dropping older images.

AImageReader acquire method similar to AImageReader_acquireLatestImage that takes an additional parameter for the sync fence. All other parameters and the return values are identical to those passed to AImageReader_acquireLatestImage.

Parameters
acquireFenceFdA sync fence fd defined in sync.h, which is used to signal when the buffer is ready to consume. When synchronization fence is not needed, fence will be set to -1 and the AImage returned is ready for use immediately. Otherwise, user shall use syscalls such as poll(), epoll(), select() to wait for the fence fd to change status before attempting to access the AImage returned.
See also
sync.h
sync_get_fence_info

§ AImageReader_acquireNextImage()

media_status_t AImageReader_acquireNextImage ( AImageReader reader,
AImage **  image 
)

Acquire the next AImage from the image reader's queue.

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

This method will fail if maxImages have been acquired with AImageReader_acquireNextImage or AImageReader_acquireLatestImage. In particular a sequence of AImageReader_acquireNextImage or AImageReader_acquireLatestImage calls greater than maxImages without calling AImage_delete in-between will exhaust the underlying queue. At such a time, AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED will be returned until more images are released with AImage_delete.

Parameters
readerThe image reader of interest.
imagethe acquired AImage will be filled here if the method call succeeeds.
Returns
See also
AImageReader_acquireLatestImage

§ AImageReader_acquireNextImageAsync()

media_status_t AImageReader_acquireNextImageAsync ( AImageReader reader,
AImage **  image,
int *  acquireFenceFd 
)

Acquire the next AImage from the image reader's queue asynchronously.

AImageReader acquire method similar to AImageReader_acquireNextImage that takes an additional parameter for the sync fence. All other parameters and the return values are identical to those passed to AImageReader_acquireNextImage.

Parameters
acquireFenceFdA sync fence fd defined in sync.h, which is used to signal when the buffer is ready to consume. When synchronization fence is not needed, fence will be set to -1 and the AImage returned is ready for use immediately. Otherwise, user shall use syscalls such as poll(), epoll(), select() to wait for the fence fd to change status before attempting to access the AImage returned.
See also
sync.h
sync_get_fence_info

§ AImageReader_delete()

void AImageReader_delete ( AImageReader reader)

Delete an AImageReader and return all images generated by this reader to system.

This method will return all AImage objects acquired by this reader (via AImageReader_acquireNextImage or AImageReader_acquireLatestImage) to system, making any of data pointers obtained from AImage_getPlaneData invalid. Do NOT access the reader object or any of those data pointers after this method returns.

Parameters
readerThe image reader to be deleted.

§ AImageReader_getFormat()

media_status_t AImageReader_getFormat ( const AImageReader reader,
int32_t *  format 
)

Query the format of the AImage generated by this reader.

Parameters
readerThe image reader of interest.
formatthe fromat of the reader will be filled here if the method call succeeeds. The value will be one of the AIMAGE_FORMAT_* enum value defiend in NdkImage.h.
Returns

§ AImageReader_getHeight()

media_status_t AImageReader_getHeight ( const AImageReader reader,
int32_t *  height 
)

Query the default height of the AImage generated by this reader, in pixels.

The height may be overridden by the producer sending buffers to this reader's ANativeWindow. If so, the actual height of the images can be found using AImage_getHeight.

Parameters
readerThe image reader of interest.
heightthe default height of the reader will be filled here if the method call succeeeds.
Returns

§ AImageReader_getMaxImages()

media_status_t AImageReader_getMaxImages ( const AImageReader reader,
int32_t *  maxImages 
)

Query the maximum number of concurrently acquired AImages of this reader.

Parameters
readerThe image reader of interest.
maxImagesthe maximum number of concurrently acquired images of the reader will be filled here if the method call succeeeds.
Returns

§ AImageReader_getWidth()

media_status_t AImageReader_getWidth ( const AImageReader reader,
int32_t *  width 
)

Query the default width of the AImage generated by this reader, in pixels.

The width may be overridden by the producer sending buffers to this reader's ANativeWindow. If so, the actual width of the images can be found using AImage_getWidth.

Parameters
readerThe image reader of interest.
widththe default width of the reader will be filled here if the method call succeeeds.
Returns

§ AImageReader_getWindow()

media_status_t AImageReader_getWindow ( AImageReader reader,
ANativeWindow **  window 
)

Get a ANativeWindow that can be used to produce AImage for this image reader.

Parameters
readerThe image reader of interest.
windowThe output ANativeWindow will be filled here if the method call succeeds. The ANativeWindow is managed by this image reader. Do NOT call ANativeWindow_release on it. Instead, use AImageReader_delete.
Returns

§ AImageReader_new()

media_status_t AImageReader_new ( int32_t  width,
int32_t  height,
int32_t  format,
int32_t  maxImages,
AImageReader **  reader 
)

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

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

Parameters
widthThe default width in pixels of the Images that this reader will produce.
heightThe default height in pixels of the Images that this reader will produce.
formatThe format of the Image that this reader will produce. This must be one of the AIMAGE_FORMAT_* enum value defined in AIMAGE_FORMATS. Note that not all formats are supported. One example is AIMAGE_FORMAT_PRIVATE, as it is not intended to be read by applications directly. That format is supported by AImageReader_newWithUsage introduced in API 26.
maxImagesThe 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 AImage will become available for access through AImageReader_acquireLatestImage or AImageReader_acquireNextImage. Must be greater than 0.
readerThe created image reader will be filled here if the method call succeeeds.
Returns
See also
AImage

§ AImageReader_newWithUsage()

media_status_t AImageReader_newWithUsage ( int32_t  width,
int32_t  height,
int32_t  format,
uint64_t  usage,
int32_t  maxImages,
AImageReader **  reader 
)

AImageReader constructor similar to AImageReader_new that takes an additional parameter for the consumer usage. All other parameters and the return values are identical to those passed to {

If the format is AIMAGE_FORMAT_PRIVATE, the created AImageReader will produce images whose contents are not directly accessible by the application. The application can still acquire images from this AImageReader and access AHardwareBuffer via AImage_getHardwareBuffer(). The AHardwareBuffer gained this way can then be passed back to hardware (such as GPU or hardware encoder if supported) for future processing. For example, you can obtain an EGLClientBuffer from the AHardwareBuffer by using eglGetNativeClientBufferANDROID extension and pass that EGLClientBuffer to eglCreateImageKHR to create an EGLImage resource type, which may then be bound to a texture via glEGLImageTargetTexture2DOES on supported devices. This can be useful for transporting textures that may be shared cross-process.

In general, when software access to image data is not necessary, an AImageReader created with AIMAGE_FORMAT_PRIVATE format is more efficient, compared with AImageReaders using other format such as AIMAGE_FORMAT_YUV_420_888.

Note that not all format and usage flag combination is supported by the AImageReader, especially if format is AIMAGE_FORMAT_PRIVATE, usage must not include either AHARDWAREBUFFER_USAGE_READ_RARELY or AHARDWAREBUFFER_USAGE_READ_OFTEN

Parameters
widthThe default width in pixels of the Images that this reader will produce.
heightThe default height in pixels of the Images that this reader will produce.
formatThe format of the Image that this reader will produce. This must be one of the AIMAGE_FORMAT_* enum value defined in AIMAGE_FORMATS.
usagespecifies how the consumer will access the AImage, using combination of the AHARDWAREBUFFER_USAGE flags described in hardware_buffer.h. Passing AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN is equivalent to calling AImageReader_new with the same parameters.

Note that not all format and usage flag combination is supported by the AImageReader. Below are the combinations supported by the AImageReader.

Format Compatible usage flags
non-PRIVATE formats defined in AImage.h AHARDWAREBUFFER_USAGE_CPU_READ_RARELY or AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN
AIMAGE_FORMAT_RGBA_8888 AHARDWAREBUFFER_USAGE_VIDEO_ENCODE or AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE, or combined
Returns
See also
AImage
AImageReader_new
AHardwareBuffer

§ AImageReader_setBufferRemovedListener()

media_status_t AImageReader_setBufferRemovedListener ( AImageReader reader,
AImageReader_BufferRemovedListener listener 
)

Set the onBufferRemoved listener of this image reader.

Note that calling this method will replace previously registered listeners.

Parameters
readerThe image reader of interest.
listenerthe AImageReader_BufferRemovedListener to be registered. Set this to NULL if application no longer needs to listen to buffer removed events.
Returns
See also
AImage_getHardwareBuffer

§ AImageReader_setImageListener()

media_status_t AImageReader_setImageListener ( AImageReader reader,
AImageReader_ImageListener listener 
)

Set the onImageAvailable listener of this image reader.

Note that calling this method will replace previously registered listeners.

Parameters
readerThe image reader of interest.
listenerthe AImageReader_ImageListener to be registered. Set this to NULL if application no longer needs to listen to new images.
Returns
This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience. (Dec 2017 Android Platform & Tools Survey)