1 /* 2 * Copyright (C) 2019 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * @defgroup ImageDecoder Android Image Decoder 19 * 20 * Functions for converting encoded images into RGBA pixels. 21 * 22 * Similar to the Java counterpart android.graphics.ImageDecoder, it can be used 23 * to decode images in the following formats: 24 * - JPEG 25 * - PNG 26 * - GIF 27 * - WebP 28 * - BMP 29 * - ICO 30 * - WBMP 31 * - HEIF 32 * - Digital negatives (via the DNG SDK) 33 * <p>It has similar options for scaling, cropping, and choosing the output format. 34 * Unlike the Java API, which can create an android.graphics.Bitmap or 35 * android.graphics.drawable.Drawable object, AImageDecoder decodes directly 36 * into memory provided by the client. For more information, see the 37 * <a href="https://developer.android.com/ndk/guides/image-decoder">Image decoder</a> 38 * developer guide. 39 * @{ 40 */ 41 42 /** 43 * @file imagedecoder.h 44 * @brief API for decoding images. 45 */ 46 47 #ifndef ANDROID_IMAGE_DECODER_H 48 #define ANDROID_IMAGE_DECODER_H 49 50 #include "bitmap.h" 51 #include <android/rect.h> 52 #include <stdint.h> 53 54 #if !defined(__INTRODUCED_IN) 55 #define __INTRODUCED_IN(__api_level) /* nothing */ 56 #endif 57 58 #ifdef __cplusplus 59 extern "C" { 60 #endif 61 62 struct AAsset; 63 64 /** 65 * {@link AImageDecoder} functions result code. 66 * 67 * Introduced in API 30. 68 * 69 * Many functions will return this to indicate success 70 * ({@link ANDROID_IMAGE_DECODER_SUCCESS}) or the reason for the failure. On 71 * failure, any out-parameters should be considered uninitialized, except where 72 * specified. Use {@link AImageDecoder_resultToString} for a readable 73 * version of the result code. 74 */ 75 enum { 76 /** 77 * Decoding was successful and complete. 78 */ 79 ANDROID_IMAGE_DECODER_SUCCESS = 0, 80 /** 81 * The input is incomplete. 82 */ 83 ANDROID_IMAGE_DECODER_INCOMPLETE = -1, 84 /** 85 * The input contained an error after decoding some lines. 86 */ 87 ANDROID_IMAGE_DECODER_ERROR = -2, 88 /** 89 * Could not convert. For example, attempting to decode an image with 90 * alpha to an opaque format. 91 */ 92 ANDROID_IMAGE_DECODER_INVALID_CONVERSION = -3, 93 /** 94 * The scale is invalid. It may have overflowed, or it may be incompatible 95 * with the current alpha setting. 96 */ 97 ANDROID_IMAGE_DECODER_INVALID_SCALE = -4, 98 /** 99 * Some other parameter is invalid. 100 */ 101 ANDROID_IMAGE_DECODER_BAD_PARAMETER = -5, 102 /** 103 * Input was invalid before decoding any pixels. 104 */ 105 ANDROID_IMAGE_DECODER_INVALID_INPUT = -6, 106 /** 107 * A seek was required and it failed. 108 */ 109 ANDROID_IMAGE_DECODER_SEEK_ERROR = -7, 110 /** 111 * Some other error. For example, an internal allocation failed. 112 */ 113 ANDROID_IMAGE_DECODER_INTERNAL_ERROR = -8, 114 /** 115 * AImageDecoder did not recognize the format. 116 */ 117 ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT = -9, 118 /** 119 * The animation has reached the end. 120 */ 121 ANDROID_IMAGE_DECODER_FINISHED = -10, 122 /** 123 * This method cannot be called while the AImageDecoder is in its current 124 * state. For example, various setters (like {@link AImageDecoder_setTargetSize}) 125 * can only be called while the AImageDecoder is set to decode the first 126 * frame of an animation. This ensures that any blending and/or restoring 127 * prior frames works correctly. 128 */ 129 ANDROID_IMAGE_DECODER_INVALID_STATE = -11, 130 }; 131 132 /** 133 * Return a constant string value representing the error code. 134 * 135 * Introduced in API 31. 136 * 137 * Pass the return value from an {@link AImageDecoder} method (e.g. 138 * {@link AImageDecoder_decodeImage}) for a text string representing the error 139 * code. 140 * 141 * Errors: 142 * - Returns null for a value out of range. 143 */ 144 const char* _Nullable AImageDecoder_resultToString(int)__INTRODUCED_IN(31); 145 146 struct AImageDecoder; 147 148 /** 149 * Opaque handle for decoding images. 150 * 151 * Introduced in API 30 152 * 153 * Create using one of the following: 154 * - {@link AImageDecoder_createFromAAsset} 155 * - {@link AImageDecoder_createFromFd} 156 * - {@link AImageDecoder_createFromBuffer} 157 * 158 * After creation, {@link AImageDecoder_getHeaderInfo} can be used to retrieve 159 * information about the encoded image. Other functions, like 160 * {@link AImageDecoder_setTargetSize}, can be used to specify how to decode, and 161 * {@link AImageDecoder_decodeImage} will decode into client provided memory. 162 * 163 * {@link AImageDecoder} objects are NOT thread-safe, and should not be shared across 164 * threads. 165 */ 166 typedef struct AImageDecoder AImageDecoder; 167 168 /** 169 * Create a new {@link AImageDecoder} from an {@link AAsset}. 170 * 171 * Available since API level 30. 172 * 173 * @param asset {@link AAsset} containing encoded image data. Client is still 174 * responsible for calling {@link AAsset_close} on it, which may be 175 * done after deleting the returned {@link AImageDecoder}. 176 * @param outDecoder On success (i.e. return value is 177 * {@link ANDROID_IMAGE_DECODER_SUCCESS}), this will be set to 178 * a newly created {@link AImageDecoder}. Caller is 179 * responsible for calling {@link AImageDecoder_delete} on it. 180 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 181 * indicating the reason for the failure. 182 * 183 * Errors: 184 * - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The asset was truncated before 185 * reading the image header. 186 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: One of the parameters is 187 * null. 188 * - {@link ANDROID_IMAGE_DECODER_INVALID_INPUT}: There is an error in the 189 * header. 190 * - {@link ANDROID_IMAGE_DECODER_SEEK_ERROR}: The asset failed to seek. 191 * - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a 192 * failure to allocate memory. 193 * - {@link ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT}: The format is not 194 * supported. 195 */ 196 int AImageDecoder_createFromAAsset(struct AAsset* _Nonnull asset, 197 AImageDecoder* _Nullable * _Nonnull outDecoder) 198 __INTRODUCED_IN(30); 199 200 /** 201 * Create a new {@link AImageDecoder} from a file descriptor. 202 * 203 * Available since API level 30. 204 * 205 * @param fd Seekable, readable, open file descriptor for encoded data. 206 * Client is still responsible for closing it, which may be done 207 * after deleting the returned {@link AImageDecoder}. 208 * @param outDecoder On success (i.e. return value is 209 * {@link ANDROID_IMAGE_DECODER_SUCCESS}), this will be set to 210 * a newly created {@link AImageDecoder}. Caller is 211 * responsible for calling {@link AImageDecoder_delete} on it. 212 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 213 * indicating the reason for the failure. 214 * 215 * Errors: 216 * - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The file was truncated before 217 * reading the image header. 218 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The {@link AImageDecoder} is 219 * null, or |fd| does not represent a valid, seekable file descriptor. 220 * - {@link ANDROID_IMAGE_DECODER_INVALID_INPUT}: There is an error in the 221 * header. 222 * - {@link ANDROID_IMAGE_DECODER_SEEK_ERROR}: The descriptor failed to seek. 223 * - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a 224 * failure to allocate memory. 225 * - {@link ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT}: The format is not 226 * supported. 227 */ 228 int AImageDecoder_createFromFd(int fd, AImageDecoder* _Nullable * _Nonnull outDecoder) 229 __INTRODUCED_IN(30); 230 231 /** 232 * Create a new AImageDecoder from a buffer. 233 * 234 * Available since API level 30. 235 * 236 * @param buffer Pointer to encoded data. Must be valid for the entire time 237 * the {@link AImageDecoder} is used. 238 * @param length Byte length of buffer. 239 * @param outDecoder On success (i.e. return value is 240 * {@link ANDROID_IMAGE_DECODER_SUCCESS}), this will be set to 241 * a newly created {@link AImageDecoder}. Caller is 242 * responsible for calling {@link AImageDecoder_delete} on it. 243 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 244 * indicating the reason for the failure. 245 * 246 * Errors: 247 * - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The encoded image was truncated before 248 * reading the image header. 249 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: One of the parameters is 250 * invalid. 251 * - {@link ANDROID_IMAGE_DECODER_INVALID_INPUT}: There is an error in the 252 * header. 253 * - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a 254 * failure to allocate memory. 255 * - {@link ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT}: The format is not 256 * supported. 257 */ 258 int AImageDecoder_createFromBuffer(const void* _Nonnull buffer, size_t length, 259 AImageDecoder* _Nullable * _Nonnull outDecoder) 260 __INTRODUCED_IN(30); 261 262 /** 263 * Delete the AImageDecoder. 264 * @param decoder {@link AImageDecoder} object created with one of AImageDecoder_createFrom... 265 * functions. 266 * Available since API level 30. 267 */ 268 void AImageDecoder_delete(AImageDecoder* _Nullable decoder) __INTRODUCED_IN(30); 269 270 /** 271 * Choose the desired output format. 272 * 273 * If the encoded image represents an animation, this must be called while on 274 * the first frame (e.g. before calling {@link AImageDecoder_advanceFrame} or 275 * after calling {@link AImageDecoder_rewind}). 276 * 277 * Available since API level 30. 278 * 279 * @param format {@link AndroidBitmapFormat} to use for the output. 280 * @param decoder an {@link AImageDecoder} object. 281 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 282 * indicating the reason for the failure. On failure, the 283 * {@link AImageDecoder} uses the format it was already planning 284 * to use (either its default or a previously successful setting 285 * from this function). 286 * 287 * Errors: 288 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 289 * {@link AImageDecoder} is null or |format| does not correspond to an 290 * {@link AndroidBitmapFormat}. 291 * - {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION}: The 292 * {@link AndroidBitmapFormat} is incompatible with the image. 293 * - {@link ANDROID_IMAGE_DECODER_INVALID_STATE}: The animation is not on 294 * the first frame. 295 */ 296 int AImageDecoder_setAndroidBitmapFormat(AImageDecoder* _Nonnull decoder, 297 int32_t format) __INTRODUCED_IN(30); 298 299 /** 300 * Specify whether the output's pixels should be unpremultiplied. 301 * 302 * By default, {@link AImageDecoder_decodeImage} will premultiply the pixels, if they have alpha. 303 * Pass true to this method to leave them unpremultiplied. This has no effect on an 304 * opaque image. 305 * 306 * If the encoded image represents an animation, this must be called while on 307 * the first frame (e.g. before calling {@link AImageDecoder_advanceFrame} or 308 * after calling {@link AImageDecoder_rewind}). 309 * 310 * Available since API level 30. 311 * 312 * @param decoder an {@link AImageDecoder} object. 313 * @param unpremultipliedRequired Pass true to leave the pixels unpremultiplied. 314 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 315 * indicating the reason for the failure. 316 * 317 * Errors: 318 * - {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION}: Unpremultiplied is not 319 * possible due to an existing scale set by 320 * {@link AImageDecoder_setTargetSize}. 321 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 322 * {@link AImageDecoder} is null. 323 * - {@link ANDROID_IMAGE_DECODER_INVALID_STATE}: The animation is not on 324 * the first frame. 325 */ 326 int AImageDecoder_setUnpremultipliedRequired(AImageDecoder* _Nonnull decoder, 327 bool unpremultipliedRequired) __INTRODUCED_IN(30); 328 329 /** 330 * Choose the dataspace for the output. 331 * 332 * Ignored by {@link ANDROID_BITMAP_FORMAT_A_8}, which does not support 333 * an {@link ADataSpace}. 334 * 335 * If the encoded image represents an animation, this must be called while on 336 * the first frame (e.g. before calling {@link AImageDecoder_advanceFrame} or 337 * after calling {@link AImageDecoder_rewind}). 338 * 339 * Available since API level 30. 340 * 341 * @param decoder an {@link AImageDecoder} object. 342 * @param dataspace The {@link ADataSpace} to decode into. An ADataSpace 343 * specifies how to interpret the colors. By default, 344 * AImageDecoder will decode into the ADataSpace specified by 345 * {@link AImageDecoderHeaderInfo_getDataSpace}. If this 346 * parameter is set to a different ADataSpace, AImageDecoder 347 * will transform the output into the specified ADataSpace. 348 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 349 * indicating the reason for the failure. 350 * 351 * Errors: 352 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 353 * {@link AImageDecoder} is null or |dataspace| does not correspond to an 354 * {@link ADataSpace} value. 355 * - {@link ANDROID_IMAGE_DECODER_INVALID_STATE}: The animation is not on 356 * the first frame. 357 */ 358 int AImageDecoder_setDataSpace(AImageDecoder* _Nonnull decoder, int32_t dataspace) 359 __INTRODUCED_IN(30); 360 361 /** 362 * Specify the output size for a decoded image. 363 * 364 * Future calls to {@link AImageDecoder_decodeImage} will sample or scale the 365 * encoded image to reach the desired size. If a crop rect is set (via 366 * {@link AImageDecoder_setCrop}), it must be contained within the dimensions 367 * specified by width and height, and the output image will be the size of the 368 * crop rect. 369 * 370 * If the encoded image represents an animation, this must be called while on 371 * the first frame (e.g. before calling {@link AImageDecoder_advanceFrame} or 372 * after calling {@link AImageDecoder_rewind}). 373 * 374 * It is strongly recommended to use setTargetSize only for downscaling, as it 375 * is often more efficient to scale-up when rendering than up-front due to 376 * reduced overall memory. 377 * 378 * Available since API level 30. 379 * 380 * @param decoder an {@link AImageDecoder} object. 381 * @param width Width of the output (prior to cropping). 382 * This will affect future calls to 383 * {@link AImageDecoder_getMinimumStride}, which will now return 384 * a value based on this width. 385 * @param height Height of the output (prior to cropping). 386 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 387 * indicating the reason for the failure. 388 * 389 * Errors: 390 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 391 * {@link AImageDecoder} is null. 392 * - {@link ANDROID_IMAGE_DECODER_INVALID_SCALE}: |width| or |height| is <= 0, 393 * the size is too big, any existing crop is not contained by the new image 394 * dimensions, or the scale is incompatible with a previous call to 395 * {@link AImageDecoder_setUnpremultipliedRequired}(true). 396 * - {@link ANDROID_IMAGE_DECODER_INVALID_STATE}: The animation is not on 397 * the first frame. 398 */ 399 int AImageDecoder_setTargetSize(AImageDecoder* _Nonnull decoder, int32_t width, 400 int32_t height) __INTRODUCED_IN(30); 401 402 /** 403 * Compute the dimensions to use for a given sampleSize. 404 * 405 * Although AImageDecoder can scale to an arbitrary target size (see 406 * {@link AImageDecoder_setTargetSize}), some sizes may be more efficient than 407 * others. This computes the most efficient target size to use to reach a 408 * particular sampleSize. 409 * 410 * Available since API level 30. 411 * 412 * @param decoder an {@link AImageDecoder} object. 413 * @param sampleSize A subsampling rate of the original image. Must be greater 414 * than or equal to 1. A sampleSize of 2 means to skip every 415 * other pixel/line, resulting in a width and height that are 416 * 1/2 of the original dimensions, with 1/4 the number of 417 * pixels. 418 * @param width Out parameter for the width sampled by sampleSize, and rounded 419 * in the direction that the decoder can do most efficiently. 420 * @param height Out parameter for the height sampled by sampleSize, and rounded 421 * in the direction that the decoder can do most efficiently. 422 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 423 * indicating the reason for the failure. 424 * 425 * Errors: 426 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 427 * {@link AImageDecoder}, |width| or |height| is null or |sampleSize| is < 1. 428 */ 429 int AImageDecoder_computeSampledSize(const AImageDecoder* _Nonnull decoder, int sampleSize, 430 int32_t* _Nonnull width, int32_t* _Nonnull height) 431 __INTRODUCED_IN(30); 432 433 /** 434 * Specify how to crop the output after scaling (if any). 435 * 436 * Future calls to {@link AImageDecoder_decodeImage} will crop their output to 437 * the specified {@link ARect}. Clients will only need to allocate enough memory 438 * for the cropped ARect. 439 * 440 * If the encoded image represents an animation, this must be called while on 441 * the first frame (e.g. before calling {@link AImageDecoder_advanceFrame} or 442 * after calling {@link AImageDecoder_rewind}). 443 * 444 * Available since API level 30. 445 * 446 * @param decoder an {@link AImageDecoder} object. 447 * @param crop Rectangle describing a crop of the decode. It must be contained inside of 448 * the (possibly scaled, by {@link AImageDecoder_setTargetSize}) 449 * image dimensions. This will affect future calls to 450 * {@link AImageDecoder_getMinimumStride}, which will now return a 451 * value based on the width of the crop. An empty ARect - 452 * specifically { 0, 0, 0, 0 } - may be used to remove the cropping 453 * behavior. Any other empty or unsorted ARects will result in 454 * returning {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}. 455 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 456 * indicating the reason for the failure. 457 * 458 * Errors: 459 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 460 * {@link AImageDecoder} is null, or the crop is not contained by the 461 * (possibly scaled) image dimensions. 462 * - {@link ANDROID_IMAGE_DECODER_INVALID_STATE}: The animation is not on 463 * the first frame. 464 */ 465 int AImageDecoder_setCrop(AImageDecoder* _Nonnull decoder, ARect crop) __INTRODUCED_IN(30); 466 467 struct AImageDecoderHeaderInfo; 468 /** 469 * Opaque handle for representing information about the encoded image. 470 * 471 * Introduced in API 30 472 * 473 * Retrieved using {@link AImageDecoder_getHeaderInfo} and passed to methods 474 * like {@link AImageDecoderHeaderInfo_getWidth} and 475 * {@link AImageDecoderHeaderInfo_getHeight}. 476 */ 477 typedef struct AImageDecoderHeaderInfo AImageDecoderHeaderInfo; 478 479 /** 480 * Return an opaque handle for reading header info. 481 * 482 * This is owned by the {@link AImageDecoder} and will be destroyed when the 483 * AImageDecoder is destroyed via {@link AImageDecoder_delete}. 484 * 485 * @param decoder an {@link AImageDecoder} object. 486 * 487 * Available since API level 30. 488 */ 489 const AImageDecoderHeaderInfo* _Nonnull AImageDecoder_getHeaderInfo( 490 const AImageDecoder* _Nonnull decoder) __INTRODUCED_IN(30); 491 492 /** 493 * Report the native width of the encoded image. This is also the logical 494 * pixel width of the output, unless {@link AImageDecoder_setTargetSize} is 495 * used to choose a different size or {@link AImageDecoder_setCrop} is used to 496 * set a crop rect. 497 * 498 * Available since API level 30. 499 */ 500 int32_t AImageDecoderHeaderInfo_getWidth(const AImageDecoderHeaderInfo* _Nonnull) 501 __INTRODUCED_IN(30); 502 503 /** 504 * Report the native height of the encoded image. This is also the logical 505 * pixel height of the output, unless {@link AImageDecoder_setTargetSize} is 506 * used to choose a different size or {@link AImageDecoder_setCrop} is used to 507 * set a crop rect. 508 * 509 * Available since API level 30. 510 */ 511 int32_t AImageDecoderHeaderInfo_getHeight(const AImageDecoderHeaderInfo* _Nonnull) 512 __INTRODUCED_IN(30); 513 514 /** 515 * Report the mimeType of the encoded image. 516 * 517 * Available since API level 30. 518 * 519 * @return a string literal describing the mime type. 520 */ 521 const char* _Nonnull AImageDecoderHeaderInfo_getMimeType( 522 const AImageDecoderHeaderInfo* _Nonnull) __INTRODUCED_IN(30); 523 524 /** 525 * Report the {@link AndroidBitmapFormat} the AImageDecoder will decode to 526 * by default. {@link AImageDecoder} will try to choose one that is sensible 527 * for the image and the system. Note that this does not indicate the 528 * encoded format of the image. 529 * 530 * Available since API level 30. 531 */ 532 int32_t AImageDecoderHeaderInfo_getAndroidBitmapFormat( 533 const AImageDecoderHeaderInfo* _Nonnull) __INTRODUCED_IN(30); 534 535 /** 536 * Report how the {@link AImageDecoder} will handle alpha by default. If the image 537 * contains no alpha (according to its header), this will return 538 * {@link ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE}. If the image may contain alpha, 539 * this returns {@link ANDROID_BITMAP_FLAGS_ALPHA_PREMUL}, because 540 * {@link AImageDecoder_decodeImage} will premultiply pixels by default. 541 * 542 * Available since API level 30. 543 * 544 * Starting in API level 31, an AImageDecoder may contain multiple frames of an 545 * animation, but this method still only reports whether the first frame has 546 * alpha. 547 */ 548 int AImageDecoderHeaderInfo_getAlphaFlags( 549 const AImageDecoderHeaderInfo* _Nonnull) __INTRODUCED_IN(30); 550 551 /** 552 * Report the dataspace the AImageDecoder will decode to by default. 553 * 554 * By default, {@link AImageDecoder_decodeImage} will not do any color 555 * conversion. 556 * 557 * Available since API level 30. 558 * 559 * @return The {@link ADataSpace} representing the way the colors 560 * are encoded (or {@link ADATASPACE_UNKNOWN} if there is not a 561 * corresponding ADataSpace). This specifies how to interpret the colors 562 * in the decoded image, unless {@link AImageDecoder_setDataSpace} is 563 * called to decode to a different ADataSpace. 564 * 565 * Note that ADataSpace only exposes a few values. This may return 566 * {@link ADATASPACE_UNKNOWN}, even for Named ColorSpaces, if they have 567 * no corresponding {@link ADataSpace}. 568 */ 569 int32_t AImageDecoderHeaderInfo_getDataSpace( 570 const AImageDecoderHeaderInfo* _Nonnull) __INTRODUCED_IN(30); 571 572 /** 573 * Return the minimum stride that can be used in 574 * {@link AImageDecoder_decodeImage}. 575 * 576 * This stride provides no padding, meaning it will be exactly equal to the 577 * width times the number of bytes per pixel for the {@link AndroidBitmapFormat} 578 * being used. 579 * 580 * If the output is scaled (via {@link AImageDecoder_setTargetSize}) and/or 581 * cropped (via {@link AImageDecoder_setCrop}), this takes those into account. 582 * 583 * @param decoder an {@link AImageDecoder} object. 584 * 585 * Available since API level 30. 586 */ 587 size_t AImageDecoder_getMinimumStride(AImageDecoder* _Nonnull decoder) __INTRODUCED_IN(30); 588 589 /** 590 * Decode the image into pixels, using the settings of the {@link AImageDecoder}. 591 * 592 * Available since API level 30. 593 * 594 * Starting in API level 31, it can be used to decode all of the frames of an 595 * animated image (i.e. GIF, WebP) using new APIs. Internally, 596 * AImageDecoder keeps track of its "current frame" - that is, the frame that 597 * will be decoded by a call to AImageDecoder_decodeImage. At creation time, the 598 * current frame is always the first frame, and multiple calls to this method 599 * will each decode the first frame. {@link AImageDecoder_advanceFrame} advances 600 * the current frame to the following frame, so that future calls to this method 601 * will decode that frame. Some frames may update only part of the image. They 602 * may only update a sub-rectangle (see {@link 603 * AImageDecoderFrameInfo_getFrameRect}), or they may have alpha (see 604 * {@link AImageDecoderFrameInfo_hasAlphaWithinBounds}). In these cases, this 605 * method assumes that the prior frame is still residing in the |pixels| buffer, 606 * decodes only the new portion, and blends it with the buffer. Frames that change 607 * the entire |pixels| buffer are "independent", and do not require the prior 608 * frame to remain in the buffer. The first frame is always independent. A 609 * sophisticated client can use information from the {@link AImageDecoderFrameInfo} 610 * to determine whether other frames are independent, or what frames they rely on. 611 * 612 * If the current frame is marked {@link ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS}, 613 * AImageDecoder_decodeImage will store the |pixels| buffer prior to decoding 614 * (note: this only happens for the first in a string of consecutive 615 * ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS frames). After advancing to the 616 * following frame, AImageDecoder_decodeImage will restore that buffer prior to 617 * decoding that frame. This is the default behavior, but it can be disabled 618 * by passing false to {@link AImageDecoder_setInternallyHandleDisposePrevious}. 619 * 620 * Ignoring timing information, display, etc, a client wishing to decode all 621 * frames of an animated image may conceptually use code like the following: 622 * 623 * while (true) { 624 * int result = AImageDecoder_decodeImage(decoder, pixels, stride, size); 625 * if (result != ANDROID_IMAGE_DECODER_SUCCESS) break; 626 * 627 * // Display or save the image in |pixels|, keeping the buffer intact for 628 * // AImageDecoder to decode the next frame correctly. 629 * Application_viewImage(pixels); 630 * 631 * result = AImageDecoder_advanceFrame(decoder); 632 * if (result != ANDROID_IMAGE_DECODER_SUCCESS) break; 633 * } 634 * 635 * @param decoder Opaque object representing the decoder. 636 * @param pixels On success, will be filled with the result 637 * of the decode. Must be large enough to hold |size| bytes. 638 * @param stride Width in bytes of a single row. Must be at least 639 * {@link AImageDecoder_getMinimumStride} and a multiple of the 640 * bytes per pixel of the {@link AndroidBitmapFormat}. 641 * @param size Size of the pixel buffer in bytes. Must be at least 642 * stride * (height - 1) + 643 * {@link AImageDecoder_getMinimumStride}. 644 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 645 * indicating the reason for the failure. 646 * 647 * Errors: 648 * - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The image was truncated. A 649 * partial image was decoded, and undecoded lines have been initialized to all 650 * zeroes. 651 * - {@link ANDROID_IMAGE_DECODER_ERROR}: The image contained an error. A 652 * partial image was decoded, and undecoded lines have been initialized to all 653 * zeroes. 654 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The {@link AImageDecoder} or 655 * |pixels| is null, the stride is not large enough or not pixel aligned, or 656 * |size| is not large enough. 657 * - {@link ANDROID_IMAGE_DECODER_SEEK_ERROR}: The asset or file descriptor 658 * failed to seek. 659 * - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a 660 * failure to allocate memory. 661 * - {@link ANDROID_IMAGE_DECODER_FINISHED}: The input contains no 662 * more frames. No decoding occurred. The client must call 663 * {@link AImageDecoder_rewind} before calling 664 * {@link AImageDecoder_decodeImage} again. 665 */ 666 int AImageDecoder_decodeImage(AImageDecoder* _Nonnull decoder, 667 void* _Nonnull pixels, size_t stride, 668 size_t size) __INTRODUCED_IN(30); 669 670 /** 671 * Return true iff the image is animated - i.e. has multiple frames. 672 * 673 * Introduced in API 31. 674 * 675 * A single frame GIF is considered to *not* be animated. This may require 676 * seeking past the first frame to verify whether there is a following frame. 677 * 678 * @param decoder an {@link AImageDecoder} object. 679 * 680 * Errors: 681 * - returns false if |decoder| is null. 682 */ 683 bool AImageDecoder_isAnimated(AImageDecoder* _Nonnull decoder) 684 __INTRODUCED_IN(31); 685 686 enum { 687 /** 688 * Reported by {@link AImageDecoder_getRepeatCount} if the 689 * animation should repeat forever. 690 * 691 * Introduced in API 31 692 */ 693 ANDROID_IMAGE_DECODER_INFINITE = INT32_MAX, 694 }; 695 696 /** 697 * Report how many times the animation should repeat. 698 * 699 * Introduced in API 31. 700 * 701 * This does not include the first play through. e.g. a repeat 702 * count of 4 means that each frame is played 5 times. 703 * 704 * {@link ANDROID_IMAGE_DECODER_INFINITE} means to repeat forever. 705 * 706 * This may require seeking. 707 * 708 * For non-animated formats, this returns 0. It may return non-zero for 709 * an image with only one frame (i.e. {@link AImageDecoder_isAnimated} returns 710 * false) if the encoded image contains a repeat count. 711 * 712 * @param decoder an {@link AImageDecoder} object. 713 * @return Number of times to repeat on success or a value 714 * indicating the reason for the failure. 715 * 716 * Errors: 717 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The AImageDecoder 718 * is null. 719 */ 720 int32_t AImageDecoder_getRepeatCount(AImageDecoder* _Nonnull decoder) 721 __INTRODUCED_IN(31); 722 723 /** 724 * Advance to the next frame in the animation. 725 * 726 * Introduced in API 31. 727 * 728 * The AImageDecoder keeps track internally which frame it is ready to decode 729 * (the "current frame"). Initially it is set to decode the first frame, and 730 * each call to {@link AImageDecoder_decodeImage} will continue to decode 731 * the same frame until this method (or {@link AImageDecoder_rewind}) 732 * is called. 733 * 734 * Note that this can be used to skip a frame without decoding it. But 735 * some frames depend on (i.e. blend with) prior frames, and 736 * AImageDecoder_decodeImage assumes that the prior frame is in the 737 * |pixels| buffer. In addition, AImageDecoder_decodeImage handles caching and 738 * restoring frames (see {@link ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS}), so 739 * skipping frames in an image with such frames may not produce the correct 740 * results. 741 * 742 * Only supported by {@link ANDROID_BITMAP_FORMAT_RGBA_8888} and 743 * {@link ANDROID_BITMAP_FORMAT_RGBA_F16}. 744 * 745 * @param decoder an {@link AImageDecoder} object. 746 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 747 * indicating the reason for the failure. 748 * 749 * Errors: 750 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The AImageDecoder 751 * represents an image that is not animated (see 752 * {@link AImageDecoder_isAnimated}) or the AImageDecoder is null. 753 * - {@link ANDROID_IMAGE_DECODER_INVALID_STATE): The requested 754 * {@link AndroidBitmapFormat} does not support animation. 755 * - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The input appears 756 * to be truncated. The client must call {@link AImageDecoder_rewind} 757 * before calling {@link AImageDecoder_decodeImage} again. 758 * - {@link ANDROID_IMAGE_DECODER_ERROR}: The input contains an error. 759 * The client must call {@link AImageDecoder_rewind} before 760 * calling {@link AImageDecoder_decodeImage} again. 761 * - {@link ANDROID_IMAGE_DECODER_FINISHED}: The input contains no 762 * more frames. The client must call {@link AImageDecoder_rewind} 763 * before calling {@link AImageDecoder_decodeImage} again. 764 */ 765 int AImageDecoder_advanceFrame(AImageDecoder* _Nonnull decoder) 766 __INTRODUCED_IN(31); 767 768 /** 769 * Return to the beginning of the animation. 770 * 771 * Introduced in API 31. 772 * 773 * After this call, the AImageDecoder will be ready to decode the 774 * first frame of the animation. This can be called after reaching 775 * the end of the animation or an error or in the middle of the 776 * animation. 777 * 778 * @param decoder an {@link AImageDecoder} object. 779 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 780 * indicating the reason for the failure. 781 * 782 * Errors: 783 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The AImageDecoder 784 * represents an image that is not animated (see 785 * {@link AImageDecoder_isAnimated}) or the AImageDecoder is 786 * null. 787 * - {@link ANDROID_IMAGE_DECODER_SEEK_ERROR}: The asset or file 788 * descriptor failed to seek. 789 */ 790 int AImageDecoder_rewind(AImageDecoder* _Nonnull decoder) 791 __INTRODUCED_IN(31); 792 793 struct AImageDecoderFrameInfo; 794 795 /** 796 * Opaque handle to animation information about a single frame. 797 * 798 * Introduced in API 31 799 * 800 * The duration (retrieved with {@link AImageDecoderFrameInfo_getDuration}) is 801 * necessary for clients to display the animation at the proper speed. The other 802 * information is helpful for a client that wants to determine what frames are 803 * independent (or what frames they depend on), but is unnecessary for 804 * a simple client that wants to sequentially display all frames. 805 */ 806 typedef struct AImageDecoderFrameInfo AImageDecoderFrameInfo; 807 808 /** 809 * Create an uninitialized AImageDecoderFrameInfo. 810 * 811 * Introduced in API 31. 812 * 813 * This can be passed to {@link AImageDecoder_getFrameInfo} to fill 814 * in information about the current frame. It may be reused. 815 * 816 * Must be deleted with {@link AImageDecoderFrameInfo_delete}. 817 */ 818 AImageDecoderFrameInfo* _Nullable AImageDecoderFrameInfo_create() 819 __INTRODUCED_IN(31); 820 821 /** 822 * Delete an AImageDecoderFrameInfo. 823 * 824 * Introduced in API 31. 825 */ 826 void AImageDecoderFrameInfo_delete( 827 AImageDecoderFrameInfo* _Nullable info) __INTRODUCED_IN(31); 828 829 /** 830 * Fill |info| with information about the current frame. 831 * 832 * Introduced in API 31. 833 * 834 * Initially, this will return information about the first frame. 835 * {@link AImageDecoder_advanceFrame} and 836 * {@link AImageDecoder_rewind} can be used to change which frame 837 * is the current frame. 838 * 839 * If the image only has one frame, this will fill the {@link 840 * AImageDecoderFrameInfo} with the encoded info and reasonable 841 * defaults. 842 * 843 * If {@link AImageDecoder_advanceFrame} succeeded, this will succeed as well. 844 * 845 * @param decoder Opaque object representing the decoder. 846 * @param info Opaque object to hold frame information. On success, will be 847 * filled with information regarding the current frame. 848 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 849 * indicating the reason for the failure. 850 * 851 * Errors: 852 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: One of the parameters is null. 853 * - {@link ANDROID_IMAGE_DECODER_FINISHED}: The input contains no 854 * more frames. The client must call {@link AImageDecoder_rewind} to reset the 855 * current frame to a valid frame (0). 856 */ 857 int AImageDecoder_getFrameInfo(AImageDecoder* _Nonnull decoder, 858 AImageDecoderFrameInfo* _Nonnull info) __INTRODUCED_IN(31); 859 860 /** 861 * Report the number of nanoseconds to show the current frame. 862 * 863 * Introduced in API 31. 864 * 865 * Errors: 866 * - returns {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if |info| is null. 867 */ 868 int64_t AImageDecoderFrameInfo_getDuration( 869 const AImageDecoderFrameInfo* _Nonnull info) __INTRODUCED_IN(31); 870 871 /** 872 * The rectangle of the image (within 0, 0, 873 * {@link AImageDecoderHeaderInfo_getWidth}, {@link AImageDecoderHeaderInfo_getHeight}) 874 * updated by this frame. 875 * 876 * Introduced in API 31. 877 * 878 * Note that this is unaffected by calls to 879 * {@link AImageDecoder_setTargetSize} or 880 * {@link AImageDecoder_setCrop}. 881 * 882 * A frame may update only part of the image. This will always be 883 * contained by the image’s dimensions. 884 * 885 * This, along with other information in AImageDecoderFrameInfo, 886 * can be useful for determining whether a frame is independent, but 887 * the decoder handles blending frames, so a simple 888 * sequential client does not need this. 889 * 890 * Errors: 891 * - returns an empty ARect if |info| is null. 892 */ 893 ARect AImageDecoderFrameInfo_getFrameRect( 894 const AImageDecoderFrameInfo* _Nonnull info) __INTRODUCED_IN(31); 895 896 /** 897 * Whether the new portion of this frame may contain alpha. 898 * 899 * Introduced in API 31. 900 * 901 * Unless this frame is independent (see {@link AImageDecoder_decodeImage}), 902 * a single call to {@link AImageDecoder_decodeImage} will decode an updated 903 * rectangle of pixels and then blend it with the existing pixels in the 904 * |pixels| buffer according to {@link AImageDecoderFrameInfo_getBlendOp}. This 905 * method returns whether the updated rectangle has alpha, prior to blending. 906 * The return value is conservative; for example, if a color-index-based frame 907 * has a color with alpha but does not use it, this will still return true. 908 * 909 * This, along with other information in AImageDecoderFrameInfo, 910 * can be useful for determining whether a frame is independent, but 911 * the decoder handles blending frames, so a simple 912 * sequential client does not need this. 913 * 914 * Note that this may differ from whether the composed frame (that is, the 915 * resulting image after blending) has alpha. If this frame does not fill the 916 * entire image dimensions (see {@link AImageDecoderFrameInfo_getFrameRect}) 917 * or it blends with an opaque frame, for example, the composed frame’s alpha 918 * may not match. 919 * 920 * Errors: 921 * - returns false if |info| is null. 922 */ 923 bool AImageDecoderFrameInfo_hasAlphaWithinBounds( 924 const AImageDecoderFrameInfo* _Nonnull info) __INTRODUCED_IN(31); 925 926 /** 927 * How a frame is “disposed” before showing the next one. 928 * 929 * Introduced in API 31. 930 * 931 * This, along with other information in AImageDecoderFrameInfo, 932 * can be useful for determining whether a frame is independent, but 933 * the decoder handles disposing of frames, so a simple 934 * sequential client does not need this. 935 */ 936 enum { 937 /// No disposal. The following frame will be drawn directly 938 /// on top of this one. 939 ANDROID_IMAGE_DECODER_DISPOSE_OP_NONE = 1, 940 /// The frame’s rectangle is cleared to transparent (by AImageDecoder) 941 /// before decoding the next frame. 942 ANDROID_IMAGE_DECODER_DISPOSE_OP_BACKGROUND = 2, 943 /// The frame’s rectangle is reverted to the prior frame before decoding 944 /// the next frame. This is handled by AImageDecoder, unless 945 /// {@link AImageDecoder_setInternallyHandleDisposePrevious} is set to false. 946 ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS = 3, 947 }; 948 949 /** 950 * Return how this frame is “disposed” before showing the next one. 951 * 952 * Introduced in API 31. 953 * 954 * This, along with other information in AImageDecoderFrameInfo, 955 * can be useful for determining whether a frame is independent, but 956 * the decoder handles disposing of frames, so a simple 957 * sequential client does not need this. 958 * 959 * @return one of: 960 * - {@link ANDROID_IMAGE_DECODER_DISPOSE_OP_NONE} 961 * - {@link ANDROID_IMAGE_DECODER_DISPOSE_OP_BACKGROUND} 962 * - {@link ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS} 963 * Errors: 964 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if |info| is null. 965 */ 966 int32_t AImageDecoderFrameInfo_getDisposeOp( 967 const AImageDecoderFrameInfo* _Nonnull info) __INTRODUCED_IN(31); 968 969 /** 970 * How a frame is blended with the previous frame. 971 * 972 * Introduced in API 31. 973 * 974 * This, along with other information in AImageDecoderFrameInfo, 975 * can be useful for determining whether a frame is independent, but 976 * the decoder handles blending frames, so a simple 977 * sequential client does not need this. 978 */ 979 enum { 980 /// This frame replaces existing content. This corresponds 981 /// to webp’s “do not blend”. 982 ANDROID_IMAGE_DECODER_BLEND_OP_SRC = 1, 983 /// This frame blends with the previous frame. 984 ANDROID_IMAGE_DECODER_BLEND_OP_SRC_OVER = 2, 985 }; 986 987 /** 988 * Return how this frame is blended with the previous frame. 989 * 990 * Introduced in API 31. 991 * 992 * This, along with other information in AImageDecoderFrameInfo, 993 * can be useful for determining whether a frame is independent, but 994 * the decoder handles blending frames, so a simple 995 * sequential client does not need this. 996 * 997 * @return one of: 998 * - {@link ANDROID_IMAGE_DECODER_BLEND_OP_SRC} 999 * - {@link ANDROID_IMAGE_DECODER_BLEND_OP_SRC_OVER} 1000 * Errors: 1001 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER} if |info| is null. 1002 */ 1003 int32_t AImageDecoderFrameInfo_getBlendOp( 1004 const AImageDecoderFrameInfo* _Nonnull info) 1005 __INTRODUCED_IN(31); 1006 1007 /** 1008 * Whether to have AImageDecoder store the frame prior to a 1009 * frame marked {@link ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS}. 1010 * 1011 * Introduced in API 31. 1012 * 1013 * The default is true. Many images will not have such a frame (it 1014 * is not supported by WebP, and only some GIFs use it). But 1015 * if frame i is ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS, then i+1 1016 * may depend on i-1. When this setting is true, AImageDecoder will 1017 * defensively copy frame i-1 (i.e. the contents of |pixels| in 1018 * {@link AImageDecoder_decodeImage}) into an internal buffer so that 1019 * it can be used to decode i+1. 1020 * 1021 * AImageDecoder will only store a single frame, at the size specified 1022 * by {@link AImageDecoder_setTargetSize} (or the original dimensions 1023 * if that method has not been called), and will discard it when it is 1024 * no longer necessary. 1025 * 1026 * A client that desires to manually store such frames may set this to 1027 * false, so that AImageDecoder does not need to store this extra 1028 * frame. Instead, when decoding the same 1029 * ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS frame i, AImageDecoder 1030 * will decode directly into |pixels|, assuming the client stored i-1. 1031 * When asked to decode frame i+1, AImageDecoder will now assume that 1032 * the client provided i-1 in |pixels|. 1033 * 1034 * @param decoder an {@link AImageDecoder} object. 1035 * @param handleInternally Whether AImageDecoder will internally 1036 * handle ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS 1037 * frames. 1038 */ 1039 void AImageDecoder_setInternallyHandleDisposePrevious( 1040 AImageDecoder* _Nonnull decoder, bool handleInternally) 1041 __INTRODUCED_IN(31); 1042 1043 1044 #ifdef __cplusplus 1045 } 1046 #endif 1047 1048 #endif // ANDROID_IMAGE_DECODER_H 1049 1050 /** @} */ 1051