Struct ndk::hardware_buffer::HardwareBufferRef

source · [−]

pub struct HardwareBufferRef { /* private fields */ }

Available on crate feature api-level-26 only.

Expand description

A HardwareBuffer with an owned reference, that is released when dropped. It behaves much like a strong std::rc::Rc reference.

Implementations

source

impl HardwareBufferRef

source

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

Create an owned HardwareBuffer from a native pointer

To wrap a weak reference (that is not released on Drop), call HardwareBuffer::from_ptr() instead.

Safety

By calling this function, you assert that it is a valid pointer to an NDK ffi::AHardwareBuffer.

Methods from Deref<Target = HardwareBuffer>

source

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.

source

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.

source

pub fn describe(&self) -> HardwareBufferDesc

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

source

pub fn lock(
 &self,
 usage: HardwareBufferUsage,
 fence: Option<RawFd>,
 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.

source

pub fn lock_and_get_info(
 &self,
 usage: HardwareBufferUsage,
 fence: Option<RawFd>,
 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.

source

pub fn lock_planes(
 &self,
 usage: HardwareBufferUsage,
 fence: Option<RawFd>,
 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.

source

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.

source

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

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.

source