Struct CVPixelBuffer 

pub struct CVPixelBuffer(/* private fields */);

Owned wrapper around Apple’s CVPixelBufferRef.

Implementations

impl CVPixelBuffer

pub unsafe fn from_raw(ptr: *mut c_void) -> Option<CVPixelBuffer>

Adopts a +1 retained CVPixelBufferRef and returns None for null.

Safety

A non-null ptr must be a live CVPixelBufferRef of the exact type carrying one retain transferred to this wrapper. The caller must not release or separately adopt that transferred retain.

pub unsafe fn from_raw_borrowed(ptr: *mut c_void) -> Option<CVPixelBuffer>

Retains a +0 borrowed CVPixelBufferRef and returns an owned wrapper.

Safety

A non-null ptr must be a live CVPixelBufferRef of the exact type for the duration of the retain call.

pub const unsafe fn from_ptr(ptr: *mut c_void) -> CVPixelBuffer

Wraps a raw CVPixelBufferRef by taking ownership without retaining it.

Safety

ptr must be a non-null, live CVPixelBufferRef of the exact type carrying one retain transferred to this wrapper.

pub const fn as_ptr(&self) -> *mut c_void

Borrows the raw +0 CVPixelBufferRef while self remains alive.

pub fn create( width: usize, height: usize, pixel_format: u32, ) -> Result<CVPixelBuffer, i32>

Create a new pixel buffer with the specified dimensions and pixel format

Arguments

• width - Width of the pixel buffer in pixels
• height - Height of the pixel buffer in pixels
• pixel_format - Pixel format type (e.g., 0x42475241 for BGRA)

Errors

Returns a Core Video error code if the pixel buffer creation fails.

Examples

use apple_cf::cv::CVPixelBuffer;

// Create a 1920x1080 BGRA pixel buffer
let buffer = CVPixelBuffer::create(1920, 1080, 0x42475241)
    .expect("Failed to create pixel buffer");

assert_eq!(buffer.width(), 1920);
assert_eq!(buffer.height(), 1080);
assert_eq!(buffer.pixel_format(), 0x42475241);

pub unsafe fn create_with_bytes( width: usize, height: usize, pixel_format: u32, base_address: *mut c_void, bytes_per_row: usize, ) -> Result<CVPixelBuffer, i32>

Create a pixel buffer from existing memory

Arguments

• width - Width of the pixel buffer in pixels
• height - Height of the pixel buffer in pixels
• pixel_format - Pixel format type (e.g., 0x42475241 for BGRA)
• base_address - Pointer to pixel data
• bytes_per_row - Number of bytes per row

Safety

The caller must ensure that:

• base_address points to valid memory
• Memory remains valid for the lifetime of the pixel buffer
• bytes_per_row correctly represents the memory layout

Errors

Returns a Core Video error code if the pixel buffer creation fails.

Examples

use apple_cf::cv::CVPixelBuffer;

// Create pixel data (100x100 BGRA image)
let width = 100;
let height = 100;
let bytes_per_pixel = 4; // BGRA
let bytes_per_row = width * bytes_per_pixel;
let mut pixel_data = vec![0u8; width * height * bytes_per_pixel];

// Fill with blue color
for y in 0..height {
    for x in 0..width {
        let offset = y * bytes_per_row + x * bytes_per_pixel;
        pixel_data[offset] = 255;     // B
        pixel_data[offset + 1] = 0;   // G
        pixel_data[offset + 2] = 0;   // R
        pixel_data[offset + 3] = 255; // A
    }
}

// Create pixel buffer from the data
let buffer = unsafe {
    CVPixelBuffer::create_with_bytes(
        width,
        height,
        0x42475241, // BGRA
        pixel_data.as_mut_ptr() as *mut std::ffi::c_void,
        bytes_per_row,
    )
}.expect("Failed to create pixel buffer");

assert_eq!(buffer.width(), width);
assert_eq!(buffer.height(), height);

pub fn fill_extended_pixels(&self) -> Result<(), i32>

Fill the extended pixels of a pixel buffer

This is useful for pixel buffers that have been created with extended pixels enabled, to ensure proper edge handling for effects and filters.

Errors

Returns a Core Video error code if the operation fails.

pub unsafe fn create_with_planar_bytes( width: usize, height: usize, pixel_format: u32, plane_base_addresses: &[*mut c_void], plane_widths: &[usize], plane_heights: &[usize], plane_bytes_per_row: &[usize], ) -> Result<CVPixelBuffer, i32>

