rust/src/lib.rs

// Copyright (C) 2023 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Pleasant Rust bindings for libnativewindow, including AHardwareBuffer

extern crate nativewindow_bindgen as ffi;

mod handle;
mod surface;

pub use ffi::{AHardwareBuffer_Format, AHardwareBuffer_UsageFlags};
pub use handle::NativeHandle;
pub use surface::{buffer::Buffer, Surface};

use binder::{
    binder_impl::{BorrowedParcel, UnstructuredParcelable},
    impl_deserialize_for_unstructured_parcelable, impl_serialize_for_unstructured_parcelable,
    unstable_api::{status_result, AsNative},
    StatusCode,
};
use ffi::{
    AHardwareBuffer, AHardwareBuffer_Desc, AHardwareBuffer_Plane, AHardwareBuffer_Planes,
    AHardwareBuffer_readFromParcel, AHardwareBuffer_writeToParcel, ARect,
};
use std::ffi::c_void;
use std::fmt::{self, Debug, Formatter};
use std::mem::{forget, ManuallyDrop};
use std::os::fd::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd};
use std::ptr::{self, null, null_mut, NonNull};

/// Wrapper around a C `AHardwareBuffer_Desc`.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct HardwareBufferDescription(AHardwareBuffer_Desc);

impl HardwareBufferDescription {
    /// Creates a new `HardwareBufferDescription` with the given parameters.
    pub fn new(
        width: u32,
        height: u32,
        layers: u32,
        format: AHardwareBuffer_Format::Type,
        usage: AHardwareBuffer_UsageFlags,
        stride: u32,
    ) -> Self {
        Self(AHardwareBuffer_Desc {
            width,
            height,
            layers,
            format,
            usage: usage.0,
            stride,
            rfu0: 0,
            rfu1: 0,
        })
    }

    /// Returns the width from the buffer description.
    pub fn width(&self) -> u32 {
        self.0.width
    }

    /// Returns the height from the buffer description.
    pub fn height(&self) -> u32 {
        self.0.height
    }

    /// Returns the number from layers from the buffer description.
    pub fn layers(&self) -> u32 {
        self.0.layers
    }

    /// Returns the format from the buffer description.
    pub fn format(&self) -> AHardwareBuffer_Format::Type {
        self.0.format
    }

    /// Returns the usage bitvector from the buffer description.
    pub fn usage(&self) -> AHardwareBuffer_UsageFlags {
        AHardwareBuffer_UsageFlags(self.0.usage)
    }

    /// Returns the stride from the buffer description.
    pub fn stride(&self) -> u32 {
        self.0.stride
    }
}

impl Default for HardwareBufferDescription {
    fn default() -> Self {
        Self(AHardwareBuffer_Desc {
            width: 0,
            height: 0,
            layers: 0,
            format: 0,
            usage: 0,
            stride: 0,
            rfu0: 0,
            rfu1: 0,
        })
    }
}

/// Wrapper around an opaque C `AHardwareBuffer`.
#[derive(PartialEq, Eq)]
pub struct HardwareBuffer(NonNull<AHardwareBuffer>);

impl HardwareBuffer {
    /// 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.
    ///
    /// Available since API 29
    pub fn is_supported(buffer_description: &HardwareBufferDescription) -> bool {
        // SAFETY: The pointer comes from a reference so must be valid.
        let status = unsafe { ffi::AHardwareBuffer_isSupported(&buffer_description.0) };

        status == 1
    }

    /// 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.
    #[inline]
    pub fn new(buffer_description: &HardwareBufferDescription) -> Option<Self> {
        let mut ptr = ptr::null_mut();
        // SAFETY: The returned pointer is valid until we drop/deallocate it. The function may fail
        // and return a status, but we check it later.
        let status = unsafe { ffi::AHardwareBuffer_allocate(&buffer_description.0, &mut ptr) };

        if status == 0 {
            Some(Self(NonNull::new(ptr).expect("Allocated AHardwareBuffer was null")))
        } else {
            None
        }
    }

