Android Image Decoder

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.

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.

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.

Opaque handle for decoding images.

Introduced in API 30

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

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

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.

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.

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.

Delete an AImageDecoderFrameInfo.

Introduced in API 31.

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.

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.

Report the number of nanoseconds to show the current frame.

Introduced in API 31.

Errors:

• returns ANDROID_IMAGE_DECODER_BAD_PARAMETER if |info| is null.

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.

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.

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.

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.

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.

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.

Report the mimeType of the encoded image.

Available since API level 30.

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.

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:

• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder represents an image that is not animated (see AImageDecoder_isAnimated) or the AImageDecoder is null.
• The requested AndroidBitmapFormat does not support animation.
• ANDROID_IMAGE_DECODER_INCOMPLETE: The input appears to be truncated. The client must call AImageDecoder_rewind before calling AImageDecoder_decodeImage again.
• ANDROID_IMAGE_DECODER_ERROR: The input contains an error. The client must call AImageDecoder_rewind before calling AImageDecoder_decodeImage again.
• ANDROID_IMAGE_DECODER_FINISHED: The input contains no more frames. The client must call AImageDecoder_rewind before calling AImageDecoder_decodeImage again.

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.

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.

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.

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.

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:

• 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.
• ANDROID_IMAGE_DECODER_FINISHED: The input contains no more frames. No decoding occurred. The client must call AImageDecoder_rewind before calling AImageDecoder_decodeImage again.

Delete the AImageDecoder.

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:

• ANDROID_IMAGE_DECODER_BAD_PARAMETER: One of the parameters is null.
• ANDROID_IMAGE_DECODER_FINISHED: The input contains no more frames. The client must call AImageDecoder_rewind to reset the current frame to a valid frame (0).

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.

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.

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:

• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder is null.

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.

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.

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:

• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder represents an image that is not animated (see AImageDecoder_isAnimated) or the AImageDecoder is null.
• ANDROID_IMAGE_DECODER_SEEK_ERROR: The asset or file descriptor failed to seek.

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:

• 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.
• ANDROID_IMAGE_DECODER_INVALID_STATE: The animation is not on the first frame.

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:

• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder is null, or the crop is not contained by the (possibly scaled) image dimensions.
• ANDROID_IMAGE_DECODER_INVALID_STATE: The animation is not on the first frame.

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:

• ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder is null or |dataspace| does not correspond to an ADataSpace value.
• ANDROID_IMAGE_DECODER_INVALID_STATE: The animation is not on the first frame.

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|.

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:

• 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).
• ANDROID_IMAGE_DECODER_INVALID_STATE: The animation is not on the first frame.

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:

• 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.
• ANDROID_IMAGE_DECODER_INVALID_STATE: The animation is not on the first frame.