1 /* 2 * Copyright (C) 2016 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 * @addtogroup Media 19 * @{ 20 */ 21 22 /** 23 * @file NdkImage.h 24 */ 25 26 /* 27 * This file defines an NDK API. 28 * Do not remove methods. 29 * Do not change method signatures. 30 * Do not change the value of constants. 31 * Do not change the size of any of the classes defined in here. 32 * Do not reference types that are not part of the NDK. 33 * Do not #include files that aren't part of the NDK. 34 */ 35 36 #ifndef _NDK_IMAGE_H 37 #define _NDK_IMAGE_H 38 39 #include <stdint.h> 40 #include <sys/cdefs.h> 41 42 #include "NdkMediaError.h" 43 44 #include <android/hardware_buffer.h> 45 46 __BEGIN_DECLS 47 48 /** 49 * AImage is an opaque type that provides access to image generated by {@link AImageReader}. 50 */ 51 typedef struct AImage AImage; 52 53 /** 54 * AImage supported formats: AImageReader only guarantees the support for the formats 55 * listed here. 56 */ 57 enum AIMAGE_FORMATS { 58 /** 59 * 32 bits RGBA format, 8 bits for each of the four channels. 60 * 61 * <p> 62 * Corresponding formats: 63 * <ul> 64 * <li>AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM</li> 65 * <li>Vulkan: VK_FORMAT_R8G8B8A8_UNORM</li> 66 * <li>OpenGL ES: GL_RGBA8</li> 67 * </ul> 68 * </p> 69 * 70 * @see AImage 71 * @see AImageReader 72 * @see AHardwareBuffer 73 */ 74 AIMAGE_FORMAT_RGBA_8888 = 0x1, 75 76 /** 77 * 32 bits RGBX format, 8 bits for each of the four channels. The values 78 * of the alpha channel bits are ignored (image is assumed to be opaque). 79 * 80 * <p> 81 * Corresponding formats: 82 * <ul> 83 * <li>AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM</li> 84 * <li>Vulkan: VK_FORMAT_R8G8B8A8_UNORM</li> 85 * <li>OpenGL ES: GL_RGB8</li> 86 * </ul> 87 * </p> 88 * 89 * @see AImage 90 * @see AImageReader 91 * @see AHardwareBuffer 92 */ 93 AIMAGE_FORMAT_RGBX_8888 = 0x2, 94 95 /** 96 * 24 bits RGB format, 8 bits for each of the three channels. 97 * 98 * <p> 99 * Corresponding formats: 100 * <ul> 101 * <li>AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM</li> 102 * <li>Vulkan: VK_FORMAT_R8G8B8_UNORM</li> 103 * <li>OpenGL ES: GL_RGB8</li> 104 * </ul> 105 * </p> 106 * 107 * @see AImage 108 * @see AImageReader 109 * @see AHardwareBuffer 110 */ 111 AIMAGE_FORMAT_RGB_888 = 0x3, 112 113 /** 114 * 16 bits RGB format, 5 bits for Red channel, 6 bits for Green channel, 115 * and 5 bits for Blue channel. 116 * 117 * <p> 118 * Corresponding formats: 119 * <ul> 120 * <li>AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM</li> 121 * <li>Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16</li> 122 * <li>OpenGL ES: GL_RGB565</li> 123 * </ul> 124 * </p> 125 * 126 * @see AImage 127 * @see AImageReader 128 * @see AHardwareBuffer 129 */ 130 AIMAGE_FORMAT_RGB_565 = 0x4, 131 132 /** 133 * 64 bits RGBA format, 16 bits for each of the four channels. 134 * 135 * <p> 136 * Corresponding formats: 137 * <ul> 138 * <li>AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT</li> 139 * <li>Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT</li> 140 * <li>OpenGL ES: GL_RGBA16F</li> 141 * </ul> 142 * </p> 143 * 144 * @see AImage 145 * @see AImageReader 146 * @see AHardwareBuffer 147 */ 148 AIMAGE_FORMAT_RGBA_FP16 = 0x16, 149 150 /** 151 * Multi-plane Android YUV 420 format. 152 * 153 * <p>This format is a generic YCbCr format, capable of describing any 4:2:0 154 * chroma-subsampled planar or semiplanar buffer (but not fully interleaved), 155 * with 8 bits per color sample.</p> 156 * 157 * <p>Images in this format are always represented by three separate buffers 158 * of data, one for each color plane. Additional information always 159 * accompanies the buffers, describing the row stride and the pixel stride 160 * for each plane.</p> 161 * 162 * <p>The order of planes is guaranteed such that plane #0 is always Y, plane #1 is always 163 * U (Cb), and plane #2 is always V (Cr).</p> 164 * 165 * <p>The Y-plane is guaranteed not to be interleaved with the U/V planes 166 * (in particular, pixel stride is always 1 in {@link AImage_getPlanePixelStride}).</p> 167 * 168 * <p>The U/V planes are guaranteed to have the same row stride and pixel stride, that is, the 169 * return value of {@link AImage_getPlaneRowStride} for the U/V plane are guaranteed to be the 170 * same, and the return value of {@link AImage_getPlanePixelStride} for the U/V plane are also 171 * guaranteed to be the same.</p> 172 * 173 * <p>For example, the {@link AImage} object can provide data 174 * in this format from a {@link ACameraDevice} through an {@link AImageReader} object.</p> 175 * 176 * <p>This format is always supported as an output format for the android Camera2 NDK API.</p> 177 * 178 * @see AImage 179 * @see AImageReader 180 * @see ACameraDevice 181 */ 182 AIMAGE_FORMAT_YUV_420_888 = 0x23, 183 184 /** 185 * Compressed JPEG format. 186 * 187 * <p>This format is always supported as an output format for the android Camera2 NDK API.</p> 188 */ 189 AIMAGE_FORMAT_JPEG = 0x100, 190 191 /** 192 * 16 bits per pixel raw camera sensor image format, usually representing a single-channel 193 * Bayer-mosaic image. 194 * 195 * <p>The layout of the color mosaic, the maximum and minimum encoding 196 * values of the raw pixel data, the color space of the image, and all other 197 * needed information to interpret a raw sensor image must be queried from 198 * the {@link ACameraDevice} which produced the image.</p> 199 */ 200 AIMAGE_FORMAT_RAW16 = 0x20, 201 202 /** 203 * Private raw camera sensor image format, a single channel image with implementation depedent 204 * pixel layout. 205 * 206 * <p>AIMAGE_FORMAT_RAW_PRIVATE is a format for unprocessed raw image buffers coming from an 207 * image sensor. The actual structure of buffers of this format is implementation-dependent.</p> 208 * 209 */ 210 AIMAGE_FORMAT_RAW_PRIVATE = 0x24, 211 212 /** 213 * Android 10-bit raw format. 214 * 215 * <p> 216 * This is a single-plane, 10-bit per pixel, densely packed (in each row), 217 * unprocessed format, usually representing raw Bayer-pattern images coming 218 * from an image sensor. 219 * </p> 220 * <p> 221 * In an image buffer with this format, starting from the first pixel of 222 * each row, each 4 consecutive pixels are packed into 5 bytes (40 bits). 223 * Each one of the first 4 bytes contains the top 8 bits of each pixel, The 224 * fifth byte contains the 2 least significant bits of the 4 pixels, the 225 * exact layout data for each 4 consecutive pixels is illustrated below 226 * (Pi[j] stands for the jth bit of the ith pixel): 227 * </p> 228 * <table> 229 * <tr> 230 * <th align="center"></th> 231 * <th align="center">bit 7</th> 232 * <th align="center">bit 6</th> 233 * <th align="center">bit 5</th> 234 * <th align="center">bit 4</th> 235 * <th align="center">bit 3</th> 236 * <th align="center">bit 2</th> 237 * <th align="center">bit 1</th> 238 * <th align="center">bit 0</th> 239 * </tr> 240 * <tr> 241 * <td align="center">Byte 0:</td> 242 * <td align="center">P0[9]</td> 243 * <td align="center">P0[8]</td> 244 * <td align="center">P0[7]</td> 245 * <td align="center">P0[6]</td> 246 * <td align="center">P0[5]</td> 247 * <td align="center">P0[4]</td> 248 * <td align="center">P0[3]</td> 249 * <td align="center">P0[2]</td> 250 * </tr> 251 * <tr> 252 * <td align="center">Byte 1:</td> 253 * <td align="center">P1[9]</td> 254 * <td align="center">P1[8]</td> 255 * <td align="center">P1[7]</td> 256 * <td align="center">P1[6]</td> 257 * <td align="center">P1[5]</td> 258 * <td align="center">P1[4]</td> 259 * <td align="center">P1[3]</td> 260 * <td align="center">P1[2]</td> 261 * </tr> 262 * <tr> 263 * <td align="center">Byte 2:</td> 264 * <td align="center">P2[9]</td> 265 * <td align="center">P2[8]</td> 266 * <td align="center">P2[7]</td> 267 * <td align="center">P2[6]</td> 268 * <td align="center">P2[5]</td> 269 * <td align="center">P2[4]</td> 270 * <td align="center">P2[3]</td> 271 * <td align="center">P2[2]</td> 272 * </tr> 273 * <tr> 274 * <td align="center">Byte 3:</td> 275 * <td align="center">P3[9]</td> 276 * <td align="center">P3[8]</td> 277 * <td align="center">P3[7]</td> 278 * <td align="center">P3[6]</td> 279 * <td align="center">P3[5]</td> 280 * <td align="center">P3[4]</td> 281 * <td align="center">P3[3]</td> 282 * <td align="center">P3[2]</td> 283 * </tr> 284 * <tr> 285 * <td align="center">Byte 4:</td> 286 * <td align="center">P3[1]</td> 287 * <td align="center">P3[0]</td> 288 * <td align="center">P2[1]</td> 289 * <td align="center">P2[0]</td> 290 * <td align="center">P1[1]</td> 291 * <td align="center">P1[0]</td> 292 * <td align="center">P0[1]</td> 293 * <td align="center">P0[0]</td> 294 * </tr> 295 * </table> 296 * <p> 297 * This format assumes 298 * <ul> 299 * <li>a width multiple of 4 pixels</li> 300 * <li>an even height</li> 301 * </ul> 302 * </p> 303 * 304 * <pre>size = row stride * height</pre> where the row stride is in <em>bytes</em>, 305 * not pixels. 306 * 307 * <p> 308 * Since this is a densely packed format, the pixel stride is always 0. The 309 * application must use the pixel data layout defined in above table to 310 * access each row data. When row stride is equal to (width * (10 / 8)), there 311 * will be no padding bytes at the end of each row, the entire image data is 312 * densely packed. When stride is larger than (width * (10 / 8)), padding 313 * bytes will be present at the end of each row. 314 * </p> 315 * <p> 316 * For example, the {@link AImage} object can provide data in this format from a 317 * {@link ACameraDevice} (if supported) through a {@link AImageReader} object. 318 * The number of planes returned by {@link AImage_getNumberOfPlanes} will always be 1. 319 * The pixel stride is undefined ({@link AImage_getPlanePixelStride} will return 320 * {@link AMEDIA_ERROR_UNSUPPORTED}), and the {@link AImage_getPlaneRowStride} described the 321 * vertical neighboring pixel distance (in bytes) between adjacent rows. 322 * </p> 323 * 324 * @see AImage 325 * @see AImageReader 326 * @see ACameraDevice 327 */ 328 AIMAGE_FORMAT_RAW10 = 0x25, 329 330 /** 331 * Android 12-bit raw format. 332 * 333 * <p> 334 * This is a single-plane, 12-bit per pixel, densely packed (in each row), 335 * unprocessed format, usually representing raw Bayer-pattern images coming 336 * from an image sensor. 337 * </p> 338 * <p> 339 * In an image buffer with this format, starting from the first pixel of each 340 * row, each two consecutive pixels are packed into 3 bytes (24 bits). The first 341 * and second byte contains the top 8 bits of first and second pixel. The third 342 * byte contains the 4 least significant bits of the two pixels, the exact layout 343 * data for each two consecutive pixels is illustrated below (Pi[j] stands for 344 * the jth bit of the ith pixel): 345 * </p> 346 * <table> 347 * <tr> 348 * <th align="center"></th> 349 * <th align="center">bit 7</th> 350 * <th align="center">bit 6</th> 351 * <th align="center">bit 5</th> 352 * <th align="center">bit 4</th> 353 * <th align="center">bit 3</th> 354 * <th align="center">bit 2</th> 355 * <th align="center">bit 1</th> 356 * <th align="center">bit 0</th> 357 * </tr> 358 * <tr> 359 * <td align="center">Byte 0:</td> 360 * <td align="center">P0[11]</td> 361 * <td align="center">P0[10]</td> 362 * <td align="center">P0[ 9]</td> 363 * <td align="center">P0[ 8]</td> 364 * <td align="center">P0[ 7]</td> 365 * <td align="center">P0[ 6]</td> 366 * <td align="center">P0[ 5]</td> 367 * <td align="center">P0[ 4]</td> 368 * </tr> 369 * <tr> 370 * <td align="center">Byte 1:</td> 371 * <td align="center">P1[11]</td> 372 * <td align="center">P1[10]</td> 373 * <td align="center">P1[ 9]</td> 374 * <td align="center">P1[ 8]</td> 375 * <td align="center">P1[ 7]</td> 376 * <td align="center">P1[ 6]</td> 377 * <td align="center">P1[ 5]</td> 378 * <td align="center">P1[ 4]</td> 379 * </tr> 380 * <tr> 381 * <td align="center">Byte 2:</td> 382 * <td align="center">P1[ 3]</td> 383 * <td align="center">P1[ 2]</td> 384 * <td align="center">P1[ 1]</td> 385 * <td align="center">P1[ 0]</td> 386 * <td align="center">P0[ 3]</td> 387 * <td align="center">P0[ 2]</td> 388 * <td align="center">P0[ 1]</td> 389 * <td align="center">P0[ 0]</td> 390 * </tr> 391 * </table> 392 * <p> 393 * This format assumes 394 * <ul> 395 * <li>a width multiple of 4 pixels</li> 396 * <li>an even height</li> 397 * </ul> 398 * </p> 399 * 400 * <pre>size = row stride * height</pre> where the row stride is in <em>bytes</em>, 401 * not pixels. 402 * 403 * <p> 404 * Since this is a densely packed format, the pixel stride is always 0. The 405 * application must use the pixel data layout defined in above table to 406 * access each row data. When row stride is equal to (width * (12 / 8)), there 407 * will be no padding bytes at the end of each row, the entire image data is 408 * densely packed. When stride is larger than (width * (12 / 8)), padding 409 * bytes will be present at the end of each row. 410 * </p> 411 * <p> 412 * For example, the {@link AImage} object can provide data in this format from a 413 * {@link ACameraDevice} (if supported) through a {@link AImageReader} object. 414 * The number of planes returned by {@link AImage_getNumberOfPlanes} will always be 1. 415 * The pixel stride is undefined ({@link AImage_getPlanePixelStride} will return 416 * {@link AMEDIA_ERROR_UNSUPPORTED}), and the {@link AImage_getPlaneRowStride} described the 417 * vertical neighboring pixel distance (in bytes) between adjacent rows. 418 * </p> 419 * 420 * @see AImage 421 * @see AImageReader 422 * @see ACameraDevice 423 */ 424 AIMAGE_FORMAT_RAW12 = 0x26, 425 426 /** 427 * Android dense depth image format. 428 * 429 * <p>Each pixel is 16 bits, representing a depth ranging measurement from a depth camera or 430 * similar sensor. The 16-bit sample consists of a confidence value and the actual ranging 431 * measurement.</p> 432 * 433 * <p>The confidence value is an estimate of correctness for this sample. It is encoded in the 434 * 3 most significant bits of the sample, with a value of 0 representing 100% confidence, a 435 * value of 1 representing 0% confidence, a value of 2 representing 1/7, a value of 3 436 * representing 2/7, and so on.</p> 437 * 438 * <p>As an example, the following sample extracts the range and confidence from the first pixel 439 * of a DEPTH16-format {@link AImage}, and converts the confidence to a floating-point value 440 * between 0 and 1.f inclusive, with 1.f representing maximum confidence: 441 * 442 * <pre> 443 * uint16_t* data; 444 * int dataLength; 445 * AImage_getPlaneData(image, 0, (uint8_t**)&data, &dataLength); 446 * uint16_t depthSample = data[0]; 447 * uint16_t depthRange = (depthSample & 0x1FFF); 448 * uint16_t depthConfidence = ((depthSample >> 13) & 0x7); 449 * float depthPercentage = depthConfidence == 0 ? 1.f : (depthConfidence - 1) / 7.f; 450 * </pre> 451 * </p> 452 * 453 * <p>This format assumes 454 * <ul> 455 * <li>an even width</li> 456 * <li>an even height</li> 457 * <li>a horizontal stride multiple of 16 pixels</li> 458 * </ul> 459 * </p> 460 * 461 * <pre> y_size = stride * height </pre> 462 * 463 * When produced by a camera, the units for the range are millimeters. 464 */ 465 AIMAGE_FORMAT_DEPTH16 = 0x44363159, 466 467 /** 468 * Android sparse depth point cloud format. 469 * 470 * <p>A variable-length list of 3D points plus a confidence value, with each point represented 471 * by four floats; first the X, Y, Z position coordinates, and then the confidence value.</p> 472 * 473 * <p>The number of points is ((size of the buffer in bytes) / 16). 474 * 475 * <p>The coordinate system and units of the position values depend on the source of the point 476 * cloud data. The confidence value is between 0.f and 1.f, inclusive, with 0 representing 0% 477 * confidence and 1.f representing 100% confidence in the measured position values.</p> 478 * 479 * <p>As an example, the following code extracts the first depth point in a DEPTH_POINT_CLOUD 480 * format {@link AImage}: 481 * <pre> 482 * float* data; 483 * int dataLength; 484 * AImage_getPlaneData(image, 0, (uint8_t**)&data, &dataLength); 485 * float x = data[0]; 486 * float y = data[1]; 487 * float z = data[2]; 488 * float confidence = data[3]; 489 * </pre> 490 * 491 */ 492 AIMAGE_FORMAT_DEPTH_POINT_CLOUD = 0x101, 493 494 /** 495 * Android private opaque image format. 496 * 497 * <p>The choices of the actual format and pixel data layout are entirely up to the 498 * device-specific and framework internal implementations, and may vary depending on use cases 499 * even for the same device. Also note that the contents of these buffers are not directly 500 * accessible to the application.</p> 501 * 502 * <p>When an {@link AImage} of this format is obtained from an {@link AImageReader} or 503 * {@link AImage_getNumberOfPlanes()} method will return zero.</p> 504 */ 505 AIMAGE_FORMAT_PRIVATE = 0x22, 506 507 /** 508 * Android Y8 format. 509 * 510 * <p>Y8 is a planar format comprised of a WxH Y plane only, with each pixel 511 * being represented by 8 bits.</p> 512 * 513 * <p>This format assumes 514 * <ul> 515 * <li>an even width</li> 516 * <li>an even height</li> 517 * <li>a horizontal stride multiple of 16 pixels</li> 518 * </ul> 519 * </p> 520 * 521 * <pre> size = stride * height </pre> 522 * 523 * <p>For example, the {@link AImage} object can provide data 524 * in this format from a {@link ACameraDevice} (if supported) through a 525 * {@link AImageReader} object. The number of planes returned by 526 * {@link AImage_getNumberOfPlanes} will always be 1. The pixel stride returned by 527 * {@link AImage_getPlanePixelStride} will always be 1, and the 528 * {@link AImage_getPlaneRowStride} described the vertical neighboring pixel distance 529 * (in bytes) between adjacent rows.</p> 530 * 531 */ 532 AIMAGE_FORMAT_Y8 = 0x20203859, 533 534 /** 535 * Compressed HEIC format. 536 * 537 * <p>This format defines the HEIC brand of High Efficiency Image File 538 * Format as described in ISO/IEC 23008-12.</p> 539 */ 540 AIMAGE_FORMAT_HEIC = 0x48454946, 541 542 /** 543 * Depth augmented compressed JPEG format. 544 * 545 * <p>JPEG compressed main image along with XMP embedded depth metadata 546 * following ISO 16684-1:2011(E).</p> 547 */ 548 AIMAGE_FORMAT_DEPTH_JPEG = 0x69656963, 549 550 }; 551 552 /** 553 * Data type describing an cropped rectangle returned by {@link AImage_getCropRect}. 554 * 555 * <p>Note that the right and bottom coordinates are exclusive, so the width of the rectangle is 556 * (right - left) and the height of the rectangle is (bottom - top).</p> 557 */ 558 typedef struct AImageCropRect { 559 int32_t left; 560 int32_t top; 561 int32_t right; 562 int32_t bottom; 563 } AImageCropRect; 564 565 /** 566 * Return the image back the the system and delete the AImage object from memory. 567 * 568 * <p>Do NOT use the image pointer after this method returns. 569 * Note that if the parent {@link AImageReader} is closed, all the {@link AImage} objects acquired 570 * from the parent reader will be returned to system. All AImage_* methods except this method will 571 * return {@link AMEDIA_ERROR_INVALID_OBJECT}. Application still needs to call this method on those 572 * {@link AImage} objects to fully delete the {@link AImage} object from memory.</p> 573 * 574 * Available since API level 24. 575 * 576 * @param image The {@link AImage} to be deleted. 577 */ 578 void AImage_delete(AImage* image) __INTRODUCED_IN(24); 579 580 /** 581 * Query the width of the input {@link AImage}. 582 * 583 * Available since API level 24. 584 * 585 * @param image the {@link AImage} of interest. 586 * @param width the width of the image will be filled here if the method call succeeds. 587 * 588 * @return <ul> 589 * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 590 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or width is NULL.</li> 591 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this 592 * image has been deleted.</li></ul> 593 */ 594 media_status_t AImage_getWidth(const AImage* image, /*out*/int32_t* width) __INTRODUCED_IN(24); 595 596 /** 597 * Query the height of the input {@link AImage}. 598 * 599 * Available since API level 24. 600 * 601 * @param image the {@link AImage} of interest. 602 * @param height the height of the image will be filled here if the method call succeeds. 603 * 604 * @return <ul> 605 * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 606 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or height is NULL.</li> 607 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this 608 * image has been deleted.</li></ul> 609 */ 610 media_status_t AImage_getHeight(const AImage* image, /*out*/int32_t* height) __INTRODUCED_IN(24); 611 612 /** 613 * Query the format of the input {@link AImage}. 614 * 615 * <p>The format value will be one of AIMAGE_FORMAT_* enum value.</p> 616 * 617 * Available since API level 24. 618 * 619 * @param image the {@link AImage} of interest. 620 * @param format the format of the image will be filled here if the method call succeeds. 621 * 622 * @return <ul> 623 * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 624 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or format is NULL.</li> 625 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this 626 * image has been deleted.</li></ul> 627 */ 628 media_status_t AImage_getFormat(const AImage* image, /*out*/int32_t* format) __INTRODUCED_IN(24); 629 630 /** 631 * Query the cropped rectangle of the input {@link AImage}. 632 * 633 * <p>The crop rectangle specifies the region of valid pixels in the image, using coordinates in the 634 * largest-resolution plane.</p> 635 * 636 * Available since API level 24. 637 * 638 * @param image the {@link AImage} of interest. 639 * @param rect the cropped rectangle of the image will be filled here if the method call succeeds. 640 * 641 * @return <ul> 642 * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 643 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or rect is NULL.</li> 644 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this 645 * image has been deleted.</li></ul> 646 */ 647 media_status_t AImage_getCropRect(const AImage* image, /*out*/AImageCropRect* rect) __INTRODUCED_IN(24); 648 649 /** 650 * Query the timestamp of the input {@link AImage}. 651 * 652 * <p> 653 * The timestamp is measured in nanoseconds, and is normally monotonically increasing. The 654 * timestamps for the images from different sources may have different timebases therefore may not 655 * be comparable. The specific meaning and timebase of the timestamp depend on the source providing 656 * images. For images generated by camera, the timestamp value will match 657 * {@link ACAMERA_SENSOR_TIMESTAMP} of the {@link ACameraMetadata} in 658 * {@link ACameraCaptureSession_captureCallbacks#onCaptureStarted} and 659 * {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted} callback. 660 * </p> 661 * 662 * Available since API level 24. 663 * 664 * @param image the {@link AImage} of interest. 665 * @param timestampNs the timestamp of the image will be filled here if the method call succeeds. 666 * 667 * @return <ul> 668 * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 669 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or timestampNs is NULL.</li> 670 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this 671 * image has been deleted.</li></ul> 672 */ 673 media_status_t AImage_getTimestamp(const AImage* image, /*out*/int64_t* timestampNs) __INTRODUCED_IN(24); 674 675 /** 676 * Query the number of planes of the input {@link AImage}. 677 * 678 * <p>The number of plane of an {@link AImage} is determined by its format, which can be queried by 679 * {@link AImage_getFormat} method.</p> 680 * 681 * Available since API level 24. 682 * 683 * @param image the {@link AImage} of interest. 684 * @param numPlanes the number of planes of the image will be filled here if the method call 685 * succeeds. 686 * 687 * @return <ul> 688 * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 689 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or numPlanes is NULL.</li> 690 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this 691 * image has been deleted.</li></ul> 692 */ 693 media_status_t AImage_getNumberOfPlanes(const AImage* image, /*out*/int32_t* numPlanes) __INTRODUCED_IN(24); 694 695 /** 696 * Query the pixel stride of the input {@link AImage}. 697 * 698 * <p>This is the distance between two consecutive pixel values in a row of pixels. It may be 699 * larger than the size of a single pixel to account for interleaved image data or padded formats. 700 * Note that pixel stride is undefined for some formats such as {@link AIMAGE_FORMAT_RAW_PRIVATE}, 701 * and calling this method on images of these formats will cause {@link AMEDIA_ERROR_UNSUPPORTED} 702 * being returned. 703 * For formats where pixel stride is well defined, the pixel stride is always greater than 0.</p> 704 * 705 * Available since API level 24. 706 * 707 * @param image the {@link AImage} of interest. 708 * @param planeIdx the index of the plane. Must be less than the number of planes of input image. 709 * @param pixelStride the pixel stride of the image will be filled here if the method call succeeds. 710 * 711 * @return <ul> 712 * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 713 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or pixelStride is NULL, or planeIdx 714 * is out of the range of [0, numOfPlanes - 1].</li> 715 * <li>{@link AMEDIA_ERROR_UNSUPPORTED} if pixel stride is undefined for the format of input 716 * image.</li> 717 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this 718 * image has been deleted.</li> 719 * <li>{@link AMEDIA_IMGREADER_CANNOT_LOCK_IMAGE} if the {@link AImage} cannot be locked 720 * for CPU access.</li></ul> 721 */ 722 media_status_t AImage_getPlanePixelStride( 723 const AImage* image, int planeIdx, /*out*/int32_t* pixelStride) __INTRODUCED_IN(24); 724 725 /** 726 * Query the row stride of the input {@link AImage}. 727 * 728 * <p>This is the distance between the start of two consecutive rows of pixels in the image. Note 729 * that row stried is undefined for some formats such as {@link AIMAGE_FORMAT_RAW_PRIVATE}, and 730 * calling this method on images of these formats will cause {@link AMEDIA_ERROR_UNSUPPORTED} 731 * being returned. 732 * For formats where row stride is well defined, the row stride is always greater than 0.</p> 733 * 734 * Available since API level 24. 735 * 736 * @param image the {@link AImage} of interest. 737 * @param planeIdx the index of the plane. Must be less than the number of planes of input image. 738 * @param rowStride the row stride of the image will be filled here if the method call succeeds. 739 * 740 * @return <ul> 741 * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 742 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or rowStride is NULL, or planeIdx 743 * is out of the range of [0, numOfPlanes - 1].</li> 744 * <li>{@link AMEDIA_ERROR_UNSUPPORTED} if row stride is undefined for the format of input 745 * image.</li> 746 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this 747 * image has been deleted.</li> 748 * <li>{@link AMEDIA_IMGREADER_CANNOT_LOCK_IMAGE} if the {@link AImage} cannot be locked 749 * for CPU access.</li></ul> 750 */ 751 media_status_t AImage_getPlaneRowStride( 752 const AImage* image, int planeIdx, /*out*/int32_t* rowStride) __INTRODUCED_IN(24); 753 754 /** 755 * Get the data pointer of the input image for direct application access. 756 * 757 * <p>Note that once the {@link AImage} or the parent {@link AImageReader} is deleted, the data 758 * pointer from previous AImage_getPlaneData call becomes invalid. Do NOT use it after the 759 * {@link AImage} or the parent {@link AImageReader} is deleted.</p> 760 * 761 * Available since API level 24. 762 * 763 * @param image the {@link AImage} of interest. 764 * @param planeIdx the index of the plane. Must be less than the number of planes of input image. 765 * @param data the data pointer of the image will be filled here if the method call succeeds. 766 * @param dataLength the valid length of data will be filled here if the method call succeeds. 767 * 768 * @return <ul> 769 * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 770 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image, data or dataLength is NULL, or 771 * planeIdx is out of the range of [0, numOfPlanes - 1].</li> 772 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this 773 * image has been deleted.</li> 774 * <li>{@link AMEDIA_IMGREADER_CANNOT_LOCK_IMAGE} if the {@link AImage} cannot be locked 775 * for CPU access.</li></ul> 776 */ 777 media_status_t AImage_getPlaneData( 778 const AImage* image, int planeIdx, 779 /*out*/uint8_t** data, /*out*/int* dataLength) __INTRODUCED_IN(24); 780 781 /** 782 * Return the image back the the system and delete the AImage object from memory asynchronously. 783 * 784 * <p>Similar to {@link AImage_delete}, do NOT use the image pointer after this method returns. 785 * However, the caller can still hold on to the {@link AHardwareBuffer} returned from this image and 786 * signal the release of the hardware buffer back to the {@link AImageReader}'s queue using 787 * releaseFenceFd.</p> 788 * 789 * Available since API level 26. 790 * 791 * @param image The {@link AImage} to be deleted. 792 * @param releaseFenceFd A sync fence fd defined in {@link sync.h}, which signals the release of 793 * underlying {@link AHardwareBuffer}. 794 * 795 * @see sync.h 796 */ 797 void AImage_deleteAsync(AImage* image, int releaseFenceFd) __INTRODUCED_IN(26); 798 799 /** 800 * Get the hardware buffer handle of the input image intended for GPU and/or hardware access. 801 * 802 * <p>Note that no reference on the returned {@link AHardwareBuffer} handle is acquired 803 * automatically. Once the {@link AImage} or the parent {@link AImageReader} is deleted, the 804 * {@link AHardwareBuffer} handle from previous {@link AImage_getHardwareBuffer} becomes 805 * invalid.</p> 806 * 807 * <p>If the caller ever needs to hold on a reference to the {@link AHardwareBuffer} handle after 808 * the {@link AImage} or the parent {@link AImageReader} is deleted, it must call {@link 809 * AHardwareBuffer_acquire} to acquire an extra reference, and call {@link AHardwareBuffer_release} 810 * once it has finished using it in order to properly deallocate the underlying memory managed by 811 * {@link AHardwareBuffer}. If the caller has acquired extra reference on an {@link AHardwareBuffer} 812 * returned from this function, it must also register a listener using the function 813 * {@link AImageReader_setBufferRemovedListener} to be notified when the buffer is no longer used 814 * by {@link AImageReader}.</p> 815 * 816 * Available since API level 26. 817 * 818 * @param image the {@link AImage} of interest. 819 * @param buffer The memory area pointed to by buffer will contain the acquired AHardwareBuffer 820 * handle. 821 * @return <ul> 822 * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 823 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or buffer is NULL</li></ul> 824 * 825 * @see AImageReader_ImageCallback 826 */ 827 media_status_t AImage_getHardwareBuffer(const AImage* image, /*out*/AHardwareBuffer** buffer) __INTRODUCED_IN(26); 828 829 /** 830 * Query the dataspace of the input {@link AImage}. 831 * 832 * Available since API level 34. 833 * 834 * @param image the {@link AImage} of interest. 835 * @param dataSpace the dataspace of the image will be filled here if the method call succeeds. 836 * This must be one of the ADATASPACE_* enum value defined in 837 * {@link ADataSpace}. 838 * 839 * @return <ul> 840 * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 841 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or dataSpace is NULL.</li> 842 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this 843 * image has been deleted.</li></ul> 844 */ 845 media_status_t AImage_getDataSpace(const AImage* image, 846 /*out*/int32_t* dataSpace) __INTRODUCED_IN(34); 847 848 __END_DECLS 849 850 #endif //_NDK_IMAGE_H 851 852 /** @} */ 853