Create a pixel buffer with planar bytes

Safety

The caller must ensure that:

• plane_base_addresses points to valid memory for each plane
• Memory remains valid for the lifetime of the pixel buffer
• All plane parameters correctly represent the memory layout

Errors

Returns a Core Video error code if the pixel buffer creation fails.

pub fn create_with_io_surface(surface: &IOSurface) -> Result<CVPixelBuffer, i32>

Create a pixel buffer from an IOSurface

Errors

Returns a Core Video error code if the pixel buffer creation fails.

pub fn type_id() -> usize

Get the Core Foundation type ID for CVPixelBuffer

pub fn data_size(&self) -> usize

Get the data size of the pixel buffer

pub fn is_planar(&self) -> bool

Check if the pixel buffer is planar

pub fn plane_count(&self) -> usize

Get the number of planes in the pixel buffer

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 fn extended_pixels(&self) -> (usize, usize, usize, usize)

Get the extended pixel information (left, right, top, bottom)

pub fn is_backed_by_io_surface(&self) -> bool

Check if the pixel buffer is backed by an IOSurface

pub fn width(&self) -> usize

Get the width of the pixel buffer in pixels

pub fn height(&self) -> usize

Returns the height of the pixel buffer in pixels.

pub fn pixel_format(&self) -> u32

Returns the Core Video pixel format type.

pub fn bytes_per_row(&self) -> usize

Returns the number of bytes in each row.

pub unsafe fn lock_raw(&self, flags: CVPixelBufferLockFlags) -> Result<(), i32>

Lock the base address for raw access.

This is a native synchronization/mapping operation and does not grant Rust-exclusive access to the backing bytes.

Safety

Every successful call must be paired exactly once with Self::unlock_raw using identical flags. The caller must not mix this protocol with a live RAII guard or allow any derived access to outlive the matching unlock.

Errors

Returns a Core Video error code if the lock operation fails.

pub unsafe fn unlock_raw( &self, flags: CVPixelBufferLockFlags, ) -> Result<(), i32>

Unlock the base address after raw access.

Safety

This call must balance exactly one successful Self::lock_raw call with identical flags. No pointer or reference derived from that mapping may be accessed after this call, and the mapping must not belong to an RAII guard.

Errors

Returns a Core Video error code if the unlock operation fails.

pub fn io_surface(&self) -> Option<IOSurface>

Get the IOSurface backing this pixel buffer

pub fn lock( &self, flags: CVPixelBufferLockFlags, ) -> Result<CVPixelBufferLockGuard<'_>, i32>

Lock the base address and return a guard for RAII-style access

Arguments

• flags - Lock flags (use CVPixelBufferLockFlags::READ_ONLY for read-only access)

Errors

Returns a Core Video error code if the lock operation fails.

Examples

use apple_cf::cv::{CVPixelBuffer, CVPixelBufferLockFlags};

fn read_buffer(buffer: &CVPixelBuffer) {
    let guard = buffer.lock(CVPixelBufferLockFlags::READ_ONLY).unwrap();
    // SAFETY: this scope excludes every native and retained alias that
    // could mutate or remap the pixel bytes.
    let data = unsafe { guard.as_slice() }.unwrap();
    println!("Buffer has {} bytes", data.len());
    // Buffer automatically unlocked when guard drops
}

pub fn lock_read_only(&self) -> Result<CVPixelBufferLockGuard<'_>, i32>

Lock the base address for read-only access

This is a convenience method equivalent to lock(CVPixelBufferLockFlags::READ_ONLY).

Errors

Returns a Core Video error code if the lock operation fails.

pub fn lock_read_write(&self) -> Result<CVPixelBufferLockGuard<'_>, i32>

Lock the base address for read-write access

This is a convenience method equivalent to lock(CVPixelBufferLockFlags::NONE).

Errors

Returns a Core Video error code if the lock operation fails.

Trait Implementations

impl Clone for CVPixelBuffer

fn clone(&self) -> CVPixelBuffer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CVPixelBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for CVPixelBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Drop for CVPixelBuffer

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Eq for CVPixelBuffer

impl Hash for CVPixelBuffer

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for CVPixelBuffer

fn eq(&self, other: &CVPixelBuffer) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Send for CVPixelBuffer

impl Sync for CVPixelBuffer