原生硬件缓冲区

AHardwareBuffer 对象表示系统中各种硬件组件可以访问的内存块。

摘要

对 AHardwareBuffer 的 Parcelable 支持。

它可以轻松转换为对应的 Java android.hardware.HardwareBuffer，并使用 Binder 在进程之间传递。所有涉及 AHardwareBuffer 和 HardwareBuffer 的操作都是零拷贝的，即，将 AHardwareBuffer 传递给另一个进程会创建同一内存区域的共享视图。

AHardwareBuffer 可以绑定到 EGL/OpenGL 和 Vulkan 原语。对于 EGL，使用扩展函数 eglGetNativeClientBufferANDROID 获取 EGLClientBuffer 并直接将其传递给 eglCreateImageKHR。有关更多信息，请参阅 EGL 扩展 EGL_ANDROID_get_native_client_buffer 和 EGL_ANDROID_image_native_buffer。在 Vulkan 中，AHardwareBuffer 的内容可以作为外部内存访问。有关详细信息，请参阅 VK_ANDROID_external_memory_android_hardware_buffer 扩展。

可与 libbinder_ndk 一起使用

枚举
AHardwareBuffer_Format{ AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM = 1, AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM = 2, AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM = 3, AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM = 4, AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT = 0x16, AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM = 0x2b, AHARDWAREBUFFER_FORMAT_BLOB = 0x21, AHARDWAREBUFFER_FORMAT_D16_UNORM = 0x30, AHARDWAREBUFFER_FORMAT_D24_UNORM = 0x31, AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT = 0x32, AHARDWAREBUFFER_FORMAT_D32_FLOAT = 0x33, AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT = 0x34, AHARDWAREBUFFER_FORMAT_S8_UINT = 0x35, AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420 = 0x23, AHARDWAREBUFFER_FORMAT_YCbCr_P010 = 0x36, AHARDWAREBUFFER_FORMAT_YCbCr_P210 = 0x3c, AHARDWAREBUFFER_FORMAT_R8_UNORM = 0x38, AHARDWAREBUFFER_FORMAT_R16_UINT = 0x39, AHARDWAREBUFFER_FORMAT_R16G16_UINT = 0x3a, AHARDWAREBUFFER_FORMAT_R10G10B10A10_UNORM = 0x3b }	enum 缓冲区像素格式。
AHardwareBuffer_UsageFlags{ AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL, AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL, AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL, AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL, AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4, AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4, AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4, AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4, AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8, AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER = 1UL << 9, AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER, AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY = 1ULL << 11, AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14, AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16, AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23, AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24, AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP = 1UL << 25, AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE = 1UL << 26, AHARDWAREBUFFER_USAGE_FRONT_BUFFER = 1ULL << 32, 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 }	enum 缓冲区使用标记，指定如何访问缓冲区。

枚举

AHardwareBuffer_Format{
  AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM = 1,
  AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM = 2,
  AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM = 3,
  AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM = 4,
  AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT = 0x16,
  AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM = 0x2b,
  AHARDWAREBUFFER_FORMAT_BLOB = 0x21,
  AHARDWAREBUFFER_FORMAT_D16_UNORM = 0x30,
  AHARDWAREBUFFER_FORMAT_D24_UNORM = 0x31,
  AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT = 0x32,
  AHARDWAREBUFFER_FORMAT_D32_FLOAT = 0x33,
  AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT = 0x34,
  AHARDWAREBUFFER_FORMAT_S8_UINT = 0x35,
  AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420 = 0x23,
  AHARDWAREBUFFER_FORMAT_YCbCr_P010 = 0x36,
  AHARDWAREBUFFER_FORMAT_YCbCr_P210 = 0x3c,
  AHARDWAREBUFFER_FORMAT_R8_UNORM = 0x38,
  AHARDWAREBUFFER_FORMAT_R16_UINT = 0x39,
  AHARDWAREBUFFER_FORMAT_R16G16_UINT = 0x3a,
  AHARDWAREBUFFER_FORMAT_R10G10B10A10_UNORM = 0x3b
}

