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