AImageDecoder: respond to API feedback

Bug: 186656488
Test: I4dc406e85709dda14af8b414e2da3d39bb07643b

AImageDecoderFrameInfo_getDuration returns
ANDROID_IMAGE_DECODER_BAD_PARAMETER on null info.

Clarify that AImageDecoder_getFrameInfo will succeed if
AImageDecoder_advanceFrame does, explaining why there are not more error
possibilities.

Explain more clearly what AImageDecoderFrameInfo_hasAlphaWithinBounds
means.

Change-Id: Ic02f1798904ad5ccc446fb4cd76cbff451a4e450

1 files changed, 17 insertions, 9 deletions

diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index c3d3a4b35a..fb7d09c04d 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -837,9 +837,11 @@ void AImageDecoderFrameInfo_delete(
  * is the current frame.
  *
  * If the image only has one frame, this will fill the {@link
- * AImageDecoderFrameInfo} with the encoded info, if any, or reasonable
+ * AImageDecoderFrameInfo} with the encoded info and reasonable
  * defaults.
  *
+ * If {@link AImageDecoder_advanceFrame} succeeded, this will succeed as well.
+ *
  * @param decoder Opaque object representing the decoder.
  * @param info Opaque object to hold frame information. On success, will be
  *             filled with information regarding the current frame.
@@ -861,7 +863,7 @@ int AImageDecoder_getFrameInfo(AImageDecoder* _Nonnull decoder,
  * Introduced in API 31.
  *
  * Errors:
- * - returns 0 if |info| is null.
+ * - returns {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if |info| is null.
  */
 int64_t AImageDecoderFrameInfo_getDuration(
         const AImageDecoderFrameInfo* _Nonnull info) __INTRODUCED_IN(31);
@@ -896,19 +898,25 @@ ARect AImageDecoderFrameInfo_getFrameRect(
  *
  * Introduced in API 31.
  *
- * Note that this may differ from whether the composed frame has
- * alpha. If this frame does not fill the entire image dimensions
- * (see {@link AImageDecoderFrameInfo_getFrameRect}) or it blends
- * with an opaque frame, for example, the composed frame’s alpha
- * may not match. It is also conservative; for example, if a color
- * index-based frame has a color with alpha but does not use it,
- * this will still return true.
+ * Unless this frame is independent (see {@link AImageDecoder_decodeImage}),
+ * a single call to {@link AImageDecoder_decodeImage} will decode an updated
+ * rectangle of pixels and then blend it with the existing pixels in the
+ * |pixels| buffer according to {@link AImageDecoderFrameInfo_getBlendOp}. This
+ * method returns whether the updated rectangle has alpha, prior to blending.
+ * The return value is conservative; for example, if a color-index-based frame
+ * has a color with alpha but does not use it, this will still return true.
  *
  * This, along with other information in AImageDecoderFrameInfo,
  * can be useful for determining whether a frame is independent, but
  * the decoder handles blending frames, so a simple
  * sequential client does not need this.
  *
+ * Note that this may differ from whether the composed frame (that is, the
+ * resulting image after blending) has alpha. If this frame does not fill the
+ * entire image dimensions (see {@link AImageDecoderFrameInfo_getFrameRect})
+ * or it blends with an opaque frame, for example, the composed frame’s alpha
+ * may not match.
+ *
  * Errors:
  * - returns false if |info| is null.
  */