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