feat(clients/android): OnFrameRendered display stage — HUD headline becomes capture→displayed
The long-deferred Android display stage (design/stats-unification.md; plan 4.1 of design/client-parity-and-network-resilience.md): AMediaCodec_setOnFrameRenderedCallback (API 26, under the minSdk-28 floor ⇒ hard-linked via ndk-sys) reports SurfaceFlinger's per-frame render timestamp, giving the HUD the spec's `display` = decoded→displayed term and the directly-measured capture→displayed end-to-end headline on both decode loops. Falls back per spec to the v1 capture→decoded endpoint on any window without render callbacks (the platform may drop them under load), and to it permanently if registration is refused. - The render timestamp arrives on CLOCK_MONOTONIC; it's re-based onto CLOCK_REALTIME against monotonic-now at callback time, which also cancels the (batchable) callback delivery lag. - The `ndk` crate exposes neither the callback nor the codec pointer needed to bind it raw, so the workspace pins `ndk` 0.9.0 to a vendored copy (clients/android/native/ vendor/ndk) whose ONLY change makes MediaCodec::as_ptr public — the "as_ptr patch". Workspace-excluded so host builds never compile it; drop when upstream exposes either. - nativeVideoStats grows to 26 doubles (22–25: dispValid, displayP50, e2eDispP50/P95; 0–21 unchanged for older readers); StatsOverlay moves headline endpoint + equation together so the equation always tiles the headline interval. Verified: host cargo check/test/clippy, aarch64-linux-android check/clippy, Kotlin app+kit+tests compile, roborazzi HUD render shows the full 4-term equation. Device verification rides plan 4.2's phone A/B. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,640 @@
|
||||
//! Bindings for [`AHardwareBuffer`]
|
||||
//!
|
||||
//! [`AHardwareBuffer`]: https://developer.android.com/ndk/reference/group/a-hardware-buffer#ahardwarebuffer
|
||||
|
||||
#![cfg(feature = "api-level-26")]
|
||||
|
||||
use std::{
|
||||
io::Result,
|
||||
mem::MaybeUninit,
|
||||
ops::Deref,
|
||||
os::{
|
||||
fd::{AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd},
|
||||
raw::c_void,
|
||||
},
|
||||
ptr::NonNull,
|
||||
};
|
||||
|
||||
use jni_sys::{jobject, JNIEnv};
|
||||
|
||||
use super::{hardware_buffer_format::HardwareBufferFormat, utils::status_to_io_result};
|
||||
|
||||
bitflags::bitflags! {
|
||||
/// Buffer usage flags, specifying how the buffer will be accessed.
|
||||
#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
|
||||
#[doc(alias = "AHardwareBuffer_UsageFlags")]
|
||||
pub struct HardwareBufferUsage : u64 {
|
||||
/// The buffer will never be locked for direct CPU reads using the
|
||||
/// [`HardwareBuffer::lock()`] function. Note that reading the buffer using OpenGL or Vulkan
|
||||
/// functions or memory mappings is still allowed.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_READ_NEVER")]
|
||||
const CPU_READ_NEVER = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_NEVER.0;
|
||||
/// The buffer will sometimes be locked for direct CPU reads using the
|
||||
/// [`HardwareBuffer::lock()`] function. Note that reading the buffer using OpenGL or Vulkan
|
||||
/// functions or memory mappings does not require the presence of this flag.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_READ_RARELY")]
|
||||
const CPU_READ_RARELY = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_RARELY.0;
|
||||
/// The buffer will often be locked for direct CPU reads using the
|
||||
/// [`HardwareBuffer::lock()`] function. Note that reading the buffer using OpenGL or Vulkan
|
||||
/// functions or memory mappings does not require the presence of this flag.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN")]
|
||||
const CPU_READ_OFTEN = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN.0;
|
||||
/// CPU read value mask.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_READ_MASK")]
|
||||
const CPU_READ_MASK = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_MASK.0;
|
||||
|
||||
/// The buffer will never be locked for direct CPU writes using the
|
||||
/// [`HardwareBuffer::lock()`] function. Note that writing the buffer using OpenGL or Vulkan
|
||||
/// functions or memory mappings is still allowed.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER")]
|
||||
const CPU_WRITE_NEVER = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER.0;
|
||||
/// The buffer will sometimes be locked for direct CPU writes using the
|
||||
/// [`HardwareBuffer::lock()`] function. Note that writing the buffer using OpenGL or Vulkan
|
||||
/// functions or memory mappings does not require the presence of this flag.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY")]
|
||||
const CPU_WRITE_RARELY = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY.0;
|
||||
/// The buffer will often be locked for direct CPU writes using the
|
||||
/// [`HardwareBuffer::lock()`] function. Note that writing the buffer using OpenGL or Vulkan
|
||||
/// functions or memory mappings does not require the presence of this flag.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN")]
|
||||
const CPU_WRITE_OFTEN = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN.0;
|
||||
/// CPU write value mask.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK")]
|
||||
const CPU_WRITE_MASK = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK.0;
|
||||
|
||||
/// The buffer will be read from by the GPU as a texture.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE")]
|
||||
const GPU_SAMPLED_IMAGE = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE.0;
|
||||
/// The buffer will be written to by the GPU as a framebuffer attachment.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER")]
|
||||
const GPU_FRAMEBUFFER = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER.0;
|
||||
/// 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
|
||||
/// [`HardwareBufferusage::GPU_FRAMEBUFFER`] to avoid this confusion.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT")]
|
||||
const GPU_COLOR_OUTPUT = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT.0;
|
||||
/// The buffer will be used as a composer HAL overlay layer.
|
||||
///
|
||||
/// This flag is currently only needed when using [`SurfaceTransaction::set_buffer()`] to
|
||||
/// set a buffer. In all other cases, the framework adds this flag internally to buffers
|
||||
/// that could be presented in a composer overlay. [`SurfaceTransaction::set_buffer()`]
|
||||
/// is special because it uses buffers allocated directly through
|
||||
/// [`HardwareBuffer::allocate()`] instead of buffers allocated by the framework.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY")]
|
||||
const COMPOSER_OVERLAY = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY.0;
|
||||
/// 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.
|
||||
///
|
||||
/// [`EGL_EXT_protected_content`]: https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_protected_content.txt
|
||||
/// [`GL_EXT_protected_textures`]: https://registry.khronos.org/OpenGL/extensions/EXT/EXT_protected_textures.txt
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT")]
|
||||
const PROTECTED_CONTENT = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT.0;
|
||||
/// The buffer will be read by a hardware video encoder.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VIDEO_ENCODE")]
|
||||
const VIDEO_ENCODE = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VIDEO_ENCODE.0;
|
||||
/// The buffer will be used for direct writes from sensors. When this flag is present, the
|
||||
/// format must be [`HardwareBufferFormat::Blob`].
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA")]
|
||||
const SENSOR_DIRECT_DATA = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA.0;
|
||||
/// The buffer will be used as a shader storage or uniform buffer object. When this flag is
|
||||
/// present, the format must be [`HardwareBufferFormat::Blob`].
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER")]
|
||||
const GPU_DATA_BUFFER = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER.0;
|
||||
/// 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`].
|
||||
///
|
||||
/// [`GL_EXT_EGL_image_storage`]: https://registry.khronos.org/OpenGL/extensions/EXT/EXT_EGL_image_storage.txt
|
||||
// TODO: This extension only exists for VG. Reported at https://issuetracker.google.com/issues/300602767#comment16
|
||||
/// [`GL_KHR_EGL_image`]: https://registry.khronos.org/OpenVG/extensions/KHR/VG_KHR_EGL_image.txt
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP")]
|
||||
const GPU_CUBE_MAP = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP.0;
|
||||
/// 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`].
|
||||
///
|
||||
/// [`GL_EXT_EGL_image_storage`]: https://registry.khronos.org/OpenGL/extensions/EXT/EXT_EGL_image_storage.txt
|
||||
// TODO: This extension only exists for VG. Reported at https://issuetracker.google.com/issues/300602767#comment16
|
||||
/// [`GL_KHR_EGL_image`]: https://registry.khronos.org/OpenVG/extensions/KHR/VG_KHR_EGL_image.txt
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE")]
|
||||
const GPU_MIPMAP_COMPLETE = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE.0;
|
||||
|
||||
// TODO: Only available in a newer NDK
|
||||
// /// 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 [`HardwareBufferFormat::GPU_COLOR_OUTPUT`] the buffer will behave similar to a
|
||||
// /// single-buffered window. When used with [`HardwareBufferFormat::COMPOSER_OVERLAY`], the
|
||||
// /// system will try to prioritize the buffer receiving an overlay plane & avoid caching it
|
||||
// /// in intermediate composition buffers.
|
||||
// #[doc(alias = "AHARDWAREBUFFER_USAGE_FRONT_BUFFER")]
|
||||
// const USAGE_FRONT_BUFFER = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_FRONT_BUFFER.0;
|
||||
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_0")]
|
||||
const VENDOR_0 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_0.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_1")]
|
||||
const VENDOR_1 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_1.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_2")]
|
||||
const VENDOR_2 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_2.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_3")]
|
||||
const VENDOR_3 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_3.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_4")]
|
||||
const VENDOR_4 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_4.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_5")]
|
||||
const VENDOR_5 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_5.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_6")]
|
||||
const VENDOR_6 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_6.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_7")]
|
||||
const VENDOR_7 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_7.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_8")]
|
||||
const VENDOR_8 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_8.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_9")]
|
||||
const VENDOR_9 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_9.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_10")]
|
||||
const VENDOR_10 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_10.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_11")]
|
||||
const VENDOR_11 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_11.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_12")]
|
||||
const VENDOR_12 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_12.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_13")]
|
||||
const VENDOR_13 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_13.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_14")]
|
||||
const VENDOR_14 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_14.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_15")]
|
||||
const VENDOR_15 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_15.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_16")]
|
||||
const VENDOR_16 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_16.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_17")]
|
||||
const VENDOR_17 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_17.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_18")]
|
||||
const VENDOR_18 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_18.0;
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_19")]
|
||||
const VENDOR_19 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_19.0;
|
||||
}
|
||||
}
|
||||
|
||||
impl HardwareBufferUsage {
|
||||
/// Helper to read [`HardwareBufferUsage::CPU_READ_MASK`] values.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_READ_MASK")]
|
||||
pub fn cpu_read(self) -> HardwareBufferUsage {
|
||||
self.intersection(Self::CPU_READ_MASK)
|
||||
}
|
||||
|
||||
/// Helper to read [`HardwareBufferUsage::CPU_WRITE_MASK`] values.
|
||||
#[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK")]
|
||||
pub fn cpu_write(self) -> HardwareBufferUsage {
|
||||
self.intersection(Self::CPU_WRITE_MASK)
|
||||
}
|
||||
}
|
||||
|
||||
pub type Rect = ffi::ARect;
|
||||
|
||||
fn construct<T>(with_ptr: impl FnOnce(*mut T) -> i32) -> Result<T> {
|
||||
let mut result = MaybeUninit::uninit();
|
||||
let status = with_ptr(result.as_mut_ptr());
|
||||
status_to_io_result(status).map(|()| unsafe { result.assume_init() })
|
||||
}
|
||||
|
||||
/// 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.
|
||||
///
|
||||
/// [`AHardwareBuffer *`]: https://developer.android.com/ndk/reference/group/a-hardware-buffer#ahardwarebuffer
|
||||
/// [`android.hardware.HardwareBuffer`]: https://developer.android.com/reference/android/hardware/HardwareBuffer
|
||||
/// [`eglGetNativeClientBufferANDROID`]: https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt
|
||||
/// [`eglCreateImageKHR`]: https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_image_base.txt
|
||||
/// [`EGL_ANDROID_get_native_client_buffer`]: https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt
|
||||
/// [`EGL_ANDROID_image_native_buffer`]: https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_image_native_buffer.txt
|
||||
/// [external memory]: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_memory.html
|
||||
/// [`VK_ANDROID_external_memory_android_hardware_buffer`]: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_ANDROID_external_memory_android_hardware_buffer.html
|
||||
#[derive(Debug)]
|
||||
pub struct HardwareBuffer {
|
||||
inner: NonNull<ffi::AHardwareBuffer>,
|
||||
}
|
||||
|
||||
impl HardwareBuffer {
|
||||
/// Create an _unowned_ [`HardwareBuffer`] from a native pointer
|
||||
///
|
||||
/// To wrap a strong reference (that is `release`d 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 unsafe fn from_ptr(ptr: NonNull<ffi::AHardwareBuffer>) -> Self {
|
||||
Self { inner: ptr }
|
||||
}
|
||||
|
||||
/// Returns the underlying [`ffi::AHardwareBuffer`] pointer
|
||||
///
|
||||
/// See the top-level [`HardwareBuffer`] struct documentation for (graphics) APIs that accept
|
||||
/// this pointer.
|
||||
pub fn as_ptr(&self) -> *mut ffi::AHardwareBuffer {
|
||||
self.inner.as_ptr()
|
||||
}
|
||||
|
||||
/// 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 fn allocate(desc: HardwareBufferDesc) -> Result<HardwareBufferRef> {
|
||||
unsafe {
|
||||
let ptr = construct(|res| ffi::AHardwareBuffer_allocate(&desc.into_native(), res))?;
|
||||
|
||||
Ok(HardwareBufferRef::from_ptr(NonNull::new_unchecked(ptr)))
|
||||
}
|
||||
}
|
||||
|
||||
/// 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()`].
|
||||
///
|
||||
/// [Java `HardwareBuffer`]: https://developer.android.com/reference/android/hardware/HardwareBuffer
|
||||
pub unsafe fn from_jni(env: *mut JNIEnv, hardware_buffer: jobject) -> Self {
|
||||
let ptr = ffi::AHardwareBuffer_fromHardwareBuffer(env, hardware_buffer);
|
||||
|
||||
Self::from_ptr(NonNull::new_unchecked(ptr))
|
||||
}
|
||||
|
||||
/// # Safety
|
||||
/// By calling this function, you assert that `env` is a valid pointer to a [`JNIEnv`].
|
||||
pub unsafe fn to_jni(&self, env: *mut JNIEnv) -> jobject {
|
||||
ffi::AHardwareBuffer_toHardwareBuffer(env, self.as_ptr())
|
||||
}
|
||||
|
||||
/// Return a description of the [`HardwareBuffer`] in the passed [`HardwareBufferDesc`] struct.
|
||||
pub fn describe(&self) -> HardwareBufferDesc {
|
||||
let desc = unsafe {
|
||||
let mut result = MaybeUninit::uninit();
|
||||
ffi::AHardwareBuffer_describe(self.as_ptr(), result.as_mut_ptr());
|
||||
result.assume_init()
|
||||
};
|
||||
|
||||
HardwareBufferDesc {
|
||||
width: desc.width,
|
||||
height: desc.height,
|
||||
layers: desc.layers,
|
||||
format: i32::try_from(desc.format)
|
||||
.expect("i32->u32 overflow in HardwareBuffer::describe()")
|
||||
.into(),
|
||||
usage: HardwareBufferUsage::from_bits_retain(desc.usage),
|
||||
stride: desc.stride,
|
||||
}
|
||||
}
|
||||
|
||||
/// 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.
|
||||
#[cfg(feature = "api-level-29")]
|
||||
pub fn is_supported(desc: HardwareBufferDesc) -> bool {
|
||||
let res = unsafe { ffi::AHardwareBuffer_isSupported(&desc.into_native()) };
|
||||
res == 1
|
||||
}
|
||||
|
||||
/// Get the system-wide unique id for this [`HardwareBuffer`].
|
||||
#[cfg(feature = "api-level-31")]
|
||||
#[doc(alias = "AHardwareBuffer_getId")]
|
||||
pub fn id(&self) -> Result<u64> {
|
||||
construct(|res| unsafe { ffi::AHardwareBuffer_getId(self.as_ptr(), res) })
|
||||
}
|
||||
|
||||
/// 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(
|
||||
&self,
|
||||
usage: HardwareBufferUsage,
|
||||
fence: Option<OwnedFd>,
|
||||
rect: Option<Rect>,
|
||||
) -> Result<*mut c_void> {
|
||||
let fence = fence.map_or(-1, IntoRawFd::into_raw_fd);
|
||||
let rect = match rect {
|
||||
Some(rect) => &rect,
|
||||
None => std::ptr::null(),
|
||||
};
|
||||
construct(|res| unsafe {
|
||||
ffi::AHardwareBuffer_lock(self.as_ptr(), usage.bits(), fence, rect, res)
|
||||
})
|
||||
}
|
||||
|
||||
/// Lock a [`HardwareBuffer`] for direct CPU access.
|
||||
///
|
||||
/// This function is the same as the above [`lock()`][Self::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`].
|
||||
#[cfg(feature = "api-level-29")]
|
||||
pub fn lock_and_get_info(
|
||||
&self,
|
||||
usage: HardwareBufferUsage,
|
||||
fence: Option<OwnedFd>,
|
||||
rect: Option<Rect>,
|
||||
) -> Result<LockedPlaneInfo> {
|
||||
let fence = fence.map_or(-1, IntoRawFd::into_raw_fd);
|
||||
let rect = match rect {
|
||||
Some(rect) => &rect,
|
||||
None => std::ptr::null(),
|
||||
};
|
||||
let mut virtual_address = MaybeUninit::uninit();
|
||||
let mut bytes_per_pixel = MaybeUninit::uninit();
|
||||
let mut bytes_per_stride = MaybeUninit::uninit();
|
||||
let status = unsafe {
|
||||
ffi::AHardwareBuffer_lockAndGetInfo(
|
||||
self.as_ptr(),
|
||||
usage.bits(),
|
||||
fence,
|
||||
rect,
|
||||
virtual_address.as_mut_ptr(),
|
||||
bytes_per_pixel.as_mut_ptr(),
|
||||
bytes_per_stride.as_mut_ptr(),
|
||||
)
|
||||
};
|
||||
status_to_io_result(status).map(|()| unsafe {
|
||||
LockedPlaneInfo {
|
||||
virtual_address: virtual_address.assume_init(),
|
||||
bytes_per_pixel: bytes_per_pixel.assume_init() as u32,
|
||||
bytes_per_stride: bytes_per_stride.assume_init() as u32,
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
/// Lock a potentially multi-planar [`HardwareBuffer`] for direct CPU access.
|
||||
///
|
||||
/// This function is similar to [`lock()`][Self::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()`][Self::lock()] documentation for all other locking semantics.
|
||||
#[cfg(feature = "api-level-29")]
|
||||
pub fn lock_planes(
|
||||
&self,
|
||||
usage: HardwareBufferUsage,
|
||||
fence: Option<OwnedFd>,
|
||||
rect: Option<Rect>,
|
||||
) -> Result<HardwareBufferPlanes> {
|
||||
let fence = fence.map_or(-1, IntoRawFd::into_raw_fd);
|
||||
let rect = match rect {
|
||||
Some(rect) => &rect,
|
||||
None => std::ptr::null(),
|
||||
};
|
||||
let planes = construct(|res| unsafe {
|
||||
ffi::AHardwareBuffer_lockPlanes(self.as_ptr(), usage.bits(), fence, rect, res)
|
||||
})?;
|
||||
|
||||
Ok(HardwareBufferPlanes {
|
||||
inner: planes,
|
||||
index: 0,
|
||||
})
|
||||
}
|
||||
|
||||
/// 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()`][Self::unlock_async()] for
|
||||
/// a non-blocking variant that returns a file descriptor to be signaled on unlocking instead.
|
||||
pub fn unlock(&self) -> Result<()> {
|
||||
let status = unsafe { ffi::AHardwareBuffer_unlock(self.as_ptr(), std::ptr::null_mut()) };
|
||||
status_to_io_result(status)
|
||||
}
|
||||
|
||||
/// 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()`][Self::unlock()] for a variant that
|
||||
/// blocks instead.
|
||||
pub fn unlock_async(&self) -> Result<Option<OwnedFd>> {
|
||||
let fence = construct(|res| unsafe { ffi::AHardwareBuffer_unlock(self.as_ptr(), res) })?;
|
||||
Ok(match fence {
|
||||
-1 => None,
|
||||
fence => Some(unsafe { OwnedFd::from_raw_fd(fence) }),
|
||||
})
|
||||
}
|
||||
|
||||
/// 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 recv_handle_from_unix_socket(socket_fd: BorrowedFd<'_>) -> Result<Self> {
|
||||
unsafe {
|
||||
let ptr = construct(|res| {
|
||||
ffi::AHardwareBuffer_recvHandleFromUnixSocket(socket_fd.as_raw_fd(), res)
|
||||
})?;
|
||||
|
||||
Ok(Self::from_ptr(NonNull::new_unchecked(ptr)))
|
||||
}
|
||||
}
|
||||
|
||||
/// 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 send_handle_to_unix_socket(&self, socket_fd: BorrowedFd<'_>) -> Result<()> {
|
||||
let status = unsafe {
|
||||
ffi::AHardwareBuffer_sendHandleToUnixSocket(self.as_ptr(), socket_fd.as_raw_fd())
|
||||
};
|
||||
status_to_io_result(status)
|
||||
}
|
||||
|
||||
/// 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.
|
||||
pub fn acquire(&self) -> HardwareBufferRef {
|
||||
unsafe {
|
||||
ffi::AHardwareBuffer_acquire(self.as_ptr());
|
||||
HardwareBufferRef::from_ptr(self.inner)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// A [`HardwareBuffer`] with an owned reference, that is released when dropped.
|
||||
/// It behaves much like a strong [`std::rc::Rc`] reference.
|
||||
#[derive(Debug)]
|
||||
pub struct HardwareBufferRef {
|
||||
inner: HardwareBuffer,
|
||||
}
|
||||
|
||||
impl HardwareBufferRef {
|
||||
/// Create an _owned_ [`HardwareBuffer`] from a native pointer
|
||||
///
|
||||
/// To wrap a weak reference (that is **not** `release`d 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`].
|
||||
pub unsafe fn from_ptr(ptr: NonNull<ffi::AHardwareBuffer>) -> Self {
|
||||
Self {
|
||||
inner: HardwareBuffer { inner: ptr },
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Deref for HardwareBufferRef {
|
||||
type Target = HardwareBuffer;
|
||||
|
||||
fn deref(&self) -> &Self::Target {
|
||||
&self.inner
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for HardwareBufferRef {
|
||||
fn drop(&mut self) {
|
||||
unsafe { ffi::AHardwareBuffer_release(self.inner.as_ptr()) }
|
||||
}
|
||||
}
|
||||
|
||||
impl Clone for HardwareBufferRef {
|
||||
fn clone(&self) -> Self {
|
||||
self.acquire()
|
||||
}
|
||||
}
|
||||
|
||||
/// Buffer description.
|
||||
///
|
||||
/// Used for allocating new buffers and querying parameters of existing ones.
|
||||
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
|
||||
pub struct HardwareBufferDesc {
|
||||
pub width: u32,
|
||||
pub height: u32,
|
||||
pub layers: u32,
|
||||
pub format: HardwareBufferFormat,
|
||||
pub usage: HardwareBufferUsage,
|
||||
pub stride: u32,
|
||||
}
|
||||
|
||||
impl HardwareBufferDesc {
|
||||
fn into_native(self) -> ffi::AHardwareBuffer_Desc {
|
||||
ffi::AHardwareBuffer_Desc {
|
||||
width: self.width,
|
||||
height: self.height,
|
||||
layers: self.layers,
|
||||
format: i32::from(self.format)
|
||||
.try_into()
|
||||
.expect("i32->u32 overflow in HardwareBufferDesc::into_native()"),
|
||||
usage: self.usage.bits(),
|
||||
stride: self.stride,
|
||||
rfu0: 0,
|
||||
rfu1: 0,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// A native [`AHardwareBuffer_Plane`]
|
||||
///
|
||||
/// Contains the same fields as [`ffi::AHardwareBuffer_Plane`].
|
||||
///
|
||||
/// [`AHardwareBuffer_Plane`]: https://developer.android.com/ndk/reference/group/a-hardware-buffer#ahardwarebuffer_plane
|
||||
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
|
||||
pub struct LockedPlaneInfo {
|
||||
pub virtual_address: *mut c_void,
|
||||
pub bytes_per_pixel: u32,
|
||||
pub bytes_per_stride: u32,
|
||||
}
|
||||
|
||||
/// Iterator over [`ffi::AHardwareBuffer_Planes`], containing a list of [`LockedPlaneInfo`].
|
||||
#[derive(Debug)]
|
||||
pub struct HardwareBufferPlanes {
|
||||
inner: ffi::AHardwareBuffer_Planes,
|
||||
index: u32,
|
||||
}
|
||||
|
||||
impl Iterator for HardwareBufferPlanes {
|
||||
type Item = LockedPlaneInfo;
|
||||
|
||||
fn next(&mut self) -> Option<LockedPlaneInfo> {
|
||||
if self.index == self.inner.planeCount {
|
||||
None
|
||||
} else {
|
||||
let plane = self.inner.planes[self.index as usize];
|
||||
self.index += 1;
|
||||
Some(LockedPlaneInfo {
|
||||
virtual_address: plane.data,
|
||||
bytes_per_pixel: plane.pixelStride,
|
||||
bytes_per_stride: plane.rowStride,
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user