enum

缓冲区像素格式。

AHardwareBuffer_UsageFlags{
  AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL,
  AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL,
  AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL,
  AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL,
  AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4,
  AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4,
  AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4,
  AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4,
  AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8,
  AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER = 1UL << 9,
  AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER,
  AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY = 1ULL << 11,
  AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14,
  AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16,
  AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23,
  AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24,
  AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP = 1UL << 25,
  AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE = 1UL << 26,
  AHARDWAREBUFFER_USAGE_FRONT_BUFFER = 1ULL << 32,
  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
}

enum

缓冲区使用标记，指定如何访问缓冲区。

Typedefs
`AHardwareBuffer`	typedef `struct AHardwareBuffer` 原生硬件缓冲区的不透明句柄。
`AHardwareBuffer_Desc`	typedef `struct AHardwareBuffer_Desc` 缓冲区描述。
`AHardwareBuffer_Plane`	typedef `struct AHardwareBuffer_Plane` 包含单个图像平面数据。
`AHardwareBuffer_Planes`	typedef `struct AHardwareBuffer_Planes` 包含所有包含像素数据的图像平面。

函数
`AHardwareBuffer_acquire(AHardwareBuffer *_Nonnull buffer)`	`void` 获取给定 AHardwareBuffer 对象的引用。
`AHardwareBuffer_allocate(const AHardwareBuffer_Desc _Nonnull desc, AHardwareBuffer _Nullable *_Nonnull outBuffer)`	`int` 分配一个与传入的 AHardwareBuffer_Desc 匹配的缓冲区。
`AHardwareBuffer_describe(const AHardwareBuffer _Nonnull buffer, AHardwareBuffer_Desc _Nonnull outDesc)`	`void` 在传入的 AHardwareBuffer_Desc 结构体中返回 AHardwareBuffer 的描述。
`AHardwareBuffer_fromHardwareBuffer(JNIEnv *env, jobject hardwareBufferObj)`	`AHardwareBuffer *` 返回由 Java HardwareBuffer 对象封装的 AHardwareBuffer。
`AHardwareBuffer_getId(const AHardwareBuffer _Nonnull buffer, uint64_t _Nonnull outId)`	`int` 获取 AHardwareBuffer 的系统范围唯一 ID。
`AHardwareBuffer_isSupported(const AHardwareBuffer_Desc *_Nonnull desc)`	`int` 测试给定的格式和使用标记组合是否可分配。
`AHardwareBuffer_lock(AHardwareBuffer _Nonnull buffer, uint64_t usage, int32_t fence, const ARect _Nullable rect, void _Nullable _Nonnull outVirtualAddress)`	`int` 锁定 AHardwareBuffer 以供 CPU 直接访问。
`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)`	`int` 锁定 AHardwareBuffer 以供 CPU 直接访问。
`AHardwareBuffer_lockPlanes(AHardwareBuffer _Nonnull buffer, uint64_t usage, int32_t fence, const ARect _Nullable rect, AHardwareBuffer_Planes *_Nonnull outPlanes)`	`int` 锁定潜在的多平面 AHardwareBuffer 以供 CPU 直接访问。
`AHardwareBuffer_readFromParcel(const AParcel _Nonnull parcel, AHardwareBuffer _Nullable *_Nonnull outBuffer)`	`binder_status_t` 从 AParcel 读取 AHardwareBuffer。
`AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer _Nullable _Nonnull outBuffer)`	`int` 从 AF_UNIX 套接字接收 AHardwareBuffer。
`AHardwareBuffer_release(AHardwareBuffer *_Nonnull buffer)`	`void` 移除之前通过 AHardwareBuffer_acquire() 或 AHardwareBuffer_allocate() 获取的引用。
`AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer *_Nonnull buffer, int socketFd)`	`int` 将 AHardwareBuffer 发送到 AF_UNIX 套接字。
`AHardwareBuffer_toHardwareBuffer(JNIEnv env, AHardwareBuffer hardwareBuffer)`	`jobject` 返回一个新的 Java HardwareBuffer 对象，该对象封装了传入的原生 AHardwareBuffer 对象。
`AHardwareBuffer_unlock(AHardwareBuffer _Nonnull buffer, int32_t _Nullable fence)`	`int` 解锁 AHardwareBuffer，不再允许 CPU 直接访问。
`AHardwareBuffer_writeToParcel(const AHardwareBuffer _Nonnull buffer, AParcel _Nonnull parcel)`	`binder_status_t` 将 AHardwareBuffer 写入 AParcel。

