1 /* 2 * Copyright 2017 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 * @file hardware_buffer.h 19 * @brief API for native hardware buffers. 20 */ 21 /** 22 * @defgroup AHardwareBuffer Native Hardware Buffer 23 * 24 * AHardwareBuffer objects represent chunks of memory that can be 25 * accessed by various hardware components in the system. It can be 26 * easily converted to the Java counterpart 27 * android.hardware.HardwareBuffer and passed between processes using 28 * Binder. All operations involving AHardwareBuffer and HardwareBuffer 29 * are zero-copy, i.e., passing AHardwareBuffer to another process 30 * creates a shared view of the same region of memory. 31 * 32 * AHardwareBuffers can be bound to EGL/OpenGL and Vulkan primitives. 33 * For EGL, use the extension function eglGetNativeClientBufferANDROID 34 * to obtain an EGLClientBuffer and pass it directly to 35 * eglCreateImageKHR. Refer to the EGL extensions 36 * EGL_ANDROID_get_native_client_buffer and 37 * EGL_ANDROID_image_native_buffer for more information. In Vulkan, 38 * the contents of the AHardwareBuffer can be accessed as external 39 * memory. See the VK_ANDROID_external_memory_android_hardware_buffer 40 * extension for details. 41 * 42 * @{ 43 */ 44 45 #ifndef ANDROID_HARDWARE_BUFFER_H 46 #define ANDROID_HARDWARE_BUFFER_H 47 48 #include <android/rect.h> 49 #include <inttypes.h> 50 #include <sys/cdefs.h> 51 52 __BEGIN_DECLS 53 54 // clang-format off 55 56 /** 57 * Buffer pixel formats. 58 */ 59 enum AHardwareBuffer_Format { 60 /** 61 * Corresponding formats: 62 * Vulkan: VK_FORMAT_R8G8B8A8_UNORM 63 * OpenGL ES: GL_RGBA8 64 */ 65 AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM = 1, 66 67 /** 68 * 32 bits per pixel, 8 bits per channel format where alpha values are 69 * ignored (always opaque). 70 * Corresponding formats: 71 * Vulkan: VK_FORMAT_R8G8B8A8_UNORM 72 * OpenGL ES: GL_RGB8 73 */ 74 AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM = 2, 75 76 /** 77 * Corresponding formats: 78 * Vulkan: VK_FORMAT_R8G8B8_UNORM 79 * OpenGL ES: GL_RGB8 80 */ 81 AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM = 3, 82 83 /** 84 * Corresponding formats: 85 * Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16 86 * OpenGL ES: GL_RGB565 87 */ 88 AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM = 4, 89 90 /** 91 * Corresponding formats: 92 * Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT 93 * OpenGL ES: GL_RGBA16F 94 */ 95 AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT = 0x16, 96 97 /** 98 * Corresponding formats: 99 * Vulkan: VK_FORMAT_A2B10G10R10_UNORM_PACK32 100 * OpenGL ES: GL_RGB10_A2 101 */ 102 AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM = 0x2b, 103 104 /** 105 * Opaque binary blob format. 106 * Must have height 1 and one layer, with width equal to the buffer 107 * size in bytes. Corresponds to Vulkan buffers and OpenGL buffer 108 * objects. Can be bound to the latter using GL_EXT_external_buffer. 109 */ 110 AHARDWAREBUFFER_FORMAT_BLOB = 0x21, 111 112 /** 113 * Corresponding formats: 114 * Vulkan: VK_FORMAT_D16_UNORM 115 * OpenGL ES: GL_DEPTH_COMPONENT16 116 */ 117 AHARDWAREBUFFER_FORMAT_D16_UNORM = 0x30, 118 119 /** 120 * Corresponding formats: 121 * Vulkan: VK_FORMAT_X8_D24_UNORM_PACK32 122 * OpenGL ES: GL_DEPTH_COMPONENT24 123 */ 124 AHARDWAREBUFFER_FORMAT_D24_UNORM = 0x31, 125 126 /** 127 * Corresponding formats: 128 * Vulkan: VK_FORMAT_D24_UNORM_S8_UINT 129 * OpenGL ES: GL_DEPTH24_STENCIL8 130 */ 131 AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT = 0x32, 132 133 /** 134 * Corresponding formats: 135 * Vulkan: VK_FORMAT_D32_SFLOAT 136 * OpenGL ES: GL_DEPTH_COMPONENT32F 137 */ 138 AHARDWAREBUFFER_FORMAT_D32_FLOAT = 0x33, 139 140 /** 141 * Corresponding formats: 142 * Vulkan: VK_FORMAT_D32_SFLOAT_S8_UINT 143 * OpenGL ES: GL_DEPTH32F_STENCIL8 144 */ 145 AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT = 0x34, 146 147 /** 148 * Corresponding formats: 149 * Vulkan: VK_FORMAT_S8_UINT 150 * OpenGL ES: GL_STENCIL_INDEX8 151 */ 152 AHARDWAREBUFFER_FORMAT_S8_UINT = 0x35, 153 154 /** 155 * YUV 420 888 format. 156 * Must have an even width and height. Can be accessed in OpenGL 157 * shaders through an external sampler. Does not support mip-maps 158 * cube-maps or multi-layered textures. 159 */ 160 AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420 = 0x23, 161 162 /** 163 * YUV P010 format. 164 * Must have an even width and height. Can be accessed in OpenGL 165 * shaders through an external sampler. Does not support mip-maps 166 * cube-maps or multi-layered textures. 167 */ 168 AHARDWAREBUFFER_FORMAT_YCbCr_P010 = 0x36, 169 170 /** 171 * Corresponding formats: 172 * Vulkan: VK_FORMAT_R8_UNORM 173 * OpenGL ES: GR_GL_R8 174 */ 175 AHARDWAREBUFFER_FORMAT_R8_UNORM = 0x38, 176 177 /** 178 * Corresponding formats: 179 * Vulkan: VK_FORMAT_R16_UINT 180 * OpenGL ES: GL_R16UI 181 */ 182 AHARDWAREBUFFER_FORMAT_R16_UINT = 0x39, 183 184 /** 185 * Corresponding formats: 186 * Vulkan: VK_FORMAT_R16G16_UINT 187 * OpenGL ES: GL_RG16UI 188 */ 189 AHARDWAREBUFFER_FORMAT_R16G16_UINT = 0x3a, 190 191 /** 192 * Corresponding formats: 193 * Vulkan: VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16 194 * OpenGL ES: N/A 195 */ 196 AHARDWAREBUFFER_FORMAT_R10G10B10A10_UNORM = 0x3b, 197 }; 198 199 /** 200 * Buffer usage flags, specifying how the buffer will be accessed. 201 */ 202 enum AHardwareBuffer_UsageFlags { 203 /** 204 * The buffer will never be locked for direct CPU reads using the 205 * AHardwareBuffer_lock() function. Note that reading the buffer 206 * using OpenGL or Vulkan functions or memory mappings is still 207 * allowed. 208 */ 209 AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL, 210 /** 211 * The buffer will sometimes be locked for direct CPU reads using 212 * the AHardwareBuffer_lock() function. Note that reading the 213 * buffer using OpenGL or Vulkan functions or memory mappings 214 * does not require the presence of this flag. 215 */ 216 AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL, 217 /** 218 * The buffer will often be locked for direct CPU reads using 219 * the AHardwareBuffer_lock() function. Note that reading the 220 * buffer using OpenGL or Vulkan functions or memory mappings 221 * does not require the presence of this flag. 222 */ 223 AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL, 224 225 /** CPU read value mask. */ 226 AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL, 227 /** 228 * The buffer will never be locked for direct CPU writes using the 229 * AHardwareBuffer_lock() function. Note that writing the buffer 230 * using OpenGL or Vulkan functions or memory mappings is still 231 * allowed. 232 */ 233 AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4, 234 /** 235 * The buffer will sometimes be locked for direct CPU writes using 236 * the AHardwareBuffer_lock() function. Note that writing the 237 * buffer using OpenGL or Vulkan functions or memory mappings 238 * does not require the presence of this flag. 239 */ 240 AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4, 241 /** 242 * The buffer will often be locked for direct CPU writes using 243 * the AHardwareBuffer_lock() function. Note that writing the 244 * buffer using OpenGL or Vulkan functions or memory mappings 245 * does not require the presence of this flag. 246 */ 247 AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4, 248 /** CPU write value mask. */ 249 AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4, 250 /** The buffer will be read from by the GPU as a texture. */ 251 AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8, 252 /** The buffer will be written to by the GPU as a framebuffer attachment.*/ 253 AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER = 1UL << 9, 254 /** 255 * The buffer will be written to by the GPU as a framebuffer 256 * attachment. 257 * 258 * Note that the name of this flag is somewhat misleading: it does 259 * not imply that the buffer contains a color format. A buffer with 260 * depth or stencil format that will be used as a framebuffer 261 * attachment should also have this flag. Use the equivalent flag 262 * AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER to avoid this confusion. 263 */ 264 AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER, 265 /** 266 * The buffer will be used as a composer HAL overlay layer. 267 * 268 * This flag is currently only needed when using ASurfaceTransaction_setBuffer 269 * to set a buffer. In all other cases, the framework adds this flag 270 * internally to buffers that could be presented in a composer overlay. 271 * ASurfaceTransaction_setBuffer is special because it uses buffers allocated 272 * directly through AHardwareBuffer_allocate instead of buffers allocated 273 * by the framework. 274 */ 275 AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY = 1ULL << 11, 276 /** 277 * The buffer is protected from direct CPU access or being read by 278 * non-secure hardware, such as video encoders. 279 * 280 * This flag is incompatible with CPU read and write flags. It is 281 * mainly used when handling DRM video. Refer to the EGL extension 282 * EGL_EXT_protected_content and GL extension 283 * GL_EXT_protected_textures for more information on how these 284 * buffers are expected to behave. 285 */ 286 AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14, 287 /** The buffer will be read by a hardware video encoder. */ 288 AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16, 289 /** 290 * The buffer will be used for direct writes from sensors. 291 * When this flag is present, the format must be AHARDWAREBUFFER_FORMAT_BLOB. 292 */ 293 AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23, 294 /** 295 * The buffer will be used as a shader storage or uniform buffer object. 296 * When this flag is present, the format must be AHARDWAREBUFFER_FORMAT_BLOB. 297 */ 298 AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24, 299 /** 300 * The buffer will be used as a cube map texture. 301 * When this flag is present, the buffer must have a layer count 302 * that is a multiple of 6. Note that buffers with this flag must be 303 * bound to OpenGL textures using the extension 304 * GL_EXT_EGL_image_storage instead of GL_KHR_EGL_image. 305 */ 306 AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP = 1UL << 25, 307 /** 308 * The buffer contains a complete mipmap hierarchy. 309 * Note that buffers with this flag must be bound to OpenGL textures using 310 * the extension GL_EXT_EGL_image_storage instead of GL_KHR_EGL_image. 311 */ 312 AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE = 1UL << 26, 313 314 /** 315 * Usage: The buffer is used for front-buffer rendering. When 316 * front-buffering rendering is specified, different usages may adjust their 317 * behavior as a result. For example, when used as GPU_COLOR_OUTPUT the buffer 318 * will behave similar to a single-buffered window. When used with 319 * COMPOSER_OVERLAY, the system will try to prioritize the buffer receiving 320 * an overlay plane & avoid caching it in intermediate composition buffers. 321 */ 322 AHARDWAREBUFFER_USAGE_FRONT_BUFFER = 1UL << 32, 323 324 AHARDWAREBUFFER_USAGE_VENDOR_0 = 1ULL << 28, 325 AHARDWAREBUFFER_USAGE_VENDOR_1 = 1ULL << 29, 326 AHARDWAREBUFFER_USAGE_VENDOR_2 = 1ULL << 30, 327 AHARDWAREBUFFER_USAGE_VENDOR_3 = 1ULL << 31, 328 AHARDWAREBUFFER_USAGE_VENDOR_4 = 1ULL << 48, 329 AHARDWAREBUFFER_USAGE_VENDOR_5 = 1ULL << 49, 330 AHARDWAREBUFFER_USAGE_VENDOR_6 = 1ULL << 50, 331 AHARDWAREBUFFER_USAGE_VENDOR_7 = 1ULL << 51, 332 AHARDWAREBUFFER_USAGE_VENDOR_8 = 1ULL << 52, 333 AHARDWAREBUFFER_USAGE_VENDOR_9 = 1ULL << 53, 334 AHARDWAREBUFFER_USAGE_VENDOR_10 = 1ULL << 54, 335 AHARDWAREBUFFER_USAGE_VENDOR_11 = 1ULL << 55, 336 AHARDWAREBUFFER_USAGE_VENDOR_12 = 1ULL << 56, 337 AHARDWAREBUFFER_USAGE_VENDOR_13 = 1ULL << 57, 338 AHARDWAREBUFFER_USAGE_VENDOR_14 = 1ULL << 58, 339 AHARDWAREBUFFER_USAGE_VENDOR_15 = 1ULL << 59, 340 AHARDWAREBUFFER_USAGE_VENDOR_16 = 1ULL << 60, 341 AHARDWAREBUFFER_USAGE_VENDOR_17 = 1ULL << 61, 342 AHARDWAREBUFFER_USAGE_VENDOR_18 = 1ULL << 62, 343 AHARDWAREBUFFER_USAGE_VENDOR_19 = 1ULL << 63, 344 }; 345 346 /** 347 * Buffer description. Used for allocating new buffers and querying 348 * parameters of existing ones. 349 */ 350 typedef struct AHardwareBuffer_Desc { 351 uint32_t width; ///< Width in pixels. 352 uint32_t height; ///< Height in pixels. 353 /** 354 * Number of images in an image array. AHardwareBuffers with one 355 * layer correspond to regular 2D textures. AHardwareBuffers with 356 * more than layer correspond to texture arrays. If the layer count 357 * is a multiple of 6 and the usage flag 358 * AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP is present, the buffer is 359 * a cube map or a cube map array. 360 */ 361 uint32_t layers; 362 uint32_t format; ///< One of AHardwareBuffer_Format. 363 uint64_t usage; ///< Combination of AHardwareBuffer_UsageFlags. 364 uint32_t stride; ///< Row stride in pixels, ignored for AHardwareBuffer_allocate() 365 uint32_t rfu0; ///< Initialize to zero, reserved for future use. 366 uint64_t rfu1; ///< Initialize to zero, reserved for future use. 367 } AHardwareBuffer_Desc; 368 369 /** 370 * Holds data for a single image plane. 371 */ 372 typedef struct AHardwareBuffer_Plane { 373 void* _Nullable data; ///< Points to first byte in plane 374 uint32_t pixelStride; ///< Distance in bytes from the color channel of one pixel to the next 375 uint32_t rowStride; ///< Distance in bytes from the first value of one row of the image to 376 /// the first value of the next row. 377 } AHardwareBuffer_Plane; 378 379 /** 380 * Holds all image planes that contain the pixel data. 381 */ 382 typedef struct AHardwareBuffer_Planes { 383 uint32_t planeCount; ///< Number of distinct planes 384 AHardwareBuffer_Plane planes[4]; ///< Array of image planes 385 } AHardwareBuffer_Planes; 386 387 /** 388 * Opaque handle for a native hardware buffer. 389 */ 390 typedef struct AHardwareBuffer AHardwareBuffer; 391 392 // clang-format on 393 394 /** 395 * Allocates a buffer that matches the passed AHardwareBuffer_Desc. 396 * 397 * If allocation succeeds, the buffer can be used according to the 398 * usage flags specified in its description. If a buffer is used in ways 399 * not compatible with its usage flags, the results are undefined and 400 * may include program termination. 401 * 402 * Available since API level 26. 403 * 404 * \return 0 on success, or an error number of the allocation fails for 405 * any reason. The returned buffer has a reference count of 1. 406 */ 407 int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* _Nonnull desc, 408 AHardwareBuffer* _Nullable* _Nonnull outBuffer) __INTRODUCED_IN(26); 409 /** 410 * Acquire a reference on the given AHardwareBuffer object. 411 * 412 * This prevents the object from being deleted until the last reference 413 * is removed. 414 * 415 * Available since API level 26. 416 */ 417 void AHardwareBuffer_acquire(AHardwareBuffer* _Nonnull buffer) __INTRODUCED_IN(26); 418 419 /** 420 * Remove a reference that was previously acquired with 421 * AHardwareBuffer_acquire() or AHardwareBuffer_allocate(). 422 * 423 * Available since API level 26. 424 */ 425 void AHardwareBuffer_release(AHardwareBuffer* _Nonnull buffer) __INTRODUCED_IN(26); 426 427 /** 428 * Return a description of the AHardwareBuffer in the passed 429 * AHardwareBuffer_Desc struct. 430 * 431 * Available since API level 26. 432 */ 433 void AHardwareBuffer_describe(const AHardwareBuffer* _Nonnull buffer, 434 AHardwareBuffer_Desc* _Nonnull outDesc) __INTRODUCED_IN(26); 435 436 /** 437 * Lock the AHardwareBuffer for direct CPU access. 438 * 439 * This function can lock the buffer for either reading or writing. 440 * It may block if the hardware needs to finish rendering, if CPU caches 441 * need to be synchronized, or possibly for other implementation- 442 * specific reasons. 443 * 444 * The passed AHardwareBuffer must have one layer, otherwise the call 445 * will fail. 446 * 447 * If \a fence is not negative, it specifies a fence file descriptor on 448 * which to wait before locking the buffer. If it's negative, the caller 449 * is responsible for ensuring that writes to the buffer have completed 450 * before calling this function. Using this parameter is more efficient 451 * than waiting on the fence and then calling this function. 452 * 453 * The \a usage parameter may only specify AHARDWAREBUFFER_USAGE_CPU_*. 454 * If set, then outVirtualAddress is filled with the address of the 455 * buffer in virtual memory. The flags must also be compatible with 456 * usage flags specified at buffer creation: if a read flag is passed, 457 * the buffer must have been created with 458 * AHARDWAREBUFFER_USAGE_CPU_READ_RARELY or 459 * AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN. If a write flag is passed, it 460 * must have been created with AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY or 461 * AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN. 462 * 463 * If \a rect is not NULL, the caller promises to modify only data in 464 * the area specified by rect. If rect is NULL, the caller may modify 465 * the contents of the entire buffer. The content of the buffer outside 466 * of the specified rect is NOT modified by this call. 467 * 468 * It is legal for several different threads to lock a buffer for read 469 * access; none of the threads are blocked. 470 * 471 * Locking a buffer simultaneously for write or read/write is undefined, 472 * but will neither terminate the process nor block the caller. 473 * AHardwareBuffer_lock may return an error or leave the buffer's 474 * content in an indeterminate state. 475 * 476 * If the buffer has AHARDWAREBUFFER_FORMAT_BLOB, it is legal lock it 477 * for reading and writing in multiple threads and/or processes 478 * simultaneously, and the contents of the buffer behave like shared 479 * memory. 480 * 481 * Available since API level 26. 482 * 483 * \return 0 on success. -EINVAL if \a buffer is NULL, the usage flags 484 * are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or the buffer 485 * has more than one layer. Error number if the lock fails for any other 486 * reason. 487 */ 488 int AHardwareBuffer_lock(AHardwareBuffer* _Nonnull buffer, uint64_t usage, int32_t fence, 489 const ARect* _Nullable rect, void* _Nullable* _Nonnull outVirtualAddress) 490 __INTRODUCED_IN(26); 491 492 /** 493 * Unlock the AHardwareBuffer from direct CPU access. 494 * 495 * Must be called after all changes to the buffer are completed by the 496 * caller. If \a fence is NULL, the function will block until all work 497 * is completed. Otherwise, \a fence will be set either to a valid file 498 * descriptor or to -1. The file descriptor will become signaled once 499 * the unlocking is complete and buffer contents are updated. 500 * The caller is responsible for closing the file descriptor once it's 501 * no longer needed. The value -1 indicates that unlocking has already 502 * completed before the function returned and no further operations are 503 * necessary. 504 * 505 * Available since API level 26. 506 * 507 * \return 0 on success. -EINVAL if \a buffer is NULL. Error number if 508 * the unlock fails for any reason. 509 */ 510 int AHardwareBuffer_unlock(AHardwareBuffer* _Nonnull buffer, int32_t* _Nullable fence) 511 __INTRODUCED_IN(26); 512 513 /** 514 * Send the AHardwareBuffer to an AF_UNIX socket. 515 * 516 * Available since API level 26. 517 * 518 * \return 0 on success, -EINVAL if \a buffer is NULL, or an error 519 * number if the operation fails for any reason. 520 */ 521 int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* _Nonnull buffer, int socketFd) 522 __INTRODUCED_IN(26); 523 524 /** 525 * Receive an AHardwareBuffer from an AF_UNIX socket. 526 * 527 * Available since API level 26. 528 * 529 * \return 0 on success, -EINVAL if \a outBuffer is NULL, or an error 530 * number if the operation fails for any reason. 531 */ 532 int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, 533 AHardwareBuffer* _Nullable* _Nonnull outBuffer) 534 __INTRODUCED_IN(26); 535 536 /** 537 * Lock a potentially multi-planar AHardwareBuffer for direct CPU access. 538 * 539 * This function is similar to AHardwareBuffer_lock, but can lock multi-planar 540 * formats. The locked planes are returned in the \a outPlanes argument. Note, 541 * that multi-planar should not be confused with multi-layer images, which this 542 * locking function does not support. 543 * 544 * YUV formats are always represented by three separate planes of data, one for 545 * each color plane. The order of planes in the array is guaranteed such that 546 * plane #0 is always Y, plane #1 is always U (Cb), and plane #2 is always V 547 * (Cr). All other formats are represented by a single plane. 548 * 549 * Additional information always accompanies the buffers, describing the row 550 * stride and the pixel stride for each plane. 551 * 552 * In case the buffer cannot be locked, \a outPlanes will contain zero planes. 553 * 554 * See the AHardwareBuffer_lock documentation for all other locking semantics. 555 * 556 * Available since API level 29. 557 * 558 * \return 0 on success. -EINVAL if \a buffer is NULL, the usage flags 559 * are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or the buffer 560 * has more than one layer. Error number if the lock fails for any other 561 * reason. 562 */ 563 int AHardwareBuffer_lockPlanes(AHardwareBuffer* _Nonnull buffer, uint64_t usage, int32_t fence, 564 const ARect* _Nullable rect, 565 AHardwareBuffer_Planes* _Nonnull outPlanes) __INTRODUCED_IN(29); 566 567 /** 568 * Test whether the given format and usage flag combination is 569 * allocatable. 570 * 571 * If this function returns true, it means that a buffer with the given 572 * description can be allocated on this implementation, unless resource 573 * exhaustion occurs. If this function returns false, it means that the 574 * allocation of the given description will never succeed. 575 * 576 * The return value of this function may depend on all fields in the 577 * description, except stride, which is always ignored. For example, 578 * some implementations have implementation-defined limits on texture 579 * size and layer count. 580 * 581 * Available since API level 29. 582 * 583 * \return 1 if the format and usage flag combination is allocatable, 584 * 0 otherwise. 585 */ 586 int AHardwareBuffer_isSupported(const AHardwareBuffer_Desc* _Nonnull desc) __INTRODUCED_IN(29); 587 588 /** 589 * Lock an AHardwareBuffer for direct CPU access. 590 * 591 * This function is the same as the above lock function, but passes back 592 * additional information about the bytes per pixel and the bytes per stride 593 * of the locked buffer. If the bytes per pixel or bytes per stride are unknown 594 * or variable, or if the underlying mapper implementation does not support returning 595 * additional information, then this call will fail with INVALID_OPERATION 596 * 597 * Available since API level 29. 598 */ 599 int AHardwareBuffer_lockAndGetInfo(AHardwareBuffer* _Nonnull buffer, uint64_t usage, int32_t fence, 600 const ARect* _Nullable rect, 601 void* _Nullable* _Nonnull outVirtualAddress, 602 int32_t* _Nonnull outBytesPerPixel, 603 int32_t* _Nonnull outBytesPerStride) __INTRODUCED_IN(29); 604 605 606 /** 607 * Get the system wide unique id for an AHardwareBuffer. 608 * 609 * Available since API level 31. 610 * 611 * \return 0 on success, -EINVAL if \a buffer or \a outId is NULL, or an error number if the 612 * operation fails for any reason. 613 */ 614 int AHardwareBuffer_getId(const AHardwareBuffer* _Nonnull buffer, uint64_t* _Nonnull outId) 615 __INTRODUCED_IN(31); 616 617 __END_DECLS 618 619 #endif // ANDROID_HARDWARE_BUFFER_H 620 621 /** @} */ 622