Struct CVPixelBuffer

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

Expand description

Owned wrapper around Apple’s CVPixelBufferRef.

Implementations§

§

impl CVPixelBuffer

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

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

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

Wraps a raw CVPixelBufferRef by taking ownership without retaining it.

§Safety

The caller must ensure ptr is a valid +1 retained CVPixelBufferRef.

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

Returns the wrapped raw CVPixelBufferRef.

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 fn lock_raw(&self, flags: CVPixelBufferLockFlags) -> Result<(), i32>

Lock the base address for raw access

§Errors

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

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

Unlock the base address after raw access

§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();
    let data = guard.as_slice();
    println!("Buffer has {} bytes", data.len());
    // Buffer automatically unlocked when guard drops
}