结构体
AHardwareBuffer_Desc	缓冲区描述。
AHardwareBuffer_Plane	包含单个图像平面数据。
AHardwareBuffer_Planes	包含所有包含像素数据的图像平面。

枚举

AHardwareBuffer_Format

声明于 android/hardware_buffer.h

 AHardwareBuffer_Format

缓冲区像素格式。

属性
`AHARDWAREBUFFER_FORMAT_BLOB`	不透明二进制 blob 格式。高度必须为 1，层数必须为 1，宽度等于缓冲区大小（以字节为单位）。对应于 Vulkan 缓冲区和 OpenGL 缓冲区对象。可以使用 GL_EXT_external_buffer 将其绑定到后者。
`AHARDWAREBUFFER_FORMAT_D16_UNORM`	对应的格式：Vulkan: VK_FORMAT_D16_UNORM OpenGL ES: GL_DEPTH_COMPONENT16。
`AHARDWAREBUFFER_FORMAT_D24_UNORM`	对应的格式：Vulkan: VK_FORMAT_X8_D24_UNORM_PACK32 OpenGL ES: GL_DEPTH_COMPONENT24。
`AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT`	对应的格式：Vulkan: VK_FORMAT_D24_UNORM_S8_UINT OpenGL ES: GL_DEPTH24_STENCIL8。
`AHARDWAREBUFFER_FORMAT_D32_FLOAT`	对应的格式：Vulkan: VK_FORMAT_D32_SFLOAT OpenGL ES: GL_DEPTH_COMPONENT32F。
`AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT`	对应的格式：Vulkan: VK_FORMAT_D32_SFLOAT_S8_UINT OpenGL ES: GL_DEPTH32F_STENCIL8。
`AHARDWAREBUFFER_FORMAT_R10G10B10A10_UNORM`	对应的格式：Vulkan: VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16 OpenGL ES: 不适用。
`AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM`	对应的格式：Vulkan: VK_FORMAT_A2B10G10R10_UNORM_PACK32 OpenGL ES: GL_RGB10_A2。
`AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT`	对应的格式：Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT OpenGL ES: GL_RGBA16F。
`AHARDWAREBUFFER_FORMAT_R16G16_UINT`	对应的格式：Vulkan: VK_FORMAT_R16G16_UINT OpenGL ES: GL_RG16UI。
`AHARDWAREBUFFER_FORMAT_R16_UINT`	对应的格式：Vulkan: VK_FORMAT_R16_UINT OpenGL ES: GL_R16UI。
`AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM`	对应的格式：Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16 OpenGL ES: GL_RGB565。
`AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM`	对应的格式：Vulkan: VK_FORMAT_R8G8B8A8_UNORM OpenGL ES: GL_RGBA8。
`AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM`	每像素 32 位，每通道 8 位格式，其中 alpha 值被忽略（始终不透明）。对应的格式：Vulkan: VK_FORMAT_R8G8B8A8_UNORM OpenGL ES: GL_RGB8
`AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM`	对应的格式：Vulkan: VK_FORMAT_R8G8B8_UNORM OpenGL ES: GL_RGB8。
`AHARDWAREBUFFER_FORMAT_R8_UNORM`	对应的格式：Vulkan: VK_FORMAT_R8_UNORM OpenGL ES: GR_GL_R8。
`AHARDWAREBUFFER_FORMAT_S8_UINT`	对应的格式：Vulkan: VK_FORMAT_S8_UINT OpenGL ES: GL_STENCIL_INDEX8。
`AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420`	YUV 420 888 格式。宽度和高度必须为偶数。可以通过外部采样器在 OpenGL 着色器中访问。不支持 mipmap、立方体贴图或多层纹理。
`AHARDWAREBUFFER_FORMAT_YCbCr_P010`	YUV P010 格式。宽度和高度必须为偶数。可以通过外部采样器在 OpenGL 着色器中访问。不支持 mipmap、立方体贴图或多层纹理。
`AHARDWAREBUFFER_FORMAT_YCbCr_P210`	YUV P210 格式。宽度和高度必须为偶数。可以通过外部采样器在 OpenGL 着色器中访问。不支持 mipmap、立方体贴图或多层纹理。

