Struct IOSurfaceLockGuard

Source

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

Available on crate feature iosurface only.

Expand description

RAII guard for locked IOSurface

Balances a native surface mapping while the guard is held. The surface is automatically unlocked when this guard is dropped.

§Memory Access

The guard establishes native synchronization, not Rust exclusivity.

§Examples

use apple_cf::iosurface::{IOSurface, IOSurfaceLockOptions};

fn access_surface(surface: &IOSurface) -> Result<(), i32> {
    let guard = surface.lock(IOSurfaceLockOptions::READ_ONLY)?;
     
    // SAFETY: no alias can mutate or remap the surface while `data` lives.
    let data = unsafe { guard.as_slice() }.expect("surface base address");
     
    // Access a specific row
    if let Some(row) = unsafe { guard.row(0) } {
        println!("First row: {} bytes", row.len());
    }
     
    // Access a specific plane (for multi-planar formats)
    if let Some(plane_data) = unsafe { guard.plane_data(0) } {
        println!("Plane 0: {} bytes", plane_data.len());
    }
     
    Ok(())
}

Implementations§

Source §

impl IOSurfaceLockGuard<'_>

Source

pub fn width(&self) -> usize

Get the width of the surface in pixels

Source

pub fn height(&self) -> usize

Get the height of the surface in pixels

Source

pub fn bytes_per_row(&self) -> usize

Get the bytes per row of the surface

Source

pub fn alloc_size(&self) -> usize

Get the total allocation size in bytes

Source

pub fn data_size(&self) -> usize

Get the data size of the surface (alias for alloc_size)

Source

pub fn pixel_format(&self) -> u32

Get the pixel format of the surface

Source

pub fn plane_count(&self) -> usize

Get the number of planes in the surface

Source

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

Get the base address of the locked surface.

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

Source

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

Get the 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.

Source

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.

Source

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.

Source

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

Get a slice view of the surface allocation.

Returns None for a missing base address or a length that cannot be represented by a Rust slice.

§Safety

For the returned reference’s lifetime, the allocation must remain initialized, immovable, and locked, and no Rust or native alias may mutate or remap any byte in it.

Source

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

Get a mutable slice view of the surface allocation.

Returns None for read-only locks, a missing base address, or a length that cannot be represented by a Rust slice.

§Safety

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

Source

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

Get a specific 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 initialized, immovable, locked, and immutable through every Rust and native alias.

Source

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. The slice size is calculated from the plane’s height and bytes per row.

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 initialized, immovable, locked, and immutable through every Rust and native alias.

Source

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 initialized, immovable, locked, and immutable through every Rust and native alias.

Source

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

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

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

§Examples

use std::io::{Read, Seek, SeekFrom};
use apple_cf::iosurface::{IOSurface, IOSurfaceLockOptions};

fn read_surface(surface: &IOSurface) {
    let guard = surface.lock(IOSurfaceLockOptions::READ_ONLY).unwrap();
    // SAFETY: no alias can mutate or remap the surface 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();
}