Documentation
¶
Overview ¶
Hardware buffer allocation and CPU-lock lifecycle.
Demonstrates how to allocate an AHardwareBuffer via the low-level API, wrap it in the idiomatic hwbuf.Buffer, lock it for CPU access, write pixel data, unlock it, and release the buffer.
The idiomatic hwbuf package exposes the Buffer type with Acquire, Unlock, and Close methods. Allocation and locking require the the low-level layer layer because the idiomatic package does not yet wrap AHardwareBuffer_allocate or AHardwareBuffer_lock. This example documents the full pattern and shows how to bridge the gap.
AHardwareBuffer lifecycle:
Describe -- Fill an AHardwareBuffer_Desc with width, height, layers, pixel format, and usage flags. Usage flags control which hardware blocks (CPU, GPU, compositor, video encoder) may access the buffer.
Allocate -- Call AHardwareBuffer_allocate with the descriptor. The driver chooses the optimal memory domain. (Not yet exposed in the idiomatic layer; use )
Lock -- Call AHardwareBuffer_lock with the desired CPU usage (read, write, or both) and an optional dirty rectangle. The call returns a raw pointer to the pixel data. (Not yet exposed in the idiomatic layer.)
Access -- Read or write pixels through the returned pointer. Respect the stride returned in the descriptor or via AHardwareBuffer_lockAndGetInfo.
Unlock -- Call Buffer.Unlock to release the CPU mapping and allow the GPU or other consumers to access the buffer. The optional fence parameter signals when the unlock completes asynchronously; pass nil for synchronous.
Share -- Optionally call Buffer.Acquire to increment the reference count before passing the buffer to another component (another thread, process, or API such as Vulkan or EGL).
Release -- Call Buffer.Close to decrement the reference count. When the count reaches zero the driver frees the memory.
This example exercises only the type system and documents the allocation pattern. Because AHardwareBuffer_allocate is not available in the idiomatic layer, the allocation step is shown as pseudocode in comments. The Acquire/Unlock/Close lifecycle is demonstrated with a hypothetical buffer pointer.
Prerequisites:
- Android device with API level 26+ (AHardwareBuffer was added in API 26).
This program must run on an Android device.
Source Files