ImageDecoder

#include <imagedecoder.h>

Functions for converting encoded images into RGBA pixels.

Summary

Similar to the Java counterpart android.graphics.ImageDecoder, it can be used to decode images in the following formats:

  • JPEG
  • PNG
  • GIF
  • WebP
  • BMP
  • ICO
  • WBMP
  • HEIF
  • Digital negatives (via the DNG SDK)

It has similar options for scaling, cropping, and choosing the output format. Unlike the Java API, which can create an android.graphics.Bitmap or android.graphics.drawable.Drawable object, AImageDecoder decodes directly into memory provided by the client. For more information, see the Image decoder developer guide.

Enumerations

Anonymous Enum 26{
  ANDROID_IMAGE_DECODER_SUCCESS = 0,
  ANDROID_IMAGE_DECODER_INCOMPLETE = -1,
  ANDROID_IMAGE_DECODER_ERROR = -2,
  ANDROID_IMAGE_DECODER_INVALID_CONVERSION = -3,
  ANDROID_IMAGE_DECODER_INVALID_SCALE = -4,
  ANDROID_IMAGE_DECODER_BAD_PARAMETER = -5,
  ANDROID_IMAGE_DECODER_INVALID_INPUT = -6,
  ANDROID_IMAGE_DECODER_SEEK_ERROR = -7,
  ANDROID_IMAGE_DECODER_INTERNAL_ERROR = -8,
  ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT = -9
}
enum
AImageDecoder functions result code.

Typedefs

AImageDecoder typedef
struct AImageDecoder
Opaque handle for decoding images.
AImageDecoderHeaderInfo typedef
Opaque handle for representing information about the encoded image.

Functions

AImageDecoderHeaderInfo_getAlphaFlags(const AImageDecoderHeaderInfo *)
int
Report how the AImageDecoder will handle alpha by default.
AImageDecoderHeaderInfo_getAndroidBitmapFormat(const AImageDecoderHeaderInfo *)
int32_t
Report the AndroidBitmapFormat the AImageDecoder will decode to by default.
AImageDecoderHeaderInfo_getDataSpace(const AImageDecoderHeaderInfo *)
int32_t
Report the dataspace the AImageDecoder will decode to by default.
AImageDecoderHeaderInfo_getHeight(const AImageDecoderHeaderInfo *)
int32_t
Report the native height of the encoded image.
AImageDecoderHeaderInfo_getMimeType(const AImageDecoderHeaderInfo *)
const char *
Report the mimeType of the encoded image.
AImageDecoderHeaderInfo_getWidth(const AImageDecoderHeaderInfo *)
int32_t
Report the native width of the encoded image.
AImageDecoder_computeSampledSize(const AImageDecoder *, int sampleSize, int32_t *width, int32_t *height)
int
Compute the dimensions to use for a given sampleSize.
AImageDecoder_createFromAAsset(struct AAsset *asset, AImageDecoder **outDecoder)
int
Create a new AImageDecoder from an AAsset.
AImageDecoder_createFromBuffer(const void *buffer, size_t length, AImageDecoder **outDecoder)
int
Create a new AImageDecoder from a buffer.
AImageDecoder_createFromFd(int fd, AImageDecoder **outDecoder)
int
Create a new AImageDecoder from a file descriptor.
AImageDecoder_decodeImage(AImageDecoder *decoder, void *pixels, size_t stride, size_t size)
int
Decode the image into pixels, using the settings of the AImageDecoder.
AImageDecoder_delete(AImageDecoder *decoder)
void
Delete the AImageDecoder.
AImageDecoder_getHeaderInfo(const AImageDecoder *)
Return an opaque handle for reading header info.
AImageDecoder_getMinimumStride(AImageDecoder *)
size_t
Return the minimum stride that can be used in AImageDecoder_decodeImage).
AImageDecoder_setAndroidBitmapFormat(AImageDecoder *, int32_t format)
int
Choose the desired output format.
AImageDecoder_setCrop(AImageDecoder *, ARect crop)
int
Specify how to crop the output after scaling (if any).
AImageDecoder_setDataSpace(AImageDecoder *, int32_t dataspace)
int
Choose the dataspace for the output.
AImageDecoder_setTargetSize(AImageDecoder *, int32_t width, int32_t height)
int
Specify the output size for a decoded image.
AImageDecoder_setUnpremultipliedRequired(AImageDecoder *, bool unpremultipliedRequired)
int
Specify whether the output's pixels should be unpremultiplied.

