/* * Copyright 2017 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @file hardware_buffer.h */ #ifndef ANDROID_HARDWARE_BUFFER_H #define ANDROID_HARDWARE_BUFFER_H #include #include #include __BEGIN_DECLS /** * Buffer pixel formats. */ enum { /** * Corresponding formats: * Vulkan: VK_FORMAT_R8G8B8A8_UNORM * OpenGL ES: GL_RGBA8 */ AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM = 1, /** * Corresponding formats: * Vulkan: VK_FORMAT_R8G8B8A8_UNORM * OpenGL ES: GL_RGBA8 */ AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM = 2, /** * Corresponding formats: * Vulkan: VK_FORMAT_R8G8B8_UNORM * OpenGL ES: GL_RGB8 */ AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM = 3, /** * Corresponding formats: * Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16 * OpenGL ES: GL_RGB565 */ AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM = 4, /** * Corresponding formats: * Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT * OpenGL ES: GL_RGBA16F */ AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT = 0x16, /** * Corresponding formats: * Vulkan: VK_FORMAT_A2B10G10R10_UNORM_PACK32 * OpenGL ES: GL_RGB10_A2 */ AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM = 0x2b, /** * An opaque binary blob format that must have height 1, with width equal to * the buffer size in bytes. */ AHARDWAREBUFFER_FORMAT_BLOB = 0x21, }; enum { /* The buffer will never be read by the CPU */ AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL, /* The buffer will sometimes be read by the CPU */ AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL, /* The buffer will often be read by the CPU */ AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL, /* CPU read value mask */ AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL, /* The buffer will never be written by the CPU */ AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4, /* The buffer will sometimes be written to by the CPU */ AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4, /* The buffer will often be written to by the CPU */ AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4, /* CPU write value mask */ AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4, /* The buffer will be read from by the GPU */ AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8, /* The buffer will be written to by the GPU */ AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = 1UL << 9, /* The buffer must not be used outside of a protected hardware path */ AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14, /* The buffer will be read by a hardware video encoder */ AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16, /** The buffer will be used for sensor direct data */ AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23, /* The buffer will be used as a shader storage or uniform buffer object*/ AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24, AHARDWAREBUFFER_USAGE_VENDOR_0 = 1ULL << 28, AHARDWAREBUFFER_USAGE_VENDOR_1 = 1ULL << 29, AHARDWAREBUFFER_USAGE_VENDOR_2 = 1ULL << 30, AHARDWAREBUFFER_USAGE_VENDOR_3 = 1ULL << 31, AHARDWAREBUFFER_USAGE_VENDOR_4 = 1ULL << 48, AHARDWAREBUFFER_USAGE_VENDOR_5 = 1ULL << 49, AHARDWAREBUFFER_USAGE_VENDOR_6 = 1ULL << 50, AHARDWAREBUFFER_USAGE_VENDOR_7 = 1ULL << 51, AHARDWAREBUFFER_USAGE_VENDOR_8 = 1ULL << 52, AHARDWAREBUFFER_USAGE_VENDOR_9 = 1ULL << 53, AHARDWAREBUFFER_USAGE_VENDOR_10 = 1ULL << 54, AHARDWAREBUFFER_USAGE_VENDOR_11 = 1ULL << 55, AHARDWAREBUFFER_USAGE_VENDOR_12 = 1ULL << 56, AHARDWAREBUFFER_USAGE_VENDOR_13 = 1ULL << 57, AHARDWAREBUFFER_USAGE_VENDOR_14 = 1ULL << 58, AHARDWAREBUFFER_USAGE_VENDOR_15 = 1ULL << 59, AHARDWAREBUFFER_USAGE_VENDOR_16 = 1ULL << 60, AHARDWAREBUFFER_USAGE_VENDOR_17 = 1ULL << 61, AHARDWAREBUFFER_USAGE_VENDOR_18 = 1ULL << 62, AHARDWAREBUFFER_USAGE_VENDOR_19 = 1ULL << 63, }; typedef struct AHardwareBuffer_Desc { uint32_t width; // width in pixels uint32_t height; // height in pixels uint32_t layers; // number of images uint32_t format; // One of AHARDWAREBUFFER_FORMAT_* uint64_t usage; // Combination of AHARDWAREBUFFER_USAGE_* uint32_t stride; // Stride in pixels, ignored for AHardwareBuffer_allocate() uint32_t rfu0; // Initialize to zero, reserved for future use uint64_t rfu1; // Initialize to zero, reserved for future use } AHardwareBuffer_Desc; typedef struct AHardwareBuffer AHardwareBuffer; /** * Allocates a buffer that backs an AHardwareBuffer using the passed * AHardwareBuffer_Desc. * * Returns NO_ERROR on success, or an error number of the allocation fails for * any reason. */ int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* desc, AHardwareBuffer** outBuffer); /** * Acquire a reference on the given AHardwareBuffer object. This prevents the * object from being deleted until the last reference is removed. */ void AHardwareBuffer_acquire(AHardwareBuffer* buffer); /** * Remove a reference that was previously acquired with * AHardwareBuffer_acquire(). */ void AHardwareBuffer_release(AHardwareBuffer* buffer); /** * Return a description of the AHardwareBuffer in the passed * AHardwareBuffer_Desc struct. */ void AHardwareBuffer_describe(const AHardwareBuffer* buffer, AHardwareBuffer_Desc* outDesc); /* * Lock the AHardwareBuffer for reading or writing, depending on the usage flags * passed. This call may block if the hardware needs to finish rendering or if * CPU caches need to be synchronized, or possibly for other implementation- * specific reasons. If fence is not negative, then it specifies a fence file * descriptor that will be signaled when the buffer is locked, otherwise the * caller will block until the buffer is available. * * If rect is not NULL, the caller promises to modify only data in the area * specified by rect. If rect is NULL, the caller may modify the contents of the * entire buffer. * * The content of the buffer outside of the specified rect is NOT modified * by this call. * * The buffer usage may only specify AHARDWAREBUFFER_USAGE_CPU_*. If set, then * outVirtualAddress is filled with the address of the buffer in virtual memory, * otherwise this function will fail. * * THREADING CONSIDERATIONS: * * It is legal for several different threads to lock a buffer for read access; * none of the threads are blocked. * * Locking a buffer simultaneously for write or read/write is undefined, but * will neither terminate the process nor block the caller; AHardwareBuffer_lock * may return an error or leave the buffer's content into an indeterminate * state. * * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL or if the usage * flags are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or an error * number of the lock fails for any reason. */ int AHardwareBuffer_lock(AHardwareBuffer* buffer, uint64_t usage, int32_t fence, const ARect* rect, void** outVirtualAddress); /* * Unlock the AHardwareBuffer; must be called after all changes to the buffer * are completed by the caller. If fence is not NULL then it will be set to a * file descriptor that is signaled when all pending work on the buffer is * completed. The caller is responsible for closing the fence when it is no * longer needed. * * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error * number of the lock fails for any reason. */ int AHardwareBuffer_unlock(AHardwareBuffer* buffer, int32_t* fence); /* * Send the AHardwareBuffer to an AF_UNIX socket. * * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error * number of the lock fails for any reason. */ int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* buffer, int socketFd); /* * Receive the AHardwareBuffer from an AF_UNIX socket. * * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error * number of the lock fails for any reason. */ int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer** outBuffer); __END_DECLS #endif // ANDROID_HARDWARE_BUFFER_H