//+build android package android foreign import android "system:android" /** * @file hardware_buffer.h * @brief API for native hardware buffers. */ /** * @defgroup AHardwareBuffer Native Hardware Buffer * * AHardwareBuffer objects represent chunks of memory that can be * accessed by various hardware components in the system. It can be * easily converted to the Java counterpart * android.hardware.HardwareBuffer and passed between processes using * Binder. All operations involving AHardwareBuffer and HardwareBuffer * are zero-copy, i.e., passing AHardwareBuffer to another process * creates a shared view of the same region of memory. * * AHardwareBuffers can be bound to EGL/OpenGL and Vulkan primitives. * For EGL, use the extension function eglGetNativeClientBufferANDROID * to obtain an EGLClientBuffer and pass it directly to * eglCreateImageKHR. Refer to the EGL extensions * EGL_ANDROID_get_native_client_buffer and * EGL_ANDROID_image_native_buffer for more information. In Vulkan, * the contents of the AHardwareBuffer can be accessed as external * memory. See the VK_ANDROID_external_memory_android_hardware_buffer * extension for details. * * @{ */ /** * Buffer pixel formats. */ AHardwareBuffer_Format :: enum u32 { /** * Corresponding formats: * Vulkan: VK_FORMAT_R8G8B8A8_UNORM * OpenGL ES: GL_RGBA8 */ R8G8B8A8_UNORM = 1, /** * 32 bits per pixel, 8 bits per channel format where alpha values are * ignored (always opaque). * Corresponding formats: * Vulkan: VK_FORMAT_R8G8B8A8_UNORM * OpenGL ES: GL_RGB8 */ R8G8B8X8_UNORM = 2, /** * Corresponding formats: * Vulkan: VK_FORMAT_R8G8B8_UNORM * OpenGL ES: GL_RGB8 */ R8G8B8_UNORM = 3, /** * Corresponding formats: * Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16 * OpenGL ES: GL_RGB565 */ R5G6B5_UNORM = 4, /** * Corresponding formats: * Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT * OpenGL ES: GL_RGBA16F */ R16G16B16A16_FLOAT = 0x16, /** * Corresponding formats: * Vulkan: VK_FORMAT_A2B10G10R10_UNORM_PACK32 * OpenGL ES: GL_RGB10_A2 */ R10G10B10A2_UNORM = 0x2b, /** * Opaque binary blob format. * Must have height 1 and one layer, with width equal to the buffer * size in bytes. Corresponds to Vulkan buffers and OpenGL buffer * objects. Can be bound to the latter using GL_EXT_external_buffer. */ BLOB = 0x21, /** * Corresponding formats: * Vulkan: VK_FORMAT_D16_UNORM * OpenGL ES: GL_DEPTH_COMPONENT16 */ D16_UNORM = 0x30, /** * Corresponding formats: * Vulkan: VK_FORMAT_X8_D24_UNORM_PACK32 * OpenGL ES: GL_DEPTH_COMPONENT24 */ D24_UNORM = 0x31, /** * Corresponding formats: * Vulkan: VK_FORMAT_D24_UNORM_S8_UINT * OpenGL ES: GL_DEPTH24_STENCIL8 */ D24_UNORM_S8_UINT = 0x32, /** * Corresponding formats: * Vulkan: VK_FORMAT_D32_SFLOAT * OpenGL ES: GL_DEPTH_COMPONENT32F */ D32_FLOAT = 0x33, /** * Corresponding formats: * Vulkan: VK_FORMAT_D32_SFLOAT_S8_UINT * OpenGL ES: GL_DEPTH32F_STENCIL8 */ D32_FLOAT_S8_UINT = 0x34, /** * Corresponding formats: * Vulkan: VK_FORMAT_S8_UINT * OpenGL ES: GL_STENCIL_INDEX8 */ S8_UINT = 0x35, /** * YUV 420 888 format. * Must have an even width and height. Can be accessed in OpenGL * shaders through an external sampler. Does not support mip-maps * cube-maps or multi-layered textures. */ Y8Cb8Cr8_420 = 0x23, /** * YUV P010 format. * Must have an even width and height. Can be accessed in OpenGL * shaders through an external sampler. Does not support mip-maps * cube-maps or multi-layered textures. */ YCbCr_P010 = 0x36, /** * Corresponding formats: * Vulkan: VK_FORMAT_R8_UNORM * OpenGL ES: GR_GL_R8 */ R8_UNORM = 0x38, /** * Corresponding formats: * Vulkan: VK_FORMAT_R16_UINT * OpenGL ES: GL_R16UI */ R16_UINT = 0x39, /** * Corresponding formats: * Vulkan: VK_FORMAT_R16G16_UINT * OpenGL ES: GL_RG16UI */ R16G16_UINT = 0x3a, /** * Corresponding formats: * Vulkan: VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16 * OpenGL ES: N/A */ R10G10B10A10_UNORM = 0x3b, } /** * Buffer usage flags, specifying how the buffer will be accessed. */ AHardwareBuffer_UsageFlags :: enum u64 { /** * 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. */ CPU_READ_NEVER = 0, /** * 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. */ CPU_READ_RARELY = 2, /** * 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. */ CPU_READ_OFTEN = 3, /** CPU read value mask. */ CPU_READ_MASK = 0xF, /** * 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. */ CPU_WRITE_NEVER = 0 << 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. */ CPU_WRITE_RARELY = 2 << 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. */ CPU_WRITE_OFTEN = 3 << 4, /** CPU write value mask. */ CPU_WRITE_MASK = 0xF << 4, /** The buffer will be read from by the GPU as a texture. */ GPU_SAMPLED_IMAGE = 1 << 8, /** The buffer will be written to by the GPU as a framebuffer attachment.*/ GPU_FRAMEBUFFER = 1 << 9, /** * The buffer will be written to by the GPU as a framebuffer * attachment. * * Note that the name of this flag is somewhat misleading: it does * not imply that the buffer contains a color format. A buffer with * depth or stencil format that will be used as a framebuffer * attachment should also have this flag. Use the equivalent flag * AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER to avoid this confusion. */ GPU_COLOR_OUTPUT = GPU_FRAMEBUFFER, /** * The buffer will be used as a composer HAL overlay layer. * * This flag is currently only needed when using ASurfaceTransaction_setBuffer * to set a buffer. In all other cases, the framework adds this flag * internally to buffers that could be presented in a composer overlay. * ASurfaceTransaction_setBuffer is special because it uses buffers allocated * directly through AHardwareBuffer_allocate instead of buffers allocated * by the framework. */ COMPOSER_OVERLAY = 1 << 11, /** * The buffer is protected from direct CPU access or being read by * non-secure hardware, such as video encoders. * * This flag is incompatible with CPU read and write flags. It is * mainly used when handling DRM video. Refer to the EGL extension * EGL_EXT_protected_content and GL extension * GL_EXT_protected_textures for more information on how these * buffers are expected to behave. */ PROTECTED_CONTENT = 1 << 14, /** The buffer will be read by a hardware video encoder. */ VIDEO_ENCODE = 1 << 16, /** * The buffer will be used for direct writes from sensors. * When this flag is present, the format must be AHARDWAREBUFFER_FORMAT_BLOB. */ SENSOR_DIRECT_DATA = 1 << 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. */ GPU_DATA_BUFFER = 1 << 24, /** * The buffer will be used as a cube map texture. * When this flag is present, the buffer must have a layer count * that is a multiple of 6. 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. */ GPU_CUBE_MAP = 1 << 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. */ GPU_MIPMAP_COMPLETE = 1 << 26, /** * Usage: The buffer is used for front-buffer rendering. When * front-buffering rendering is specified, different usages may adjust their * behavior as a result. For example, when used as GPU_COLOR_OUTPUT the buffer * will behave similar to a single-buffered window. When used with * COMPOSER_OVERLAY, the system will try to prioritize the buffer receiving * an overlay plane & avoid caching it in intermediate composition buffers. */ FRONT_BUFFER = 1 << 32, VENDOR_0 = 1 << 28, VENDOR_1 = 1 << 29, VENDOR_2 = 1 << 30, VENDOR_3 = 1 << 31, VENDOR_4 = 1 << 48, VENDOR_5 = 1 << 49, VENDOR_6 = 1 << 50, VENDOR_7 = 1 << 51, VENDOR_8 = 1 << 52, VENDOR_9 = 1 << 53, VENDOR_10 = 1 << 54, VENDOR_11 = 1 << 55, VENDOR_12 = 1 << 56, VENDOR_13 = 1 << 57, VENDOR_14 = 1 << 58, VENDOR_15 = 1 << 59, VENDOR_16 = 1 << 60, VENDOR_17 = 1 << 61, VENDOR_18 = 1 << 62, VENDOR_19 = 1 << 63, } /** * Buffer description. Used for allocating new buffers and querying * parameters of existing ones. */ AHardwareBuffer_Desc :: struct { width: u32, ///< Width in pixels. height: u32, ///< Height in pixels. /** * Number of images in an image array. AHardwareBuffers with one * layer correspond to regular 2D textures. AHardwareBuffers with * more than layer correspond to texture arrays. If the layer count * is a multiple of 6 and the usage flag * AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP is present, the buffer is * a cube map or a cube map array. */ layers: u32, format: AHardwareBuffer_Format, ///< One of AHardwareBuffer_Format. usage: AHardwareBuffer_UsageFlags, ///< Combination of AHardwareBuffer_UsageFlags. stride: u32, ///< Row stride in pixels, ignored for AHardwareBuffer_allocate() rfu0: u32, ///< Initialize to zero, reserved for future use. rfu1: u64, ///< Initialize to zero, reserved for future use. } /** * Holds data for a single image plane. */ AHardwareBuffer_Plane :: struct { data: rawptr, ///< Points to first byte in plane pixelStride: u32, ///< Distance in bytes from the color channel of one pixel to the next rowStride: u32, ///< Distance in bytes from the first value of one row of the image to /// the first value of the next row. } /** * Holds all image planes that contain the pixel data. */ AHardwareBuffer_Planes :: struct { planeCount: u32, ///< Number of distinct planes planes: [4]AHardwareBuffer_Plane, ///< Array of image planes } /** * Opaque handle for a native hardware buffer. */ AHardwareBuffer :: struct{} foreign android { /** * Allocates a buffer that matches the passed AHardwareBuffer_Desc. * * If allocation succeeds, the buffer can be used according to the * usage flags specified in its description. If a buffer is used in ways * not compatible with its usage flags, the results are undefined and * may include program termination. * * Available since API level 26. * * \return 0 on success, or an error number of the allocation fails for * any reason. The returned buffer has a reference count of 1. */ AHardwareBuffer_allocate :: proc(desc: ^AHardwareBuffer_Desc, outBuffer: ^^AHardwareBuffer) -> i32 --- /** * Acquire a reference on the given AHardwareBuffer object. * * This prevents the object from being deleted until the last reference * is removed. * * Available since API level 26. */ AHardwareBuffer_acquire :: proc(buffer: ^AHardwareBuffer) --- /** * Remove a reference that was previously acquired with * AHardwareBuffer_acquire() or AHardwareBuffer_allocate(). * * Available since API level 26. */ AHardwareBuffer_release :: proc(buffer: ^AHardwareBuffer) --- /** * Return a description of the AHardwareBuffer in the passed * AHardwareBuffer_Desc struct. * * Available since API level 26. */ AHardwareBuffer_describe :: proc(buffer: ^AHardwareBuffer, outDesc: ^AHardwareBuffer_Desc) --- /** * Lock the AHardwareBuffer for direct CPU access. * * This function can lock the buffer for either reading or writing. * It may block if the hardware needs to finish rendering, if CPU caches * need to be synchronized, or possibly for other implementation- * specific reasons. * * The passed AHardwareBuffer must have one layer, otherwise the call * will fail. * * If \a fence is not negative, it specifies a fence file descriptor on * which to wait before locking the buffer. If it's negative, the caller * is responsible for ensuring that writes to the buffer have completed * before calling this function. Using this parameter is more efficient * than waiting on the fence and then calling this function. * * The \a usage parameter may only specify AHARDWAREBUFFER_USAGE_CPU_*. * If set, then outVirtualAddress is filled with the address of the * buffer in virtual memory. The flags must also be compatible with * usage flags specified at buffer creation: if a read flag is passed, * the buffer must have been created with * AHARDWAREBUFFER_USAGE_CPU_READ_RARELY or * AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN. If a write flag is passed, it * must have been created with AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY or * AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN. * * If \a 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. * * 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 in an indeterminate state. * * If the buffer has AHARDWAREBUFFER_FORMAT_BLOB, it is legal lock it * for reading and writing in multiple threads and/or processes * simultaneously, and the contents of the buffer behave like shared * memory. * * Available since API level 26. * * \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. */ AHardwareBuffer_lock :: proc(buffer: ^AHardwareBuffer, usage: AHardwareBuffer_UsageFlags, fence: i32, rect: ^ARect, outVirtualAddress: ^rawptr) -> i32 --- /** * Unlock the AHardwareBuffer from direct CPU access. * * Must be called after all changes to the buffer are completed by the * caller. If \a fence is NULL, the function will block until all work * is completed. Otherwise, \a fence will be set either to a valid file * descriptor or to -1. The file descriptor will become signaled once * the unlocking is complete and buffer contents are updated. * The caller is responsible for closing the file descriptor once it's * no longer needed. The value -1 indicates that unlocking has already * completed before the function returned and no further operations are * necessary. * * Available since API level 26. * * \return 0 on success. -EINVAL if \a buffer is NULL. Error number if * the unlock fails for any reason. */ AHardwareBuffer_unlock :: proc(buffer: ^AHardwareBuffer, fence: ^i32) -> i32 --- /** * Send the AHardwareBuffer to an AF_UNIX socket. * * Available since API level 26. * * \return 0 on success, -EINVAL if \a buffer is NULL, or an error * number if the operation fails for any reason. */ AHardwareBuffer_sendHandleToUnixSocket :: proc(buffer: ^AHardwareBuffer, socketFd: i32) -> i32 --- /** * Receive an AHardwareBuffer from an AF_UNIX socket. * * Available since API level 26. * * \return 0 on success, -EINVAL if \a outBuffer is NULL, or an error * number if the operation fails for any reason. */ AHardwareBuffer_recvHandleFromUnixSocket :: proc(socketFd: i32, outBuffer: ^^AHardwareBuffer) -> i32 --- /** * 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. */ AHardwareBuffer_lockPlanes :: proc(buffer: ^AHardwareBuffer, usage: AHardwareBuffer_UsageFlags, fence: i32, rect: ^ARect, outPlanes: ^AHardwareBuffer_Planes) -> i32 --- /** * Test whether the given format and usage flag combination is * allocatable. * * If this function returns true, it means that a buffer with the given * description can be allocated on this implementation, unless resource * exhaustion occurs. If this function returns false, it means that the * allocation of the given description will never succeed. * * The return value of this function may depend on all fields in the * description, except stride, which is always ignored. For example, * some implementations have implementation-defined limits on texture * size and layer count. * * Available since API level 29. * * \return 1 if the format and usage flag combination is allocatable, * 0 otherwise. */ AHardwareBuffer_isSupported :: proc(desc: ^AHardwareBuffer_Desc) -> i32 --- /** * Lock an AHardwareBuffer for direct CPU access. * * This function is the same as the above lock function, but passes back * additional information about the bytes per pixel and the bytes per stride * of the locked buffer. If the bytes per pixel or bytes per stride are unknown * or variable, or if the underlying mapper implementation does not support returning * additional information, then this call will fail with INVALID_OPERATION * * Available since API level 29. */ AHardwareBuffer_lockAndGetInfo :: proc(buffer: ^AHardwareBuffer, usage: AHardwareBuffer_UsageFlags, fence: i32, rect: ^ARect, outVirtualAddress: ^rawptr, outBytesPerPixel: ^i32, outBytesPerStride: ^i32) -> i32 --- /** * 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. */ AHardwareBuffer_getId :: proc(buffer: ^AHardwareBuffer, outId: ^u64) -> i32 --- }