AHardwareBuffer_UsageFlags

声明于 android/hardware_buffer.h

 AHardwareBuffer_UsageFlags

缓冲区使用标记，指定如何访问缓冲区。

属性
`AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY`	缓冲区将用作合成器 HAL 叠加层。当前仅在使用 ASurfaceTransaction_setBuffer 设置缓冲区时才需要此标记。在所有其他情况下，框架会在内部为可以在合成器叠加层中呈现的缓冲区添加此标记。ASurfaceTransaction_setBuffer 之所以特殊，是因为它直接通过 AHardwareBuffer_allocate 分配缓冲区，而不是使用框架分配的缓冲区。
`AHARDWAREBUFFER_USAGE_CPU_READ_MASK`	CPU 读取值掩码。
`AHARDWAREBUFFER_USAGE_CPU_READ_NEVER`	缓冲区将永远不会使用 AHardwareBuffer_lock() 函数锁定以供 CPU 直接读取。请注意，仍然允许使用 OpenGL 或 Vulkan 函数或内存映射读取缓冲区。
`AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN`	缓冲区通常会使用 AHardwareBuffer_lock() 函数锁定以供 CPU 直接读取。请注意，使用 OpenGL 或 Vulkan 函数或内存映射读取缓冲区不需要此标记存在。
`AHARDWAREBUFFER_USAGE_CPU_READ_RARELY`	缓冲区有时会使用 AHardwareBuffer_lock() 函数锁定以供 CPU 直接读取。请注意，使用 OpenGL 或 Vulkan 函数或内存映射读取缓冲区不需要此标记存在。
`AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK`	CPU 写入值掩码。
`AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER`	缓冲区将永远不会使用 AHardwareBuffer_lock() 函数锁定以供 CPU 直接写入。请注意，仍然允许使用 OpenGL 或 Vulkan 函数或内存映射写入缓冲区。
`AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN`	缓冲区通常会使用 AHardwareBuffer_lock() 函数锁定以供 CPU 直接写入。请注意，使用 OpenGL 或 Vulkan 函数或内存映射写入缓冲区不需要此标记存在。
`AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY`	缓冲区有时会使用 AHardwareBuffer_lock() 函数锁定以供 CPU 直接写入。请注意，使用 OpenGL 或 Vulkan 函数或内存映射写入缓冲区不需要此标记存在。
`AHARDWAREBUFFER_USAGE_FRONT_BUFFER`	用途：缓冲区用于前缓冲区渲染。指定前缓冲区渲染时，不同的用法可能会相应地调整其行为。例如，当用作 GPU_COLOR_OUTPUT 时，缓冲区将 behaves 类似于单缓冲窗口。与 COMPOSER_OVERLAY 一起使用时，系统将尝试优先处理接收叠加层平面的缓冲区，并避免将其缓存在中间合成缓冲区中。
`AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT`	缓冲区将由 GPU 作为帧缓冲区附件写入。请注意，此标记的名称有些误导：它并不意味着缓冲区包含颜色格式。将用作帧缓冲区附件的深度或模板格式的缓冲区也应具有此标记。使用等效标记 AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER 以避免混淆。
`AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP`	缓冲区将用作立方体贴图纹理。存在此标记时，缓冲区的层数必须是 6 的倍数。请注意，具有此标记的缓冲区必须使用扩展 GL_EXT_EGL_image_storage 绑定到 OpenGL 纹理，而不是 GL_KHR_EGL_image。
`AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER`	缓冲区将用作着色器存储或 uniform 缓冲区对象。存在此标记时，格式必须为 AHARDWAREBUFFER_FORMAT_BLOB。
`AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER`	缓冲区将由 GPU 作为帧缓冲区附件写入。
`AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE`	缓冲区包含完整的 mipmap 层次结构。请注意，具有此标记的缓冲区必须使用扩展 GL_EXT_EGL_image_storage 绑定到 OpenGL 纹理，而不是 GL_KHR_EGL_image。
`AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE`	缓冲区将由 GPU 作为纹理读取。
`AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT`	缓冲区受到保护，无法被 CPU 直接访问或被非安全硬件（例如视频编码器）读取。此标记与 CPU 读写标记不兼容。它主要用于处理 DRM 视频。有关这些缓冲区的预期行为的更多信息，请参阅 EGL 扩展 EGL_EXT_protected_content 和 GL 扩展 GL_EXT_protected_textures。
`AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA`	缓冲区将用于传感器直接写入。存在此标记时，格式必须为 AHARDWAREBUFFER_FORMAT_BLOB。
`AHARDWAREBUFFER_USAGE_VENDOR_0`
`AHARDWAREBUFFER_USAGE_VENDOR_1`
`AHARDWAREBUFFER_USAGE_VENDOR_10`
`AHARDWAREBUFFER_USAGE_VENDOR_11`
`AHARDWAREBUFFER_USAGE_VENDOR_12`
`AHARDWAREBUFFER_USAGE_VENDOR_13`
`AHARDWAREBUFFER_USAGE_VENDOR_14`
`AHARDWAREBUFFER_USAGE_VENDOR_15`
`AHARDWAREBUFFER_USAGE_VENDOR_16`
`AHARDWAREBUFFER_USAGE_VENDOR_17`
`AHARDWAREBUFFER_USAGE_VENDOR_18`
`AHARDWAREBUFFER_USAGE_VENDOR_19`
`AHARDWAREBUFFER_USAGE_VENDOR_2`
`AHARDWAREBUFFER_USAGE_VENDOR_3`
`AHARDWAREBUFFER_USAGE_VENDOR_4`
`AHARDWAREBUFFER_USAGE_VENDOR_5`
`AHARDWAREBUFFER_USAGE_VENDOR_6`
`AHARDWAREBUFFER_USAGE_VENDOR_7`
`AHARDWAREBUFFER_USAGE_VENDOR_8`
`AHARDWAREBUFFER_USAGE_VENDOR_9`
`AHARDWAREBUFFER_USAGE_VIDEO_ENCODE`	缓冲区将由硬件视频编码器读取。