Enumerations

Anonymous Enum 26

 Anonymous Enum 26

AImageDecoder functions result code.

Many functions will return one of these to indicate success (ANDROID_IMAGE_DECODER_SUCCESS) or the reason for the failure. On failure, any out-parameters should be considered uninitialized, except where specified.

Properties
ANDROID_IMAGE_DECODER_BAD_PARAMETER

Some other parameter is invalid.

ANDROID_IMAGE_DECODER_ERROR

The input contained an error after decoding some lines.

ANDROID_IMAGE_DECODER_INCOMPLETE

The input is incomplete.

ANDROID_IMAGE_DECODER_INTERNAL_ERROR

Some other error.

For example, an internal allocation failed.

ANDROID_IMAGE_DECODER_INVALID_CONVERSION

Could not convert.

For example, attempting to decode an image with alpha to an opaque format.

ANDROID_IMAGE_DECODER_INVALID_INPUT

Input was invalid before decoding any pixels.

ANDROID_IMAGE_DECODER_INVALID_SCALE

The scale is invalid.

It may have overflowed, or it may be incompatible with the current alpha setting.

ANDROID_IMAGE_DECODER_SEEK_ERROR

A seek was required and it failed.

ANDROID_IMAGE_DECODER_SUCCESS

Decoding was successful and complete.

ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT

AImageDecoder did not recognize the format.

Typedefs

AImageDecoder

struct AImageDecoder AImageDecoder

Opaque handle for decoding images.

Create using one of the following:

After creation, AImageDecoder_getHeaderInfo can be used to retrieve information about the encoded image. Other functions, like AImageDecoder_setTargetSize, can be used to specify how to decode, and AImageDecoder_decode will decode into client provided memory.

AImageDecoder objects are NOT thread-safe, and should not be shared across threads.

AImageDecoderHeaderInfo

struct AImageDecoderHeaderInfo AImageDecoderHeaderInfo

Opaque handle for representing information about the encoded image.

Retrieved using AImageDecoder_getHeaderInfo and passed to methods like AImageDecoderHeaderInfo_getWidth and AImageDecoderHeaderInfo_getHeight.

Functions

AImageDecoderHeaderInfo_getAlphaFlags

int AImageDecoderHeaderInfo_getAlphaFlags(
  const AImageDecoderHeaderInfo *
)

Report how the AImageDecoder will handle alpha by default.

If the image contains no alpha (according to its header), this will return ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE. If the image may contain alpha, this returns ANDROID_BITMAP_FLAGS_ALPHA_PREMUL, because AImageDecoder_decodeImage will premultiply pixels by default.

Available since API level 30.

AImageDecoderHeaderInfo_getAndroidBitmapFormat

int32_t AImageDecoderHeaderInfo_getAndroidBitmapFormat(
  const AImageDecoderHeaderInfo *
)

Report the AndroidBitmapFormat the AImageDecoder will decode to by default.

AImageDecoder will try to choose one that is sensible for the image and the system. Note that this does not indicate the encoded format of the image.

Available since API level 30.

AImageDecoderHeaderInfo_getDataSpace

int32_t AImageDecoderHeaderInfo_getDataSpace(
  const AImageDecoderHeaderInfo *
)

Report the dataspace the AImageDecoder will decode to by default.

By default, AImageDecoder_decodeImage will not do any color conversion.

Available since API level 30.

Note that ADataSpace only exposes a few values. This may return ADATASPACE_UNKNOWN, even for Named ColorSpaces, if they have no corresponding ADataSpace.

Details
Returns
The ADataSpace representing the way the colors are encoded (or ADATASPACE_UNKNOWN if there is not a corresponding ADataSpace). This specifies how to interpret the colors in the decoded image, unless AImageDecoder_setDataSpace is called to decode to a different ADataSpace.

AImageDecoderHeaderInfo_getHeight

int32_t AImageDecoderHeaderInfo_getHeight(
  const AImageDecoderHeaderInfo *
)

