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 * Corresponding formats: 45 * Vulkan: VK_FORMAT_R8G8B8A8_UNORM 46 * OpenGL ES: GL_RGBA8 47 */ 48 AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM = 2, 49 50 /** 51 * Corresponding formats: 52 * Vulkan: VK_FORMAT_R8G8B8_UNORM 53 * OpenGL ES: GL_RGB8 54 */ 55 AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM = 3, 56 57 /** 58 * Corresponding formats: 59 * Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16 60 * OpenGL ES: GL_RGB565 61 */ 62 AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM = 4, 63 64 /** 65 * Corresponding formats: 66 * Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT 67 * OpenGL ES: GL_RGBA16F 68 */ 69 AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT = 0x16, 70 71 /** 72 * Corresponding formats: 73 * Vulkan: VK_FORMAT_A2B10G10R10_UNORM_PACK32 74 * OpenGL ES: GL_RGB10_A2 75 */ 76 AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM = 0x2b, 77 78 /** 79 * An opaque binary blob format that must have height 1, with width equal to 80 * the buffer size in bytes. 81 */ 82 AHARDWAREBUFFER_FORMAT_BLOB = 0x21, 83 }; 84 85 enum { 86 /* The buffer will never be read by the CPU */ 87 AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL, 88 /* The buffer will sometimes be read by the CPU */ 89 AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL, 90 /* The buffer will often be read by the CPU */ 91 AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL, 92 /* CPU read value mask */ 93 AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL, 94 95 /* The buffer will never be written by the CPU */ 96 AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4, 97 /* The buffer will sometimes be written to by the CPU */ 98 AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4, 99 /* The buffer will often be written to by the CPU */ 100 AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4, 101 /* CPU write value mask */ 102 AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4, 103 104 /* The buffer will be read from by the GPU */ 105 AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8, 106 /* The buffer will be written to by the GPU */ 107 AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = 1UL << 9, 108 /* The buffer must not be used outside of a protected hardware path */ 109 AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14, 110 /* The buffer will be read by a hardware video encoder */ 111 AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16, 112 /** The buffer will be used for sensor direct data */ 113 AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23, 114 /* The buffer will be used as a shader storage or uniform buffer object*/ 115 AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24, 116 117 AHARDWAREBUFFER_USAGE_VENDOR_0 = 1ULL << 28, 118 AHARDWAREBUFFER_USAGE_VENDOR_1 = 1ULL << 29, 119 AHARDWAREBUFFER_USAGE_VENDOR_2 = 1ULL << 30, 120 AHARDWAREBUFFER_USAGE_VENDOR_3 = 1ULL << 31, 121 AHARDWAREBUFFER_USAGE_VENDOR_4 = 1ULL << 48, 122 AHARDWAREBUFFER_USAGE_VENDOR_5 = 1ULL << 49, 123 AHARDWAREBUFFER_USAGE_VENDOR_6 = 1ULL << 50, 124 AHARDWAREBUFFER_USAGE_VENDOR_7 = 1ULL << 51, 125 AHARDWAREBUFFER_USAGE_VENDOR_8 = 1ULL << 52, 126 AHARDWAREBUFFER_USAGE_VENDOR_9 = 1ULL << 53, 127 AHARDWAREBUFFER_USAGE_VENDOR_10 = 1ULL << 54, 128 AHARDWAREBUFFER_USAGE_VENDOR_11 = 1ULL << 55, 129 AHARDWAREBUFFER_USAGE_VENDOR_12 = 1ULL << 56, 130 AHARDWAREBUFFER_USAGE_VENDOR_13 = 1ULL << 57, 131 AHARDWAREBUFFER_USAGE_VENDOR_14 = 1ULL << 58, 132 AHARDWAREBUFFER_USAGE_VENDOR_15 = 1ULL << 59, 133 AHARDWAREBUFFER_USAGE_VENDOR_16 = 1ULL << 60, 134 AHARDWAREBUFFER_USAGE_VENDOR_17 = 1ULL << 61, 135 AHARDWAREBUFFER_USAGE_VENDOR_18 = 1ULL << 62, 136 AHARDWAREBUFFER_USAGE_VENDOR_19 = 1ULL << 63, 137 }; 138 139 typedef struct AHardwareBuffer_Desc { 140 uint32_t width; // width in pixels 141 uint32_t height; // height in pixels 142 uint32_t layers; // number of images 143 uint32_t format; // One of AHARDWAREBUFFER_FORMAT_* 144 uint64_t usage; // Combination of AHARDWAREBUFFER_USAGE_* 145 uint32_t stride; // Stride in pixels, ignored for AHardwareBuffer_allocate() 146 uint32_t rfu0; // Initialize to zero, reserved for future use 147 uint64_t rfu1; // Initialize to zero, reserved for future use 148 } AHardwareBuffer_Desc; 149 150 typedef struct AHardwareBuffer AHardwareBuffer; 151 152 /** 153 * Allocates a buffer that backs an AHardwareBuffer using the passed 154 * AHardwareBuffer_Desc. 155 * 156 * Returns NO_ERROR on success, or an error number of the allocation fails for 157 * any reason. 158 */ 159 int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* desc, 160 AHardwareBuffer** outBuffer); 161 /** 162 * Acquire a reference on the given AHardwareBuffer object. This prevents the 163 * object from being deleted until the last reference is removed. 164 */ 165 void AHardwareBuffer_acquire(AHardwareBuffer* buffer); 166 167 /** 168 * Remove a reference that was previously acquired with 169 * AHardwareBuffer_acquire(). 170 */ 171 void AHardwareBuffer_release(AHardwareBuffer* buffer); 172 173 /** 174 * Return a description of the AHardwareBuffer in the passed 175 * AHardwareBuffer_Desc struct. 176 */ 177 void AHardwareBuffer_describe(const AHardwareBuffer* buffer, 178 AHardwareBuffer_Desc* outDesc); 179 180 /* 181 * Lock the AHardwareBuffer for reading or writing, depending on the usage flags 182 * passed. This call may block if the hardware needs to finish rendering or if 183 * CPU caches need to be synchronized, or possibly for other implementation- 184 * specific reasons. If fence is not negative, then it specifies a fence file 185 * descriptor that will be signaled when the buffer is locked, otherwise the 186 * caller will block until the buffer is available. 187 * 188 * If rect is not NULL, the caller promises to modify only data in the area 189 * specified by rect. If rect is NULL, the caller may modify the contents of the 190 * entire buffer. 191 * 192 * The content of the buffer outside of the specified rect is NOT modified 193 * by this call. 194 * 195 * The buffer usage may only specify AHARDWAREBUFFER_USAGE_CPU_*. If set, then 196 * outVirtualAddress is filled with the address of the buffer in virtual memory, 197 * otherwise this function will fail. 198 * 199 * THREADING CONSIDERATIONS: 200 * 201 * It is legal for several different threads to lock a buffer for read access; 202 * none of the threads are blocked. 203 * 204 * Locking a buffer simultaneously for write or read/write is undefined, but 205 * will neither terminate the process nor block the caller; AHardwareBuffer_lock 206 * may return an error or leave the buffer's content into an indeterminate 207 * state. 208 * 209 * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL or if the usage 210 * flags are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or an error 211 * number of the lock fails for any reason. 212 */ 213 int AHardwareBuffer_lock(AHardwareBuffer* buffer, uint64_t usage, 214 int32_t fence, const ARect* rect, void** outVirtualAddress); 215 216 /* 217 * Unlock the AHardwareBuffer; must be called after all changes to the buffer 218 * are completed by the caller. If fence is not NULL then it will be set to a 219 * file descriptor that is signaled when all pending work on the buffer is 220 * completed. The caller is responsible for closing the fence when it is no 221 * longer needed. 222 * 223 * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error 224 * number of the lock fails for any reason. 225 */ 226 int AHardwareBuffer_unlock(AHardwareBuffer* buffer, int32_t* fence); 227 228 /* 229 * Send the AHardwareBuffer to an AF_UNIX socket. 230 * 231 * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error 232 * number of the lock fails for any reason. 233 */ 234 int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* buffer, int socketFd); 235 236 /* 237 * Receive the AHardwareBuffer from an AF_UNIX socket. 238 * 239 * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error 240 * number of the lock fails for any reason. 241 */ 242 int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer** outBuffer); 243 244 __END_DECLS 245 246 #endif // ANDROID_HARDWARE_BUFFER_H 247