Android Image Decoder

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 28{
  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,
  ANDROID_IMAGE_DECODER_FINISHED = -10,
  ANDROID_IMAGE_DECODER_INVALID_STATE = -11
} 		enum
AImageDecoder functions result code.
Anonymous Enum 29{
  ANDROID_IMAGE_DECODER_INFINITE = INT32_MAX
} 		enum
Anonymous Enum 30{
  ANDROID_IMAGE_DECODER_DISPOSE_OP_NONE = 1,
  ANDROID_IMAGE_DECODER_DISPOSE_OP_BACKGROUND = 2,
  ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS = 3
} 		enum
How a frame is “disposed” before showing the next one.
Anonymous Enum 31{
  ANDROID_IMAGE_DECODER_BLEND_OP_SRC = 1,
  ANDROID_IMAGE_DECODER_BLEND_OP_SRC_OVER = 2
} 		enum
How a frame is blended with the previous frame.

Typedefs
AImageDecoder typedef
struct AImageDecoder
Opaque handle for decoding images.
AImageDecoderFrameInfo typedef
Opaque handle to animation information about a single frame.
AImageDecoderHeaderInfo typedef
Opaque handle for representing information about the encoded image.

Functions
AImageDecoderFrameInfo_create()
Create an uninitialized AImageDecoderFrameInfo.
AImageDecoderFrameInfo_delete(AImageDecoderFrameInfo *_Nullable info)
void
Delete an AImageDecoderFrameInfo.
AImageDecoderFrameInfo_getBlendOp(const AImageDecoderFrameInfo *_Nonnull info)
int32_t
Return how this frame is blended with the previous frame.
AImageDecoderFrameInfo_getDisposeOp(const AImageDecoderFrameInfo *_Nonnull info)
int32_t
Return how this frame is “disposed” before showing the next one.
AImageDecoderFrameInfo_getDuration(const AImageDecoderFrameInfo *_Nonnull info)
int64_t
Report the number of nanoseconds to show the current frame.
AImageDecoderFrameInfo_getFrameRect(const AImageDecoderFrameInfo *_Nonnull info)
The rectangle of the image (within 0, 0, AImageDecoderHeaderInfo_getWidth, AImageDecoderHeaderInfo_getHeight) updated by this frame.
AImageDecoderFrameInfo_hasAlphaWithinBounds(const AImageDecoderFrameInfo *_Nonnull info)
bool
Whether the new portion of this frame may contain alpha.
AImageDecoderHeaderInfo_getAlphaFlags(const AImageDecoderHeaderInfo *_Nonnull)
int
Report how the AImageDecoder will handle alpha by default.
AImageDecoderHeaderInfo_getAndroidBitmapFormat(const AImageDecoderHeaderInfo *_Nonnull)
int32_t
Report the AndroidBitmapFormat the AImageDecoder will decode to by default.
AImageDecoderHeaderInfo_getDataSpace(const AImageDecoderHeaderInfo *_Nonnull)
int32_t
Report the dataspace the AImageDecoder will decode to by default.
AImageDecoderHeaderInfo_getHeight(const AImageDecoderHeaderInfo *_Nonnull)
int32_t
Report the native height of the encoded image.
AImageDecoderHeaderInfo_getMimeType(const AImageDecoderHeaderInfo *_Nonnull)
const char *_Nonnull
Report the mimeType of the encoded image.
AImageDecoderHeaderInfo_getWidth(const AImageDecoderHeaderInfo *_Nonnull)
int32_t
Report the native width of the encoded image.
AImageDecoder_advanceFrame(AImageDecoder *_Nonnull decoder)
int
Advance to the next frame in the animation.
AImageDecoder_computeSampledSize(const AImageDecoder *_Nonnull decoder, int sampleSize, int32_t *_Nonnull width, int32_t *_Nonnull height)
int
Compute the dimensions to use for a given sampleSize.
AImageDecoder_createFromAAsset(struct AAsset *_Nonnull asset, AImageDecoder *_Nullable *_Nonnull outDecoder)
int
Create a new AImageDecoder from an AAsset.
AImageDecoder_createFromBuffer(const void *_Nonnull buffer, size_t length, AImageDecoder *_Nullable *_Nonnull outDecoder)
int
Create a new AImageDecoder from a buffer.
AImageDecoder_createFromFd(int fd, AImageDecoder *_Nullable *_Nonnull outDecoder)
int
Create a new AImageDecoder from a file descriptor.
AImageDecoder_decodeImage(AImageDecoder *_Nonnull decoder, void *_Nonnull pixels, size_t stride, size_t size)
int
Decode the image into pixels, using the settings of the AImageDecoder.
AImageDecoder_delete(AImageDecoder *_Nullable decoder)
void
Delete the AImageDecoder.
AImageDecoder_getFrameInfo(AImageDecoder *_Nonnull decoder, AImageDecoderFrameInfo *_Nonnull info)
int
Fill |info| with information about the current frame.
AImageDecoder_getHeaderInfo(const AImageDecoder *_Nonnull decoder)
const AImageDecoderHeaderInfo *_Nonnull
Return an opaque handle for reading header info.
AImageDecoder_getMinimumStride(AImageDecoder *_Nonnull decoder)
size_t
Return the minimum stride that can be used in AImageDecoder_decodeImage.
AImageDecoder_getRepeatCount(AImageDecoder *_Nonnull decoder)
int32_t
Report how many times the animation should repeat.
AImageDecoder_isAnimated(AImageDecoder *_Nonnull decoder)
bool
Return true iff the image is animated - i.e.
AImageDecoder_resultToString(int)
const char *_Nullable
Return a constant string value representing the error code.
AImageDecoder_rewind(AImageDecoder *_Nonnull decoder)
int
Return to the beginning of the animation.
AImageDecoder_setAndroidBitmapFormat(AImageDecoder *_Nonnull decoder, int32_t format)
int
Choose the desired output format.
AImageDecoder_setCrop(AImageDecoder *_Nonnull decoder, ARect crop)
int
Specify how to crop the output after scaling (if any).
AImageDecoder_setDataSpace(AImageDecoder *_Nonnull decoder, int32_t dataspace)
int
Choose the dataspace for the output.
AImageDecoder_setInternallyHandleDisposePrevious(AImageDecoder *_Nonnull decoder, bool handleInternally)
void
Whether to have AImageDecoder store the frame prior to a frame marked ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS.
AImageDecoder_setTargetSize(AImageDecoder *_Nonnull decoder, int32_t width, int32_t height)
int
Specify the output size for a decoded image.
AImageDecoder_setUnpremultipliedRequired(AImageDecoder *_Nonnull decoder, bool unpremultipliedRequired)
int
Specify whether the output's pixels should be unpremultiplied.

