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