Native Hardware Buffer
#include <hardware_buffer_jni.h>
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
Typedefs |
|
|---|---|
AHardwareBuffer
|
typedefstruct AHardwareBuffer
Opaque handle for a native hardware buffer. |
AHardwareBuffer_Desc
|
typedefstruct AHardwareBuffer_Desc
Buffer description. |
AHardwareBuffer_Plane
|
typedefstruct AHardwareBuffer_Plane
Holds data for a single image plane. |
AHardwareBuffer_Planes
|
typedefstruct AHardwareBuffer_Planes
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
AHardwareBuffer_Format
Buffer pixel formats.
AHardwareBuffer_UsageFlags
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
struct AHardwareBuffer AHardwareBuffer
Opaque handle for a native hardware buffer.
AHardwareBuffer_Desc
struct AHardwareBuffer_Desc AHardwareBuffer_Desc
Buffer description.
Used for allocating new buffers and querying parameters of existing ones.
AHardwareBuffer_Plane
struct AHardwareBuffer_Plane AHardwareBuffer_Plane
Holds data for a single image plane.
AHardwareBuffer_Planes
struct AHardwareBuffer_Planes AHardwareBuffer_Planes
Holds all image planes that contain the pixel data.
Functions
AHardwareBuffer_acquire
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
|