Enumerations

Anonymous Enum 28

Declared in android/imagedecoder.h 
 Anonymous Enum 28

AImageDecoder functions result code.

Introduced in API 30.

Many functions will return this 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. Use AImageDecoder_resultToString for a readable version of the result code.

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_FINISHED

The animation has reached the end.

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_INVALID_STATE

This method cannot be called while the AImageDecoder is in its current state.

For example, various setters (like AImageDecoder_setTargetSize) can only be called while the AImageDecoder is set to decode the first frame of an animation. This ensures that any blending and/or restoring prior frames works correctly.

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.

Anonymous Enum 29

Declared in android/imagedecoder.h 
 Anonymous Enum 29
Properties
ANDROID_IMAGE_DECODER_INFINITE

Reported by AImageDecoder_getRepeatCount if the animation should repeat forever.

Introduced in API 31

Anonymous Enum 30

Declared in android/imagedecoder.h 
 Anonymous Enum 30

How a frame is “disposed” before showing the next one.

Introduced in API 31.

This, along with other information in AImageDecoderFrameInfo, can be useful for determining whether a frame is independent, but the decoder handles disposing of frames, so a simple sequential client does not need this.

Properties
ANDROID_IMAGE_DECODER_DISPOSE_OP_BACKGROUND

The frame’s rectangle is cleared to transparent (by AImageDecoder) before decoding the next frame.

ANDROID_IMAGE_DECODER_DISPOSE_OP_NONE

No disposal.

The following frame will be drawn directly on top of this one.

ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS

The frame’s rectangle is reverted to the prior frame before decoding the next frame.

This is handled by AImageDecoder, unless AImageDecoder_setInternallyHandleDisposePrevious is set to false.

Anonymous Enum 31

Declared in android/imagedecoder.h 
 Anonymous Enum 31

How a frame is blended with the previous frame.

Introduced in API 31.

This, along with other information in AImageDecoderFrameInfo, can be useful for determining whether a frame is independent, but the decoder handles blending frames, so a simple sequential client does not need this.

Properties
ANDROID_IMAGE_DECODER_BLEND_OP_SRC

This frame replaces existing content.

This corresponds to webp’s “do not blend”.

