Native Hardware Buffer

AHardwareBuffer objects represent chunks of memory that can be accessed by various hardware components in the system.

Summary

Parcelable support for AHardwareBuffer.

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.

Can be used with libbinder_ndk

Enumerations
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_R8_UNORM = 0x38,
  AHARDWAREBUFFER_FORMAT_R16_UINT = 0x39,
  AHARDWAREBUFFER_FORMAT_R16G16_UINT = 0x3a,
  AHARDWAREBUFFER_FORMAT_R10G10B10A10_UNORM = 0x3b
} 		enum
Buffer pixel formats.
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
Buffer usage flags, specifying how the buffer will be accessed.

Typedefs
AHardwareBuffer typedef
struct AHardwareBuffer
Opaque handle for a native hardware buffer.
AHardwareBuffer_Desc typedef
Buffer description.
AHardwareBuffer_Plane typedef
Holds data for a single image plane.
AHardwareBuffer_Planes typedef
Holds all image planes that contain the pixel data.

Functions
AHardwareBuffer_acquire(AHardwareBuffer *_Nonnull buffer)
void
Acquire a reference on the given AHardwareBuffer object.
AHardwareBuffer_allocate(const AHardwareBuffer_Desc *_Nonnull desc, AHardwareBuffer *_Nullable *_Nonnull outBuffer)
int
Allocates a buffer that matches the passed AHardwareBuffer_Desc.
AHardwareBuffer_describe(const AHardwareBuffer *_Nonnull buffer, AHardwareBuffer_Desc *_Nonnull outDesc)
void
Return a description of the AHardwareBuffer in the passed AHardwareBuffer_Desc struct.
AHardwareBuffer_fromHardwareBuffer(JNIEnv *env, jobject hardwareBufferObj)
Return the AHardwareBuffer wrapped by a Java HardwareBuffer object.
AHardwareBuffer_getId(const AHardwareBuffer *_Nonnull buffer, uint64_t *_Nonnull outId)
int
Get the system wide unique id for an AHardwareBuffer.
AHardwareBuffer_isSupported(const AHardwareBuffer_Desc *_Nonnull desc)
int
Test whether the given format and usage flag combination is allocatable.
AHardwareBuffer_lock(AHardwareBuffer *_Nonnull buffer, uint64_t usage, int32_t fence, const ARect *_Nullable rect, void *_Nullable *_Nonnull outVirtualAddress)
int
Lock the AHardwareBuffer for direct CPU access.
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
Lock an AHardwareBuffer for direct CPU access.
AHardwareBuffer_lockPlanes(AHardwareBuffer *_Nonnull buffer, uint64_t usage, int32_t fence, const ARect *_Nullable rect, AHardwareBuffer_Planes *_Nonnull outPlanes)
int
Lock a potentially multi-planar AHardwareBuffer for direct CPU access.
AHardwareBuffer_readFromParcel(const AParcel *_Nonnull parcel, AHardwareBuffer *_Nullable *_Nonnull outBuffer)
Read an AHardwareBuffer from a AParcel.
AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer *_Nullable *_Nonnull outBuffer)
int
Receive an AHardwareBuffer from an AF_UNIX socket.
AHardwareBuffer_release(AHardwareBuffer *_Nonnull buffer)
void
Remove a reference that was previously acquired with AHardwareBuffer_acquire() or AHardwareBuffer_allocate().
AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer *_Nonnull buffer, int socketFd)
int
Send the AHardwareBuffer to an AF_UNIX socket.
AHardwareBuffer_toHardwareBuffer(JNIEnv *env, AHardwareBuffer *hardwareBuffer)
jobject
Return a new Java HardwareBuffer object that wraps the passed native AHardwareBuffer object.
AHardwareBuffer_unlock(AHardwareBuffer *_Nonnull buffer, int32_t *_Nullable fence)
int
Unlock the AHardwareBuffer from direct CPU access.
AHardwareBuffer_writeToParcel(const AHardwareBuffer *_Nonnull buffer, AParcel *_Nonnull parcel)
Write an AHardwareBuffer to an AParcel.

