Struct ndk::hardware_buffer::HardwareBuffer

pub struct HardwareBuffer { /* private fields */ }

Available on crate feature api-level-26 only.

A native AHardwareBuffer *

HardwareBuffer 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 HardwareBuffer and android.hardware.HardwareBuffer are zero-copy, i.e., passing HardwareBuffer to another process creates a shared view of the same region of memory.

HardwareBuffer 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 HardwareBuffer can be accessed as external memory. See the VK_ANDROID_external_memory_android_hardware_buffer extension for details.

Implementations

impl HardwareBuffer

pub unsafe fn from_ptr(ptr: NonNull<AHardwareBuffer>) -> Self

Create an unowned HardwareBuffer from a native pointer

To wrap a strong reference (that is released on Drop), call HardwareBufferRef::from_ptr() instead.

Safety

By calling this function, you assert that it is a valid pointer to an NDK ffi::AHardwareBuffer that is kept alive externally, or retrieve a strong reference using HardwareBuffer::acquire().

pub fn as_ptr(&self) -> *mut AHardwareBuffer

Returns the underlying ffi::AHardwareBuffer pointer

See the top-level HardwareBuffer struct documentation for (graphics) APIs that accept this pointer.

pub fn allocate(desc: HardwareBufferDesc) -> Result<HardwareBufferRef>

Allocates a buffer that matches the passed HardwareBufferDesc.

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.

pub unsafe fn from_jni(env: *mut JNIEnv, hardware_buffer: jobject) -> Self

Create a HardwareBuffer from JNI pointers

Safety

By calling this function, you assert that these are valid pointers to JNI objects.

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

pub unsafe fn to_jni(&self, env: *mut JNIEnv) -> jobject

Safety

By calling this function, you assert that env is a valid pointer to a JNIEnv.

pub fn describe(&self) -> HardwareBufferDesc

Return a description of the HardwareBuffer in the passed HardwareBufferDesc struct.

pub fn is_supported(desc: HardwareBufferDesc) -> bool

Available on crate feature api-level-29 only.

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 HardwareBufferDesc::stride, which is always ignored. For example, some implementations have implementation-defined limits on texture size and layer count.

pub fn id(&self) -> Result<u64>

Available on crate feature api-level-31 only.

Get the system-wide unique id for this HardwareBuffer.

pub fn lock( &self, usage: HardwareBufferUsage, fence: Option<OwnedFd>, rect: Option<Rect> ) -> Result<*mut c_void>

Lock the HardwareBuffer 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 HardwareBuffer must have one layer, otherwise the call will fail.

If fence is not None, it specifies a fence file descriptor on which to wait before locking the buffer. If it’s None, 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 HardwareBufferUsage::CPU_*. If set, then the address of the buffer in virtual memory is returned. 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 HardwareBufferUsage::CPU_READ_RARELY or HardwareBufferUsage::CPU_READ_OFTEN. If a write flag is passed, it must have been created with HardwareBufferUsage::CPU_WRITE_RARELY or HardwareBufferUsage::CPU_WRITE_OFTEN.

If rect is not None, the caller promises to modify only data in the area specified by rect. If rect is None, 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. This function may return an error or leave the buffer’s content in an indeterminate state.

If the buffer has HardwareBufferFormat::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.

pub fn lock_and_get_info( &self, usage: HardwareBufferUsage, fence: Option<OwnedFd>, rect: Option<Rect> ) -> Result<LockedPlaneInfo>

Available on crate feature api-level-29 only.

Lock a HardwareBuffer 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 std::io::Error::kind() = std::io::ErrorKind::Unsupported.

pub fn lock_planes( &self, usage: HardwareBufferUsage, fence: Option<OwnedFd>, rect: Option<Rect> ) -> Result<HardwareBufferPlanes>

Available on crate feature api-level-29 only.

Lock a potentially multi-planar HardwareBuffer for direct CPU access.

This function is similar to lock(), but can lock multi-planar formats. 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, this will return zero planes.

See the lock() documentation for all other locking semantics.

pub fn unlock(&self) -> Result<()>

Unlock the HardwareBuffer from direct CPU access.

Must be called after all changes to the buffer are completed by the caller. The function will block until all work is completed. See unlock_async() for a non-blocking variant that returns a file descriptor to be signaled on unlocking instead.

pub fn unlock_async(&self) -> Result<Option<OwnedFd>>

Unlock the HardwareBuffer from direct CPU access.

Returns a fence file descriptor that will become signaled when unlocking is completed, or None if unlocking is already finished. The caller is responsible for closing the file descriptor once it’s no longer needed. See unlock() for a variant that blocks instead.

pub fn recv_handle_from_unix_socket(socket_fd: BorrowedFd<'_>) -> Result<Self>

Receive a HardwareBuffer from an AF_UNIX socket.

AF_UNIX sockets are wrapped by std::os::unix::net::UnixListener and std::os::unix::net::UnixStream in Rust and have a corresponding std::os::unix::io::AsFd::as_fd() implementation.

pub fn send_handle_to_unix_socket( &self, socket_fd: BorrowedFd<'_> ) -> Result<()>

Send the HardwareBuffer to an AF_UNIX socket.

AF_UNIX sockets are wrapped by std::os::unix::net::UnixListener and std::os::unix::net::UnixStream in Rust and have a corresponding std::os::unix::io::AsFd::as_fd() implementation.

pub fn acquire(&self) -> HardwareBufferRef

Acquire a reference on the given HardwareBuffer object.

This prevents the object from being deleted until the last strong reference, represented by HardwareBufferRef, is drop()ped.

Trait Implementations

impl Debug for HardwareBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.