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 */ 20 21 #ifndef ANDROID_HARDWARE_BUFFER_H 22 #define ANDROID_HARDWARE_BUFFER_H 23 24 #include <inttypes.h> 25 26 #include <sys/cdefs.h> 27 28 #include <android/rect.h> 29 30 __BEGIN_DECLS 31 32 /** 33 * Buffer pixel formats. 34 */ 35 enum { 36 /** 37 * Corresponding formats: 38 * Vulkan: VK_FORMAT_R8G8B8A8_UNORM 39 * OpenGL ES: GL_RGBA8 40 */ 41 AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM = 1, 42 43 /** 44 * 32 bits per pixel, 8 bits per channel format where alpha values are 45 * ignored (always opaque). 46 * Corresponding formats: 47 * Vulkan: VK_FORMAT_R8G8B8A8_UNORM 48 * OpenGL ES: GL_RGB8 49 */ 50 AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM = 2, 51 52 /** 53 * Corresponding formats: 54 * Vulkan: VK_FORMAT_R8G8B8_UNORM 55 * OpenGL ES: GL_RGB8 56 */ 57 AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM = 3, 58 59 /** 60 * Corresponding formats: 61 * Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16 62 * OpenGL ES: GL_RGB565 63 */ 64 AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM = 4, 65 66 /** 67 * Corresponding formats: 68 * Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT 69 * OpenGL ES: GL_RGBA16F 70 */ 71 AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT = 0x16, 72 73 /** 74 * Corresponding formats: 75 * Vulkan: VK_FORMAT_A2B10G10R10_UNORM_PACK32 76 * OpenGL ES: GL_RGB10_A2 77 */ 78 AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM = 0x2b, 79 80 /** 81 * An opaque binary blob format that must have height 1, with width equal to 82 * the buffer size in bytes. 83 */ 84 AHARDWAREBUFFER_FORMAT_BLOB = 0x21, 85 86 /** 87 * Corresponding formats: 88 * Vulkan: VK_FORMAT_D16_UNORM 89 * OpenGL ES: GL_DEPTH_COMPONENT16 90 */ 91 AHARDWAREBUFFER_FORMAT_D16_UNORM = 0x30, 92 93 /** 94 * Corresponding formats: 95 * Vulkan: VK_FORMAT_X8_D24_UNORM_PACK32 96 * OpenGL ES: GL_DEPTH_COMPONENT24 97 */ 98 AHARDWAREBUFFER_FORMAT_D24_UNORM = 0x31, 99 100 /** 101 * Corresponding formats: 102 * Vulkan: VK_FORMAT_D24_UNORM_S8_UINT 103 * OpenGL ES: GL_DEPTH24_STENCIL8 104 */ 105 AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT = 0x32, 106 107 /** 108 * Corresponding formats: 109 * Vulkan: VK_FORMAT_D32_SFLOAT 110 * OpenGL ES: GL_DEPTH_COMPONENT32F 111 */ 112 AHARDWAREBUFFER_FORMAT_D32_FLOAT = 0x33, 113 114 /** 115 * Corresponding formats: 116 * Vulkan: VK_FORMAT_D32_SFLOAT_S8_UINT 117 * OpenGL ES: GL_DEPTH32F_STENCIL8 118 */ 119 AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT = 0x34, 120 121 /** 122 * Corresponding formats: 123 * Vulkan: VK_FORMAT_S8_UINT 124 * OpenGL ES: GL_STENCIL_INDEX8 125 */ 126 AHARDWAREBUFFER_FORMAT_S8_UINT = 0x35, 127 }; 128 129 /** 130 * Buffer usage flags, specifying how the buffer will be accessed. 131 */ 132 enum { 133 /// The buffer will never be read by the CPU. 134 AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL, 135 /// The buffer will sometimes be read by the CPU. 136 AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL, 137 /// The buffer will often be read by the CPU. 138 AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL, 139 /// CPU read value mask. 140 AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL, 141 142 /// The buffer will never be written by the CPU. 143 AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4, 144 /// The buffer will sometimes be written to by the CPU. 145 AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4, 146 /// The buffer will often be written to by the CPU. 147 AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4, 148 /// CPU write value mask. 149 AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4, 150 151 /// The buffer will be read from by the GPU as a texture. 152 AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8, 153 /** 154 * The buffer will be written to by the GPU as a framebuffer attachment. 155 * Note that the name of this flag is somewhat misleading: it does not imply 156 * that the buffer contains a color format. A buffer with depth or stencil 157 * format that will be used as a framebuffer attachment should also have 158 * this flag. 159 */ 160 AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = 1UL << 9, 161 /// The buffer must not be used outside of a protected hardware path. 162 AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14, 163 /// The buffer will be read by a hardware video encoder. 164 AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16, 165 /// The buffer will be used for direct writes from sensors. 166 AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23, 167 /// The buffer will be used as a shader storage or uniform buffer object. 168 AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24, 169 /// The buffer will be used as a cube map texture. 170 AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP = 1UL << 25, 171 /// The buffer contains a complete mipmap hierarchy. 172 AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE = 1UL << 26, 173 174 AHARDWAREBUFFER_USAGE_VENDOR_0 = 1ULL << 28, 175 AHARDWAREBUFFER_USAGE_VENDOR_1 = 1ULL << 29, 176 AHARDWAREBUFFER_USAGE_VENDOR_2 = 1ULL << 30, 177 AHARDWAREBUFFER_USAGE_VENDOR_3 = 1ULL << 31, 178 AHARDWAREBUFFER_USAGE_VENDOR_4 = 1ULL << 48, 179 AHARDWAREBUFFER_USAGE_VENDOR_5 = 1ULL << 49, 180 AHARDWAREBUFFER_USAGE_VENDOR_6 = 1ULL << 50, 181 AHARDWAREBUFFER_USAGE_VENDOR_7 = 1ULL << 51, 182 AHARDWAREBUFFER_USAGE_VENDOR_8 = 1ULL << 52, 183 AHARDWAREBUFFER_USAGE_VENDOR_9 = 1ULL << 53, 184 AHARDWAREBUFFER_USAGE_VENDOR_10 = 1ULL << 54, 185 AHARDWAREBUFFER_USAGE_VENDOR_11 = 1ULL << 55, 186 AHARDWAREBUFFER_USAGE_VENDOR_12 = 1ULL << 56, 187 AHARDWAREBUFFER_USAGE_VENDOR_13 = 1ULL << 57, 188 AHARDWAREBUFFER_USAGE_VENDOR_14 = 1ULL << 58, 189 AHARDWAREBUFFER_USAGE_VENDOR_15 = 1ULL << 59, 190 AHARDWAREBUFFER_USAGE_VENDOR_16 = 1ULL << 60, 191 AHARDWAREBUFFER_USAGE_VENDOR_17 = 1ULL << 61, 192 AHARDWAREBUFFER_USAGE_VENDOR_18 = 1ULL << 62, 193 AHARDWAREBUFFER_USAGE_VENDOR_19 = 1ULL << 63, 194 }; 195 196 /** 197 * Buffer description. Used for allocating new buffers and querying parameters 198 * of existing ones. 199 */ 200 typedef struct AHardwareBuffer_Desc { 201 uint32_t width; ///< Width in pixels. 202 uint32_t height; ///< Height in pixels. 203 uint32_t layers; ///< Number of images in an image array. 204 uint32_t format; ///< One of AHARDWAREBUFFER_FORMAT_* 205 uint64_t usage; ///< Combination of AHARDWAREBUFFER_USAGE_* 206 uint32_t stride; ///< Row stride in pixels, ignored for AHardwareBuffer_allocate() 207 uint32_t rfu0; ///< Initialize to zero, reserved for future use. 208 uint64_t rfu1; ///< Initialize to zero, reserved for future use. 209 } AHardwareBuffer_Desc; 210 211 typedef struct AHardwareBuffer AHardwareBuffer; 212 213 /** 214 * Allocates a buffer that backs an AHardwareBuffer using the passed 215 * AHardwareBuffer_Desc. 216 * 217 * \return 0 on success, or an error number of the allocation fails for 218 * any reason. The returned buffer has a reference count of 1. 219 */ 220 int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* desc, 221 AHardwareBuffer** outBuffer); 222 /** 223 * Acquire a reference on the given AHardwareBuffer object. This prevents the 224 * object from being deleted until the last reference is removed. 225 */ 226 void AHardwareBuffer_acquire(AHardwareBuffer* buffer); 227 228 /** 229 * Remove a reference that was previously acquired with 230 * AHardwareBuffer_acquire(). 231 */ 232 void AHardwareBuffer_release(AHardwareBuffer* buffer); 233 234 /** 235 * Return a description of the AHardwareBuffer in the passed 236 * AHardwareBuffer_Desc struct. 237 */ 238 void AHardwareBuffer_describe(const AHardwareBuffer* buffer, 239 AHardwareBuffer_Desc* outDesc); 240 241 /** 242 * Lock the AHardwareBuffer for reading or writing, depending on the usage flags 243 * passed. This call may block if the hardware needs to finish rendering or if 244 * CPU caches need to be synchronized, or possibly for other implementation- 245 * specific reasons. If fence is not negative, then it specifies a fence file 246 * descriptor that will be signaled when the buffer is locked, otherwise the 247 * caller will block until the buffer is available. 248 * 249 * If \a rect is not NULL, the caller promises to modify only data in the area 250 * specified by rect. If rect is NULL, the caller may modify the contents of the 251 * entire buffer. 252 * 253 * The content of the buffer outside of the specified rect is NOT modified 254 * by this call. 255 * 256 * The \a usage parameter may only specify AHARDWAREBUFFER_USAGE_CPU_*. If set, 257 * then outVirtualAddress is filled with the address of the buffer in virtual 258 * memory. 259 * 260 * THREADING CONSIDERATIONS: 261 * 262 * It is legal for several different threads to lock a buffer for read access; 263 * none of the threads are blocked. 264 * 265 * Locking a buffer simultaneously for write or read/write is undefined, but 266 * will neither terminate the process nor block the caller; AHardwareBuffer_lock 267 * may return an error or leave the buffer's content into an indeterminate 268 * state. 269 * 270 * \return 0 on success, -EINVAL if \a buffer is NULL or if the usage 271 * flags are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or an error 272 * number of the lock fails for any reason. 273 */ 274 int AHardwareBuffer_lock(AHardwareBuffer* buffer, uint64_t usage, 275 int32_t fence, const ARect* rect, void** outVirtualAddress); 276 277 /** 278 * Unlock the AHardwareBuffer; must be called after all changes to the buffer 279 * are completed by the caller. If fence is not NULL then it will be set to a 280 * file descriptor that is signaled when all pending work on the buffer is 281 * completed. The caller is responsible for closing the fence when it is no 282 * longer needed. 283 * 284 * \return 0 on success, -EINVAL if \a buffer is NULL, or an error 285 * number if the unlock fails for any reason. 286 */ 287 int AHardwareBuffer_unlock(AHardwareBuffer* buffer, int32_t* fence); 288 289 /** 290 * Send the AHardwareBuffer to an AF_UNIX socket. 291 * 292 * \return 0 on success, -EINVAL if \a buffer is NULL, or an error 293 * number if the operation fails for any reason. 294 */ 295 int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* buffer, int socketFd); 296 297 /** 298 * Receive the AHardwareBuffer from an AF_UNIX socket. 299 * 300 * \return 0 on success, -EINVAL if \a outBuffer is NULL, or an error 301 * number if the operation fails for any reason. 302 */ 303 int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer** outBuffer); 304 305 __END_DECLS 306 307 #endif // ANDROID_HARDWARE_BUFFER_H 308