From 2f98494d4d689a9484942435e4101114daadd91f Mon Sep 17 00:00:00 2001
From: Leon Scroggins III <scroggo@google.com>
Date: Fri, 22 Nov 2019 17:02:23 -0500
Subject: Add NDK Apis for image decoding

Bug: 135133301
Test: Ib84462ea5fa8a7779eaa44494775e182e52ecaca
Change-Id: I8fd341c538f6b0d96f7abed77d58b003a3aefd12
---
 include/android/imagedecoder.h | 299 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 299 insertions(+)
 create mode 100644 include/android/imagedecoder.h

(limited to 'include/android/imagedecoder.h')

diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
new file mode 100644
index 0000000000..50daabaaff
--- /dev/null
+++ b/include/android/imagedecoder.h
@@ -0,0 +1,299 @@
+/*
+ * 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.
+ */
+
+/**
+ * @addtogroup ImageDecoder
+ * @{
+ */
+
+/**
+ * @file imageDecoder.h
+ */
+
+#ifndef ANDROID_IMAGE_DECODER_H
+#define ANDROID_IMAGE_DECODER_H
+
+#include "bitmap.h"
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct AAsset;
+struct ARect;
+
+#if __ANDROID_API__ >= 30
+
+/** AImageDecoder functions result code. */
+enum {
+    // Decoding was successful and complete.
+    ANDROID_IMAGE_DECODER_SUCCESS = 0,
+    // The input was incomplete. In decodeImage, this means a partial
+    // image was decoded. Undecoded lines are all zeroes.
+    // In AImageDecoder_create*, no AImageDecoder was created.
+    ANDROID_IMAGE_DECODER_INCOMPLETE = -1,
+    // The input contained an error after decoding some lines. Similar to
+    // INCOMPLETE, above.
+    ANDROID_IMAGE_DECODER_ERROR = -2,
+    // Could not convert, e.g. 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 was bad (e.g. pixels)
+    ANDROID_IMAGE_DECODER_BAD_PARAMETER = -5,
+    // Input was invalid i.e. broken before decoding any pixels.
+    ANDROID_IMAGE_DECODER_INVALID_INPUT = -6,
+    // A seek was required, and failed.
+    ANDROID_IMAGE_DECODER_SEEK_ERROR = -7,
+    // Some other error (e.g. OOM)
+    ANDROID_IMAGE_DECODER_INTERNAL_ERROR = -8,
+    // We 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}
+ */
+typedef struct AImageDecoder AImageDecoder;
+
+/**
+ * Create a new AImageDecoder from an AAsset.
+ *
+ * @param asset {@link AAsset} containing encoded image data. Client is still
+ *              responsible for calling {@link AAsset_close} on it.
+ * @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 reason for the failure.
+ */
+int AImageDecoder_createFromAAsset(AAsset* asset, AImageDecoder** outDecoder) __INTRODUCED_IN(30);
+
+/**
+ * Create a new AImageDecoder from a file descriptor.
+ *
+ * @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 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 reason for the failure.
+ */
+int AImageDecoder_createFromFd(int fd, AImageDecoder** outDecoder) __INTRODUCED_IN(30);
+
+/**
+ * Create a new AImageDecoder from a buffer.
+ *
+ * @param buffer Pointer to encoded data. Must be valid for the entire time
+ *               the 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 reason for the failure.
+ */
+int AImageDecoder_createFromBuffer(const void* buffer, size_t length,
+                                   AImageDecoder** outDecoder) __INTRODUCED_IN(30);
+
+/**
+ * Delete the AImageDecoder.
+ */
+void AImageDecoder_delete(AImageDecoder* decoder) __INTRODUCED_IN(30);
+
+/**
+ * Choose the desired output format.
+ *
+ * @param format AndroidBitmapFormat to use
+ * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} if the format is compatible
+ *         with the image and {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION}
+ *         otherwise. In the latter case, the AImageDecoder uses the
+ *         format it was already planning to use (either its default
+ *         or a previously successful setting from this function).
+ */
+int AImageDecoder_setAndroidBitmapFormat(AImageDecoder*,
+        int32_t format) __INTRODUCED_IN(30);
+
+/*
+ * Choose the desired output format.
+ *
+ * Must be one of:
+ * {@link ANDROID_BITMAP_FLAGS_ALPHA_PREMUL}
+ * {@link ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE}
+ * {@link ANDROID_BITMAP_FLAGS_ALPHA_UNPREMUL}
+ *
+ * Note: An OPAQUE image may be set to any of them.
+ *       A non-OPAQUE image may not be set to OPAQUE
+ *
+ * @return - {@link ANDROID_IMAGE_DECODER_SUCCESS} on success
+ *         - {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION} if the conversion
+ *           is not possible
+ *         - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for bad parameters
+ */
+int AImageDecoder_setAlphaFlags(AImageDecoder*, int alphaFlags) __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.
+ *
+ * @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
+ *         - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if the AImageDecoder
+ *           pointer is null, width or height is <= 0, or any existing crop is
+ *           not contained by the image dimensions.
+ */
+int AImageDecoder_setTargetSize(AImageDecoder*, int width, int 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.
+ *
+ * @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 ANDROID_IMAGE_DECODER_BAD_PARAMETER.
+ * @return - {@link ANDROID_IMAGE_DECODER_SUCCESS} on success
+ *         - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if the AImageDecoder
+ *           pointer is null or the crop is not contained by the image
+ *           dimensions.
+ */
+int AImageDecoder_setCrop(AImageDecoder*, ARect crop) __INTRODUCED_IN(30);
+
+/**
+ * Opaque handle for reading header info.
+ */
+struct AImageDecoderHeaderInfo;
+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}.
+ */
+const AImageDecoderHeaderInfo* AImageDecoder_getHeaderInfo(
+        const AImageDecoder*) __INTRODUCED_IN(30);
+
+/**
+ * Report the native width of the encoded image.
+ */
+int32_t AImageDecoderHeaderInfo_getWidth(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
+
+/**
+ * Report the native height of the encoded image.
+ */
+int32_t AImageDecoderHeaderInfo_getHeight(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
+
+/**
+ * Report the mimeType of the encoded image.
+ *
+ * @return a string literal describing the mime type.
+ */
+const char* AImageDecoderHeaderInfo_getMimeType(
+        const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
+
+/**
+ * Report whether the encoded image represents an animation.
+ */
+bool AImageDecoderHeaderInfo_isAnimated(
+        const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
+
+/**
+ * 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.
+ */
+AndroidBitmapFormat AImageDecoderHeaderInfo_getAndroidBitmapFormat(
+        const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
+
+/**
+ * Report how the 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}.
+ *
+ * For animated images only the opacity of the first frame is reported.
+ */
+int AImageDecoderHeaderInfo_getAlphaFlags(
+        const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
+
+/**
+ * Return the minimum stride that can be used, taking the specified
+ * (or default) (possibly scaled) width, crop rect and
+ * {@link AndroidBitmapFormat} into account.
+ */
+size_t AImageDecoder_getMinimumStride(AImageDecoder*) __INTRODUCED_IN(30);
+
+/**
+ * Decode the image into pixels, using the settings of the AImageDecoder.
+ *
+ * @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 fit |size| bytes.
+ * @param stride Width in bytes of a single row. Must be at least
+ *               {@link AImageDecoder_getMinimumStride}.
+ * @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 an error code
+ *         from the same enum describing the failure.
+ */
+int AImageDecoder_decodeImage(AImageDecoder* decoder,
+                              void* pixels, size_t stride,
+                              size_t size) __INTRODUCED_IN(30);
+
+#endif // __ANDROID_API__ >= 30
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // ANDROID_IMAGE_DECODER_H
+
+/** @} */
-- 
cgit v1.2.3-59-g8ed1b


From 1be112f2af35ea040d0203c765f7e229ba793a08 Mon Sep 17 00:00:00 2001
From: Leon Scroggins III <scroggo@google.com>
Date: Wed, 15 Jan 2020 04:26:44 -0500
Subject: Rename setAlphaFlags to setUnpremultipliedRequired

Bug: 135133301
Test: I48e49ee08ab1954eddf62ecae87942aeb128c10d

There is never any reason to request OPAQUE. If the image is already
opaque, using PREMUL or UNPREMUL has no effect. If the image is not
opaque, the requesting OPAQUE is an error. This behavior is not
helpful.

In addition, this matches the Java API for
android.graphics.ImageDecoder.

Lastly, the old API was confusing for animated images. It is possible
for the first frame to be opaque, while a later frame is not. Requesting
OPAQUE seems reasonable for this image, until decoding the non-opaque
frame, at which point the inconsistency shows. Having a setting of
unpremul or not makes it obvious what will happen for the later frame.

Change-Id: I3381582e27894e1072db9b8635f3762b801f5d69
---
 include/android/imagedecoder.h | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

(limited to 'include/android/imagedecoder.h')

diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index 50daabaaff..4b6446c33d 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -143,23 +143,20 @@ void AImageDecoder_delete(AImageDecoder* decoder) __INTRODUCED_IN(30);
 int AImageDecoder_setAndroidBitmapFormat(AImageDecoder*,
         int32_t format) __INTRODUCED_IN(30);
 
-/*
- * Choose the desired output format.
- *
- * Must be one of:
- * {@link ANDROID_BITMAP_FLAGS_ALPHA_PREMUL}
- * {@link ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE}
- * {@link ANDROID_BITMAP_FLAGS_ALPHA_UNPREMUL}
+/**
+ * Specify whether the output's pixels should be unpremultiplied.
  *
- * Note: An OPAQUE image may be set to any of them.
- *       A non-OPAQUE image may not be set to OPAQUE
+ * By default, the decoder will premultiply the pixels, if they have alpha. Pass
+ * false to this method to leave them unpremultiplied. This has no effect on an
+ * opaque image.
  *
+ * @param required Pass true to leave the pixels unpremultiplied.
  * @return - {@link ANDROID_IMAGE_DECODER_SUCCESS} on success
  *         - {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION} if the conversion
  *           is not possible
  *         - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for bad parameters
  */
-int AImageDecoder_setAlphaFlags(AImageDecoder*, int alphaFlags) __INTRODUCED_IN(30);
+int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*, bool required) __INTRODUCED_IN(30);
 
 /**
  * Specify the output size for a decoded image.
-- 
cgit v1.2.3-59-g8ed1b


From f27256b956d6a48ce8d74aaab36617a41d00cee2 Mon Sep 17 00:00:00 2001
From: Leon Scroggins III <scroggo@google.com>
Date: Sun, 19 Jan 2020 21:13:04 -0500
Subject: Add AImageDecoder_computeSampledSize

Bug: 135133301
Test: If9ed79d8dcf1169369ba454723f4ac8d26427b7b

This allows an NDK client to find an efficient target size to use.

Change-Id: Iabc3db1547d4863f9aa0324bc438d994eadeef01
---
 include/android/imagedecoder.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

(limited to 'include/android/imagedecoder.h')

diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index 4b6446c33d..c9fde0d3b7 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -179,6 +179,28 @@ int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*, bool required) __IN
  */
 int AImageDecoder_setTargetSize(AImageDecoder*, int width, int 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.
+ *
+ * @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
+ *              direction that the decoder can do most efficiently.
+ * @param height Out parameter for the height sampled by sampleSize, and rounded
+ *               direction that the decoder can do most efficiently.
+ * @return ANDROID_IMAGE_DECODER result code.
+ */
+int AImageDecoder_computeSampledSize(const AImageDecoder*, int sampleSize,
+                                     int* width, int* height) __INTRODUCED_IN(30);
 /**
  * Specify how to crop the output after scaling (if any).
  *
-- 
cgit v1.2.3-59-g8ed1b


From 20d480ce9c6bfdd54d2b1e5e34306744968a4f37 Mon Sep 17 00:00:00 2001
From: Leon Scroggins III <scroggo@google.com>
Date: Wed, 15 Jan 2020 15:32:59 -0500
Subject: Add AImageDecoder HeaderInfo_get/_setDataSpace

Bug: 135133301
Test: Iffe659e50078139188c3325545624640ae177cc2

Default to ADATASPACE_UNKNOWN for images that do not have a matching
ADataSpace. This matches the behavior of android.graphics.ImageDecoder
and BitmapFactory, which would use an "Unknown" ColorSpace for the same
images. It also means that a client who knows the true underlying
profile information to treat it as if it came from that profile.
Further, it means that if we add more ADataSpace values in the future,
the decode will be unchanged. A client can still choose to use a known
ADataSpace using _setDataSpace.

Change-Id: Id3ecf3bab17e4905fb2b75410ec756233d600c97
---
 include/android/imagedecoder.h | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

(limited to 'include/android/imagedecoder.h')

diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index 4b6446c33d..68401ea5a2 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -158,6 +158,25 @@ int AImageDecoder_setAndroidBitmapFormat(AImageDecoder*,
  */
 int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*, bool required) __INTRODUCED_IN(30);
 
+/**
+ * Choose the dataspace for the output.
+ *
+ * Not supported for {@link ANDROID_BITMAP_FORMAT_A_8}, which does not support
+ * an ADataSpace.
+ *
+ * @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
+ *         - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for a null
+ *           AImageDecoder or an integer that does not correspond to an
+ *           ADataSpace value.
+ */
+int AImageDecoder_setDataSpace(AImageDecoder*, int32_t dataspace) __INTRODUCED_IN(30);
+
 /**
  * Specify the output size for a decoded image.
  *
@@ -260,6 +279,25 @@ AndroidBitmapFormat AImageDecoderHeaderInfo_getAndroidBitmapFormat(
 int AImageDecoderHeaderInfo_getAlphaFlags(
         const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
 
+/**
+ * Report the dataspace 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 may not exactly match the ICC
+ * profile (or other color information) stored in the encoded image.
+ *
+ * @return The {@link ADataSpace} most closely representing the way the colors
+ *         are encoded (or {@link ADATASPACE_UNKNOWN} if there is not an
+ *         approximate 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
+ *         ADATASPACE_UNKNOWN, even for Named ColorSpaces, if they have no
+ *         corresponding ADataSpace.
+ */
+int32_t AImageDecoderHeaderInfo_getDataSpace(
+        const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
+
 /**
  * Return the minimum stride that can be used, taking the specified
  * (or default) (possibly scaled) width, crop rect and
-- 
cgit v1.2.3-59-g8ed1b


From 59262f93650e4fa7205c64680045faa52f4da5fa Mon Sep 17 00:00:00 2001
From: Leon Scroggins III <scroggo@google.com>
Date: Wed, 22 Jan 2020 17:29:06 -0500
Subject: Update decodeImage to account for alignment

Bug: 147749998
Test: I902de3410c45a21cf27b48a02cdc5d514b7ada60

Document that the stride must be pixel-aligned.

Change-Id: Ifbd667298f542f249092ae8eca744b4ed65afaee
---
 include/android/imagedecoder.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'include/android/imagedecoder.h')

diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index 469b088c89..c9a041e2ef 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -337,7 +337,8 @@ size_t AImageDecoder_getMinimumStride(AImageDecoder*) __INTRODUCED_IN(30);
  *               {@link AImageDecoder_getMinimumStride}.
  * @param size Size of the pixel buffer in bytes. Must be at least
  *             stride * (height - 1) +
- *             {@link AImageDecoder_getMinimumStride}.
+ *             {@link AImageDecoder_getMinimumStride}. Must also be a multiple
+ *             of the bytes per pixel of the {@link AndroidBitmapFormat}.
  * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success, or an error code
  *         from the same enum describing the failure.
  */
-- 
cgit v1.2.3-59-g8ed1b


From 5d0445cc3e16af2e49ae87580ecc420be54b4608 Mon Sep 17 00:00:00 2001
From: Leon Scroggins III <scroggo@google.com>
Date: Thu, 23 Jan 2020 09:43:43 -0500
Subject: Clean up imagedecoder header file

Bug: 135133301
Test: Ibf7c0e563feeb08ce6dbabb5e86ddb385c9dff54

Remove AImageDecoderHeaderInfo_isAnimated. We are punting animation
support to S, so there is no reason to report whether the image is
animated.

Use int32_t for width and height. We already return these for
AImageDecoderHeaderInfo_getWidth/getHeight, so use the same type for
AImageDecoder_setTargetSize/computeSampledSize.

Use int32_t for AImageDecoderHeaderInfo_getAndroidBitmapFormat. This
matches the convention for what to return when the value is logically an
enum.

Change-Id: I93df851dd9fee2eb8d097e2158fb95003a0474db
---
 include/android/imagedecoder.h | 16 +++++-----------
 1 file changed, 5 insertions(+), 11 deletions(-)

(limited to 'include/android/imagedecoder.h')

diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index 469b088c89..31efa65cbe 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -133,7 +133,7 @@ void AImageDecoder_delete(AImageDecoder* decoder) __INTRODUCED_IN(30);
 /**
  * Choose the desired output format.
  *
- * @param format AndroidBitmapFormat to use
+ * @param format {@link AndroidBitmapFormat} to use for the output.
  * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} if the format is compatible
  *         with the image and {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION}
  *         otherwise. In the latter case, the AImageDecoder uses the
@@ -196,7 +196,7 @@ int AImageDecoder_setDataSpace(AImageDecoder*, int32_t dataspace) __INTRODUCED_I
  *           pointer is null, width or height is <= 0, or any existing crop is
  *           not contained by the image dimensions.
  */
-int AImageDecoder_setTargetSize(AImageDecoder*, int width, int height) __INTRODUCED_IN(30);
+int AImageDecoder_setTargetSize(AImageDecoder*, int32_t width, int32_t height) __INTRODUCED_IN(30);
 
 
 /**
@@ -219,7 +219,7 @@ int AImageDecoder_setTargetSize(AImageDecoder*, int width, int height) __INTRODU
  * @return ANDROID_IMAGE_DECODER result code.
  */
 int AImageDecoder_computeSampledSize(const AImageDecoder*, int sampleSize,
-                                     int* width, int* height) __INTRODUCED_IN(30);
+                                     int32_t* width, int32_t* height) __INTRODUCED_IN(30);
 /**
  * Specify how to crop the output after scaling (if any).
  *
@@ -276,18 +276,12 @@ const char* AImageDecoderHeaderInfo_getMimeType(
         const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
 
 /**
- * Report whether the encoded image represents an animation.
- */
-bool AImageDecoderHeaderInfo_isAnimated(
-        const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
-
-/**
- * Report the AndroidBitmapFormat the AImageDecoder will decode to
+ * Report the {@link 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.
  */
-AndroidBitmapFormat AImageDecoderHeaderInfo_getAndroidBitmapFormat(
+int32_t AImageDecoderHeaderInfo_getAndroidBitmapFormat(
         const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
 
 /**
-- 
cgit v1.2.3-59-g8ed1b


From a9f397b562df067d27888789954c539f6c0fa624 Mon Sep 17 00:00:00 2001
From: Leon Scroggins III <scroggo@google.com>
Date: Mon, 27 Jan 2020 12:42:56 -0500
Subject: Update imagedecoder.h to build as a C file

Bug: 135133301
Test: build as a C file

AAsset is a forward-declared struct, so it needs to be declared in
parameters as a struct in order to compile as a C file.

In addition, include rect.h explicitly for documentation purposes. This
also means that ARect as a parameter does not need to be declared as
"struct ARect".

Change-Id: I30c5176010ec3b5b0405f0b383654a7cfca65b62
---
 include/android/imagedecoder.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'include/android/imagedecoder.h')

diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index 469b088c89..cabd626c35 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -27,7 +27,7 @@
 #define ANDROID_IMAGE_DECODER_H
 
 #include "bitmap.h"
-
+#include <android/rect.h>
 #include <stdint.h>
 
 #ifdef __cplusplus
@@ -35,7 +35,6 @@ extern "C" {
 #endif
 
 struct AAsset;
-struct ARect;
 
 #if __ANDROID_API__ >= 30
 
@@ -92,7 +91,8 @@ typedef struct AImageDecoder AImageDecoder;
  * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value
  *         indicating reason for the failure.
  */
-int AImageDecoder_createFromAAsset(AAsset* asset, AImageDecoder** outDecoder) __INTRODUCED_IN(30);
+int AImageDecoder_createFromAAsset(struct AAsset* asset, AImageDecoder** outDecoder)
+        __INTRODUCED_IN(30);
 
 /**
  * Create a new AImageDecoder from a file descriptor.
-- 
cgit v1.2.3-59-g8ed1b


From 97fea5f41c5da1765889660a881f5d7b655de544 Mon Sep 17 00:00:00 2001
From: Leon Scroggins III <scroggo@google.com>
Date: Thu, 30 Jan 2020 12:18:20 -0500
Subject: Update imagedecoder documentation

Bug: 147839368
Test: No change in behavior

Update documentation in response to feedback and after reviewing
https://android.devsite.corp.google.com/ndk/reference/group/image-decoder.html#group___image_decoder_1ga8c3a19f8ae30a936a17b3879f849ea60

- Use @defgroup instead of @addtogroup, since this is the only file for
this group.
- Add a top-level description, including supported formats
- Describe the ANDROID_IMAGE_DECODER result enum, and use proper format
for the individual values so they will be added to the documentation
page.
- for createFromAAsset, specify that the AAsset can be closed *after*
deleting the AImageDecoder, as we do in createFromFd
- reformat some return lines to look more consistent
- Remove reference to animated images
- Move comment describing AImageDecoderHeaderInfo to before the typedef,
so it will be included in the documentation, and expand the comment
- More thorough description for getWidth/getHeight
- Move comment describing limitation on stride to stride (it had been on
the description for size)
- Clarify various comments, fix links, etc.

Change-Id: I26482ea8373081ee8d47455f7028f2bb6ec6a58e
---
 include/android/imagedecoder.h | 196 +++++++++++++++++++++++++++--------------
 1 file changed, 129 insertions(+), 67 deletions(-)

(limited to 'include/android/imagedecoder.h')

diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index 0d943b7800..6e5da52cb5 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -15,12 +15,24 @@
  */
 
 /**
- * @addtogroup ImageDecoder
+ * @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 like PNG, JPEG, GIF, WEBP and HEIF. 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
+ * @file imagedecoder.h
+ * @brief API for decoding images.
  */
 
 #ifndef ANDROID_IMAGE_DECODER_H
@@ -38,32 +50,54 @@ struct AAsset;
 
 #if __ANDROID_API__ >= 30
 
-/** AImageDecoder functions result code. */
+/**
+ *  {@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.
+    /**
+     * Decoding was successful and complete.
+     */
     ANDROID_IMAGE_DECODER_SUCCESS = 0,
-    // The input was incomplete. In decodeImage, this means a partial
-    // image was decoded. Undecoded lines are all zeroes.
-    // In AImageDecoder_create*, no AImageDecoder was created.
+    /**
+     * The input was incomplete.
+     */
     ANDROID_IMAGE_DECODER_INCOMPLETE = -1,
-    // The input contained an error after decoding some lines. Similar to
-    // INCOMPLETE, above.
+    /**
+     * The input contained an error after decoding some lines.
+     */
     ANDROID_IMAGE_DECODER_ERROR = -2,
-    // Could not convert, e.g. attempting to decode an image with
-    // alpha to an opaque format.
+    /**
+     * 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.
+    /**
+     * 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 was bad (e.g. pixels)
+    /**
+     * Some other parameter was bad.
+     */
     ANDROID_IMAGE_DECODER_BAD_PARAMETER = -5,
-    // Input was invalid i.e. broken before decoding any pixels.
+    /**
+     * Input was invalid before decoding any pixels.
+     */
     ANDROID_IMAGE_DECODER_INVALID_INPUT = -6,
-    // A seek was required, and failed.
+    /**
+     * A seek was required and it failed.
+     */
     ANDROID_IMAGE_DECODER_SEEK_ERROR = -7,
-    // Some other error (e.g. OOM)
+    /**
+     * Some other error. For example, an internal allocation failed.
+     */
     ANDROID_IMAGE_DECODER_INTERNAL_ERROR = -8,
-    // We did not recognize the format
+    /**
+     * AImageDecoder did not recognize the format.
+     */
     ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT = -9
 };
 
@@ -76,36 +110,45 @@ struct AImageDecoder;
  * - {@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 AImageDecoder from an AAsset.
+ * Create a new {@link AImageDecoder} from an {@link AAsset}.
  *
  * @param asset {@link AAsset} containing encoded image data. Client is still
- *              responsible for calling {@link AAsset_close} on it.
+ *              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 reason for the failure.
+ *         indicating the reason for the failure.
  */
 int AImageDecoder_createFromAAsset(struct AAsset* asset, AImageDecoder** outDecoder)
         __INTRODUCED_IN(30);
 
 /**
- * Create a new AImageDecoder from a file descriptor.
+ * Create a new {@link AImageDecoder} from a file descriptor.
  *
  * @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 AImageDecoder.
+ *           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 reason for the failure.
+ *         indicating the reason for the failure.
  */
 int AImageDecoder_createFromFd(int fd, AImageDecoder** outDecoder) __INTRODUCED_IN(30);
 
@@ -113,7 +156,7 @@ int AImageDecoder_createFromFd(int fd, AImageDecoder** outDecoder) __INTRODUCED_
  * Create a new AImageDecoder from a buffer.
  *
  * @param buffer Pointer to encoded data. Must be valid for the entire time
- *               the AImageDecoder is used.
+ *               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
@@ -136,7 +179,7 @@ void AImageDecoder_delete(AImageDecoder* decoder) __INTRODUCED_IN(30);
  * @param format {@link AndroidBitmapFormat} to use for the output.
  * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} if the format is compatible
  *         with the image and {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION}
- *         otherwise. In the latter case, the AImageDecoder uses the
+ *         otherwise. In the latter case, the {@link AImageDecoder} uses the
  *         format it was already planning to use (either its default
  *         or a previously successful setting from this function).
  */
@@ -146,23 +189,25 @@ int AImageDecoder_setAndroidBitmapFormat(AImageDecoder*,
 /**
  * Specify whether the output's pixels should be unpremultiplied.
  *
- * By default, the decoder will premultiply the pixels, if they have alpha. Pass
- * false to this method to leave them unpremultiplied. This has no effect on an
+ * 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.
  *
- * @param required Pass true to leave the pixels unpremultiplied.
- * @return - {@link ANDROID_IMAGE_DECODER_SUCCESS} on success
+ * @param unpremultipliedRequired Pass true to leave the pixels unpremultiplied.
+ * @return an enum describing whether the call succeeded.
+ *         - {@link ANDROID_IMAGE_DECODER_SUCCESS} on success
  *         - {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION} if the conversion
  *           is not possible
  *         - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for bad parameters
  */
-int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*, bool required) __INTRODUCED_IN(30);
+int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*,
+                                             bool unpremultipliedRequired) __INTRODUCED_IN(30);
 
 /**
  * Choose the dataspace for the output.
  *
- * Not supported for {@link ANDROID_BITMAP_FORMAT_A_8}, which does not support
- * an ADataSpace.
+ * Ignored by {@link ANDROID_BITMAP_FORMAT_A_8}, which does not support
+ * an {@link ADataSpace}.
  *
  * @param dataspace The {@link ADataSpace} to decode into. An ADataSpace
  *                  specifies how to interpret the colors. By default,
@@ -170,10 +215,10 @@ int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*, bool required) __IN
  *                  {@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
- *         - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for a null
- *           AImageDecoder or an integer that does not correspond to an
- *           ADataSpace value.
+ * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or
+ *         {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for a null
+ *         {@link AImageDecoder} or an integer that does not correspond to an
+ *         {@link ADataSpace} value.
  */
 int AImageDecoder_setDataSpace(AImageDecoder*, int32_t dataspace) __INTRODUCED_IN(30);
 
@@ -191,10 +236,11 @@ int AImageDecoder_setDataSpace(AImageDecoder*, int32_t dataspace) __INTRODUCED_I
  *              {@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
- *         - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if the AImageDecoder
- *           pointer is null, width or height is <= 0, or any existing crop is
- *           not contained by the image dimensions.
+ * @return an enum describing whether the call succeeded.
+ * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or
+ *         {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if the {@link AImageDecoder}
+ *         pointer is null, width or height is <= 0, or any existing crop is
+ *         not contained by the new image dimensions.
  */
 int AImageDecoder_setTargetSize(AImageDecoder*, int32_t width, int32_t height) __INTRODUCED_IN(30);
 
@@ -213,10 +259,11 @@ int AImageDecoder_setTargetSize(AImageDecoder*, int32_t width, int32_t height) _
  *                   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
- *              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
- *               direction that the decoder can do most efficiently.
- * @return ANDROID_IMAGE_DECODER result code.
+ *               in the direction that the decoder can do most efficiently.
+ * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or
+ *         {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for bad input.
  */
 int AImageDecoder_computeSampledSize(const AImageDecoder*, int sampleSize,
                                      int32_t* width, int32_t* height) __INTRODUCED_IN(30);
@@ -234,18 +281,21 @@ int AImageDecoder_computeSampledSize(const AImageDecoder*, int sampleSize,
  *             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.
- * @return - {@link ANDROID_IMAGE_DECODER_SUCCESS} on success
- *         - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if the AImageDecoder
- *           pointer is null or the crop is not contained by the image
- *           dimensions.
+ *             returning {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}.
+ * @return an enum describing whether the call succeeded.
+ * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or
+ *         {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if the {@link AImageDecoder}
+ *         pointer is null or the crop is not contained by the image
+ *         dimensions.
  */
 int AImageDecoder_setCrop(AImageDecoder*, ARect crop) __INTRODUCED_IN(30);
 
+struct AImageDecoderHeaderInfo;
 /**
- * Opaque handle for reading header info.
+ * Opaque handle for representing information about the encoded image. It can
+ * be passed to methods like {@link AImageDecoderHeaderInfo_getWidth} and
+ * {@link AImageDecoderHeaderInfo_getHeight}.
  */
-struct AImageDecoderHeaderInfo;
 typedef struct AImageDecoderHeaderInfo AImageDecoderHeaderInfo;
 
 /**
@@ -258,12 +308,16 @@ const AImageDecoderHeaderInfo* AImageDecoder_getHeaderInfo(
         const AImageDecoder*) __INTRODUCED_IN(30);
 
 /**
- * Report the native width of the encoded image.
+ * 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.
  */
 int32_t AImageDecoderHeaderInfo_getWidth(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
 
 /**
- * Report the native height of the encoded image.
+ * 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.
  */
 int32_t AImageDecoderHeaderInfo_getHeight(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
 
@@ -277,7 +331,7 @@ const char* AImageDecoderHeaderInfo_getMimeType(
 
 /**
  * Report the {@link AndroidBitmapFormat} the AImageDecoder will decode to
- * by default. AImageDecoder will try to choose one that is sensible
+ * 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.
  */
@@ -285,18 +339,17 @@ int32_t AImageDecoderHeaderInfo_getAndroidBitmapFormat(
         const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
 
 /**
- * Report how the AImageDecoder will handle alpha by default. If the image
+ * 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}.
- *
- * For animated images only the opacity of the first frame is reported.
+ * this returns {@link ANDROID_BITMAP_FLAGS_ALPHA_PREMUL}, because
+ * {@link AImageDecoder_decodeImage} will premultiply pixels by default.
  */
 int AImageDecoderHeaderInfo_getAlphaFlags(
         const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
 
 /**
- * Report the dataspace the AImageDecoder will decode to by default.
+ * Report the dataspace the {@link AImageDecoder} will decode to by default.
  * AImageDecoder will try to choose one that is sensible for the
  * image and the system. Note that this may not exactly match the ICC
  * profile (or other color information) stored in the encoded image.
@@ -315,26 +368,35 @@ int32_t AImageDecoderHeaderInfo_getDataSpace(
         const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
 
 /**
- * Return the minimum stride that can be used, taking the specified
- * (or default) (possibly scaled) width, crop rect and
- * {@link AndroidBitmapFormat} into account.
+ * 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.
  */
 size_t AImageDecoder_getMinimumStride(AImageDecoder*) __INTRODUCED_IN(30);
 
 /**
- * Decode the image into pixels, using the settings of the AImageDecoder.
+ * Decode the image into pixels, using the settings of the {@link AImageDecoder}.
  *
  * @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 fit |size| bytes.
+ *               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}.
+ *               {@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}. Must also be a multiple
- *             of the bytes per pixel of the {@link AndroidBitmapFormat}.
+ *             {@link AImageDecoder_getMinimumStride}.
  * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success, or an error code
  *         from the same enum describing the failure.
+ *         {@link ANDROID_IMAGE_DECODER_INCOMPLETE} or
+ *         {@link ANDROID_IMAGE_DECODER_ERROR} means that a partial image was
+ *         decoded, and undecoded lines have been initialized to all zeroes.
  */
 int AImageDecoder_decodeImage(AImageDecoder* decoder,
                               void* pixels, size_t stride,
-- 
cgit v1.2.3-59-g8ed1b


From 8cee65ec1d67ee8ea0a40099a26e1f94c7b06feb Mon Sep 17 00:00:00 2001
From: Leon Scroggins III <scroggo@google.com>
Date: Thu, 30 Jan 2020 14:20:42 -0500
Subject: AImageDecoder: update comments around dataspaces

Bug: 135133301
Test: I5e8bdcdae6837db23c0f4ef08f931f3bebe0ce0d

A companion change (I489f31fef79dec11e97c8e8fb9207adb77a3d0c7) makes
AImageDecoder default to doing no color conversion. Update comments to
reflect that.

Change-Id: Icc3b0f101598ce98c458ff43597ee05b3662664c
---
 include/android/imagedecoder.h | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

(limited to 'include/android/imagedecoder.h')

diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index 6e5da52cb5..7437ab1093 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -349,20 +349,20 @@ int AImageDecoderHeaderInfo_getAlphaFlags(
         const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
 
 /**
- * Report the dataspace the {@link AImageDecoder} will decode to by default.
- * AImageDecoder will try to choose one that is sensible for the
- * image and the system. Note that this may not exactly match the ICC
- * profile (or other color information) stored in the encoded image.
+ * Report the dataspace the AImageDecoder will decode to by default.
  *
- * @return The {@link ADataSpace} most closely representing the way the colors
- *         are encoded (or {@link ADATASPACE_UNKNOWN} if there is not an
- *         approximate ADataSpace). This specifies how to interpret the colors
+ * By default, {@link AImageDecoder_decodeImage} will not do any color
+ * conversion.
+ *
+ * @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
- *         ADATASPACE_UNKNOWN, even for Named ColorSpaces, if they have no
- *         corresponding ADataSpace.
+ *         {@link ADATASPACE_UNKNOWN}, even for Named ColorSpaces, if they have
+ *         no corresponding {@link ADataSpace}.
  */
 int32_t AImageDecoderHeaderInfo_getDataSpace(
         const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30);
-- 
cgit v1.2.3-59-g8ed1b


From bb5ffd2074fe150725eee7eb1f97d5814a2df249 Mon Sep 17 00:00:00 2001
From: Leon Scroggins III <scroggo@google.com>
Date: Thu, 6 Feb 2020 11:45:16 -0500
Subject: AImageDecoder: respond to API review

Bug: 148954890
Test: Generate docs

List the formats supported.

List the possible error codes that can be returned from each method and
what it means.

Change-Id: I192888c1d438db0308cc715ab7f4997543509e73
---
 include/android/imagedecoder.h | 169 +++++++++++++++++++++++++++++++----------
 1 file changed, 128 insertions(+), 41 deletions(-)

(limited to 'include/android/imagedecoder.h')

diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index 7437ab1093..3a87da0fee 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -20,9 +20,18 @@
  * Functions for converting encoded images into RGBA pixels.
  *
  * 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
- * for scaling, cropping, and choosing the output format. Unlike the Java API,
- * which can create an android.graphics.Bitmap or
+ * 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>
@@ -62,7 +71,7 @@ enum {
      */
     ANDROID_IMAGE_DECODER_SUCCESS = 0,
     /**
-     * The input was incomplete.
+     * The input is incomplete.
      */
     ANDROID_IMAGE_DECODER_INCOMPLETE = -1,
     /**
@@ -80,7 +89,7 @@ enum {
      */
     ANDROID_IMAGE_DECODER_INVALID_SCALE = -4,
     /**
-     * Some other parameter was bad.
+     * Some other parameter is invalid.
      */
     ANDROID_IMAGE_DECODER_BAD_PARAMETER = -5,
     /**
@@ -133,6 +142,19 @@ typedef struct AImageDecoder AImageDecoder;
  *                   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);
@@ -149,6 +171,19 @@ int AImageDecoder_createFromAAsset(struct AAsset* asset, AImageDecoder** outDeco
  *                   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);
 
@@ -163,7 +198,19 @@ int AImageDecoder_createFromFd(int fd, AImageDecoder** outDecoder) __INTRODUCED_
  *                   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 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,
                                    AImageDecoder** outDecoder) __INTRODUCED_IN(30);
@@ -177,11 +224,18 @@ void AImageDecoder_delete(AImageDecoder* decoder) __INTRODUCED_IN(30);
  * Choose the desired output format.
  *
  * @param format {@link AndroidBitmapFormat} to use for the output.
- * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} if the format is compatible
- *         with the image and {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION}
- *         otherwise. In the latter case, the {@link AImageDecoder} uses the
- *         format it was already planning to use (either its default
- *         or a previously successful setting from this function).
+ * @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);
@@ -194,11 +248,15 @@ int AImageDecoder_setAndroidBitmapFormat(AImageDecoder*,
  * opaque image.
  *
  * @param unpremultipliedRequired Pass true to leave the pixels unpremultiplied.
- * @return an enum describing whether the call succeeded.
- *         - {@link ANDROID_IMAGE_DECODER_SUCCESS} on success
- *         - {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION} if the conversion
- *           is not possible
- *         - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for bad parameters
+ * @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);
@@ -215,10 +273,13 @@ int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*,
  *                  {@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
- *         {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for a null
- *         {@link AImageDecoder} or an integer that does not correspond to an
- *         {@link ADataSpace} value.
+ * @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);
 
@@ -236,11 +297,16 @@ int AImageDecoder_setDataSpace(AImageDecoder*, int32_t dataspace) __INTRODUCED_I
  *              {@link AImageDecoder_getMinimumStride}, which will now return
  *              a value based on this width.
  * @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
- *         {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if the {@link AImageDecoder}
- *         pointer is null, width or height is <= 0, or any existing crop is
- *         not contained by the new image dimensions.
+ * @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);
 
@@ -262,8 +328,12 @@ int AImageDecoder_setTargetSize(AImageDecoder*, int32_t width, int32_t height) _
  *              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
- *         {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} for bad input.
+ * @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);
@@ -282,18 +352,21 @@ int AImageDecoder_computeSampledSize(const AImageDecoder*, int sampleSize,
  *             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 an enum describing whether the call succeeded.
- * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or
- *         {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if the {@link AImageDecoder}
- *         pointer is null or the crop is not contained by the image
- *         dimensions.
+ * @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. It can
- * be passed to methods like {@link AImageDecoderHeaderInfo_getWidth} and
+ * 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;
@@ -310,14 +383,16 @@ const AImageDecoderHeaderInfo* AImageDecoder_getHeaderInfo(
 /**
  * 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.
+ * 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);
 
 /**
  * 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.
+ * 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);
 
@@ -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
  *             stride * (height - 1) +
  *             {@link AImageDecoder_getMinimumStride}.
- * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success, or an error code
- *         from the same enum describing the failure.
- *         {@link ANDROID_IMAGE_DECODER_INCOMPLETE} or
- *         {@link ANDROID_IMAGE_DECODER_ERROR} means that a partial image was
- *         decoded, and undecoded lines have been initialized to all zeroes.
+ * @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,
-- 
cgit v1.2.3-59-g8ed1b


From 7be0e2def2d9cff2436511696838fcf0734b4da1 Mon Sep 17 00:00:00 2001
From: Elliott Hughes <enh@google.com>
Date: Tue, 2 Jun 2020 13:05:04 -0700
Subject: API level 30 cleanup.

Make sure that we have the __INTRODUCED_IN()s and -- more importantly --
the API levels recorded in the documentation.

Bug: https://github.com/android/ndk/issues/1271
Test: treehugger
Change-Id: I74752f19f165fd5c56b2dfd783298c2da1a926d6
---
 include/android/bitmap.h        |  8 ++++++++
 include/android/choreographer.h | 10 ++++++++--
 include/android/imagedecoder.h  | 38 ++++++++++++++++++++++++++++++++++++++
 include/android/thermal.h       | 30 +++++++++++++++++++-----------
 4 files changed, 73 insertions(+), 13 deletions(-)

(limited to 'include/android/imagedecoder.h')

diff --git a/include/android/bitmap.h b/include/android/bitmap.h
index 2631b144af..f19539913e 100644
--- a/include/android/bitmap.h
+++ b/include/android/bitmap.h
@@ -125,6 +125,8 @@ int AndroidBitmap_getInfo(JNIEnv* env, jobject jbitmap,
  * Note that {@link ADataSpace} only exposes a few values. This may return
  * {@link ADATASPACE_UNKNOWN}, even for Named ColorSpaces, if they have no
  * corresponding ADataSpace.
+ *
+ * Available since API level 30.
  */
 int32_t AndroidBitmap_getDataSpace(JNIEnv* env, jobject jbitmap)  __INTRODUCED_IN(30);
 
@@ -189,6 +191,8 @@ enum AndroidBitmapCompressFormat {
 /**
  *  User-defined function for writing the output of compression.
  *
+ *  Available since API level 30.
+ *
  *  @param userContext Pointer to user-defined data passed to
  *         {@link AndroidBitmap_compress}.
  *  @param data Compressed data of |size| bytes to write.
@@ -202,6 +206,8 @@ typedef bool (*AndroidBitmap_CompressWriteFunc)(void* userContext,
 /**
  *  Compress |pixels| as described by |info|.
  *
+ *  Available since API level 30.
+ *
  *  @param info Description of the pixels to compress.
  *  @param dataspace {@link ADataSpace} describing the color space of the
  *                   pixels.
@@ -234,6 +240,8 @@ typedef struct AHardwareBuffer AHardwareBuffer;
  *
  *  Client must not modify it while a Bitmap is wrapping it.
  *
+ *  Available since API level 30.
+ *
  *  @param bitmap Handle to an android.graphics.Bitmap.
  *  @param outBuffer On success, is set to a pointer to the
  *         {@link AHardwareBuffer} associated with bitmap. This acquires
diff --git a/include/android/choreographer.h b/include/android/choreographer.h
index c1c4a72cd3..bdf11e42ca 100644
--- a/include/android/choreographer.h
+++ b/include/android/choreographer.h
@@ -129,9 +129,12 @@ void AChoreographer_postFrameCallbackDelayed64(AChoreographer* choreographer,
  *
  * This api is thread-safe. Any thread is allowed to register a new refresh
  * rate callback for the choreographer instance.
+ *
+ * Available since API level 30.
  */
 void AChoreographer_registerRefreshRateCallback(AChoreographer* choreographer,
-                                                AChoreographer_refreshRateCallback, void* data);
+                                                AChoreographer_refreshRateCallback, void* data)
+        __INTRODUCED_IN(30);
 
 /**
  * Unregisters a callback to be run when the display refresh rate changes, along
@@ -144,9 +147,12 @@ void AChoreographer_registerRefreshRateCallback(AChoreographer* choreographer,
  * callback and associated data pointer are unregistered, then there is a
  * guarantee that when the unregistration completes that that callback will not
  * be run with the data pointer passed.
+ *
+ * Available since API level 30.
  */
 void AChoreographer_unregisterRefreshRateCallback(AChoreographer* choreographer,
-                                                  AChoreographer_refreshRateCallback, void* data);
+                                                  AChoreographer_refreshRateCallback, void* data)
+        __INTRODUCED_IN(30);
 #endif /* __ANDROID_API__ >= 30 */
 
 __END_DECLS
diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index 3a87da0fee..d7e6e4118f 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -133,6 +133,8 @@ 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}.
@@ -162,6 +164,8 @@ int AImageDecoder_createFromAAsset(struct AAsset* asset, AImageDecoder** outDeco
 /**
  * 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}.
@@ -190,6 +194,8 @@ int AImageDecoder_createFromFd(int fd, AImageDecoder** outDecoder) __INTRODUCED_
 /**
  * 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.
@@ -217,12 +223,16 @@ int AImageDecoder_createFromBuffer(const void* buffer, size_t length,
 
 /**
  * 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
@@ -247,6 +257,8 @@ int AImageDecoder_setAndroidBitmapFormat(AImageDecoder*,
  * 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.
@@ -267,6 +279,8 @@ int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*,
  * 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
@@ -292,6 +306,8 @@ int AImageDecoder_setDataSpace(AImageDecoder*, int32_t dataspace) __INTRODUCED_I
  * 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
@@ -319,6 +335,8 @@ int AImageDecoder_setTargetSize(AImageDecoder*, int32_t width, int32_t height) _
  * 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
@@ -344,6 +362,8 @@ int AImageDecoder_computeSampledSize(const AImageDecoder*, int sampleSize,
  * 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
@@ -376,6 +396,8 @@ typedef struct AImageDecoderHeaderInfo AImageDecoderHeaderInfo;
  *
  * 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);
@@ -385,6 +407,8 @@ const AImageDecoderHeaderInfo* AImageDecoder_getHeaderInfo(
  * 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);
 
@@ -393,12 +417,16 @@ int32_t AImageDecoderHeaderInfo_getWidth(const AImageDecoderHeaderInfo*) __INTRO
  * 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(
@@ -409,6 +437,8 @@ const char* AImageDecoderHeaderInfo_getMimeType(
  * 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);
@@ -419,6 +449,8 @@ int32_t AImageDecoderHeaderInfo_getAndroidBitmapFormat(
  * {@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);
@@ -429,6 +461,8 @@ int AImageDecoderHeaderInfo_getAlphaFlags(
  * 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
@@ -452,12 +486,16 @@ int32_t AImageDecoderHeaderInfo_getDataSpace(
  *
  * 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.
diff --git a/include/android/thermal.h b/include/android/thermal.h
index 3247fa167b..83582d6791 100644
--- a/include/android/thermal.h
+++ b/include/android/thermal.h
@@ -60,8 +60,6 @@
 extern "C" {
 #endif
 
-#if __ANDROID_API__ >= 30
-
 enum AThermalStatus {
     /** Error in thermal status. */
     ATHERMAL_STATUS_ERROR = -1,
@@ -111,36 +109,45 @@ typedef struct AThermalManager AThermalManager;
  */
 typedef void (*AThermal_StatusCallback)(void *data, AThermalStatus status);
 
+#if __ANDROID_API__ >= 30
+
 /**
   * Acquire an instance of the thermal manager. This must be freed using
   * {@link AThermal_releaseManager}.
   *
+  * Available since API level 30.
+  *
   * @return manager instance on success, nullptr on failure.
- */
-AThermalManager* AThermal_acquireManager();
+  */
+AThermalManager* AThermal_acquireManager() __INTRODUCED_IN(30);
 
 /**
  * Release the thermal manager pointer acquired via
  * {@link AThermal_acquireManager}.
  *
- * @param manager The manager to be released.
+ * Available since API level 30.
  *
+ * @param manager The manager to be released.
  */
-void AThermal_releaseManager(AThermalManager *manager);
+void AThermal_releaseManager(AThermalManager *manager) __INTRODUCED_IN(30);
 
 /**
   * Gets the current thermal status.
   *
+  * Available since API level 30.
+  *
   * @param manager The manager instance to use to query the thermal status.
   * Acquired via {@link AThermal_acquireManager}.
   *
   * @return current thermal status, ATHERMAL_STATUS_ERROR on failure.
-*/
-AThermalStatus AThermal_getCurrentThermalStatus(AThermalManager *manager);
+  */
+AThermalStatus AThermal_getCurrentThermalStatus(AThermalManager *manager) __INTRODUCED_IN(30);
 
 /**
  * Register the thermal status listener for thermal status change.
  *
+ * Available since API level 30.
+ *
  * @param manager The manager instance to use to register.
  * Acquired via {@link AThermal_acquireManager}.
  * @param callback The callback function to be called when thermal status updated.
@@ -152,11 +159,13 @@ AThermalStatus AThermal_getCurrentThermalStatus(AThermalManager *manager);
  *         EPIPE if communication with the system service has failed.
  */
 int AThermal_registerThermalStatusListener(AThermalManager *manager,
-        AThermal_StatusCallback callback, void *data);
+        AThermal_StatusCallback callback, void *data) __INTRODUCED_IN(30);
 
 /**
  * Unregister the thermal status listener previously resgistered.
  *
+ * Available since API level 30.
+ *
  * @param manager The manager instance to use to unregister.
  * Acquired via {@link AThermal_acquireManager}.
  * @param callback The callback function to be called when thermal status updated.
@@ -168,8 +177,7 @@ int AThermal_registerThermalStatusListener(AThermalManager *manager,
  *         EPIPE if communication with the system service has failed.
  */
 int AThermal_unregisterThermalStatusListener(AThermalManager *manager,
-        AThermal_StatusCallback callback, void *data);
-
+        AThermal_StatusCallback callback, void *data) __INTRODUCED_IN(30);
 
 #endif  //  __ANDROID_API__ >= 30
 
-- 
cgit v1.2.3-59-g8ed1b