    /// Creates a `HardwareBuffer` from a native handle.
    ///
    /// The native handle is cloned, so this doesn't take ownership of the original handle passed
    /// in.
    pub fn create_from_handle(
        handle: &NativeHandle,
        buffer_description: &HardwareBufferDescription,
    ) -> Result<Self, StatusCode> {
        let mut buffer = ptr::null_mut();
        // SAFETY: The caller guarantees that `handle` is valid, and the buffer pointer is valid
        // because it comes from a reference. The method we pass means that
        // `AHardwareBuffer_createFromHandle` will clone the handle rather than taking ownership of
        // it.
        let status = unsafe {
            ffi::AHardwareBuffer_createFromHandle(
                &buffer_description.0,
                handle.as_raw().as_ptr(),
                ffi::CreateFromHandleMethod_AHARDWAREBUFFER_CREATE_FROM_HANDLE_METHOD_CLONE
                    .try_into()
                    .unwrap(),
                &mut buffer,
            )
        };
        status_result(status)?;
        Ok(Self(NonNull::new(buffer).expect("Allocated AHardwareBuffer was null")))
    }

    /// Returns a clone of the native handle of the buffer.
    ///
    /// Returns `None` if the operation fails for any reason.
    pub fn cloned_native_handle(&self) -> Option<NativeHandle> {
        // SAFETY: The AHardwareBuffer pointer we pass is guaranteed to be non-null and valid
        // because it must have been allocated by `AHardwareBuffer_allocate`,
        // `AHardwareBuffer_readFromParcel` or the caller of `from_raw` and we have not yet
        // released it.
        let native_handle = unsafe { ffi::AHardwareBuffer_getNativeHandle(self.0.as_ptr()) };
        NonNull::new(native_handle.cast_mut()).and_then(|native_handle| {
            // SAFETY: `AHardwareBuffer_getNativeHandle` should have returned a valid pointer which
            // is valid at least as long as the buffer is, and `clone_from_raw` clones it rather
            // than taking ownership of it so the original `native_handle` isn't stored.
            unsafe { NativeHandle::clone_from_raw(native_handle) }
        })
    }

    /// Adopts the given raw pointer and wraps it in a Rust HardwareBuffer.
    ///
    /// # Safety
    ///
    /// This function takes ownership of the pointer and does NOT increment the refcount on the
    /// buffer. If the caller uses the pointer after the created object is dropped it will cause
    /// undefined behaviour. If the caller wants to continue using the pointer after calling this
    /// then use [`clone_from_raw`](Self::clone_from_raw) instead.
    pub unsafe fn from_raw(buffer_ptr: NonNull<AHardwareBuffer>) -> Self {
        Self(buffer_ptr)
    }

    /// Creates a new Rust HardwareBuffer to wrap the given `AHardwareBuffer` without taking
    /// ownership of it.
    ///
    /// Unlike [`from_raw`](Self::from_raw) this method will increment the refcount on the buffer.
    /// This means that the caller can continue to use the raw buffer it passed in, and must call
    /// [`AHardwareBuffer_release`](ffi::AHardwareBuffer_release) when it is finished with it to
    /// avoid a memory leak.
    ///
    /// # Safety
    ///
    /// The buffer pointer must point to a valid `AHardwareBuffer`.
    pub unsafe fn clone_from_raw(buffer: NonNull<AHardwareBuffer>) -> Self {
        // SAFETY: The caller guarantees that the AHardwareBuffer pointer is valid.
        unsafe { ffi::AHardwareBuffer_acquire(buffer.as_ptr()) };
        Self(buffer)
    }

    /// Returns the internal `AHardwareBuffer` pointer.
    ///
    /// This is only valid as long as this `HardwareBuffer` exists, so shouldn't be stored. It can
    /// be used to provide a pointer for a C/C++ API over FFI.
    pub fn as_raw(&self) -> NonNull<AHardwareBuffer> {
        self.0
    }

    /// Gets the internal `AHardwareBuffer` pointer without decrementing the refcount. This can
    /// be used for a C/C++ API which takes ownership of the pointer.
    ///
    /// The caller is responsible for releasing the `AHardwareBuffer` pointer by calling
    /// `AHardwareBuffer_release` when it is finished with it, or may convert it back to a Rust
    /// `HardwareBuffer` by calling [`HardwareBuffer::from_raw`].
    pub fn into_raw(self) -> NonNull<AHardwareBuffer> {
        let buffer = ManuallyDrop::new(self);
        buffer.0
    }

