Struct CVPixelBufferLockGuard

pub struct CVPixelBufferLockGuard<'a> { /* private fields */ }

Expand description

RAII guard for locked CVPixelBuffer base address

Implementations§

§

impl CVPixelBufferLockGuard<'_>

pub fn base_address(&self) -> *const u8

Get the base address of the locked buffer.

Dereferencing the returned pointer is unsafe. The native lock keeps the mapping synchronized but does not guarantee Rust aliasing or immutability.

pub fn base_address_mut(&mut self) -> Option<*mut u8>

Get mutable base address (only valid for read-write locks).

Returns None if this is a read-only lock. Dereferencing the returned pointer requires unique access to the bytes across all Rust, native, retained, GPU, and cross-process aliases.

pub fn base_address_of_plane(&self, plane_index: usize) -> Option<*const u8>

Get the base address of a specific plane.

For multi-planar formats like YCbCr 4:2:0:

Plane 0: Y (luminance) data
Plane 1: CbCr (chrominance) data

Returns None if the plane index is out of bounds. Dereferencing the returned pointer is unsafe because the lock does not establish Rust immutability.

pub fn base_address_of_plane_mut( &mut self, plane_index: usize, ) -> Option<*mut u8>

Get the mutable base address of a specific plane.

Returns None if this is a read-only lock or the plane index is out of bounds. Dereferencing requires unique access across every alias.

pub fn width(&self) -> usize

Get the width of the buffer

pub fn height(&self) -> usize

Get the height of the buffer

pub fn bytes_per_row(&self) -> usize

Get bytes per row

pub fn data_size(&self) -> usize

Get the data size in bytes

This provides API parity with IOSurfaceLockGuard::data_size().

pub fn plane_count(&self) -> usize

Get the number of planes

pub fn width_of_plane(&self, plane_index: usize) -> usize

Get the width of a specific plane

pub fn height_of_plane(&self, plane_index: usize) -> usize

Get the height of a specific plane

pub fn bytes_per_row_of_plane(&self, plane_index: usize) -> usize

Get the bytes per row of a specific plane

pub unsafe fn as_slice(&self) -> Option<&[u8]>

Get non-planar data as a byte slice.

Returns None for planar buffers, missing base addresses, or lengths that cannot be represented by a Rust slice.

§Safety

For the returned reference’s lifetime, the mapped range must remain allocated, initialized, and immovable, and no Rust or native alias may mutate or remap any byte in it. The caller must also prevent any manual unlock of this mapping.

pub unsafe fn as_slice_mut(&mut self) -> Option<&mut [u8]>

Get non-planar data as a mutable byte slice.

Returns None for read-only locks, planar buffers, missing base addresses, or lengths that cannot be represented by a Rust slice.

§Safety

For the returned reference’s lifetime, this caller must have unique access to the full mapped range across every Rust, native, retained, GPU, and cross-process alias. The mapping must remain allocated, initialized, and locked.

pub unsafe fn plane_data(&self, plane_index: usize) -> Option<&[u8]>

Get a slice of plane data.

Returns the data for a specific plane as a byte slice.

Returns None if the plane index is out of bounds or its byte length cannot be represented.

§Safety

For the returned reference’s lifetime, the plane must remain allocated, initialized, locked, and immutable through every Rust and native alias.

pub unsafe fn plane_row( &self, plane_index: usize, row_index: usize, ) -> Option<&[u8]>

Get a specific row from a plane as a slice.

Returns None if the plane or row index is out of bounds.

§Safety

For the returned reference’s lifetime, the row must remain allocated, initialized, locked, and immutable through every Rust and native alias.

pub unsafe fn row(&self, row_index: usize) -> Option<&[u8]>

Get a specific non-planar row as a slice.

Returns None if the row index is out of bounds.

§Safety

For the returned reference’s lifetime, the row must remain allocated, initialized, locked, and immutable through every Rust and native alias.

pub unsafe fn cursor(&self) -> Option<Cursor<&[u8]>>

Access buffer with a standard std::io::Cursor

Returns a cursor over the buffer data that implements Read and Seek.

§Examples

use apple_cf::cv::{CVPixelBuffer, CVPixelBufferLockFlags};
use std::io::{Read, Seek, SeekFrom};

fn read_buffer(buffer: &CVPixelBuffer) {
    let guard = buffer.lock(CVPixelBufferLockFlags::READ_ONLY).unwrap();
    // SAFETY: no alias can mutate or remap the bytes while the cursor lives.
    let mut cursor = unsafe { guard.cursor() }.unwrap();

    // Read first 4 bytes
    let mut pixel = [0u8; 4];
    cursor.read_exact(&mut pixel).unwrap();

    // Seek to row 10
    let offset = 10 * guard.bytes_per_row();
    cursor.seek(SeekFrom::Start(offset as u64)).unwrap();
}