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 struct AImageDecoderHeaderInfo 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 *)	const AImageDecoderHeaderInfo * 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:

• AImageDecoder_createFromAAsset
• AImageDecoder_createFromFd
• AImageDecoder_createFromBuffer

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:

• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder, |width| or |height| is null or |sampleSize| is < 1.

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:

• ANDROID_IMAGE_DECODER_INCOMPLETE: The asset was truncated before reading the image header.
• ANDROID_IMAGE_DECODER_BAD_PARAMETER: One of the parameters is null.
• ANDROID_IMAGE_DECODER_INVALID_INPUT: There is an error in the header.
• ANDROID_IMAGE_DECODER_SEEK_ERROR: The asset failed to seek.
• ANDROID_IMAGE_DECODER_INTERNAL_ERROR: Some other error, like a failure to allocate memory.
• ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT: The format is not supported.

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:

• ANDROID_IMAGE_DECODER_INCOMPLETE: The encoded image was truncated before reading the image header.
• ANDROID_IMAGE_DECODER_BAD_PARAMETER: One of the parameters is invalid.
• ANDROID_IMAGE_DECODER_INVALID_INPUT: There is an error in the header.
• ANDROID_IMAGE_DECODER_INTERNAL_ERROR: Some other error, like a failure to allocate memory.
• ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT: The format is not supported.

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:

• ANDROID_IMAGE_DECODER_INCOMPLETE: The file was truncated before reading the image header.
• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder is null, or |fd| does not represent a valid, seekable file descriptor.
• ANDROID_IMAGE_DECODER_INVALID_INPUT: There is an error in the header.
• ANDROID_IMAGE_DECODER_SEEK_ERROR: The descriptor failed to seek.
• ANDROID_IMAGE_DECODER_INTERNAL_ERROR: Some other error, like a failure to allocate memory.
• ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT: The format is not supported.

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:

• ANDROID_IMAGE_DECODER_INCOMPLETE: The image was truncated. A partial image was decoded, and undecoded lines have been initialized to all zeroes.
• ANDROID_IMAGE_DECODER_ERROR: The image contained an error. A partial image was decoded, and undecoded lines have been initialized to all zeroes.
• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder or |pixels| is null, the stride is not large enough or not pixel aligned, or |size| is not large enough.
• ANDROID_IMAGE_DECODER_SEEK_ERROR: The asset or file descriptor failed to seek.
• ANDROID_IMAGE_DECODER_INTERNAL_ERROR: Some other error, like a failure to allocate memory.

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:

• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder is null or |format| does not correspond to an AndroidBitmapFormat.
• ANDROID_IMAGE_DECODER_INVALID_CONVERSION: The AndroidBitmapFormat is incompatible with the image.

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:

• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder is null or the crop is not contained by the (possibly scaled) image dimensions.

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:

• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder is null or |dataspace| does not correspond to an ADataSpace value.

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:

• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder is null.
• ANDROID_IMAGE_DECODER_INVALID_SCALE: |width| or |height| is <= 0, the size is too big, any existing crop is not contained by the new image dimensions, or the scale is incompatible with a previous call to AImageDecoder_setUnpremultipliedRequired(true).

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:

• ANDROID_IMAGE_DECODER_INVALID_CONVERSION: Unpremultiplied is not possible due to an existing scale set by AImageDecoder_setTargetSize.
• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder is null.

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.