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 * @file hardware_buffer.h 18 * @brief API for native hardware buffers. 19 */ 20 /** 21 * @defgroup AHardwareBuffer Native Hardware Buffer 22 * 23 * AHardwareBuffer objects represent chunks of memory that can be 24 * accessed by various hardware components in the system. It can be 25 * easily converted to the Java counterpart 26 * android.hardware.HardwareBuffer and passed between processes using 27 * Binder. All operations involving AHardwareBuffer and HardwareBuffer 28 * are zero-copy, i.e., passing AHardwareBuffer to another process 29 * creates a shared view of the same region of memory. 30 * 31 * AHardwareBuffers can be bound to EGL/OpenGL and Vulkan primitives. 32 * For EGL, use the extension function eglGetNativeClientBufferANDROID 33 * to obtain an EGLClientBuffer and pass it directly to 34 * eglCreateImageKHR. Refer to the EGL extensions 35 * EGL_ANDROID_get_native_client_buffer and 36 * EGL_ANDROID_image_native_buffer for more information. In Vulkan, 37 * the contents of the AHardwareBuffer can be accessed as external 38 * memory. See the VK_ANDROID_external_memory_android_hardware_buffer 39 * extension for details. 40 * 41 * @{ 42 */ 43 #ifndef ANDROID_HARDWARE_BUFFER_H 44 #define ANDROID_HARDWARE_BUFFER_H 45 #include <inttypes.h> 46 #include <sys/cdefs.h> 47 #include <android/rect.h> 48 #include <android/versioning.h> 49 __BEGIN_DECLS 50 /** 51 * Buffer pixel formats. 52 */ 53 enum AHardwareBuffer_Format { 54 /** 55 * Corresponding formats: 56 * Vulkan: VK_FORMAT_R8G8B8A8_UNORM 57 * OpenGL ES: GL_RGBA8 58 */ 59 AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM = 1, 60 /** 61 * 32 bits per pixel, 8 bits per channel format where alpha values are 62 * ignored (always opaque). 63 * Corresponding formats: 64 * Vulkan: VK_FORMAT_R8G8B8A8_UNORM 65 * OpenGL ES: GL_RGB8 66 */ 67 AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM = 2, 68 /** 69 * Corresponding formats: 70 * Vulkan: VK_FORMAT_R8G8B8_UNORM 71 * OpenGL ES: GL_RGB8 72 */ 73 AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM = 3, 74 /** 75 * Corresponding formats: 76 * Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16 77 * OpenGL ES: GL_RGB565 78 */ 79 AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM = 4, 80 /** 81 * Corresponding formats: 82 * Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT 83 * OpenGL ES: GL_RGBA16F 84 */ 85 AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT = 0x16, 86 /** 87 * Corresponding formats: 88 * Vulkan: VK_FORMAT_A2B10G10R10_UNORM_PACK32 89 * OpenGL ES: GL_RGB10_A2 90 */ 91 AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM = 0x2b, 92 /** 93 * Opaque binary blob format. 94 * Must have height 1 and one layer, with width equal to the buffer 95 * size in bytes. Corresponds to Vulkan buffers and OpenGL buffer 96 * objects. Can be bound to the latter using GL_EXT_external_buffer. 97 */ 98 AHARDWAREBUFFER_FORMAT_BLOB = 0x21, 99 /** 100 * Corresponding formats: 101 * Vulkan: VK_FORMAT_D16_UNORM 102 * OpenGL ES: GL_DEPTH_COMPONENT16 103 */ 104 AHARDWAREBUFFER_FORMAT_D16_UNORM = 0x30, 105 /** 106 * Corresponding formats: 107 * Vulkan: VK_FORMAT_X8_D24_UNORM_PACK32 108 * OpenGL ES: GL_DEPTH_COMPONENT24 109 */ 110 AHARDWAREBUFFER_FORMAT_D24_UNORM = 0x31, 111 /** 112 * Corresponding formats: 113 * Vulkan: VK_FORMAT_D24_UNORM_S8_UINT 114 * OpenGL ES: GL_DEPTH24_STENCIL8 115 */ 116 AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT = 0x32, 117 /** 118 * Corresponding formats: 119 * Vulkan: VK_FORMAT_D32_SFLOAT 120 * OpenGL ES: GL_DEPTH_COMPONENT32F 121 */ 122 AHARDWAREBUFFER_FORMAT_D32_FLOAT = 0x33, 123 /** 124 * Corresponding formats: 125 * Vulkan: VK_FORMAT_D32_SFLOAT_S8_UINT 126 * OpenGL ES: GL_DEPTH32F_STENCIL8 127 */ 128 AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT = 0x34, 129 /** 130 * Corresponding formats: 131 * Vulkan: VK_FORMAT_S8_UINT 132 * OpenGL ES: GL_STENCIL_INDEX8 133 */ 134 AHARDWAREBUFFER_FORMAT_S8_UINT = 0x35, 135 }; 136 /** 137 * Buffer usage flags, specifying how the buffer will be accessed. 138 */ 139 enum AHardwareBuffer_UsageFlags { 140 /// The buffer will never be locked for direct CPU reads using the 141 /// AHardwareBuffer_lock() function. Note that reading the buffer 142 /// using OpenGL or Vulkan functions or memory mappings is still 143 /// allowed. 144 AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL, 145 /// The buffer will sometimes be locked for direct CPU reads using 146 /// the AHardwareBuffer_lock() function. Note that reading the 147 /// buffer using OpenGL or Vulkan functions or memory mappings 148 /// does not require the presence of this flag. 149 AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL, 150 /// The buffer will often be locked for direct CPU reads using 151 /// the AHardwareBuffer_lock() function. Note that reading the 152 /// buffer using OpenGL or Vulkan functions or memory mappings 153 /// does not require the presence of this flag. 154 AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL, 155 /// CPU read value mask. 156 AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL, 157 /// The buffer will never be locked for direct CPU writes using the 158 /// AHardwareBuffer_lock() function. Note that writing the buffer 159 /// using OpenGL or Vulkan functions or memory mappings is still 160 /// allowed. 161 AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4, 162 /// The buffer will sometimes be locked for direct CPU writes using 163 /// the AHardwareBuffer_lock() function. Note that writing the 164 /// buffer using OpenGL or Vulkan functions or memory mappings 165 /// does not require the presence of this flag. 166 AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4, 167 /// The buffer will often be locked for direct CPU writes using 168 /// the AHardwareBuffer_lock() function. Note that writing the 169 /// buffer using OpenGL or Vulkan functions or memory mappings 170 /// does not require the presence of this flag. 171 AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4, 172 /// CPU write value mask. 173 AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4, 174 /// The buffer will be read from by the GPU as a texture. 175 AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8, 176 /** 177 * The buffer will be written to by the GPU as a framebuffer 178 * attachment. 179 * 180 * Note that the name of this flag is somewhat misleading: it does 181 * not imply that the buffer contains a color format. A buffer with 182 * depth or stencil format that will be used as a framebuffer 183 * attachment should also have this flag. 184 */ 185 AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = 1UL << 9, 186 /** 187 * The buffer is protected from direct CPU access or being read by 188 * non-secure hardware, such as video encoders. 189 * 190 * This flag is incompatible with CPU read and write flags. It is 191 * mainly used when handling DRM video. Refer to the EGL extension 192 * EGL_EXT_protected_content and GL extension 193 * GL_EXT_protected_textures for more information on how these 194 * buffers are expected to behave. 195 */ 196 AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14, 197 /// The buffer will be read by a hardware video encoder. 198 AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16, 199 /** 200 * The buffer will be used for direct writes from sensors. 201 * When this flag is present, the format must be AHARDWAREBUFFER_FORMAT_BLOB. 202 */ 203 AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23, 204 /** 205 * The buffer will be used as a shader storage or uniform buffer object. 206 * When this flag is present, the format must be AHARDWAREBUFFER_FORMAT_BLOB. 207 */ 208 AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24, 209 /** 210 * The buffer will be used as a cube map texture. 211 * When this flag is present, the buffer must have a layer count 212 * that is a multiple of 6. Note that buffers with this flag must be 213 * bound to OpenGL textures using the extension 214 * GL_EXT_EGL_image_storage instead of GL_KHR_EGL_image. 215 */ 216 AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP = 1UL << 25, 217 /** 218 * The buffer contains a complete mipmap hierarchy. 219 * Note that buffers with this flag must be bound to OpenGL textures using 220 * the extension GL_EXT_EGL_image_storage instead of GL_KHR_EGL_image. 221 */ 222 AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE = 1UL << 26, 223 AHARDWAREBUFFER_USAGE_VENDOR_0 = 1ULL << 28, 224 AHARDWAREBUFFER_USAGE_VENDOR_1 = 1ULL << 29, 225 AHARDWAREBUFFER_USAGE_VENDOR_2 = 1ULL << 30, 226 AHARDWAREBUFFER_USAGE_VENDOR_3 = 1ULL << 31, 227 AHARDWAREBUFFER_USAGE_VENDOR_4 = 1ULL << 48, 228 AHARDWAREBUFFER_USAGE_VENDOR_5 = 1ULL << 49, 229 AHARDWAREBUFFER_USAGE_VENDOR_6 = 1ULL << 50, 230 AHARDWAREBUFFER_USAGE_VENDOR_7 = 1ULL << 51, 231 AHARDWAREBUFFER_USAGE_VENDOR_8 = 1ULL << 52, 232 AHARDWAREBUFFER_USAGE_VENDOR_9 = 1ULL << 53, 233 AHARDWAREBUFFER_USAGE_VENDOR_10 = 1ULL << 54, 234 AHARDWAREBUFFER_USAGE_VENDOR_11 = 1ULL << 55, 235 AHARDWAREBUFFER_USAGE_VENDOR_12 = 1ULL << 56, 236 AHARDWAREBUFFER_USAGE_VENDOR_13 = 1ULL << 57, 237 AHARDWAREBUFFER_USAGE_VENDOR_14 = 1ULL << 58, 238 AHARDWAREBUFFER_USAGE_VENDOR_15 = 1ULL << 59, 239 AHARDWAREBUFFER_USAGE_VENDOR_16 = 1ULL << 60, 240 AHARDWAREBUFFER_USAGE_VENDOR_17 = 1ULL << 61, 241 AHARDWAREBUFFER_USAGE_VENDOR_18 = 1ULL << 62, 242 AHARDWAREBUFFER_USAGE_VENDOR_19 = 1ULL << 63, 243 }; 244 /** 245 * Buffer description. Used for allocating new buffers and querying 246 * parameters of existing ones. 247 */ 248 typedef struct AHardwareBuffer_Desc { 249 uint32_t width; ///< Width in pixels. 250 uint32_t height; ///< Height in pixels. 251 /** 252 * Number of images in an image array. AHardwareBuffers with one 253 * layer correspond to regular 2D textures. AHardwareBuffers with 254 * more than layer correspond to texture arrays. If the layer count 255 * is a multiple of 6 and the usage flag 256 * AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP is present, the buffer is 257 * a cube map or a cube map array. 258 */ 259 uint32_t layers; 260 uint32_t format; ///< One of AHardwareBuffer_Format. 261 uint64_t usage; ///< Combination of AHardwareBuffer_UsageFlags. 262 uint32_t stride; ///< Row stride in pixels, ignored for AHardwareBuffer_allocate() 263 uint32_t rfu0; ///< Initialize to zero, reserved for future use. 264 uint64_t rfu1; ///< Initialize to zero, reserved for future use. 265 } AHardwareBuffer_Desc; 266 /** 267 * Opaque handle for a native hardware buffer. 268 */ 269 typedef struct AHardwareBuffer AHardwareBuffer; 270 #if __ANDROID_API__ >= 26 271 /** 272 * Allocates a buffer that matches the passed AHardwareBuffer_Desc. 273 * 274 * If allocation succeeds, the buffer can be used according to the 275 * usage flags specified in its description. If a buffer is used in ways 276 * not compatible with its usage flags, the results are undefined and 277 * may include program termination. 278 * 279 * \return 0 on success, or an error number of the allocation fails for 280 * any reason. The returned buffer has a reference count of 1. 281 */ 282 int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* desc, 283 AHardwareBuffer** outBuffer) __INTRODUCED_IN(26); 284 /** 285 * Acquire a reference on the given AHardwareBuffer object. 286 * 287 * This prevents the object from being deleted until the last reference 288 * is removed. 289 */ 290 void AHardwareBuffer_acquire(AHardwareBuffer* buffer) __INTRODUCED_IN(26); 291 /** 292 * Remove a reference that was previously acquired with 293 * AHardwareBuffer_acquire() or AHardwareBuffer_allocate(). 294 */ 295 void AHardwareBuffer_release(AHardwareBuffer* buffer) __INTRODUCED_IN(26); 296 /** 297 * Return a description of the AHardwareBuffer in the passed 298 * AHardwareBuffer_Desc struct. 299 */ 300 void AHardwareBuffer_describe(const AHardwareBuffer* buffer, 301 AHardwareBuffer_Desc* outDesc) __INTRODUCED_IN(26); 302 /** 303 * Lock the AHardwareBuffer for direct CPU access. 304 * 305 * This function can lock the buffer for either reading or writing. 306 * It may block if the hardware needs to finish rendering, if CPU caches 307 * need to be synchronized, or possibly for other implementation- 308 * specific reasons. 309 * 310 * The passed AHardwareBuffer must have one layer, otherwise the call 311 * will fail. 312 * 313 * If \a fence is not negative, it specifies a fence file descriptor on 314 * which to wait before locking the buffer. If it's negative, the caller 315 * is responsible for ensuring that writes to the buffer have completed 316 * before calling this function. Using this parameter is more efficient 317 * than waiting on the fence and then calling this function. 318 * 319 * The \a usage parameter may only specify AHARDWAREBUFFER_USAGE_CPU_*. 320 * If set, then outVirtualAddress is filled with the address of the 321 * buffer in virtual memory. The flags must also be compatible with 322 * usage flags specified at buffer creation: if a read flag is passed, 323 * the buffer must have been created with 324 * AHARDWAREBUFFER_USAGE_CPU_READ_RARELY or 325 * AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN. If a write flag is passed, it 326 * must have been created with AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY or 327 * AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN. 328 * 329 * If \a rect is not NULL, the caller promises to modify only data in 330 * the area specified by rect. If rect is NULL, the caller may modify 331 * the contents of the entire buffer. The content of the buffer outside 332 * of the specified rect is NOT modified by this call. 333 * 334 * It is legal for several different threads to lock a buffer for read 335 * access; none of the threads are blocked. 336 * 337 * Locking a buffer simultaneously for write or read/write is undefined, 338 * but will neither terminate the process nor block the caller. 339 * AHardwareBuffer_lock may return an error or leave the buffer's 340 * content in an indeterminate state. 341 * 342 * If the buffer has AHARDWAREBUFFER_FORMAT_BLOB, it is legal lock it 343 * for reading and writing in multiple threads and/or processes 344 * simultaneously, and the contents of the buffer behave like shared 345 * memory. 346 * 347 * \return 0 on success. -EINVAL if \a buffer is NULL, the usage flags 348 * are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or the buffer 349 * has more than one layer. Error number if the lock fails for any other 350 * reason. 351 */ 352 int AHardwareBuffer_lock(AHardwareBuffer* buffer, uint64_t usage, 353 int32_t fence, const ARect* rect, void** outVirtualAddress) __INTRODUCED_IN(26); 354 /** 355 * Unlock the AHardwareBuffer from direct CPU access. 356 * 357 * Must be called after all changes to the buffer are completed by the 358 * caller. If \a fence is NULL, the function will block until all work 359 * is completed. Otherwise, \a fence will be set either to a valid file 360 * descriptor or to -1. The file descriptor will become signaled once 361 * the unlocking is complete and buffer contents are updated. 362 * The caller is responsible for closing the file descriptor once it's 363 * no longer needed. The value -1 indicates that unlocking has already 364 * completed before the function returned and no further operations are 365 * necessary. 366 * 367 * \return 0 on success. -EINVAL if \a buffer is NULL. Error number if 368 * the unlock fails for any reason. 369 */ 370 int AHardwareBuffer_unlock(AHardwareBuffer* buffer, int32_t* fence) __INTRODUCED_IN(26); 371 /** 372 * Send the AHardwareBuffer to an AF_UNIX socket. 373 * 374 * \return 0 on success, -EINVAL if \a buffer is NULL, or an error 375 * number if the operation fails for any reason. 376 */ 377 int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* buffer, int socketFd) __INTRODUCED_IN(26); 378 /** 379 * Receive an AHardwareBuffer from an AF_UNIX socket. 380 * 381 * \return 0 on success, -EINVAL if \a outBuffer is NULL, or an error 382 * number if the operation fails for any reason. 383 */ 384 int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer** outBuffer) __INTRODUCED_IN(26); 385 #endif // __ANDROID_API__ >= 26 386 __END_DECLS 387 #endif // ANDROID_HARDWARE_BUFFER_H 388 /** @} */ 389