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