ANDROID_IMAGE_DECODER_BLEND_OP_SRC_OVER

This frame blends with the previous frame.

Typedefs

AImageDecoder

Declared in android/imagedecoder.h 
struct AImageDecoder AImageDecoder

Opaque handle for decoding images.

Introduced in API 30

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_decodeImage will decode into client provided memory.

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

AImageDecoderFrameInfo

Declared in android/imagedecoder.h 
struct AImageDecoderFrameInfo AImageDecoderFrameInfo

Opaque handle to animation information about a single frame.

Introduced in API 31

The duration (retrieved with AImageDecoderFrameInfo_getDuration) is necessary for clients to display the animation at the proper speed. The other information is helpful for a client that wants to determine what frames are independent (or what frames they depend on), but is unnecessary for a simple client that wants to sequentially display all frames.

AImageDecoderHeaderInfo

Declared in android/imagedecoder.h 
struct AImageDecoderHeaderInfo AImageDecoderHeaderInfo

Opaque handle for representing information about the encoded image.

Introduced in API 30

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

Functions

AImageDecoderFrameInfo_create

Declared in android/imagedecoder.h 
AImageDecoderFrameInfo *_Nullable AImageDecoderFrameInfo_create()

Create an uninitialized AImageDecoderFrameInfo.

Introduced in API 31.

This can be passed to AImageDecoder_getFrameInfo to fill in information about the current frame. It may be reused.

Must be deleted with AImageDecoderFrameInfo_delete.

AImageDecoderFrameInfo_delete

Declared in android/imagedecoder.h 
void AImageDecoderFrameInfo_delete(
  AImageDecoderFrameInfo *_Nullable info
)

Delete an AImageDecoderFrameInfo.

Introduced in API 31.

AImageDecoderFrameInfo_getBlendOp

Declared in android/imagedecoder.h 
int32_t AImageDecoderFrameInfo_getBlendOp(
  const AImageDecoderFrameInfo *_Nonnull info
)

Return how this frame is blended with the previous frame.

Introduced in API 31.

This, along with other information in AImageDecoderFrameInfo, can be useful for determining whether a frame is independent, but the decoder handles blending frames, so a simple sequential client does not need this.

Details
Returns

AImageDecoderFrameInfo_getDisposeOp

Declared in android/imagedecoder.h 
int32_t AImageDecoderFrameInfo_getDisposeOp(
  const AImageDecoderFrameInfo *_Nonnull info
)

Return how this frame is “disposed” before showing the next one.

Introduced in API 31.

This, along with other information in AImageDecoderFrameInfo, can be useful for determining whether a frame is independent, but the decoder handles disposing of frames, so a simple sequential client does not need this.

Details
Returns

AImageDecoderFrameInfo_getDuration

Declared in android/imagedecoder.h 
int64_t AImageDecoderFrameInfo_getDuration(
  const AImageDecoderFrameInfo *_Nonnull info
)

Report the number of nanoseconds to show the current frame.

Introduced in API 31.

Errors:

AImageDecoderFrameInfo_getFrameRect

Declared in android/imagedecoder.h 
ARect AImageDecoderFrameInfo_getFrameRect(
  const AImageDecoderFrameInfo *_Nonnull info
)

The rectangle of the image (within 0, 0, AImageDecoderHeaderInfo_getWidth, AImageDecoderHeaderInfo_getHeight) updated by this frame.

Introduced in API 31.

Note that this is unaffected by calls to AImageDecoder_setTargetSize or AImageDecoder_setCrop.

A frame may update only part of the image. This will always be contained by the image’s dimensions.

This, along with other information in AImageDecoderFrameInfo, can be useful for determining whether a frame is independent, but the decoder handles blending frames, so a simple sequential client does not need this.

Errors:

  • returns an empty ARect if |info| is null.

AImageDecoderFrameInfo_hasAlphaWithinBounds

Declared in android/imagedecoder.h 
bool AImageDecoderFrameInfo_hasAlphaWithinBounds(
  const AImageDecoderFrameInfo *_Nonnull info
)

Whether the new portion of this frame may contain alpha.

Introduced in API 31.

Unless this frame is independent (see AImageDecoder_decodeImage), a single call to AImageDecoder_decodeImage will decode an updated rectangle of pixels and then blend it with the existing pixels in the |pixels| buffer according to AImageDecoderFrameInfo_getBlendOp. This method returns whether the updated rectangle has alpha, prior to blending. The return value is conservative; for example, if a color-index-based frame has a color with alpha but does not use it, this will still return true.