    /// Get the system wide unique id for an AHardwareBuffer. This function may panic in extreme
    /// and undocumented circumstances.
    ///
    /// Available since API level 31.
    pub fn id(&self) -> u64 {
        let mut out_id = 0;
        // SAFETY: The AHardwareBuffer pointer we pass is guaranteed to be non-null and valid
        // because it must have been allocated by `AHardwareBuffer_allocate`,
        // `AHardwareBuffer_readFromParcel` or the caller of `from_raw` and we have not yet
        // released it. The id pointer must be valid because it comes from a reference.
        let status = unsafe { ffi::AHardwareBuffer_getId(self.0.as_ptr(), &mut out_id) };
        assert_eq!(status, 0, "id() failed for AHardwareBuffer with error code: {status}");

        out_id
    }

    /// Returns the description of this buffer.
    pub fn description(&self) -> HardwareBufferDescription {
        let mut buffer_desc = ffi::AHardwareBuffer_Desc {
            width: 0,
            height: 0,
            layers: 0,
            format: 0,
            usage: 0,
            stride: 0,
            rfu0: 0,
            rfu1: 0,
        };
        // SAFETY: The `AHardwareBuffer` pointer we wrap is always valid, and the
        // AHardwareBuffer_Desc pointer is valid because it comes from a reference.
        unsafe { ffi::AHardwareBuffer_describe(self.0.as_ref(), &mut buffer_desc) };
        HardwareBufferDescription(buffer_desc)
    }

