blob: 1298c624ddff76badceaf3f7ecc055c4ae3e45c5 [file] [log] [blame]
/*
* Copyright (C) 2019 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @defgroup ImageDecoder
*
* Functions for converting encoded images into RGBA pixels.
*
* 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)
* <p>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
* <a href="https://developer.android.com/ndk/guides/image-decoder">Image decoder</a>
* developer guide.
* @{
*/
/**
* @file imagedecoder.h
* @brief API for decoding images.
*/
#ifndef ANDROID_IMAGE_DECODER_H
#define ANDROID_IMAGE_DECODER_H
#include "bitmap.h"
#include <android/rect.h>
#include <stdint.h>
#if !defined(__INTRODUCED_IN)
#define __INTRODUCED_IN(__api_level) /* nothing */
#endif
#ifdef __cplusplus
extern "C" {
#endif
struct AAsset;
/**
* {@link AImageDecoder} functions result code. Many functions will return one of these
* to indicate success ({@link ANDROID_IMAGE_DECODER_SUCCESS}) or the reason
* for the failure. On failure, any out-parameters should be considered
* uninitialized, except where specified.
*/
enum {
/**
* Decoding was successful and complete.
*/
ANDROID_IMAGE_DECODER_SUCCESS = 0,
/**
* The input is incomplete.
*/
ANDROID_IMAGE_DECODER_INCOMPLETE = -1,
/**
* The input contained an error after decoding some lines.
*/
ANDROID_IMAGE_DECODER_ERROR = -2,
/**
* Could not convert. For example, attempting to decode an image with
* alpha to an opaque format.
*/
ANDROID_IMAGE_DECODER_INVALID_CONVERSION = -3,
/**
* The scale is invalid. It may have overflowed, or it may be incompatible
* with the current alpha setting.
*/
ANDROID_IMAGE_DECODER_INVALID_SCALE = -4,
/**
* Some other parameter is invalid.
*/
ANDROID_IMAGE_DECODER_BAD_PARAMETER = -5,
/**
* Input was invalid before decoding any pixels.
*/
ANDROID_IMAGE_DECODER_INVALID_INPUT = -6,
/**
* A seek was required and it failed.
*/
ANDROID_IMAGE_DECODER_SEEK_ERROR = -7,
/**
* Some other error. For example, an internal allocation failed.
*/
ANDROID_IMAGE_DECODER_INTERNAL_ERROR = -8,
/**
* AImageDecoder did not recognize the format.
*/
ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT = -9
};
struct AImageDecoder;
/**
* Opaque handle for decoding images.
*
* Create using one of the following:
* - {@link AImageDecoder_createFromAAsset}
* - {@link AImageDecoder_createFromFd}
* - {@link AImageDecoder_createFromBuffer}
*
* After creation, {@link AImageDecoder_getHeaderInfo} can be used to retrieve
* information about the encoded image. Other functions, like
* {@link AImageDecoder_setTargetSize}, can be used to specify how to decode, and
* {@link AImageDecoder_decode} will decode into client provided memory.
*
* {@link AImageDecoder} objects are NOT thread-safe, and should not be shared across
* threads.
*/
typedef struct AImageDecoder AImageDecoder;
/**
* Create a new {@link AImageDecoder} from an {@link AAsset}.
*
* Available since API level 30.
*
* @param asset {@link AAsset} containing encoded image data. Client is still
* responsible for calling {@link AAsset_close} on it, which may be
* done after deleting the returned {@link AImageDecoder}.
* @param outDecoder On success (i.e. return value is
* {@link ANDROID_IMAGE_DECODER_SUCCESS}), this will be set to
* a newly created {@link AImageDecoder}. Caller is
* responsible for calling {@link AImageDecoder_delete} on it.
* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
* indicating the reason for the failure.
*
* Errors:
* - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The asset was truncated before
* reading the image header.
* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: One of the parameters is
* null.
* - {@link ANDROID_IMAGE_DECODER_INVALID_INPUT}: There is an error in the
* header.
* - {@link ANDROID_IMAGE_DECODER_SEEK_ERROR}: The asset failed to seek.
* - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a
* failure to allocate memory.
* - {@link ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT}: The format is not
* supported.
*/
int AImageDecoder_createFromAAsset(struct AAsset* asset, AImageDecoder** outDecoder)
__INTRODUCED_IN(30);
/**
* Create a new {@link AImageDecoder} from a file descriptor.
*
* Available since API level 30.
*
* @param fd Seekable, readable, open file descriptor for encoded data.
* Client is still responsible for closing it, which may be done
* after deleting the returned {@link AImageDecoder}.
* @param outDecoder On success (i.e. return value is
* {@link ANDROID_IMAGE_DECODER_SUCCESS}), this will be set to
* a newly created {@link AImageDecoder}. Caller is
* responsible for calling {@link AImageDecoder_delete} on it.
* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
* indicating the reason for the failure.
*
* Errors:
* - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The file was truncated before
* reading the image header.
* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The {@link AImageDecoder} is
* null, or |fd| does not represent a valid, seekable file descriptor.
* - {@link ANDROID_IMAGE_DECODER_INVALID_INPUT}: There is an error in the
* header.
* - {@link ANDROID_IMAGE_DECODER_SEEK_ERROR}: The descriptor failed to seek.
* - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a
* failure to allocate memory.
* - {@link ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT}: The format is not
* supported.
*/
int AImageDecoder_createFromFd(int fd, AImageDecoder** outDecoder) __INTRODUCED_IN(30);
/**
* Create a new AImageDecoder from a buffer.
*
* Available since API level 30.
*
* @param buffer Pointer to encoded data. Must be valid for the entire time
* the {@link AImageDecoder} is used.
* @param length Byte length of buffer.
* @param outDecoder On success (i.e. return value is
* {@link ANDROID_IMAGE_DECODER_SUCCESS}), this will be set to
* a newly created {@link AImageDecoder}. Caller is
* responsible for calling {@link AImageDecoder_delete} on it.
* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
* indicating the reason for the failure.
*
* Errors:
* - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The encoded image was truncated before
* reading the image header.
* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: One of the parameters is
* invalid.
* - {@link ANDROID_IMAGE_DECODER_INVALID_INPUT}: There is an error in the
* header.
* - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a
* failure to allocate memory.
* - {@link ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT}: The format is not
* supported.
*/
int AImageDecoder_createFromBuffer(const void* buffer, size_t length,
AImageDecoder** outDecoder) __INTRODUCED_IN(30);
/**
* Delete the AImageDecoder.
*
* Available since API level 30.
*/
void AImageDecoder_delete(AImageDecoder* decoder) __INTRODUCED_IN(30);
/**
* Choose the desired output format.
*
* Available since API level 30.
*
* @param format {@link AndroidBitmapFormat} to use for the output.
* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
* indicating the reason for the failure. On failure, the
* {@link AImageDecoder} uses the format it was already planning
* to use (either its default or a previously successful setting
* from this function).
*
* Errors:
* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The
* {@link AImageDecoder} is null or |format| does not correspond to an
* {@link AndroidBitmapFormat}.
* - {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION}: The
* {@link AndroidBitmapFormat} is incompatible with the image.
*/
int AImageDecoder_setAndroidBitmapFormat(AImageDecoder*,
int32_t format) __INTRODUCED_IN(30);
/**
* Specify whether the output's pixels should be unpremultiplied.
*
* By default, {@link 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.
*
* @param unpremultipliedRequired Pass true to leave the pixels unpremultiplied.
* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
* indicating the reason for the failure.
*
* Errors:
* - {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION}: Unpremultiplied is not
* possible due to an existing scale set by
* {@link AImageDecoder_setTargetSize}.
* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The
* {@link AImageDecoder} is null.
*/
int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*,
bool unpremultipliedRequired) __INTRODUCED_IN(30);
/**
* Choose the dataspace for the output.
*
* Ignored by {@link ANDROID_BITMAP_FORMAT_A_8}, which does not support
* an {@link ADataSpace}.
*
* Available since API level 30.
*
* @param dataspace The {@link ADataSpace} to decode into. An ADataSpace
* specifies how to interpret the colors. By default,
* AImageDecoder will decode into the ADataSpace specified by
* {@link AImageDecoderHeaderInfo_getDataSpace}. If this
* parameter is set to a different ADataSpace, AImageDecoder
* will transform the output into the specified ADataSpace.
* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
* indicating the reason for the failure.
*
* Errors:
* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The
* {@link AImageDecoder} is null or |dataspace| does not correspond to an
* {@link ADataSpace} value.
*/
int AImageDecoder_setDataSpace(AImageDecoder*, int32_t dataspace) __INTRODUCED_IN(30);
/**
* Specify the output size for a decoded image.
*
* Future calls to {@link AImageDecoder_decodeImage} will sample or scale the
* encoded image to reach the desired size. If a crop rect is set (via
* {@link 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.
*
* @param width Width of the output (prior to cropping).
* This will affect future calls to
* {@link AImageDecoder_getMinimumStride}, which will now return
* a value based on this width.
* @param height Height of the output (prior to cropping).
* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
* indicating the reason for the failure.
*
* Errors:
* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The
* {@link AImageDecoder} is null.
* - {@link 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
* {@link AImageDecoder_setUnpremultipliedRequired}(true).
*/
int AImageDecoder_setTargetSize(AImageDecoder*, int32_t width, int32_t height) __INTRODUCED_IN(30);
/**
* Compute the dimensions to use for a given sampleSize.
*
* Although AImageDecoder can scale to an arbitrary target size (see
* {@link 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.
*
* @param 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.
* @param width Out parameter for the width sampled by sampleSize, and rounded
* in the direction that the decoder can do most efficiently.
* @param height Out parameter for the height sampled by sampleSize, and rounded
* in the direction that the decoder can do most efficiently.
* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
* indicating the reason for the failure.
*
* Errors:
* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The
* {@link AImageDecoder}, |width| or |height| is null or |sampleSize| is < 1.
*/
int AImageDecoder_computeSampledSize(const AImageDecoder*, int sampleSize,
int32_t* width, int32_t* height) __INTRODUCED_IN(30);
/**
* Specify how to crop the output after scaling (if any).
*
* Future calls to {@link AImageDecoder_decodeImage} will crop their output to
* the specified {@link ARect}. Clients will only need to allocate enough memory
* for the cropped ARect.
*
* Available since API level 30.
*
* @param crop Rectangle describing a crop of the decode. It must be contained inside of
* the (possibly scaled, by {@link AImageDecoder_setTargetSize})
* image dimensions. This will affect future calls to
* {@link 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 {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}.
* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
* indicating the reason for the failure.
*
* Errors:
* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The
* {@link AImageDecoder} is null or the crop is not contained by the
* (possibly scaled) image dimensions.
*/
int AImageDecoder_setCrop(AImageDecoder*, ARect crop) __INTRODUCED_IN(30);
struct AImageDecoderHeaderInfo;
/**
* Opaque handle for representing information about the encoded image. Retrieved
* using {@link AImageDecoder_getHeaderInfo} and passed to methods like
* {@link AImageDecoderHeaderInfo_getWidth} and
* {@link AImageDecoderHeaderInfo_getHeight}.
*/
typedef struct AImageDecoderHeaderInfo AImageDecoderHeaderInfo;
/**
* Return an opaque handle for reading header info.
*
* This is owned by the {@link AImageDecoder} and will be destroyed when the
* AImageDecoder is destroyed via {@link AImageDecoder_delete}.
*
* Available since API level 30.
*/
const AImageDecoderHeaderInfo* AImageDecoder_getHeaderInfo(
const AImageDecoder*) __INTRODUCED_IN(30);
/**
* Report the native width of the encoded image. This is also the logical
* pixel width of the output, unless {@link AImageDecoder_setTargetSize} is
* used to choose a different size or {@link AImageDecoder_setCrop} is used to
* set a crop rect.
*
* Available since API level 30.
*/
int32_t AImageDecoderHeaderInfo_getWidth(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
/**
* Report the native height of the encoded image. This is also the logical
* pixel height of the output, unless {@link AImageDecoder_setTargetSize} is
* used to choose a different size or {@link AImageDecoder_setCrop} is used to
* set a crop rect.
*
* Available since API level 30.
*/
int32_t AImageDecoderHeaderInfo_getHeight(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
/**
* Report the mimeType of the encoded image.
*
* Available since API level 30.
*
* @return a string literal describing the mime type.
*/
const char* AImageDecoderHeaderInfo_getMimeType(
const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
/**
* Report the {@link AndroidBitmapFormat} the AImageDecoder will decode to
* by default. {@link 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.
*/
int32_t AImageDecoderHeaderInfo_getAndroidBitmapFormat(
const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
/**
* Report how the {@link AImageDecoder} will handle alpha by default. If the image
* contains no alpha (according to its header), this will return
* {@link ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE}. If the image may contain alpha,
* this returns {@link ANDROID_BITMAP_FLAGS_ALPHA_PREMUL}, because
* {@link AImageDecoder_decodeImage} will premultiply pixels by default.
*
* Available since API level 30.
*/
int AImageDecoderHeaderInfo_getAlphaFlags(
const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
/**
* Report the dataspace the AImageDecoder will decode to by default.
*
* By default, {@link AImageDecoder_decodeImage} will not do any color
* conversion.
*
* Available since API level 30.
*
* @return The {@link ADataSpace} representing the way the colors
* are encoded (or {@link ADATASPACE_UNKNOWN} if there is not a
* corresponding ADataSpace). This specifies how to interpret the colors
* in the decoded image, unless {@link AImageDecoder_setDataSpace} is
* called to decode to a different ADataSpace.
*
* Note that ADataSpace only exposes a few values. This may return
* {@link ADATASPACE_UNKNOWN}, even for Named ColorSpaces, if they have
* no corresponding {@link ADataSpace}.
*/
int32_t AImageDecoderHeaderInfo_getDataSpace(
const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
/**
* Return the minimum stride that can be used in
* {@link 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 {@link AndroidBitmapFormat}
* being used.
*
* If the output is scaled (via {@link AImageDecoder_setTargetSize}) and/or
* cropped (via {@link AImageDecoder_setCrop}), this takes those into account.
*
* Available since API level 30.
*/
size_t AImageDecoder_getMinimumStride(AImageDecoder*) __INTRODUCED_IN(30);
/**
* Decode the image into pixels, using the settings of the {@link AImageDecoder}.
*
* Available since API level 30.
*
* @param decoder Opaque object representing the decoder.
* @param pixels On success, will be filled with the result
* of the decode. Must be large enough to hold |size| bytes.
* @param stride Width in bytes of a single row. Must be at least
* {@link AImageDecoder_getMinimumStride} and a multiple of the
* bytes per pixel of the {@link AndroidBitmapFormat}.
* @param size Size of the pixel buffer in bytes. Must be at least
* stride * (height - 1) +
* {@link AImageDecoder_getMinimumStride}.
* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
* indicating the reason for the failure.
*
* Errors:
* - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The image was truncated. A
* partial image was decoded, and undecoded lines have been initialized to all
* zeroes.
* - {@link ANDROID_IMAGE_DECODER_ERROR}: The image contained an error. A
* partial image was decoded, and undecoded lines have been initialized to all
* zeroes.
* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The {@link AImageDecoder} or
* |pixels| is null, the stride is not large enough or not pixel aligned, or
* |size| is not large enough.
* - {@link ANDROID_IMAGE_DECODER_SEEK_ERROR}: The asset or file descriptor
* failed to seek.
* - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a
* failure to allocate memory.
*/
int AImageDecoder_decodeImage(AImageDecoder* decoder,
void* pixels, size_t stride,
size_t size) __INTRODUCED_IN(30);
#ifdef __cplusplus
}
#endif
#endif // ANDROID_IMAGE_DECODER_H
/** @} */