Report the native height of the encoded image.

This is also the logical pixel height of the output, unless AImageDecoder_setTargetSize is used to choose a different size or AImageDecoder_setCrop is used to set a crop rect.

Available since API level 30.

AImageDecoderHeaderInfo_getMimeType

const char * AImageDecoderHeaderInfo_getMimeType(
  const AImageDecoderHeaderInfo *
)

Report the mimeType of the encoded image.

Available since API level 30.

Details
Returns
a string literal describing the mime type.

AImageDecoderHeaderInfo_getWidth

int32_t AImageDecoderHeaderInfo_getWidth(
  const AImageDecoderHeaderInfo *
)

Report the native width of the encoded image.

This is also the logical pixel width of the output, unless AImageDecoder_setTargetSize is used to choose a different size or AImageDecoder_setCrop is used to set a crop rect.

Available since API level 30.

AImageDecoder_computeSampledSize

int AImageDecoder_computeSampledSize(
  const AImageDecoder *,
  int sampleSize,
  int32_t *width,
  int32_t *height
)

Compute the dimensions to use for a given sampleSize.

Although AImageDecoder can scale to an arbitrary target size (see AImageDecoder_setTargetSize), some sizes may be more efficient than others. This computes the most efficient target size to use to reach a particular sampleSize.

Available since API level 30.

Errors:

Details
Parameters
sampleSize
A subsampling rate of the original image. Must be greater than or equal to 1. A sampleSize of 2 means to skip every other pixel/line, resulting in a width and height that are 1/2 of the original dimensions, with 1/4 the number of pixels.
width
Out parameter for the width sampled by sampleSize, and rounded in the direction that the decoder can do most efficiently.
height
Out parameter for the height sampled by sampleSize, and rounded in the direction that the decoder can do most efficiently.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.

AImageDecoder_createFromAAsset

int AImageDecoder_createFromAAsset(
  struct AAsset *asset,
  AImageDecoder **outDecoder
)

Create a new AImageDecoder from an AAsset.

Available since API level 30.

Errors:

Details
Parameters
asset
AAsset containing encoded image data. Client is still responsible for calling AAsset_close on it, which may be done after deleting the returned AImageDecoder.
outDecoder
On success (i.e. return value is ANDROID_IMAGE_DECODER_SUCCESS), this will be set to a newly created AImageDecoder. Caller is responsible for calling AImageDecoder_delete on it.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.

AImageDecoder_createFromBuffer

int AImageDecoder_createFromBuffer(
  const void *buffer,
  size_t length,
  AImageDecoder **outDecoder
)

Create a new AImageDecoder from a buffer.

Available since API level 30.

Errors:

Details
Parameters
buffer
Pointer to encoded data. Must be valid for the entire time the AImageDecoder is used.
length
Byte length of buffer.
outDecoder
On success (i.e. return value is ANDROID_IMAGE_DECODER_SUCCESS), this will be set to a newly created AImageDecoder. Caller is responsible for calling AImageDecoder_delete on it.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.

AImageDecoder_createFromFd

int AImageDecoder_createFromFd(
  int fd,
  AImageDecoder **outDecoder
)

Create a new AImageDecoder from a file descriptor.

Available since API level 30.

Errors:

Details
Parameters
fd
Seekable, readable, open file descriptor for encoded data. Client is still responsible for closing it, which may be done after deleting the returned AImageDecoder.
outDecoder
On success (i.e. return value is ANDROID_IMAGE_DECODER_SUCCESS), this will be set to a newly created AImageDecoder. Caller is responsible for calling AImageDecoder_delete on it.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.

AImageDecoder_decodeImage

int AImageDecoder_decodeImage(
  AImageDecoder *decoder,
  void *pixels,
  size_t stride,
  size_t size
)

Decode the image into pixels, using the settings of the AImageDecoder.

Available since API level 30.

Errors:

Details
Parameters
decoder
Opaque object representing the decoder.
pixels
On success, will be filled with the result of the decode. Must be large enough to hold |size| bytes.
stride
Width in bytes of a single row. Must be at least AImageDecoder_getMinimumStride and a multiple of the bytes per pixel of the AndroidBitmapFormat.
size
Size of the pixel buffer in bytes. Must be at least stride * (height - 1) + AImageDecoder_getMinimumStride.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.