    /// Locks the hardware buffer for direct CPU access.
    ///
    /// # Safety
    ///
    /// - If `fence` is `None`, the caller must ensure that all writes to the buffer have completed
    ///   before calling this function.
    /// - If the buffer has `AHARDWAREBUFFER_FORMAT_BLOB`, multiple threads or process may lock the
    ///   buffer simultaneously, but the caller must ensure that they don't access it simultaneously
    ///   and break Rust's aliasing rules, like any other shared memory.
    /// - Otherwise if `usage` includes `AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY` or
    ///   `AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN`, the caller must ensure that no other threads or
    ///   processes lock the buffer simultaneously for any usage.
    /// - Otherwise, the caller must ensure that no other threads lock the buffer for writing
    ///   simultaneously.
    /// - If `rect` is not `None`, the caller must not modify the buffer outside of that rectangle.
    pub unsafe fn lock<'a>(
        &'a self,
        usage: AHardwareBuffer_UsageFlags,
        fence: Option<BorrowedFd>,
        rect: Option<&ARect>,
    ) -> Result<HardwareBufferGuard<'a>, StatusCode> {
        let fence = if let Some(fence) = fence { fence.as_raw_fd() } else { -1 };
        let rect = rect.map(ptr::from_ref).unwrap_or(null());
        let mut address = null_mut();
        // SAFETY: The `AHardwareBuffer` pointer we wrap is always valid, and the buffer address out
        // pointer is valid because it comes from a reference. Our caller promises that writes have
        // completed and there will be no simultaneous read/write locks.
        let status = unsafe {
            ffi::AHardwareBuffer_lock(self.0.as_ptr(), usage.0, fence, rect, &mut address)
        };
        status_result(status)?;
        Ok(HardwareBufferGuard {
            buffer: self,
            address: NonNull::new(address)
                .expect("AHardwareBuffer_lock set a null outVirtualAddress"),
        })
    }

    /// Lock a potentially multi-planar hardware buffer for direct CPU access.
    ///
    /// # Safety
    ///
    /// - If `fence` is `None`, the caller must ensure that all writes to the buffer have completed
    ///   before calling this function.
    /// - If the buffer has `AHARDWAREBUFFER_FORMAT_BLOB`, multiple threads or process may lock the
    ///   buffer simultaneously, but the caller must ensure that they don't access it simultaneously
    ///   and break Rust's aliasing rules, like any other shared memory.
    /// - Otherwise if `usage` includes `AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY` or
    ///   `AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN`, the caller must ensure that no other threads or
    ///   processes lock the buffer simultaneously for any usage.
    /// - Otherwise, the caller must ensure that no other threads lock the buffer for writing
    ///   simultaneously.
    /// - If `rect` is not `None`, the caller must not modify the buffer outside of that rectangle.
    pub unsafe fn lock_planes<'a>(
        &'a self,
        usage: AHardwareBuffer_UsageFlags,
        fence: Option<BorrowedFd>,
        rect: Option<&ARect>,
    ) -> Result<Vec<PlaneGuard<'a>>, StatusCode> {
        let fence = if let Some(fence) = fence { fence.as_raw_fd() } else { -1 };
        let rect = rect.map(ptr::from_ref).unwrap_or(null());
        let mut planes = AHardwareBuffer_Planes {
            planeCount: 0,
            planes: [const { AHardwareBuffer_Plane { data: null_mut(), pixelStride: 0, rowStride: 0 } };
                4],
        };

        // SAFETY: The `AHardwareBuffer` pointer we wrap is always valid, and the various out
        // pointers are valid because they come from references. Our caller promises that writes have
        // completed and there will be no simultaneous read/write locks.
        let status = unsafe {
            ffi::AHardwareBuffer_lockPlanes(self.0.as_ptr(), usage.0, fence, rect, &mut planes)
        };
        status_result(status)?;
        let plane_count = planes.planeCount.try_into().unwrap();
        Ok(planes.planes[..plane_count]
            .iter()
            .map(|plane| PlaneGuard {
                guard: HardwareBufferGuard {
                    buffer: self,
                    address: NonNull::new(plane.data)
                        .expect("AHardwareBuffer_lockAndGetInfo set a null outVirtualAddress"),
                },
                pixel_stride: plane.pixelStride,
                row_stride: plane.rowStride,
            })
            .collect())
    }

    /// Locks the hardware buffer for direct CPU access, returning information about the bytes per
    /// pixel and stride as well.
    ///
    /// # Safety
    ///
    /// - If `fence` is `None`, the caller must ensure that all writes to the buffer have completed
    ///   before calling this function.
    /// - If the buffer has `AHARDWAREBUFFER_FORMAT_BLOB`, multiple threads or process may lock the
    ///   buffer simultaneously, but the caller must ensure that they don't access it simultaneously
    ///   and break Rust's aliasing rules, like any other shared memory.
    /// - Otherwise if `usage` includes `AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY` or
    ///   `AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN`, the caller must ensure that no other threads or
    ///   processes lock the buffer simultaneously for any usage.
    /// - Otherwise, the caller must ensure that no other threads lock the buffer for writing
    ///   simultaneously.
    pub unsafe fn lock_and_get_info<'a>(
        &'a self,
        usage: AHardwareBuffer_UsageFlags,
        fence: Option<BorrowedFd>,
        rect: Option<&ARect>,
    ) -> Result<LockedBufferInfo<'a>, StatusCode> {
        let fence = if let Some(fence) = fence { fence.as_raw_fd() } else { -1 };
        let rect = rect.map(ptr::from_ref).unwrap_or(null());
        let mut address = null_mut();
        let mut bytes_per_pixel = 0;
        let mut stride = 0;
        // SAFETY: The `AHardwareBuffer` pointer we wrap is always valid, and the various out
        // pointers are valid because they come from references. Our caller promises that writes have
        // completed and there will be no simultaneous read/write locks.
        let status = unsafe {
            ffi::AHardwareBuffer_lockAndGetInfo(
                self.0.as_ptr(),
                usage.0,
                fence,
                rect,
                &mut address,
                &mut bytes_per_pixel,
                &mut stride,
            )
        };
        status_result(status)?;
        Ok(LockedBufferInfo {
            guard: HardwareBufferGuard {
                buffer: self,
                address: NonNull::new(address)
                    .expect("AHardwareBuffer_lockAndGetInfo set a null outVirtualAddress"),
            },
            bytes_per_pixel: bytes_per_pixel as u32,
            stride: stride as u32,
        })
    }

    /// Unlocks the hardware buffer from direct CPU access.
    ///
    /// Must be called after all changes to the buffer are completed by the caller. This will block
    /// until the unlocking is complete and the buffer contents are updated.
    fn unlock(&self) -> Result<(), StatusCode> {
        // SAFETY: The `AHardwareBuffer` pointer we wrap is always valid.
        let status = unsafe { ffi::AHardwareBuffer_unlock(self.0.as_ptr(), null_mut()) };
        status_result(status)?;
        Ok(())
    }

    /// Unlocks the hardware buffer from direct CPU access.
    ///
    /// Must be called after all changes to the buffer are completed by the caller.
    ///
    /// This may not block until all work is completed, but rather will return a file descriptor
    /// which will be signalled once the unlocking is complete and the buffer contents is updated.
    /// If `Ok(None)` is returned then unlocking has already completed and no further waiting is
    /// necessary. The file descriptor may be passed to a subsequent call to [`Self::lock`].
    pub fn unlock_with_fence(
        &self,
        guard: HardwareBufferGuard,
    ) -> Result<Option<OwnedFd>, StatusCode> {
        // Forget the guard so that its `Drop` implementation doesn't try to unlock the
        // HardwareBuffer again.
        forget(guard);

        let mut fence = -2;
        // SAFETY: The `AHardwareBuffer` pointer we wrap is always valid.
        let status = unsafe { ffi::AHardwareBuffer_unlock(self.0.as_ptr(), &mut fence) };
        let fence = if fence < 0 {
            None
        } else {
            // SAFETY: `AHardwareBuffer_unlock` gives us ownership of the fence file descriptor.
            Some(unsafe { OwnedFd::from_raw_fd(fence) })
        };
        status_result(status)?;
        Ok(fence)
    }
}