Structs
AHardwareBuffer_Desc

Buffer description.

AHardwareBuffer_Plane

Holds data for a single image plane.

AHardwareBuffer_Planes

Holds all image planes that contain the pixel data.

Enumerations

AHardwareBuffer_Format

Declared in android/hardware_buffer.h 
 AHardwareBuffer_Format

Buffer pixel formats.

Properties
AHARDWAREBUFFER_FORMAT_BLOB

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.

AHARDWAREBUFFER_FORMAT_D16_UNORM

Corresponding formats: Vulkan: VK_FORMAT_D16_UNORM OpenGL ES: GL_DEPTH_COMPONENT16.

AHARDWAREBUFFER_FORMAT_D24_UNORM

Corresponding formats: Vulkan: VK_FORMAT_X8_D24_UNORM_PACK32 OpenGL ES: GL_DEPTH_COMPONENT24.

AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT

Corresponding formats: Vulkan: VK_FORMAT_D24_UNORM_S8_UINT OpenGL ES: GL_DEPTH24_STENCIL8.

AHARDWAREBUFFER_FORMAT_D32_FLOAT

Corresponding formats: Vulkan: VK_FORMAT_D32_SFLOAT OpenGL ES: GL_DEPTH_COMPONENT32F.

AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT

Corresponding formats: Vulkan: VK_FORMAT_D32_SFLOAT_S8_UINT OpenGL ES: GL_DEPTH32F_STENCIL8.

AHARDWAREBUFFER_FORMAT_R10G10B10A10_UNORM

Corresponding formats: Vulkan: VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16 OpenGL ES: N/A.

AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM

Corresponding formats: Vulkan: VK_FORMAT_A2B10G10R10_UNORM_PACK32 OpenGL ES: GL_RGB10_A2.

AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT

Corresponding formats: Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT OpenGL ES: GL_RGBA16F.

AHARDWAREBUFFER_FORMAT_R16G16_UINT

Corresponding formats: Vulkan: VK_FORMAT_R16G16_UINT OpenGL ES: GL_RG16UI.

AHARDWAREBUFFER_FORMAT_R16_UINT

Corresponding formats: Vulkan: VK_FORMAT_R16_UINT OpenGL ES: GL_R16UI.

AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM

Corresponding formats: Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16 OpenGL ES: GL_RGB565.

AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM

Corresponding formats: Vulkan: VK_FORMAT_R8G8B8A8_UNORM OpenGL ES: GL_RGBA8.

AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM

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

AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM

Corresponding formats: Vulkan: VK_FORMAT_R8G8B8_UNORM OpenGL ES: GL_RGB8.

AHARDWAREBUFFER_FORMAT_R8_UNORM

Corresponding formats: Vulkan: VK_FORMAT_R8_UNORM OpenGL ES: GR_GL_R8.

AHARDWAREBUFFER_FORMAT_S8_UINT

Corresponding formats: Vulkan: VK_FORMAT_S8_UINT OpenGL ES: GL_STENCIL_INDEX8.

AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420

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.

AHARDWAREBUFFER_FORMAT_YCbCr_P010

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.

AHardwareBuffer_UsageFlags

Declared in android/hardware_buffer.h 
 AHardwareBuffer_UsageFlags

Buffer usage flags, specifying how the buffer will be accessed.

Properties
AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY

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.

AHARDWAREBUFFER_USAGE_CPU_READ_MASK

CPU read value mask.

AHARDWAREBUFFER_USAGE_CPU_READ_NEVER

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_OFTEN

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_RARELY

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_WRITE_MASK

CPU write value mask.

AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER

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_OFTEN

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_RARELY

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_FRONT_BUFFER

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.

AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT

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.

AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP

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.

AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER

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_FRAMEBUFFER

