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 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 #ifdef __cplusplus 55 extern "C" { 56 #endif 57 58 struct AAsset; 59 60 #if __ANDROID_API__ >= 30 61 62 /** 63 * {@link AImageDecoder} functions result code. Many functions will return one of these 64 * to indicate success ({@link ANDROID_IMAGE_DECODER_SUCCESS}) or the reason 65 * for the failure. On failure, any out-parameters should be considered 66 * uninitialized, except where specified. 67 */ 68 enum { 69 /** 70 * Decoding was successful and complete. 71 */ 72 ANDROID_IMAGE_DECODER_SUCCESS = 0, 73 /** 74 * The input is incomplete. 75 */ 76 ANDROID_IMAGE_DECODER_INCOMPLETE = -1, 77 /** 78 * The input contained an error after decoding some lines. 79 */ 80 ANDROID_IMAGE_DECODER_ERROR = -2, 81 /** 82 * Could not convert. For example, attempting to decode an image with 83 * alpha to an opaque format. 84 */ 85 ANDROID_IMAGE_DECODER_INVALID_CONVERSION = -3, 86 /** 87 * The scale is invalid. It may have overflowed, or it may be incompatible 88 * with the current alpha setting. 89 */ 90 ANDROID_IMAGE_DECODER_INVALID_SCALE = -4, 91 /** 92 * Some other parameter is invalid. 93 */ 94 ANDROID_IMAGE_DECODER_BAD_PARAMETER = -5, 95 /** 96 * Input was invalid before decoding any pixels. 97 */ 98 ANDROID_IMAGE_DECODER_INVALID_INPUT = -6, 99 /** 100 * A seek was required and it failed. 101 */ 102 ANDROID_IMAGE_DECODER_SEEK_ERROR = -7, 103 /** 104 * Some other error. For example, an internal allocation failed. 105 */ 106 ANDROID_IMAGE_DECODER_INTERNAL_ERROR = -8, 107 /** 108 * AImageDecoder did not recognize the format. 109 */ 110 ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT = -9 111 }; 112 113 struct AImageDecoder; 114 115 /** 116 * Opaque handle for decoding images. 117 * 118 * Create using one of the following: 119 * - {@link AImageDecoder_createFromAAsset} 120 * - {@link AImageDecoder_createFromFd} 121 * - {@link AImageDecoder_createFromBuffer} 122 * 123 * After creation, {@link AImageDecoder_getHeaderInfo} can be used to retrieve 124 * information about the encoded image. Other functions, like 125 * {@link AImageDecoder_setTargetSize}, can be used to specify how to decode, and 126 * {@link AImageDecoder_decode} will decode into client provided memory. 127 * 128 * {@link AImageDecoder} objects are NOT thread-safe, and should not be shared across 129 * threads. 130 */ 131 typedef struct AImageDecoder AImageDecoder; 132 133 /** 134 * Create a new {@link AImageDecoder} from an {@link AAsset}. 135 * 136 * @param asset {@link AAsset} containing encoded image data. Client is still 137 * responsible for calling {@link AAsset_close} on it, which may be 138 * done after deleting the returned {@link AImageDecoder}. 139 * @param outDecoder On success (i.e. return value is 140 * {@link ANDROID_IMAGE_DECODER_SUCCESS}), this will be set to 141 * a newly created {@link AImageDecoder}. Caller is 142 * responsible for calling {@link AImageDecoder_delete} on it. 143 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 144 * indicating the reason for the failure. 145 * 146 * Errors: 147 * - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The asset was truncated before 148 * reading the image header. 149 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: One of the parameters is 150 * null. 151 * - {@link ANDROID_IMAGE_DECODER_INVALID_INPUT}: There is an error in the 152 * header. 153 * - {@link ANDROID_IMAGE_DECODER_SEEK_ERROR}: The asset failed to seek. 154 * - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a 155 * failure to allocate memory. 156 * - {@link ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT}: The format is not 157 * supported. 158 */ 159 int AImageDecoder_createFromAAsset(struct AAsset* asset, AImageDecoder** outDecoder) 160 __INTRODUCED_IN(30); 161 162 /** 163 * Create a new {@link AImageDecoder} from a file descriptor. 164 * 165 * @param fd Seekable, readable, open file descriptor for encoded data. 166 * Client is still responsible for closing it, which may be done 167 * after deleting the returned {@link AImageDecoder}. 168 * @param outDecoder On success (i.e. return value is 169 * {@link ANDROID_IMAGE_DECODER_SUCCESS}), this will be set to 170 * a newly created {@link AImageDecoder}. Caller is 171 * responsible for calling {@link AImageDecoder_delete} on it. 172 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 173 * indicating the reason for the failure. 174 * 175 * Errors: 176 * - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The file was truncated before 177 * reading the image header. 178 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The {@link AImageDecoder} is 179 * null, or |fd| does not represent a valid, seekable file descriptor. 180 * - {@link ANDROID_IMAGE_DECODER_INVALID_INPUT}: There is an error in the 181 * header. 182 * - {@link ANDROID_IMAGE_DECODER_SEEK_ERROR}: The descriptor failed to seek. 183 * - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a 184 * failure to allocate memory. 185 * - {@link ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT}: The format is not 186 * supported. 187 */ 188 int AImageDecoder_createFromFd(int fd, AImageDecoder** outDecoder) __INTRODUCED_IN(30); 189 190 /** 191 * Create a new AImageDecoder from a buffer. 192 * 193 * @param buffer Pointer to encoded data. Must be valid for the entire time 194 * the {@link AImageDecoder} is used. 195 * @param length Byte length of buffer. 196 * @param outDecoder On success (i.e. return value is 197 * {@link ANDROID_IMAGE_DECODER_SUCCESS}), this will be set to 198 * a newly created {@link AImageDecoder}. Caller is 199 * responsible for calling {@link AImageDecoder_delete} on it. 200 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 201 * indicating the reason for the failure. 202 * 203 * Errors: 204 * - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The encoded image was truncated before 205 * reading the image header. 206 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: One of the parameters is 207 * invalid. 208 * - {@link ANDROID_IMAGE_DECODER_INVALID_INPUT}: There is an error in the 209 * header. 210 * - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a 211 * failure to allocate memory. 212 * - {@link ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT}: The format is not 213 * supported. 214 */ 215 int AImageDecoder_createFromBuffer(const void* buffer, size_t length, 216 AImageDecoder** outDecoder) __INTRODUCED_IN(30); 217 218 /** 219 * Delete the AImageDecoder. 220 */ 221 void AImageDecoder_delete(AImageDecoder* decoder) __INTRODUCED_IN(30); 222 223 /** 224 * Choose the desired output format. 225 * 226 * @param format {@link AndroidBitmapFormat} to use for the output. 227 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 228 * indicating the reason for the failure. On failure, the 229 * {@link AImageDecoder} uses the format it was already planning 230 * to use (either its default or a previously successful setting 231 * from this function). 232 * 233 * Errors: 234 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 235 * {@link AImageDecoder} is null or |format| does not correspond to an 236 * {@link AndroidBitmapFormat}. 237 * - {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION}: The 238 * {@link AndroidBitmapFormat} is incompatible with the image. 239 */ 240 int AImageDecoder_setAndroidBitmapFormat(AImageDecoder*, 241 int32_t format) __INTRODUCED_IN(30); 242 243 /** 244 * Specify whether the output's pixels should be unpremultiplied. 245 * 246 * By default, {@link AImageDecoder_decodeImage} will premultiply the pixels, if they have alpha. 247 * Pass true to this method to leave them unpremultiplied. This has no effect on an 248 * opaque image. 249 * 250 * @param unpremultipliedRequired Pass true to leave the pixels unpremultiplied. 251 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 252 * indicating the reason for the failure. 253 * 254 * Errors: 255 * - {@link ANDROID_IMAGE_DECODER_INVALID_CONVERSION}: Unpremultiplied is not 256 * possible due to an existing scale set by 257 * {@link AImageDecoder_setTargetSize}. 258 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 259 * {@link AImageDecoder} is null. 260 */ 261 int AImageDecoder_setUnpremultipliedRequired(AImageDecoder*, 262 bool unpremultipliedRequired) __INTRODUCED_IN(30); 263 264 /** 265 * Choose the dataspace for the output. 266 * 267 * Ignored by {@link ANDROID_BITMAP_FORMAT_A_8}, which does not support 268 * an {@link ADataSpace}. 269 * 270 * @param dataspace The {@link ADataSpace} to decode into. An ADataSpace 271 * specifies how to interpret the colors. By default, 272 * AImageDecoder will decode into the ADataSpace specified by 273 * {@link AImageDecoderHeaderInfo_getDataSpace}. If this 274 * parameter is set to a different ADataSpace, AImageDecoder 275 * will transform the output into the specified ADataSpace. 276 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 277 * indicating the reason for the failure. 278 * 279 * Errors: 280 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 281 * {@link AImageDecoder} is null or |dataspace| does not correspond to an 282 * {@link ADataSpace} value. 283 */ 284 int AImageDecoder_setDataSpace(AImageDecoder*, int32_t dataspace) __INTRODUCED_IN(30); 285 286 /** 287 * Specify the output size for a decoded image. 288 * 289 * Future calls to {@link AImageDecoder_decodeImage} will sample or scale the 290 * encoded image to reach the desired size. If a crop rect is set (via 291 * {@link AImageDecoder_setCrop}), it must be contained within the dimensions 292 * specified by width and height, and the output image will be the size of the 293 * crop rect. 294 * 295 * @param width Width of the output (prior to cropping). 296 * This will affect future calls to 297 * {@link AImageDecoder_getMinimumStride}, which will now return 298 * a value based on this width. 299 * @param height Height of the output (prior to cropping). 300 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 301 * indicating the reason for the failure. 302 * 303 * Errors: 304 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 305 * {@link AImageDecoder} is null. 306 * - {@link ANDROID_IMAGE_DECODER_INVALID_SCALE}: |width| or |height| is <= 0, 307 * the size is too big, any existing crop is not contained by the new image dimensions, 308 * or the scale is incompatible with a previous call to 309 * {@link AImageDecoder_setUnpremultipliedRequired}(true). 310 */ 311 int AImageDecoder_setTargetSize(AImageDecoder*, int32_t width, int32_t height) __INTRODUCED_IN(30); 312 313 314 /** 315 * Compute the dimensions to use for a given sampleSize. 316 * 317 * Although AImageDecoder can scale to an arbitrary target size (see 318 * {@link AImageDecoder_setTargetSize}), some sizes may be more efficient than 319 * others. This computes the most efficient target size to use to reach a 320 * particular sampleSize. 321 * 322 * @param sampleSize A subsampling rate of the original image. Must be greater 323 * than or equal to 1. A sampleSize of 2 means to skip every 324 * other pixel/line, resulting in a width and height that are 325 * 1/2 of the original dimensions, with 1/4 the number of 326 * pixels. 327 * @param width Out parameter for the width sampled by sampleSize, and rounded 328 * in the direction that the decoder can do most efficiently. 329 * @param height Out parameter for the height sampled by sampleSize, and rounded 330 * in the direction that the decoder can do most efficiently. 331 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 332 * indicating the reason for the failure. 333 * 334 * Errors: 335 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 336 * {@link AImageDecoder}, |width| or |height| is null or |sampleSize| is < 1. 337 */ 338 int AImageDecoder_computeSampledSize(const AImageDecoder*, int sampleSize, 339 int32_t* width, int32_t* height) __INTRODUCED_IN(30); 340 /** 341 * Specify how to crop the output after scaling (if any). 342 * 343 * Future calls to {@link AImageDecoder_decodeImage} will crop their output to 344 * the specified {@link ARect}. Clients will only need to allocate enough memory 345 * for the cropped ARect. 346 * 347 * @param crop Rectangle describing a crop of the decode. It must be contained inside of 348 * the (possibly scaled, by {@link AImageDecoder_setTargetSize}) 349 * image dimensions. This will affect future calls to 350 * {@link AImageDecoder_getMinimumStride}, which will now return a 351 * value based on the width of the crop. An empty ARect - 352 * specifically { 0, 0, 0, 0 } - may be used to remove the cropping 353 * behavior. Any other empty or unsorted ARects will result in 354 * returning {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}. 355 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 356 * indicating the reason for the failure. 357 * 358 * Errors: 359 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The 360 * {@link AImageDecoder} is null or the crop is not contained by the 361 * (possibly scaled) image dimensions. 362 */ 363 int AImageDecoder_setCrop(AImageDecoder*, ARect crop) __INTRODUCED_IN(30); 364 365 struct AImageDecoderHeaderInfo; 366 /** 367 * Opaque handle for representing information about the encoded image. Retrieved 368 * using {@link AImageDecoder_getHeaderInfo} and passed to methods like 369 * {@link AImageDecoderHeaderInfo_getWidth} and 370 * {@link AImageDecoderHeaderInfo_getHeight}. 371 */ 372 typedef struct AImageDecoderHeaderInfo AImageDecoderHeaderInfo; 373 374 /** 375 * Return an opaque handle for reading header info. 376 * 377 * This is owned by the {@link AImageDecoder} and will be destroyed when the 378 * AImageDecoder is destroyed via {@link AImageDecoder_delete}. 379 */ 380 const AImageDecoderHeaderInfo* AImageDecoder_getHeaderInfo( 381 const AImageDecoder*) __INTRODUCED_IN(30); 382 383 /** 384 * Report the native width of the encoded image. This is also the logical 385 * pixel width of the output, unless {@link AImageDecoder_setTargetSize} is 386 * used to choose a different size or {@link AImageDecoder_setCrop} is used to 387 * set a crop rect. 388 */ 389 int32_t AImageDecoderHeaderInfo_getWidth(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30); 390 391 /** 392 * Report the native height of the encoded image. This is also the logical 393 * pixel height of the output, unless {@link AImageDecoder_setTargetSize} is 394 * used to choose a different size or {@link AImageDecoder_setCrop} is used to 395 * set a crop rect. 396 */ 397 int32_t AImageDecoderHeaderInfo_getHeight(const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30); 398 399 /** 400 * Report the mimeType of the encoded image. 401 * 402 * @return a string literal describing the mime type. 403 */ 404 const char* AImageDecoderHeaderInfo_getMimeType( 405 const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30); 406 407 /** 408 * Report the {@link AndroidBitmapFormat} the AImageDecoder will decode to 409 * by default. {@link AImageDecoder} will try to choose one that is sensible 410 * for the image and the system. Note that this does not indicate the 411 * encoded format of the image. 412 */ 413 int32_t AImageDecoderHeaderInfo_getAndroidBitmapFormat( 414 const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30); 415 416 /** 417 * Report how the {@link AImageDecoder} will handle alpha by default. If the image 418 * contains no alpha (according to its header), this will return 419 * {@link ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE}. If the image may contain alpha, 420 * this returns {@link ANDROID_BITMAP_FLAGS_ALPHA_PREMUL}, because 421 * {@link AImageDecoder_decodeImage} will premultiply pixels by default. 422 */ 423 int AImageDecoderHeaderInfo_getAlphaFlags( 424 const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30); 425 426 /** 427 * Report the dataspace the AImageDecoder will decode to by default. 428 * 429 * By default, {@link AImageDecoder_decodeImage} will not do any color 430 * conversion. 431 * 432 * @return The {@link ADataSpace} representing the way the colors 433 * are encoded (or {@link ADATASPACE_UNKNOWN} if there is not a 434 * corresponding ADataSpace). This specifies how to interpret the colors 435 * in the decoded image, unless {@link AImageDecoder_setDataSpace} is 436 * called to decode to a different ADataSpace. 437 * 438 * Note that ADataSpace only exposes a few values. This may return 439 * {@link ADATASPACE_UNKNOWN}, even for Named ColorSpaces, if they have 440 * no corresponding {@link ADataSpace}. 441 */ 442 int32_t AImageDecoderHeaderInfo_getDataSpace( 443 const AImageDecoderHeaderInfo*) __INTRODUCED_IN(30); 444 445 /** 446 * Return the minimum stride that can be used in 447 * {@link AImageDecoder_decodeImage). 448 * 449 * This stride provides no padding, meaning it will be exactly equal to the 450 * width times the number of bytes per pixel for the {@link AndroidBitmapFormat} 451 * being used. 452 * 453 * If the output is scaled (via {@link AImageDecoder_setTargetSize}) and/or 454 * cropped (via {@link AImageDecoder_setCrop}), this takes those into account. 455 */ 456 size_t AImageDecoder_getMinimumStride(AImageDecoder*) __INTRODUCED_IN(30); 457 458 /** 459 * Decode the image into pixels, using the settings of the {@link AImageDecoder}. 460 * 461 * @param decoder Opaque object representing the decoder. 462 * @param pixels On success, will be filled with the result 463 * of the decode. Must be large enough to hold |size| bytes. 464 * @param stride Width in bytes of a single row. Must be at least 465 * {@link AImageDecoder_getMinimumStride} and a multiple of the 466 * bytes per pixel of the {@link AndroidBitmapFormat}. 467 * @param size Size of the pixel buffer in bytes. Must be at least 468 * stride * (height - 1) + 469 * {@link AImageDecoder_getMinimumStride}. 470 * @return {@link ANDROID_IMAGE_DECODER_SUCCESS} on success or a value 471 * indicating the reason for the failure. 472 * 473 * Errors: 474 * - {@link ANDROID_IMAGE_DECODER_INCOMPLETE}: The image was truncated. A 475 * partial image was decoded, and undecoded lines have been initialized to all 476 * zeroes. 477 * - {@link ANDROID_IMAGE_DECODER_ERROR}: The image contained an error. A 478 * partial image was decoded, and undecoded lines have been initialized to all 479 * zeroes. 480 * - {@link ANDROID_IMAGE_DECODER_BAD_PARAMETER}: The {@link AImageDecoder} or 481 * |pixels| is null, the stride is not large enough or not pixel aligned, or 482 * |size| is not large enough. 483 * - {@link ANDROID_IMAGE_DECODER_SEEK_ERROR}: The asset or file descriptor 484 * failed to seek. 485 * - {@link ANDROID_IMAGE_DECODER_INTERNAL_ERROR}: Some other error, like a 486 * failure to allocate memory. 487 */ 488 int AImageDecoder_decodeImage(AImageDecoder* decoder, 489 void* pixels, size_t stride, 490 size_t size) __INTRODUCED_IN(30); 491 492 #endif // __ANDROID_API__ >= 30 493 494 #ifdef __cplusplus 495 } 496 #endif 497 498 #endif // ANDROID_IMAGE_DECODER_H 499 500 /** @} */ 501