impl Drop for HardwareBuffer {
    fn drop(&mut self) {
        // SAFETY: The AHardwareBuffer pointer we pass is guaranteed to be non-null and valid
        // because it must have been allocated by `AHardwareBuffer_allocate`,
        // `AHardwareBuffer_readFromParcel` or the caller of `from_raw` and we have not yet
        // released it.
        unsafe { ffi::AHardwareBuffer_release(self.0.as_ptr()) }
    }
}

impl Debug for HardwareBuffer {
    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
        f.debug_struct("HardwareBuffer").field("id", &self.id()).finish()
    }
}

impl Clone for HardwareBuffer {
    fn clone(&self) -> Self {
        // SAFETY: ptr is guaranteed to be non-null and the acquire can not fail.
        unsafe { ffi::AHardwareBuffer_acquire(self.0.as_ptr()) };
        Self(self.0)
    }
}

impl UnstructuredParcelable for HardwareBuffer {
    fn write_to_parcel(&self, parcel: &mut BorrowedParcel) -> Result<(), StatusCode> {
        let status =
        // SAFETY: The AHardwareBuffer pointer we pass is guaranteed to be non-null and valid
        // because it must have been allocated by `AHardwareBuffer_allocate`,
        // `AHardwareBuffer_readFromParcel` or the caller of `from_raw` and we have not yet
        // released it.
            unsafe { AHardwareBuffer_writeToParcel(self.0.as_ptr(), parcel.as_native_mut()) };
        status_result(status)
    }

    fn from_parcel(parcel: &BorrowedParcel) -> Result<Self, StatusCode> {
        let mut buffer = null_mut();

        let status =
        // SAFETY: Both pointers must be valid because they are obtained from references.
        // `AHardwareBuffer_readFromParcel` doesn't store them or do anything else special
        // with them. If it returns success then it will have allocated a new
        // `AHardwareBuffer` and incremented the reference count, so we can use it until we
        // release it.
            unsafe { AHardwareBuffer_readFromParcel(parcel.as_native(), &mut buffer) };

        status_result(status)?;

        Ok(Self(
            NonNull::new(buffer).expect(
                "AHardwareBuffer_readFromParcel returned success but didn't allocate buffer",
            ),
        ))
    }
}