The buffer will be written to by the GPU as a framebuffer attachment.

AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE

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_SAMPLED_IMAGE

The buffer will be read from by the GPU as a texture.

AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT

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.

AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA

The buffer will be used for direct writes from sensors.

When this flag is present, the format must be 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

The buffer will be read by a hardware video encoder.

Typedefs

AHardwareBuffer

Declared in android/hardware_buffer.h 
struct AHardwareBuffer AHardwareBuffer

Opaque handle for a native hardware buffer.

AHardwareBuffer_Desc

Declared in android/hardware_buffer.h 
struct AHardwareBuffer_Desc AHardwareBuffer_Desc

Buffer description.

Used for allocating new buffers and querying parameters of existing ones.

AHardwareBuffer_Plane

Declared in android/hardware_buffer.h 
struct AHardwareBuffer_Plane AHardwareBuffer_Plane

Holds data for a single image plane.

AHardwareBuffer_Planes

Declared in android/hardware_buffer.h 
struct AHardwareBuffer_Planes AHardwareBuffer_Planes

Holds all image planes that contain the pixel data.

Functions

AHardwareBuffer_acquire

Declared in android/hardware_buffer.h 
void AHardwareBuffer_acquire(
  AHardwareBuffer *_Nonnull buffer
)

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_allocate

Declared in android/hardware_buffer.h 
int AHardwareBuffer_allocate(
  const AHardwareBuffer_Desc *_Nonnull desc,
  AHardwareBuffer *_Nullable *_Nonnull outBuffer
)

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.

Details
Returns
0 on success, or an error number of the allocation fails for any reason. The returned buffer has a reference count of 1.

AHardwareBuffer_describe

Declared in android/hardware_buffer.h 
void AHardwareBuffer_describe(
  const AHardwareBuffer *_Nonnull buffer,
  AHardwareBuffer_Desc *_Nonnull outDesc
)

Return a description of the AHardwareBuffer in the passed AHardwareBuffer_Desc struct.

Available since API level 26.

AHardwareBuffer_fromHardwareBuffer

Declared in android/hardware_buffer_jni.h 
AHardwareBuffer * AHardwareBuffer_fromHardwareBuffer(
  JNIEnv *env,
  jobject hardwareBufferObj
)

Return the AHardwareBuffer wrapped by a Java HardwareBuffer object.

This method does not acquire any additional reference to the AHardwareBuffer that is returned. To keep the AHardwareBuffer alive after the Java HardwareBuffer object is closed, explicitly or by the garbage collector, be sure to use AHardwareBuffer_acquire() to acquire an additional reference.

Available since API level 26.

AHardwareBuffer_getId

Declared in android/hardware_buffer.h 
int AHardwareBuffer_getId(
  const AHardwareBuffer *_Nonnull buffer,
  uint64_t *_Nonnull outId
)

Get the system wide unique id for an AHardwareBuffer.

Available since API level 31.

Details
Returns
0 on success, -EINVAL if buffer or outId is NULL, or an error number if the operation fails for any reason.

AHardwareBuffer_isSupported

Declared in android/hardware_buffer.h 
int AHardwareBuffer_isSupported(
  const AHardwareBuffer_Desc *_Nonnull desc
)

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.

Details
Returns
1 if the format and usage flag combination is allocatable, 0 otherwise.

AHardwareBuffer_lock

Declared in android/hardware_buffer.h 
int AHardwareBuffer_lock(
  AHardwareBuffer *_Nonnull buffer,
  uint64_t usage,
  int32_t fence,
  const ARect *_Nullable rect,
  void *_Nullable *_Nonnull outVirtualAddress
)

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 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 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 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.

Details
Returns
0 on success. -EINVAL if 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_lockAndGetInfo

Declared in 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
)

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_lockPlanes

