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
diff --git a/include/android/imagedecoder.h b/include/android/imagedecoder.h
index c3d3a4b..fb7d09c 100644
--- a/include/android/imagedecoder.h
+++ b/include/android/imagedecoder.h
@@ -837,9 +837,11 @@
* 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 @@
* 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 @@
*
* 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.
*/