impl_deserialize_for_unstructured_parcelable!(HardwareBuffer);
impl_serialize_for_unstructured_parcelable!(HardwareBuffer);

// SAFETY: The underlying *AHardwareBuffers can be moved between threads.
unsafe impl Send for HardwareBuffer {}

// SAFETY: The underlying *AHardwareBuffers can be used from multiple threads.
//
// AHardwareBuffers are backed by C++ GraphicBuffers, which are mostly immutable. The only cases
// where they are not immutable are:
//
//   - reallocation (which is never actually done across the codebase and requires special
//     privileges/platform code access to do)
//   - "locking" for reading/writing (which is explicitly allowed to be done across multiple threads
//     according to the docs on the underlying gralloc calls)
unsafe impl Sync for HardwareBuffer {}

/// A guard for when a `HardwareBuffer` is locked.
///
/// The `HardwareBuffer` will be unlocked when this is dropped, or may be unlocked via
/// [`HardwareBuffer::unlock_with_fence`].
#[derive(Debug)]
pub struct HardwareBufferGuard<'a> {
    buffer: &'a HardwareBuffer,
    /// The address of the buffer in memory.
    pub address: NonNull<c_void>,
}

impl<'a> Drop for HardwareBufferGuard<'a> {
    fn drop(&mut self) {
        self.buffer
            .unlock()
            .expect("Failed to unlock HardwareBuffer when dropping HardwareBufferGuard");
    }
}

/// A guard for when a `HardwareBuffer` is locked, with additional information about the number of
/// bytes per pixel and stride.
#[derive(Debug)]
pub struct LockedBufferInfo<'a> {
    /// The locked buffer guard.
    pub guard: HardwareBufferGuard<'a>,
    /// The number of bytes used for each pixel in the buffer.
    pub bytes_per_pixel: u32,
    /// The stride in bytes between rows in the buffer.
    pub stride: u32,
}

