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