diff options
Diffstat (limited to 'libs/nativewindow/include/android/hardware_buffer.h')
| -rw-r--r-- | libs/nativewindow/include/android/hardware_buffer.h | 239 |
1 files changed, 107 insertions, 132 deletions
diff --git a/libs/nativewindow/include/android/hardware_buffer.h b/libs/nativewindow/include/android/hardware_buffer.h index d93a84cd25..ae5e47ba97 100644 --- a/libs/nativewindow/include/android/hardware_buffer.h +++ b/libs/nativewindow/include/android/hardware_buffer.h @@ -45,13 +45,13 @@ #ifndef ANDROID_HARDWARE_BUFFER_H #define ANDROID_HARDWARE_BUFFER_H -#include <android/rect.h> #include <inttypes.h> + #include <sys/cdefs.h> -__BEGIN_DECLS +#include <android/rect.h> -// clang-format off +__BEGIN_DECLS /** * Buffer pixel formats. @@ -164,57 +164,46 @@ enum AHardwareBuffer_Format { * Buffer usage flags, specifying how the buffer will be accessed. */ enum AHardwareBuffer_UsageFlags { - /** - * The buffer will never be locked for direct CPU reads using the - * AHardwareBuffer_lock() function. Note that reading the buffer - * using OpenGL or Vulkan functions or memory mappings is still - * allowed. - */ + /// The buffer will never be locked for direct CPU reads using the + /// AHardwareBuffer_lock() function. Note that reading the buffer + /// using OpenGL or Vulkan functions or memory mappings is still + /// allowed. AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL, - /** - * The buffer will sometimes be locked for direct CPU reads using - * the AHardwareBuffer_lock() function. Note that reading the - * buffer using OpenGL or Vulkan functions or memory mappings - * does not require the presence of this flag. - */ + /// The buffer will sometimes be locked for direct CPU reads using + /// the AHardwareBuffer_lock() function. Note that reading the + /// buffer using OpenGL or Vulkan functions or memory mappings + /// does not require the presence of this flag. AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL, - /** - * The buffer will often be locked for direct CPU reads using - * the AHardwareBuffer_lock() function. Note that reading the - * buffer using OpenGL or Vulkan functions or memory mappings - * does not require the presence of this flag. - */ + /// The buffer will often be locked for direct CPU reads using + /// the AHardwareBuffer_lock() function. Note that reading the + /// buffer using OpenGL or Vulkan functions or memory mappings + /// does not require the presence of this flag. AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL, - - /** CPU read value mask. */ + /// CPU read value mask. AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL, - /** - * The buffer will never be locked for direct CPU writes using the - * AHardwareBuffer_lock() function. Note that writing the buffer - * using OpenGL or Vulkan functions or memory mappings is still - * allowed. - */ + + /// The buffer will never be locked for direct CPU writes using the + /// AHardwareBuffer_lock() function. Note that writing the buffer + /// using OpenGL or Vulkan functions or memory mappings is still + /// allowed. AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4, - /** - * The buffer will sometimes be locked for direct CPU writes using - * the AHardwareBuffer_lock() function. Note that writing the - * buffer using OpenGL or Vulkan functions or memory mappings - * does not require the presence of this flag. - */ + /// The buffer will sometimes be locked for direct CPU writes using + /// the AHardwareBuffer_lock() function. Note that writing the + /// buffer using OpenGL or Vulkan functions or memory mappings + /// does not require the presence of this flag. AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4, - /** - * The buffer will often be locked for direct CPU writes using - * the AHardwareBuffer_lock() function. Note that writing the - * buffer using OpenGL or Vulkan functions or memory mappings - * does not require the presence of this flag. - */ + /// The buffer will often be locked for direct CPU writes using + /// the AHardwareBuffer_lock() function. Note that writing the + /// buffer using OpenGL or Vulkan functions or memory mappings + /// does not require the presence of this flag. AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4, - /** CPU write value mask. */ + /// CPU write value mask. AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4, - /** The buffer will be read from by the GPU as a texture. */ - AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8, - /** The buffer will be written to by the GPU as a framebuffer attachment.*/ - AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER = 1UL << 9, + + /// The buffer will be read from by the GPU as a texture. + AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8, + /// The buffer will be written to by the GPU as a framebuffer attachment. + AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER = 1UL << 9, /** * The buffer will be written to by the GPU as a framebuffer * attachment. @@ -225,7 +214,7 @@ enum AHardwareBuffer_UsageFlags { * attachment should also have this flag. Use the equivalent flag * AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER to avoid this confusion. */ - AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER, + AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER, /** * The buffer will be used as a composer HAL overlay layer. * @@ -236,7 +225,7 @@ enum AHardwareBuffer_UsageFlags { * directly through AHardwareBuffer_allocate instead of buffers allocated * by the framework. */ - AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY = 1ULL << 11, + AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY = 1ULL << 11, /** * The buffer is protected from direct CPU access or being read by * non-secure hardware, such as video encoders. @@ -247,19 +236,19 @@ enum AHardwareBuffer_UsageFlags { * GL_EXT_protected_textures for more information on how these * buffers are expected to behave. */ - AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14, - /** The buffer will be read by a hardware video encoder. */ - AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16, + 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 direct writes from sensors. * When this flag is present, the format must be AHARDWAREBUFFER_FORMAT_BLOB. */ - AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23, + AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23, /** * The buffer will be used as a shader storage or uniform buffer object. * When this flag is present, the format must be AHARDWAREBUFFER_FORMAT_BLOB. */ - AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24, + AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24, /** * The buffer will be used as a cube map texture. * When this flag is present, the buffer must have a layer count @@ -267,13 +256,13 @@ enum AHardwareBuffer_UsageFlags { * bound to OpenGL textures using the extension * GL_EXT_EGL_image_storage instead of GL_KHR_EGL_image. */ - AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP = 1UL << 25, + AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP = 1UL << 25, /** * The buffer contains a complete mipmap hierarchy. * Note that buffers with this flag must be bound to OpenGL textures using * the extension GL_EXT_EGL_image_storage instead of GL_KHR_EGL_image. */ - AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE = 1UL << 26, + AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE = 1UL << 26, AHARDWAREBUFFER_USAGE_VENDOR_0 = 1ULL << 28, AHARDWAREBUFFER_USAGE_VENDOR_1 = 1ULL << 29, @@ -302,8 +291,8 @@ enum AHardwareBuffer_UsageFlags { * parameters of existing ones. */ typedef struct AHardwareBuffer_Desc { - uint32_t width; ///< Width in pixels. - uint32_t height; ///< Height in pixels. + uint32_t width; ///< Width in pixels. + uint32_t height; ///< Height in pixels. /** * Number of images in an image array. AHardwareBuffers with one * layer correspond to regular 2D textures. AHardwareBuffers with @@ -312,21 +301,21 @@ typedef struct AHardwareBuffer_Desc { * AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP is present, the buffer is * a cube map or a cube map array. */ - uint32_t layers; - uint32_t format; ///< One of AHardwareBuffer_Format. - uint64_t usage; ///< Combination of AHardwareBuffer_UsageFlags. - uint32_t stride; ///< Row 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. + uint32_t layers; + uint32_t format; ///< One of AHardwareBuffer_Format. + uint64_t usage; ///< Combination of AHardwareBuffer_UsageFlags. + uint32_t stride; ///< Row 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; /** * Holds data for a single image plane. */ typedef struct AHardwareBuffer_Plane { - void* _Nullable data; ///< Points to first byte in plane - uint32_t pixelStride; ///< Distance in bytes from the color channel of one pixel to the next - uint32_t rowStride; ///< Distance in bytes from the first value of one row of the image to + void* data; ///< Points to first byte in plane + uint32_t pixelStride; ///< Distance in bytes from the color channel of one pixel to the next + uint32_t rowStride; ///< Distance in bytes from the first value of one row of the image to /// the first value of the next row. } AHardwareBuffer_Plane; @@ -334,8 +323,8 @@ typedef struct AHardwareBuffer_Plane { * Holds all image planes that contain the pixel data. */ typedef struct AHardwareBuffer_Planes { - uint32_t planeCount; ///< Number of distinct planes - AHardwareBuffer_Plane planes[4]; ///< Array of image planes + uint32_t planeCount; ///< Number of distinct planes + AHardwareBuffer_Plane planes[4]; ///< Array of image planes } AHardwareBuffer_Planes; /** @@ -343,7 +332,7 @@ typedef struct AHardwareBuffer_Planes { */ typedef struct AHardwareBuffer AHardwareBuffer; -// clang-format on +#if __ANDROID_API__ >= 26 /** * Allocates a buffer that matches the passed AHardwareBuffer_Desc. @@ -358,8 +347,8 @@ typedef struct AHardwareBuffer AHardwareBuffer; * \return 0 on success, or an error number of the allocation fails for * any reason. The returned buffer has a reference count of 1. */ -int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* _Nonnull desc, - AHardwareBuffer* _Nullable* _Nonnull outBuffer) __INTRODUCED_IN(26); +int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* desc, + AHardwareBuffer** outBuffer) __INTRODUCED_IN(26); /** * Acquire a reference on the given AHardwareBuffer object. * @@ -368,7 +357,7 @@ int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* _Nonnull desc, * * Available since API level 26. */ -void AHardwareBuffer_acquire(AHardwareBuffer* _Nonnull buffer) __INTRODUCED_IN(26); +void AHardwareBuffer_acquire(AHardwareBuffer* buffer) __INTRODUCED_IN(26); /** * Remove a reference that was previously acquired with @@ -376,7 +365,7 @@ void AHardwareBuffer_acquire(AHardwareBuffer* _Nonnull buffer) __INTRODUCED_IN(2 * * Available since API level 26. */ -void AHardwareBuffer_release(AHardwareBuffer* _Nonnull buffer) __INTRODUCED_IN(26); +void AHardwareBuffer_release(AHardwareBuffer* buffer) __INTRODUCED_IN(26); /** * Return a description of the AHardwareBuffer in the passed @@ -384,8 +373,8 @@ void AHardwareBuffer_release(AHardwareBuffer* _Nonnull buffer) __INTRODUCED_IN(2 * * Available since API level 26. */ -void AHardwareBuffer_describe(const AHardwareBuffer* _Nonnull buffer, - AHardwareBuffer_Desc* _Nonnull outDesc) __INTRODUCED_IN(26); +void AHardwareBuffer_describe(const AHardwareBuffer* buffer, + AHardwareBuffer_Desc* outDesc) __INTRODUCED_IN(26); /** * Lock the AHardwareBuffer for direct CPU access. @@ -439,9 +428,38 @@ void AHardwareBuffer_describe(const AHardwareBuffer* _Nonnull buffer, * has more than one layer. Error number if the lock fails for any other * reason. */ -int AHardwareBuffer_lock(AHardwareBuffer* _Nonnull buffer, uint64_t usage, int32_t fence, - const ARect* _Nullable rect, void* _Nullable* _Nonnull outVirtualAddress) - __INTRODUCED_IN(26); +int AHardwareBuffer_lock(AHardwareBuffer* buffer, uint64_t usage, + int32_t fence, const ARect* rect, void** outVirtualAddress) __INTRODUCED_IN(26); + +/** + * Lock a potentially multi-planar AHardwareBuffer for direct CPU access. + * + * This function is similar to AHardwareBuffer_lock, but can lock multi-planar + * formats. The locked planes are returned in the \a outPlanes argument. Note, + * that multi-planar should not be confused with multi-layer images, which this + * locking function does not support. + * + * YUV formats are always represented by three separate planes of data, one for + * each color plane. The order of planes in the array is guaranteed such that + * plane #0 is always Y, plane #1 is always U (Cb), and plane #2 is always V + * (Cr). All other formats are represented by a single plane. + * + * Additional information always accompanies the buffers, describing the row + * stride and the pixel stride for each plane. + * + * In case the buffer cannot be locked, \a outPlanes will contain zero planes. + * + * See the AHardwareBuffer_lock documentation for all other locking semantics. + * + * Available since API level 29. + * + * \return 0 on success. -EINVAL if \a buffer is NULL, the usage flags + * are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or the buffer + * has more than one layer. Error number if the lock fails for any other + * reason. + */ +int AHardwareBuffer_lockPlanes(AHardwareBuffer* buffer, uint64_t usage, + int32_t fence, const ARect* rect, AHardwareBuffer_Planes* outPlanes) __INTRODUCED_IN(29); /** * Unlock the AHardwareBuffer from direct CPU access. @@ -461,8 +479,7 @@ int AHardwareBuffer_lock(AHardwareBuffer* _Nonnull buffer, uint64_t usage, int32 * \return 0 on success. -EINVAL if \a buffer is NULL. Error number if * the unlock fails for any reason. */ -int AHardwareBuffer_unlock(AHardwareBuffer* _Nonnull buffer, int32_t* _Nullable fence) - __INTRODUCED_IN(26); +int AHardwareBuffer_unlock(AHardwareBuffer* buffer, int32_t* fence) __INTRODUCED_IN(26); /** * Send the AHardwareBuffer to an AF_UNIX socket. @@ -472,8 +489,7 @@ int AHardwareBuffer_unlock(AHardwareBuffer* _Nonnull buffer, int32_t* _Nullable * \return 0 on success, -EINVAL if \a buffer is NULL, or an error * number if the operation fails for any reason. */ -int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* _Nonnull buffer, int socketFd) - __INTRODUCED_IN(26); +int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* buffer, int socketFd) __INTRODUCED_IN(26); /** * Receive an AHardwareBuffer from an AF_UNIX socket. @@ -483,40 +499,11 @@ int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* _Nonnull buffe * \return 0 on success, -EINVAL if \a outBuffer is NULL, or an error * number if the operation fails for any reason. */ -int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, - AHardwareBuffer* _Nullable* _Nonnull outBuffer) - __INTRODUCED_IN(26); +int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer** outBuffer) __INTRODUCED_IN(26); -/** - * Lock a potentially multi-planar AHardwareBuffer for direct CPU access. - * - * This function is similar to AHardwareBuffer_lock, but can lock multi-planar - * formats. The locked planes are returned in the \a outPlanes argument. Note, - * that multi-planar should not be confused with multi-layer images, which this - * locking function does not support. - * - * YUV formats are always represented by three separate planes of data, one for - * each color plane. The order of planes in the array is guaranteed such that - * plane #0 is always Y, plane #1 is always U (Cb), and plane #2 is always V - * (Cr). All other formats are represented by a single plane. - * - * Additional information always accompanies the buffers, describing the row - * stride and the pixel stride for each plane. - * - * In case the buffer cannot be locked, \a outPlanes will contain zero planes. - * - * See the AHardwareBuffer_lock documentation for all other locking semantics. - * - * Available since API level 29. - * - * \return 0 on success. -EINVAL if \a buffer is NULL, the usage flags - * are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or the buffer - * has more than one layer. Error number if the lock fails for any other - * reason. - */ -int AHardwareBuffer_lockPlanes(AHardwareBuffer* _Nonnull buffer, uint64_t usage, int32_t fence, - const ARect* _Nullable rect, - AHardwareBuffer_Planes* _Nonnull outPlanes) __INTRODUCED_IN(29); +#endif // __ANDROID_API__ >= 26 + +#if __ANDROID_API__ >= 29 /** * Test whether the given format and usage flag combination is @@ -537,7 +524,7 @@ int AHardwareBuffer_lockPlanes(AHardwareBuffer* _Nonnull buffer, uint64_t usage, * \return 1 if the format and usage flag combination is allocatable, * 0 otherwise. */ -int AHardwareBuffer_isSupported(const AHardwareBuffer_Desc* _Nonnull desc) __INTRODUCED_IN(29); +int AHardwareBuffer_isSupported(const AHardwareBuffer_Desc* desc) __INTRODUCED_IN(29); /** * Lock an AHardwareBuffer for direct CPU access. @@ -550,22 +537,10 @@ int AHardwareBuffer_isSupported(const AHardwareBuffer_Desc* _Nonnull desc) __INT * * Available since API level 29. */ -int AHardwareBuffer_lockAndGetInfo(AHardwareBuffer* _Nonnull buffer, uint64_t usage, int32_t fence, - const ARect* _Nullable rect, - void* _Nullable* _Nonnull outVirtualAddress, - int32_t* _Nonnull outBytesPerPixel, - int32_t* _Nonnull outBytesPerStride) __INTRODUCED_IN(29); - -/** - * Get the system wide unique id for an AHardwareBuffer. - * - * Available since API level 31. - * - * \return 0 on success, -EINVAL if \a buffer or \a outId is NULL, or an error number if the - * operation fails for any reason. - */ -int AHardwareBuffer_getId(const AHardwareBuffer* _Nonnull buffer, uint64_t* _Nonnull outId) - __INTRODUCED_IN(31); +int AHardwareBuffer_lockAndGetInfo(AHardwareBuffer* buffer, uint64_t usage, + int32_t fence, const ARect* rect, void** outVirtualAddress, + int32_t* outBytesPerPixel, int32_t* outBytesPerStride) __INTRODUCED_IN(29); +#endif // __ANDROID_API__ >= 29 __END_DECLS |