/// A guard for a single plane of a locked `HardwareBuffer`, with additional information about the
/// stride.
#[derive(Debug)]
pub struct PlaneGuard<'a> {
    /// The locked buffer guard.
    pub guard: HardwareBufferGuard<'a>,
    /// The stride in bytes between the color channel for one pixel to the next pixel.
    pub pixel_stride: u32,
    /// The stride in bytes between rows in the buffer.
    pub row_stride: u32,
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn create_valid_buffer_returns_ok() {
        let buffer = HardwareBuffer::new(&HardwareBufferDescription::new(
            512,
            512,
            1,
            AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
            AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
            0,
        ));
        assert!(buffer.is_some());
    }

    #[test]
    fn create_invalid_buffer_returns_err() {
        let buffer = HardwareBuffer::new(&HardwareBufferDescription::new(
            512,
            512,
            1,
            0,
            AHardwareBuffer_UsageFlags(0),
            0,
        ));
        assert!(buffer.is_none());
    }

    #[test]
    fn from_raw_allows_getters() {
        let buffer_desc = ffi::AHardwareBuffer_Desc {
            width: 1024,
            height: 512,
            layers: 1,
            format: AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
            usage: AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN.0,
            stride: 0,
            rfu0: 0,
            rfu1: 0,
        };
        let mut raw_buffer_ptr = ptr::null_mut();

        // SAFETY: The pointers are valid because they come from references, and
        // `AHardwareBuffer_allocate` doesn't retain them after it returns.
        let status = unsafe { ffi::AHardwareBuffer_allocate(&buffer_desc, &mut raw_buffer_ptr) };
        assert_eq!(status, 0);

        // SAFETY: The pointer must be valid because it was just allocated successfully, and we
        // don't use it after calling this.
        let buffer = unsafe { HardwareBuffer::from_raw(NonNull::new(raw_buffer_ptr).unwrap()) };
        assert_eq!(buffer.description().width(), 1024);
    }

    #[test]
    fn basic_getters() {
        let buffer = HardwareBuffer::new(&HardwareBufferDescription::new(
            1024,
            512,
            1,
            AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
            AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
            0,
        ))
        .expect("Buffer with some basic parameters was not created successfully");

        let description = buffer.description();
        assert_eq!(description.width(), 1024);
        assert_eq!(description.height(), 512);
        assert_eq!(description.layers(), 1);
        assert_eq!(
            description.format(),
            AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM
        );
        assert_eq!(
            description.usage(),
            AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN
        );
    }

    #[test]
    fn id_getter() {
        let buffer = HardwareBuffer::new(&HardwareBufferDescription::new(
            1024,
            512,
            1,
            AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
            AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
            0,
        ))
        .expect("Buffer with some basic parameters was not created successfully");

        assert_ne!(0, buffer.id());
    }

    #[test]
    fn clone() {
        let buffer = HardwareBuffer::new(&HardwareBufferDescription::new(
            1024,
            512,
            1,
            AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
            AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
            0,
        ))
        .expect("Buffer with some basic parameters was not created successfully");
        let buffer2 = buffer.clone();

        assert_eq!(buffer, buffer2);
    }

    #[test]
    fn into_raw() {
        let buffer = HardwareBuffer::new(&HardwareBufferDescription::new(
            1024,
            512,
            1,
            AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
            AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
            0,
        ))
        .expect("Buffer with some basic parameters was not created successfully");
        let buffer2 = buffer.clone();

        let raw_buffer = buffer.into_raw();
        // SAFETY: This is the same pointer we had before.
        let remade_buffer = unsafe { HardwareBuffer::from_raw(raw_buffer) };

        assert_eq!(remade_buffer, buffer2);
    }

    #[test]
    fn native_handle_and_back() {
        let buffer_description = HardwareBufferDescription::new(
            1024,
            512,
            1,
            AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
            AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
            1024,
        );
        let buffer = HardwareBuffer::new(&buffer_description)
            .expect("Buffer with some basic parameters was not created successfully");

        let native_handle =
            buffer.cloned_native_handle().expect("Failed to get native handle for buffer");
        let buffer2 = HardwareBuffer::create_from_handle(&native_handle, &buffer_description)
            .expect("Failed to create buffer from native handle");

        assert_eq!(buffer.description(), buffer_description);
        assert_eq!(buffer2.description(), buffer_description);
    }

    #[test]
    fn lock() {
        let buffer = HardwareBuffer::new(&HardwareBufferDescription::new(
            1024,
            512,
            1,
            AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
            AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
            0,
        ))
        .expect("Failed to create buffer");

        // SAFETY: No other threads or processes have access to the buffer.
        let guard = unsafe {
            buffer.lock(
                AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
                None,
                None,
            )
        }
        .unwrap();

        drop(guard);
    }

    #[test]
    fn lock_with_rect() {
        let buffer = HardwareBuffer::new(&HardwareBufferDescription::new(
            1024,
            512,
            1,
            AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
            AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
            0,
        ))
        .expect("Failed to create buffer");
        let rect = ARect { left: 10, right: 20, top: 35, bottom: 45 };

        // SAFETY: No other threads or processes have access to the buffer.
        let guard = unsafe {
            buffer.lock(
                AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
                None,
                Some(&rect),
            )
        }
        .unwrap();

        drop(guard);
    }

    #[test]
    fn unlock_with_fence() {
        let buffer = HardwareBuffer::new(&HardwareBufferDescription::new(
            1024,
            512,
            1,
            AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
            AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
            0,
        ))
        .expect("Failed to create buffer");

        // SAFETY: No other threads or processes have access to the buffer.
        let guard = unsafe {
            buffer.lock(
                AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
                None,
                None,
            )
        }
        .unwrap();

        buffer.unlock_with_fence(guard).unwrap();
    }

    #[test]
    fn lock_with_info() {
        const WIDTH: u32 = 1024;
        let buffer = HardwareBuffer::new(&HardwareBufferDescription::new(
            WIDTH,
            512,
            1,
            AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
            AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
            0,
        ))
        .expect("Failed to create buffer");

        // SAFETY: No other threads or processes have access to the buffer.
        let info = unsafe {
            buffer.lock_and_get_info(
                AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,
                None,
                None,
            )
        }
        .unwrap();

        assert_eq!(info.bytes_per_pixel, 4);
        assert_eq!(info.stride, WIDTH * 4);
        drop(info);
    }
}