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{
|
enum AImageDecoder functions result code. |
Typedefs |
|
---|---|
AImageDecoder
|
typedefstruct AImageDecoder
Opaque handle for decoding images. |
AImageDecoderHeaderInfo
|
typedefstruct 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.
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:
- ANDROID_IMAGE_DECODER_BAD_PARAMETER: The AImageDecoder, |width| or |height| is null or |sampleSize| is < 1.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
||||||
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 |
|
||||
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 |
|
||||||
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 |
|
||||
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 |
|
||||||||
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 |
|
||
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 |
|
||
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 |
|
||
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 |
|
||||
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 |
|
||
Returns |
ANDROID_IMAGE_DECODER_SUCCESS on success or a value indicating the reason for the failure.
|