Typedefs

AHardwareBuffer

声明于 android/hardware_buffer.h

struct AHardwareBuffer AHardwareBuffer

原生硬件缓冲区的不透明句柄。

AHardwareBuffer_Desc

声明于 android/hardware_buffer.h

struct AHardwareBuffer_Desc AHardwareBuffer_Desc

缓冲区描述。

用于分配新缓冲区和查询现有缓冲区的参数。

AHardwareBuffer_Plane

声明于 android/hardware_buffer.h

struct AHardwareBuffer_Plane AHardwareBuffer_Plane

包含单个图像平面数据。

AHardwareBuffer_Planes

声明于 android/hardware_buffer.h

struct AHardwareBuffer_Planes AHardwareBuffer_Planes

包含所有包含像素数据的图像平面。

函数

AHardwareBuffer_acquire

声明于 android/hardware_buffer.h

void AHardwareBuffer_acquire(
  AHardwareBuffer *_Nonnull buffer
)

获取给定 AHardwareBuffer 对象的引用。

这可以防止对象在最后一个引用被移除之前被删除。

自 API 级别 26 可用。

AHardwareBuffer_allocate

声明于 android/hardware_buffer.h

int AHardwareBuffer_allocate(
  const AHardwareBuffer_Desc *_Nonnull desc,
  AHardwareBuffer *_Nullable *_Nonnull outBuffer
)