AImageDecoder_delete

void AImageDecoder_delete(
  AImageDecoder *decoder
)

Delete the AImageDecoder.

Available since API level 30.

AImageDecoder_getHeaderInfo

const AImageDecoderHeaderInfo * AImageDecoder_getHeaderInfo(
  const AImageDecoder *
)

Return an opaque handle for reading header info.

This is owned by the AImageDecoder and will be destroyed when the AImageDecoder is destroyed via AImageDecoder_delete.

Available since API level 30.

AImageDecoder_getMinimumStride

size_t AImageDecoder_getMinimumStride(
  AImageDecoder *
)

Return the minimum stride that can be used in AImageDecoder_decodeImage).

This stride provides no padding, meaning it will be exactly equal to the width times the number of bytes per pixel for the AndroidBitmapFormat being used.

If the output is scaled (via AImageDecoder_setTargetSize) and/or cropped (via AImageDecoder_setCrop), this takes those into account.

Available since API level 30.

AImageDecoder_setAndroidBitmapFormat

int AImageDecoder_setAndroidBitmapFormat(
  AImageDecoder *,
  int32_t format
)

Choose the desired output format.

Available since API level 30.

Errors:

Details
Parameters
format
AndroidBitmapFormat to use for the output.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure. On failure, the AImageDecoder uses the format it was already planning to use (either its default or a previously successful setting from this function).

AImageDecoder_setCrop

int AImageDecoder_setCrop(
  AImageDecoder *,
  ARect crop
)

Specify how to crop the output after scaling (if any).

Future calls to AImageDecoder_decodeImage will crop their output to the specified ARect. Clients will only need to allocate enough memory for the cropped ARect.

Available since API level 30.

Errors:

Details
Parameters
crop
Rectangle describing a crop of the decode. It must be contained inside of the (possibly scaled, by AImageDecoder_setTargetSize) image dimensions. This will affect future calls to AImageDecoder_getMinimumStride, which will now return a value based on the width of the crop. An empty ARect - specifically { 0, 0, 0, 0 } - may be used to remove the cropping behavior. Any other empty or unsorted ARects will result in returning ANDROID_IMAGE_DECODER_BAD_PARAMETER.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.

AImageDecoder_setDataSpace

int AImageDecoder_setDataSpace(
  AImageDecoder *,
  int32_t dataspace
)

Choose the dataspace for the output.

Ignored by ANDROID_BITMAP_FORMAT_A_8, which does not support an ADataSpace.

Available since API level 30.

Errors:

Details
Parameters
dataspace
The ADataSpace to decode into. An ADataSpace specifies how to interpret the colors. By default, AImageDecoder will decode into the ADataSpace specified by AImageDecoderHeaderInfo_getDataSpace. If this parameter is set to a different ADataSpace, AImageDecoder will transform the output into the specified ADataSpace.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.

AImageDecoder_setTargetSize

int AImageDecoder_setTargetSize(
  AImageDecoder *,
  int32_t width,
  int32_t height
)

Specify the output size for a decoded image.

Future calls to AImageDecoder_decodeImage will sample or scale the encoded image to reach the desired size. If a crop rect is set (via AImageDecoder_setCrop), it must be contained within the dimensions specified by width and height, and the output image will be the size of the crop rect.

Available since API level 30.

Errors:

Details
Parameters
width
Width of the output (prior to cropping). This will affect future calls to AImageDecoder_getMinimumStride, which will now return a value based on this width.
height
Height of the output (prior to cropping).
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.

AImageDecoder_setUnpremultipliedRequired

int AImageDecoder_setUnpremultipliedRequired(
  AImageDecoder *,
  bool unpremultipliedRequired
)

Specify whether the output's pixels should be unpremultiplied.

By default, AImageDecoder_decodeImage will premultiply the pixels, if they have alpha. Pass true to this method to leave them unpremultiplied. This has no effect on an opaque image.

Available since API level 30.

Errors:

Details
Parameters
unpremultipliedRequired
Pass true to leave the pixels unpremultiplied.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.