AImageDecoder: respond to API review (bb5ffd20) · Commits · e / os / platform_frameworks_native

include/android/imagedecoder.h

+128 −41

Original line number	Original line	Diff line number	Diff line
	@@ -20,9 +20,18 @@
	* Functions for converting encoded images into RGBA pixels.		* Functions for converting encoded images into RGBA pixels.
	*		*
	* Similar to the Java counterpart android.graphics.ImageDecoder, it can be used		* Similar to the Java counterpart android.graphics.ImageDecoder, it can be used
	* to decode images like PNG, JPEG, GIF, WEBP and HEIF. It has similar options		* to decode images in the following formats:
	* for scaling, cropping, and choosing the output format. Unlike the Java API,		* - JPEG
	* which can create an android.graphics.Bitmap or		* - 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		* android.graphics.drawable.Drawable object, AImageDecoder decodes directly
	* into memory provided by the client. For more information, see the		* into memory provided by the client. For more information, see the
	* <a href="https://developer.android.com/ndk/guides/image-decoder">Image decoder</a>		* <a href="https://developer.android.com/ndk/guides/image-decoder">Image decoder</a>
	@@ -62,7 +71,7 @@ enum {
	*/		*/
	ANDROID_IMAGE_DECODER_SUCCESS = 0,		ANDROID_IMAGE_DECODER_SUCCESS = 0,
	/**		/**
	* The input was incomplete.		* The input is incomplete.
	*/		*/
	ANDROID_IMAGE_DECODER_INCOMPLETE = -1,		ANDROID_IMAGE_DECODER_INCOMPLETE = -1,
	/**		/**
	@@ -80,7 +89,7 @@ enum {
	*/		*/
	ANDROID_IMAGE_DECODER_INVALID_SCALE = -4,		ANDROID_IMAGE_DECODER_INVALID_SCALE = -4,
	/**		/**
	* Some other parameter was bad.		* Some other parameter is invalid.
	*/		*/
	ANDROID_IMAGE_DECODER_BAD_PARAMETER = -5,		ANDROID_IMAGE_DECODER_BAD_PARAMETER = -5,
	/**		/**
	@@ -133,6 +142,19 @@ typedef struct AImageDecoder AImageDecoder;
	* responsible for calling {@link AImageDecoder_delete} on it.		* responsible for calling {@link AImageDecoder_delete} on it.
	* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value		* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
	* indicating the reason for the failure.		* 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)		int AImageDecoder_createFromAAsset(struct AAsset* asset, AImageDecoder** outDecoder)
	__INTRODUCED_IN(30);		__INTRODUCED_IN(30);
	@@ -149,6 +171,19 @@ int AImageDecoder_createFromAAsset(struct AAsset* asset, AImageDecoder** outDeco
	* responsible for calling {@link AImageDecoder_delete} on it.		* responsible for calling {@link AImageDecoder_delete} on it.
	* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value		* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
	* indicating the reason for the failure.		* 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);		int AImageDecoder_createFromFd(int fd, AImageDecoder** outDecoder) __INTRODUCED_IN(30);

	@@ -163,7 +198,19 @@ int AImageDecoder_createFromFd(int fd, AImageDecoder** outDecoder) __INTRODUCED_
	* a newly created {@link AImageDecoder}. Caller is		* a newly created {@link AImageDecoder}. Caller is
	* responsible for calling {@link AImageDecoder_delete} on it.		* responsible for calling {@link AImageDecoder_delete} on it.
	* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value		* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
	* indicating reason for the failure.		* 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,		int AImageDecoder_createFromBuffer(const void* buffer, size_t length,
	AImageDecoder** outDecoder) __INTRODUCED_IN(30);		AImageDecoder** outDecoder) __INTRODUCED_IN(30);
	@@ -177,11 +224,18 @@ void AImageDecoder_delete(AImageDecoder* decoder) __INTRODUCED_IN(30);
	* Choose the desired output format.		* Choose the desired output format.
	*		*
	* @param format {@link AndroidBitmapFormat} to use for the output.		* @param format {@link AndroidBitmapFormat} to use for the output.
	* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} if the format is compatible		* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
	* with the image and {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION}		* indicating the reason for the failure. On failure, the
	* otherwise. In the latter case, the {@link AImageDecoder} uses the		* {@link AImageDecoder} uses the format it was already planning
	* format it was already planning to use (either its default		* to use (either its default or a previously successful setting
	* or a previously successful setting from this function).		* 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*,		int AImageDecoder_setAndroidBitmapFormat(AImageDecoder*,
	int32_t format) __INTRODUCED_IN(30);		int32_t format) __INTRODUCED_IN(30);
	@@ -194,11 +248,15 @@ int AImageDecoder_setAndroidBitmapFormat(AImageDecoder*,
	* opaque image.		* opaque image.
	*		*
	* @param unpremultipliedRequired Pass true to leave the pixels unpremultiplied.		* @param unpremultipliedRequired Pass true to leave the pixels unpremultiplied.
	* @return an enum describing whether the call succeeded.		* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
	* - {@link ANDROID_IMAGE_DECODER_SUCCESS} on success		* indicating the reason for the failure.
	* - {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION} if the conversion		*
	* is not possible		* Errors:
	* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for bad parameters		* - {@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*,		int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*,
	bool unpremultipliedRequired) __INTRODUCED_IN(30);		bool unpremultipliedRequired) __INTRODUCED_IN(30);
	@@ -215,9 +273,12 @@ int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*,
	* {@link AImageDecoderHeaderInfo_getDataSpace}. If this		* {@link AImageDecoderHeaderInfo_getDataSpace}. If this
	* parameter is set to a different ADataSpace, AImageDecoder		* parameter is set to a different ADataSpace, AImageDecoder
	* will transform the output into the specified ADataSpace.		* will transform the output into the specified ADataSpace.
	* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or		* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
	* {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for a null		* indicating the reason for the failure.
	* {@link AImageDecoder} or an integer that does not correspond to an		*
			* Errors:
			* - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The
			* {@link AImageDecoder} is null or \|dataspace\| does not correspond to an
	* {@link ADataSpace} value.		* {@link ADataSpace} value.
	*/		*/
	int AImageDecoder_setDataSpace(AImageDecoder*, int32_t dataspace) __INTRODUCED_IN(30);		int AImageDecoder_setDataSpace(AImageDecoder*, int32_t dataspace) __INTRODUCED_IN(30);
	@@ -236,11 +297,16 @@ int AImageDecoder_setDataSpace(AImageDecoder*, int32_t dataspace) __INTRODUCED_I
	* {@link AImageDecoder_getMinimumStride}, which will now return		* {@link AImageDecoder_getMinimumStride}, which will now return
	* a value based on this width.		* a value based on this width.
	* @param height Height of the output (prior to cropping).		* @param height Height of the output (prior to cropping).
	* @return an enum describing whether the call succeeded.		* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
	* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or		* indicating the reason for the failure.
	* {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if the {@link AImageDecoder}		*
	* pointer is null, width or height is <= 0, or any existing crop is		* Errors:
	* not contained by the new image dimensions.		* - {@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);		int AImageDecoder_setTargetSize(AImageDecoder*, int32_t width, int32_t height) __INTRODUCED_IN(30);

	@@ -262,8 +328,12 @@ int AImageDecoder_setTargetSize(AImageDecoder*, int32_t width, int32_t height) _
	* in the direction that the decoder can do most efficiently.		* in the direction that the decoder can do most efficiently.
	* @param height Out parameter for the height sampled by sampleSize, and rounded		* @param height Out parameter for the height sampled by sampleSize, and rounded
	* in the direction that the decoder can do most efficiently.		* in the direction that the decoder can do most efficiently.
	* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or		* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
	* {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for bad input.		* 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,		int AImageDecoder_computeSampledSize(const AImageDecoder*, int sampleSize,
	int32_t* width, int32_t* height) __INTRODUCED_IN(30);		int32_t* width, int32_t* height) __INTRODUCED_IN(30);
	@@ -282,18 +352,21 @@ int AImageDecoder_computeSampledSize(const AImageDecoder*, int sampleSize,
	* specifically { 0, 0, 0, 0 } - may be used to remove the cropping		* specifically { 0, 0, 0, 0 } - may be used to remove the cropping
	* behavior. Any other empty or unsorted ARects will result in		* behavior. Any other empty or unsorted ARects will result in
	* returning {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}.		* returning {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}.
	* @return an enum describing whether the call succeeded.		* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
	* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or		* indicating the reason for the failure.
	* {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if the {@link AImageDecoder}		*
	* pointer is null or the crop is not contained by the image		* Errors:
	* dimensions.		* - {@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);		int AImageDecoder_setCrop(AImageDecoder*, ARect crop) __INTRODUCED_IN(30);

	struct AImageDecoderHeaderInfo;		struct AImageDecoderHeaderInfo;
	/**		/**
	* Opaque handle for representing information about the encoded image. It can		* Opaque handle for representing information about the encoded image. Retrieved
	* be passed to methods like {@link AImageDecoderHeaderInfo_getWidth} and		* using {@link AImageDecoder_getHeaderInfo} and passed to methods like
			* {@link AImageDecoderHeaderInfo_getWidth} and
	* {@link AImageDecoderHeaderInfo_getHeight}.		* {@link AImageDecoderHeaderInfo_getHeight}.
	*/		*/
	typedef struct AImageDecoderHeaderInfo AImageDecoderHeaderInfo;		typedef struct AImageDecoderHeaderInfo AImageDecoderHeaderInfo;
	@@ -310,14 +383,16 @@ const AImageDecoderHeaderInfo* AImageDecoder_getHeaderInfo(
	/**		/**
	* Report the native width of the encoded image. This is also the logical		* Report the native width of the encoded image. This is also the logical
	* pixel width of the output, unless {@link AImageDecoder_setTargetSize} is		* pixel width of the output, unless {@link AImageDecoder_setTargetSize} is
	* used to choose a different size.		* used to choose a different size or {@link AImageDecoder_setCrop} is used to
			* set a crop rect.
	*/		*/
	int32_t AImageDecoderHeaderInfo_getWidth(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);		int32_t AImageDecoderHeaderInfo_getWidth(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);

	/**		/**
	* Report the native height of the encoded image. This is also the logical		* Report the native height of the encoded image. This is also the logical
	* pixel height of the output, unless {@link AImageDecoder_setTargetSize} is		* pixel height of the output, unless {@link AImageDecoder_setTargetSize} is
	* used to choose a different size.		* used to choose a different size or {@link AImageDecoder_setCrop} is used to
			* set a crop rect.
	*/		*/
	int32_t AImageDecoderHeaderInfo_getHeight(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);		int32_t AImageDecoderHeaderInfo_getHeight(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);

	@@ -392,11 +467,23 @@ size_t AImageDecoder_getMinimumStride(AImageDecoder*) __INTRODUCED_IN(30);
	* @param size Size of the pixel buffer in bytes. Must be at least		* @param size Size of the pixel buffer in bytes. Must be at least
	* stride * (height - 1) +		* stride * (height - 1) +
	* {@link AImageDecoder_getMinimumStride}.		* {@link AImageDecoder_getMinimumStride}.
	* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success, or an error code		* @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
	* from the same enum describing the failure.		* indicating the reason for the failure.
	* {@link ANDROID_IMAGE_DECODER_INCOMPLETE} or		*
	* {@link ANDROID_IMAGE_DECODER_ERROR} means that a partial image was		* Errors:
	* decoded, and undecoded lines have been initialized to all zeroes.		* - {@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,		int AImageDecoder_decodeImage(AImageDecoder* decoder,
	void* pixels, size_t stride,		void* pixels, size_t stride,