分配一个与传入的 AHardwareBuffer_Desc 匹配的缓冲区。

如果分配成功，可以根据其描述中指定的使用标记使用缓冲区。如果缓冲区的使用方式与其使用标记不兼容，则结果是未定义的，并可能导致程序终止。

自 API 级别 26 可用。

详情
返回值	成功时返回 0，如果由于任何原因分配失败，则返回错误码。返回的缓冲区引用计数为 1。

AHardwareBuffer_describe

声明于 android/hardware_buffer.h

void AHardwareBuffer_describe(
  const AHardwareBuffer *_Nonnull buffer,
  AHardwareBuffer_Desc *_Nonnull outDesc
)

在传入的 AHardwareBuffer_Desc 结构体中返回 AHardwareBuffer 的描述。

自 API 级别 26 可用。

AHardwareBuffer_fromHardwareBuffer

声明于 android/hardware_buffer_jni.h

AHardwareBuffer * AHardwareBuffer_fromHardwareBuffer(
  JNIEnv *env,
  jobject hardwareBufferObj
)

返回由 Java HardwareBuffer 对象封装的 AHardwareBuffer。

此方法不会获取返回的 AHardwareBuffer 的任何附加引用。为了在 Java HardwareBuffer 对象关闭（显式关闭或由垃圾回收器关闭）后保持 AHardwareBuffer 存活，请务必使用 AHardwareBuffer_acquire() 获取附加引用。

自 API 级别 26 可用。

AHardwareBuffer_getId

声明于 android/hardware_buffer.h

int AHardwareBuffer_getId(
  const AHardwareBuffer *_Nonnull buffer,
  uint64_t *_Nonnull outId
)

获取 AHardwareBuffer 的系统范围唯一 ID。

自 API 级别 31 可用。

详情
返回值	成功时返回 0，如果 buffer 或 outId 为 NULL，则返回 -EINVAL，如果操作因任何原因失败，则返回错误码。

AHardwareBuffer_isSupported

声明于 android/hardware_buffer.h

int AHardwareBuffer_isSupported(
  const AHardwareBuffer_Desc *_Nonnull desc
)

测试给定的格式和使用标记组合是否可分配。

如果此函数返回 true，则表示可以在此实现上分配具有给定描述的缓冲区，除非发生资源耗尽。如果此函数返回 false，则表示给定描述的分配永远不会成功。

此函数的返回值可能取决于描述中的所有字段，除了始终被忽略的 stride。例如，某些实现对纹理大小和层数有限制（由实现定义）。

自 API 级别 29 可用。

详情
返回值	如果格式和使用标记组合可分配，则返回 1，否则返回 0。

AHardwareBuffer_lock

声明于 android/hardware_buffer.h

int AHardwareBuffer_lock(
  AHardwareBuffer *_Nonnull buffer,
  uint64_t usage,
  int32_t fence,
  const ARect *_Nullable rect,
  void *_Nullable *_Nonnull outVirtualAddress
)

锁定 AHardwareBuffer 以供 CPU 直接访问。

此函数可以锁定缓冲区以进行读取或写入。如果硬件需要完成渲染，或者 CPU 缓存需要同步，或者可能由于其他特定于实现的原因，此函数可能会阻塞。

传入的 AHardwareBuffer 必须只有一层，否则调用将失败。

如果 fence 不为负，它指定一个 fence 文件描述符，在锁定缓冲区之前等待该描述符。如果为负，则调用者负责在此函数调用之前确保对缓冲区的写入已完成。使用此参数比等待 fence 然后调用此函数更高效。