This, along with other information in AImageDecoderFrameInfo, can be useful for determining whether a frame is independent, but the decoder handles blending frames, so a simple sequential client does not need this.

Note that this may differ from whether the composed frame (that is, the resulting image after blending) has alpha. If this frame does not fill the entire image dimensions (see AImageDecoderFrameInfo_getFrameRect) or it blends with an opaque frame, for example, the composed frame’s alpha may not match.

Errors:

  • returns false if |info| is null.

AImageDecoderHeaderInfo_getAlphaFlags

Declared in android/imagedecoder.h 
int AImageDecoderHeaderInfo_getAlphaFlags(
  const AImageDecoderHeaderInfo *_Nonnull
)

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.

Starting in API level 31, an AImageDecoder may contain multiple frames of an animation, but this method still only reports whether the first frame has alpha.

AImageDecoderHeaderInfo_getAndroidBitmapFormat

Declared in android/imagedecoder.h 
int32_t AImageDecoderHeaderInfo_getAndroidBitmapFormat(
  const AImageDecoderHeaderInfo *_Nonnull
)

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

Declared in android/imagedecoder.h 
int32_t AImageDecoderHeaderInfo_getDataSpace(
  const AImageDecoderHeaderInfo *_Nonnull
)

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

Declared in android/imagedecoder.h 
int32_t AImageDecoderHeaderInfo_getHeight(
  const AImageDecoderHeaderInfo *_Nonnull
)

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

Declared in android/imagedecoder.h 
const char *_Nonnull AImageDecoderHeaderInfo_getMimeType(
  const AImageDecoderHeaderInfo *_Nonnull
)

Report the mimeType of the encoded image.

Available since API level 30.

Details
Returns
a string literal describing the mime type.

AImageDecoderHeaderInfo_getWidth

Declared in android/imagedecoder.h 
int32_t AImageDecoderHeaderInfo_getWidth(
  const AImageDecoderHeaderInfo *_Nonnull
)

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_advanceFrame

Declared in android/imagedecoder.h 
int AImageDecoder_advanceFrame(
  AImageDecoder *_Nonnull decoder
)

Advance to the next frame in the animation.

Introduced in API 31.

The AImageDecoder keeps track internally which frame it is ready to decode (the "current frame"). Initially it is set to decode the first frame, and each call to AImageDecoder_decodeImage will continue to decode the same frame until this method (or AImageDecoder_rewind) is called.

Note that this can be used to skip a frame without decoding it. But some frames depend on (i.e. blend with) prior frames, and AImageDecoder_decodeImage assumes that the prior frame is in the |pixels| buffer. In addition, AImageDecoder_decodeImage handles caching and restoring frames (see ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS), so skipping frames in an image with such frames may not produce the correct results.

Only supported by ANDROID_BITMAP_FORMAT_RGBA_8888 and ANDROID_BITMAP_FORMAT_RGBA_F16.

Errors:

Details
Parameters
decoder
an AImageDecoder object.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.

AImageDecoder_computeSampledSize