Declared in android/hardware_buffer.h 
int AHardwareBuffer_lockPlanes(
  AHardwareBuffer *_Nonnull buffer,
  uint64_t usage,
  int32_t fence,
  const ARect *_Nullable rect,
  AHardwareBuffer_Planes *_Nonnull outPlanes
)

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 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, outPlanes will contain zero planes.

See the AHardwareBuffer_lock documentation for all other locking semantics.

Available since API level 29.

Details
Returns
0 on success. -EINVAL if 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_readFromParcel

Declared in android/hardware_buffer_aidl.h 
binder_status_t AHardwareBuffer_readFromParcel(
  const AParcel *_Nonnull parcel,
  AHardwareBuffer *_Nullable *_Nonnull outBuffer
)

Read an AHardwareBuffer from a AParcel.

The output buffer will have an initial reference acquired and will need to be released with AHardwareBuffer_release.

Available since API level 34.

Details
Returns
STATUS_OK on success STATUS_BAD_VALUE if the parcel or outBuffer is null, or if there's an issue deserializing (eg, corrupted parcel) STATUS_BAD_TYPE if the parcel's current data position is not that of an AHardwareBuffer type STATUS_NO_MEMORY if an allocation fails

AHardwareBuffer_recvHandleFromUnixSocket

Declared in android/hardware_buffer.h 
int AHardwareBuffer_recvHandleFromUnixSocket(
  int socketFd,
  AHardwareBuffer *_Nullable *_Nonnull outBuffer
)

Receive an AHardwareBuffer from an AF_UNIX socket.

Available since API level 26.

Details
Returns
0 on success, -EINVAL if outBuffer is NULL, or an error number if the operation fails for any reason.

AHardwareBuffer_release

Declared in android/hardware_buffer.h 
void AHardwareBuffer_release(
  AHardwareBuffer *_Nonnull buffer
)

Remove a reference that was previously acquired with AHardwareBuffer_acquire() or AHardwareBuffer_allocate().

Available since API level 26.

AHardwareBuffer_sendHandleToUnixSocket

Declared in android/hardware_buffer.h 
int AHardwareBuffer_sendHandleToUnixSocket(
  const AHardwareBuffer *_Nonnull buffer,
  int socketFd
)

Send the AHardwareBuffer to an AF_UNIX socket.

Available since API level 26.

Details
Returns
0 on success, -EINVAL if buffer is NULL, or an error number if the operation fails for any reason.

AHardwareBuffer_toHardwareBuffer

Declared in android/hardware_buffer_jni.h 
jobject AHardwareBuffer_toHardwareBuffer(
  JNIEnv *env,
  AHardwareBuffer *hardwareBuffer
)

Return a new Java HardwareBuffer object that wraps the passed native AHardwareBuffer object.

The Java HardwareBuffer will acquire a reference to the internal buffer and manage its lifetime. For example:


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().

Available since API level 26.

AHardwareBuffer_unlock

Declared in android/hardware_buffer.h 
int AHardwareBuffer_unlock(
  AHardwareBuffer *_Nonnull buffer,
  int32_t *_Nullable fence
)

Unlock the AHardwareBuffer from direct CPU access.

Must be called after all changes to the buffer are completed by the caller. If fence is NULL, the function will block until all work is completed. Otherwise, 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.

Details
Returns
0 on success. -EINVAL if buffer is NULL. Error number if the unlock fails for any reason.

AHardwareBuffer_writeToParcel

Declared in android/hardware_buffer_aidl.h 
binder_status_t AHardwareBuffer_writeToParcel(
  const AHardwareBuffer *_Nonnull buffer,
  AParcel *_Nonnull parcel
)

Write an AHardwareBuffer to an AParcel.

Available since API level 34.

Details
Returns
STATUS_OK on success. STATUS_BAD_VALUE if either buffer or parcel is null, or if the AHardwareBuffer* fails to serialize (eg, internally corrupted) STATUS_NO_MEMORY if the parcel runs out of space to store the buffer & is unable to allocate more STATUS_FDS_NOT_ALLOWED if the parcel does not allow storing FDs