usage 参数只能指定 AHARDWAREBUFFER_USAGE_CPU_*。如果设置，则 outVirtualAddress 将填充缓冲区在虚拟内存中的地址。标记还必须与缓冲区创建时指定的使用标记兼容：如果传递读取标记，则必须使用 AHARDWAREBUFFER_USAGE_CPU_READ_RARELY 或 AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN 创建缓冲区。如果传递写入标记，则必须使用 AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY 或 AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN 创建缓冲区。

如果 rect 不为 NULL，则调用者承诺仅修改 rect 指定区域中的数据。如果 rect 为 NULL，则调用者可以修改整个缓冲区的内容。此调用不会修改指定 rect 之外的缓冲区内容。

多个不同的线程锁定缓冲区以进行读取访问是合法的；没有任何线程会被阻塞。

同时锁定缓冲区进行写入或读/写是未定义的，但不会终止进程也不会阻塞调用者。AHardwareBuffer_lock 可能会返回错误或使缓冲区内容处于不确定状态。

如果缓冲区具有 AHARDWAREBUFFER_FORMAT_BLOB 格式，则合法地在多个线程和/或进程中同时锁定以进行读写，且缓冲区内容的行为类似于共享内存。

自 API 级别 26 可用。

详情
返回值	成功时返回 0。如果 buffer 为 NULL，使用标记不是 AHARDWAREBUFFER_USAGE_CPU_* 的组合，或缓冲区有多个层，则返回 -EINVAL。如果锁定因任何其他原因失败，则返回错误码。

AHardwareBuffer_lockAndGetInfo

声明于 android/hardware_buffer.h

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
)

锁定 AHardwareBuffer 以供 CPU 直接访问。

此函数与上面的锁定函数相同，但会返回有关锁定缓冲区的每像素字节数和每步长字节数的附加信息。如果每像素字节数或每步长字节数未知或可变，或者底层映射器实现不支持返回附加信息，则此调用将因 INVALID_OPERATION 而失败。

自 API 级别 29 可用。

AHardwareBuffer_lockPlanes

声明于 android/hardware_buffer.h

int AHardwareBuffer_lockPlanes(
  AHardwareBuffer *_Nonnull buffer,
  uint64_t usage,
  int32_t fence,
  const ARect *_Nullable rect,
  AHardwareBuffer_Planes *_Nonnull outPlanes
)

锁定潜在的多平面 AHardwareBuffer 以供 CPU 直接访问。

此函数类似于 AHardwareBuffer_lock，但可以锁定多平面格式。锁定的平面在 outPlanes 参数中返回。请注意，多平面不应与多层图像混淆，此锁定函数不支持多层图像。

YUV 格式始终由三个单独的数据平面表示，每个颜色平面一个。保证数组中平面的顺序是平面 #0 始终为 Y，平面 #1 始终为 U (Cb)，平面 #2 始终为 V (Cr)。所有其他格式均由单个平面表示。

缓冲区始终附带附加信息，描述每个平面的行步长和像素步长。

如果缓冲区无法锁定，outPlanes 将包含零个平面。

有关所有其他锁定语义，请参阅 AHardwareBuffer_lock 文档。

自 API 级别 29 可用。

详情
返回值	成功时返回 0。如果 buffer 为 NULL，使用标记不是 AHARDWAREBUFFER_USAGE_CPU_* 的组合，或缓冲区有多个层，则返回 -EINVAL。如果锁定因任何其他原因失败，则返回错误码。

AHardwareBuffer_readFromParcel

声明于 android/hardware_buffer_aidl.h

binder_status_t AHardwareBuffer_readFromParcel(
  const AParcel *_Nonnull parcel,
  AHardwareBuffer *_Nullable *_Nonnull outBuffer
)

从 AParcel 读取 AHardwareBuffer。

输出缓冲区将有一个初始引用，需要通过 AHardwareBuffer_release 释放。

自 API 级别 34 可用。

详情
返回值	成功时返回 STATUS_OK 如果 parcel 或 outBuffer 为 null，或者反序列化时出现问题（例如 parcel 已损坏），则返回 STATUS_BAD_VALUE 如果 parcel 的当前数据位置不是 AHardwareBuffer 类型，则返回 STATUS_BAD_TYPE 如果分配失败，则返回 STATUS_NO_MEMORY