Declared in android/imagedecoder.h 
int AImageDecoder_computeSampledSize(
  const AImageDecoder *_Nonnull decoder,
  int sampleSize,
  int32_t *_Nonnull width,
  int32_t *_Nonnull 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
decoder
an AImageDecoder object.
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

Declared in android/imagedecoder.h 
int AImageDecoder_createFromAAsset(
  struct AAsset *_Nonnull asset,
  AImageDecoder *_Nullable *_Nonnull 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

Declared in android/imagedecoder.h 
int AImageDecoder_createFromBuffer(
  const void *_Nonnull buffer,
  size_t length,
  AImageDecoder *_Nullable *_Nonnull 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

Declared in android/imagedecoder.h 
int AImageDecoder_createFromFd(
  int fd,
  AImageDecoder *_Nullable *_Nonnull 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

Declared in android/imagedecoder.h 
int AImageDecoder_decodeImage(
  AImageDecoder *_Nonnull decoder,
  void *_Nonnull pixels,
  size_t stride,
  size_t size
)

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

Available since API level 30.

Starting in API level 31, it can be used to decode all of the frames of an animated image (i.e. GIF, WebP) using new APIs. Internally, AImageDecoder keeps track of its "current frame" - that is, the frame that will be decoded by a call to AImageDecoder_decodeImage. At creation time, the current frame is always the first frame, and multiple calls to this method will each decode the first frame. AImageDecoder_advanceFrame advances the current frame to the following frame, so that future calls to this method will decode that frame. Some frames may update only part of the image. They may only update a sub-rectangle (see AImageDecoderFrameInfo_getFrameRect), or they may have alpha (see AImageDecoderFrameInfo_hasAlphaWithinBounds). In these cases, this method assumes that the prior frame is still residing in the |pixels| buffer, decodes only the new portion, and blends it with the buffer. Frames that change the entire |pixels| buffer are "independent", and do not require the prior frame to remain in the buffer. The first frame is always independent. A sophisticated client can use information from the AImageDecoderFrameInfo to determine whether other frames are independent, or what frames they rely on.

If the current frame is marked ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS, AImageDecoder_decodeImage will store the |pixels| buffer prior to decoding (note: this only happens for the first in a string of consecutive ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS frames). After advancing to the following frame, AImageDecoder_decodeImage will restore that buffer prior to decoding that frame. This is the default behavior, but it can be disabled by passing false to AImageDecoder_setInternallyHandleDisposePrevious.

Ignoring timing information, display, etc, a client wishing to decode all frames of an animated image may conceptually use code like the following:

while (true) { int result = AImageDecoder_decodeImage(decoder, pixels, stride, size); if (result != ANDROID_IMAGE_DECODER_SUCCESS) break;

// Display or save the image in |pixels|, keeping the buffer intact for // AImageDecoder to decode the next frame correctly. Application_viewImage(pixels);

result = AImageDecoder_advanceFrame(decoder); if (result != ANDROID_IMAGE_DECODER_SUCCESS) break; }

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

Declared in android/imagedecoder.h 
void AImageDecoder_delete(
  AImageDecoder *_Nullable decoder
)

Delete the AImageDecoder.

Details
Parameters
decoder
AImageDecoder object created with one of AImageDecoder_createFrom... functions. Available since API level 30.

AImageDecoder_getFrameInfo

Declared in android/imagedecoder.h 
int AImageDecoder_getFrameInfo(
  AImageDecoder *_Nonnull decoder,
  AImageDecoderFrameInfo *_Nonnull info
)

Fill |info| with information about the current frame.

Introduced in API 31.

Initially, this will return information about the first frame. AImageDecoder_advanceFrame and AImageDecoder_rewind can be used to change which frame is the current frame.

If the image only has one frame, this will fill the AImageDecoderFrameInfo with the encoded info and reasonable defaults.

If AImageDecoder_advanceFrame succeeded, this will succeed as well.

Errors:

Details
Parameters
decoder
Opaque object representing the decoder.
info
Opaque object to hold frame information. On success, will be filled with information regarding the current frame.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.

AImageDecoder_getHeaderInfo

Declared in android/imagedecoder.h 
const AImageDecoderHeaderInfo *_Nonnull AImageDecoder_getHeaderInfo(
  const AImageDecoder *_Nonnull decoder
)

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.

Details
Parameters
decoder
an AImageDecoder object.

AImageDecoder_getMinimumStride

Declared in android/imagedecoder.h 
size_t AImageDecoder_getMinimumStride(
  AImageDecoder *_Nonnull decoder
)

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.

Details
Parameters
decoder
an AImageDecoder object.

AImageDecoder_getRepeatCount

Declared in android/imagedecoder.h 
int32_t AImageDecoder_getRepeatCount(
  AImageDecoder *_Nonnull decoder
)

Report how many times the animation should repeat.

Introduced in API 31.

This does not include the first play through. e.g. a repeat count of 4 means that each frame is played 5 times.

ANDROID_IMAGE_DECODER_INFINITE means to repeat forever.

This may require seeking.

For non-animated formats, this returns 0. It may return non-zero for an image with only one frame (i.e. AImageDecoder_isAnimated returns false) if the encoded image contains a repeat count.

Errors:

Details
Parameters
decoder
an AImageDecoder object.
Returns
Number of times to repeat on success or a value indicating the reason for the failure.

AImageDecoder_isAnimated

Declared in android/imagedecoder.h 
bool AImageDecoder_isAnimated(
  AImageDecoder *_Nonnull decoder
)

Return true iff the image is animated - i.e.

has multiple frames.

Introduced in API 31.

A single frame GIF is considered to not be animated. This may require seeking past the first frame to verify whether there is a following frame.

Errors:

  • returns false if |decoder| is null.

Details
Parameters
decoder
an AImageDecoder object.

AImageDecoder_resultToString

Declared in android/imagedecoder.h 
const char *_Nullable AImageDecoder_resultToString(
  int
)

Return a constant string value representing the error code.

Introduced in API 31.

Pass the return value from an AImageDecoder method (e.g. AImageDecoder_decodeImage) for a text string representing the error code.

Errors:

  • Returns null for a value out of range.

AImageDecoder_rewind

Declared in android/imagedecoder.h 
int AImageDecoder_rewind(
  AImageDecoder *_Nonnull decoder
)

Return to the beginning of the animation.

Introduced in API 31.

After this call, the AImageDecoder will be ready to decode the first frame of the animation. This can be called after reaching the end of the animation or an error or in the middle of the animation.

Errors:

Details
Parameters
decoder
an AImageDecoder object.
Returns
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.

AImageDecoder_setAndroidBitmapFormat

Declared in android/imagedecoder.h 
int AImageDecoder_setAndroidBitmapFormat(
  AImageDecoder *_Nonnull decoder,
  int32_t format
)

Choose the desired output format.

If the encoded image represents an animation, this must be called while on the first frame (e.g. before calling AImageDecoder_advanceFrame or after calling AImageDecoder_rewind).

Available since API level 30.

Errors:

Details
Parameters
format
AndroidBitmapFormat to use for the output.
decoder
an AImageDecoder object.
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

Declared in android/imagedecoder.h 
int AImageDecoder_setCrop(
  AImageDecoder *_Nonnull decoder,
  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.

If the encoded image represents an animation, this must be called while on the first frame (e.g. before calling AImageDecoder_advanceFrame or after calling AImageDecoder_rewind).

Available since API level 30.

Errors:

Details
Parameters
decoder
an AImageDecoder object.
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

Declared in android/imagedecoder.h 
int AImageDecoder_setDataSpace(
  AImageDecoder *_Nonnull decoder,
  int32_t dataspace
)

Choose the dataspace for the output.

Ignored by ANDROID_BITMAP_FORMAT_A_8, which does not support an ADataSpace.

If the encoded image represents an animation, this must be called while on the first frame (e.g. before calling AImageDecoder_advanceFrame or after calling AImageDecoder_rewind).

Available since API level 30.

Errors:

Details
Parameters
decoder
an AImageDecoder object.
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_setInternallyHandleDisposePrevious

Declared in android/imagedecoder.h 
void AImageDecoder_setInternallyHandleDisposePrevious(
  AImageDecoder *_Nonnull decoder,
  bool handleInternally
)

Whether to have AImageDecoder store the frame prior to a frame marked ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS.

Introduced in API 31.

The default is true. Many images will not have such a frame (it is not supported by WebP, and only some GIFs use it). But if frame i is ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS, then i+1 may depend on i-1. When this setting is true, AImageDecoder will defensively copy frame i-1 (i.e. the contents of |pixels| in AImageDecoder_decodeImage) into an internal buffer so that it can be used to decode i+1.

AImageDecoder will only store a single frame, at the size specified by AImageDecoder_setTargetSize (or the original dimensions if that method has not been called), and will discard it when it is no longer necessary.

A client that desires to manually store such frames may set this to false, so that AImageDecoder does not need to store this extra frame. Instead, when decoding the same ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS frame i, AImageDecoder will decode directly into |pixels|, assuming the client stored i-1. When asked to decode frame i+1, AImageDecoder will now assume that the client provided i-1 in |pixels|.

Details
Parameters
decoder
an AImageDecoder object.
handleInternally
Whether AImageDecoder will internally handle ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS frames.

AImageDecoder_setTargetSize

Declared in android/imagedecoder.h 
int AImageDecoder_setTargetSize(
  AImageDecoder *_Nonnull decoder,
  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.

If the encoded image represents an animation, this must be called while on the first frame (e.g. before calling AImageDecoder_advanceFrame or after calling AImageDecoder_rewind).

It is strongly recommended to use setTargetSize only for downscaling, as it is often more efficient to scale-up when rendering than up-front due to reduced overall memory.

Available since API level 30.

Errors:

Details
Parameters
decoder
an AImageDecoder object.
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

Declared in android/imagedecoder.h 
int AImageDecoder_setUnpremultipliedRequired(
  AImageDecoder *_Nonnull decoder,
  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.

If the encoded image represents an animation, this must be called while on the first frame (e.g. before calling AImageDecoder_advanceFrame or after calling AImageDecoder_rewind).

Available since API level 30.

Errors:

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