AHardwareBuffer_recvHandleFromUnixSocket

声明于 android/hardware_buffer.h

int AHardwareBuffer_recvHandleFromUnixSocket(
  int socketFd,
  AHardwareBuffer *_Nullable *_Nonnull outBuffer
)

从 AF_UNIX 套接字接收 AHardwareBuffer。

自 API 级别 26 可用。

详情
返回值	成功时返回 0，如果 outBuffer 为 NULL，则返回 -EINVAL，如果操作因任何原因失败，则返回错误码。

AHardwareBuffer_release

声明于 android/hardware_buffer.h

void AHardwareBuffer_release(
  AHardwareBuffer *_Nonnull buffer
)

移除之前通过 AHardwareBuffer_acquire() 或 AHardwareBuffer_allocate() 获取的引用。

自 API 级别 26 可用。

AHardwareBuffer_sendHandleToUnixSocket

声明于 android/hardware_buffer.h

int AHardwareBuffer_sendHandleToUnixSocket(
  const AHardwareBuffer *_Nonnull buffer,
  int socketFd
)

将 AHardwareBuffer 发送到 AF_UNIX 套接字。

自 API 级别 26 可用。

详情
返回值	成功时返回 0，如果 buffer 为 NULL，则返回 -EINVAL，如果操作因任何原因失败，则返回错误码。

AHardwareBuffer_toHardwareBuffer

声明于 android/hardware_buffer_jni.h

jobject AHardwareBuffer_toHardwareBuffer(
  JNIEnv *env,
  AHardwareBuffer *hardwareBuffer
)

返回一个新的 Java HardwareBuffer 对象，该对象封装了传入的原生 AHardwareBuffer 对象。

Java HardwareBuffer 将获取对内部缓冲区的引用并管理其生命周期。例如


AHardwareBuffer* buffer;
AHardwareBuffer_allocate(..., &buffer);  // `buffer` has reference count 1
jobject java_result = AHardwareBuffer_toHardwareBuffer(buffer);  // `buffer` has reference count 2.
AHardwareBuffer_release(buffer); // `buffer` has reference count 1
return result;  // The underlying buffer is kept alive by `java_result` and
                // will be set to 0 when it is closed on the Java side with
                // HardwareBuffer::close().

自 API 级别 26 可用。

AHardwareBuffer_unlock

声明于 android/hardware_buffer.h

int AHardwareBuffer_unlock(
  AHardwareBuffer *_Nonnull buffer,
  int32_t *_Nullable fence
)

解锁 AHardwareBuffer，不再允许 CPU 直接访问。

必须在调用者完成对缓冲区的所有更改后调用此函数。如果 fence 为 NULL，函数将阻塞直到所有工作完成。否则，fence 将设置为有效的文件描述符或 -1。一旦解锁完成且缓冲区内容更新，文件描述符将变为 signaled 状态。调用者负责在不再需要文件描述符时将其关闭。值 -1 表示函数返回之前解锁已经完成，无需进一步操作。

自 API 级别 26 可用。

详情
返回值	成功时返回 0。如果 buffer 为 NULL，则返回 -EINVAL。如果解锁因任何原因失败，则返回错误码。

AHardwareBuffer_writeToParcel

声明于 android/hardware_buffer_aidl.h

binder_status_t AHardwareBuffer_writeToParcel(
  const AHardwareBuffer *_Nonnull buffer,
  AParcel *_Nonnull parcel
)

将 AHardwareBuffer 写入 AParcel。

自 API 级别 34 可用。

详情
返回值	成功时返回 STATUS_OK。如果 buffer 或 parcel 为 null，或者 AHardwareBuffer* 序列化失败（例如内部损坏），则返回 STATUS_BAD_VALUE 如果 parcel 存储缓冲区空间不足且无法分配更多空间，则返回 STATUS_NO_MEMORY 如果 parcel 不允许存储 FDs，则返回 STATUS_FDS_NOT_ALLOWED