apple_cf/cv/
pixel_buffer.rs

1//! `CVPixelBuffer` - Video pixel buffer
2
3use crate::cf::{AsCFType, CFDictionary, CFNumber, CFString};
4use crate::iosurface::IOSurface;
5use crate::{ffi, raw};
6use std::collections::HashMap;
7use std::fmt;
8use std::io::{self, Read, Seek, SeekFrom};
9use std::sync::Arc;
10
11/// Lock flags for `CVPixelBuffer`
12///
13/// This is a bitmask type matching Apple's `CVPixelBufferLockFlags`.
14///
15/// # Examples
16///
17/// ```
18/// use apple_cf::cv::CVPixelBufferLockFlags;
19///
20/// // Read-only lock
21/// let flags = CVPixelBufferLockFlags::READ_ONLY;
22/// assert!(flags.is_read_only());
23///
24/// // Read-write lock (default)
25/// let flags = CVPixelBufferLockFlags::NONE;
26/// assert!(!flags.is_read_only());
27/// ```
28#[repr(transparent)]
29#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
30pub struct CVPixelBufferLockFlags(u64);
31
32impl CVPixelBufferLockFlags {
33    /// No special options (read-write lock)
34    pub const NONE: Self = Self(0);
35
36    /// Read-only lock - use when you only need to read data.
37    /// This allows Core Video to keep caches valid.
38    pub const READ_ONLY: Self = Self(0x0000_0001);
39
40    /// Create from a raw `CVOptionFlags` value.
41    #[must_use]
42    pub const fn from_bits(bits: u64) -> Self {
43        Self(bits)
44    }
45
46    /// Return the raw `CVOptionFlags` bits.
47    #[must_use]
48    pub const fn bits(self) -> u64 {
49        self.0
50    }
51
52    /// Check if this is a read-only lock
53    #[must_use]
54    pub const fn is_read_only(self) -> bool {
55        (self.0 & Self::READ_ONLY.0) != 0
56    }
57
58    /// Check if no flags are set (read-write lock)
59    #[must_use]
60    pub const fn is_empty(self) -> bool {
61        self.0 == 0
62    }
63}
64
65impl From<CVPixelBufferLockFlags> for u64 {
66    fn from(flags: CVPixelBufferLockFlags) -> Self {
67        flags.0
68    }
69}
70
71#[derive(Debug)]
72/// Owned wrapper around Apple's `CVPixelBufferRef`.
73pub struct CVPixelBuffer(*mut std::ffi::c_void);
74
75impl PartialEq for CVPixelBuffer {
76    fn eq(&self, other: &Self) -> bool {
77        self.0 == other.0
78    }
79}
80
81impl Eq for CVPixelBuffer {}
82
83impl std::hash::Hash for CVPixelBuffer {
84    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
85        unsafe {
86            let hash_value = ffi::cv_pixel_buffer_hash(self.0);
87            hash_value.hash(state);
88        }
89    }
90}
91
92impl CVPixelBuffer {
93    /// Adopts a +1 retained `CVPixelBufferRef` and returns `None` for null.
94    ///
95    /// # Safety
96    ///
97    /// A non-null `ptr` must be a live `CVPixelBufferRef` of the exact type
98    /// carrying one retain transferred to this wrapper. The caller must not
99    /// release or separately adopt that transferred retain.
100    pub unsafe fn from_raw(ptr: *mut std::ffi::c_void) -> Option<Self> {
101        if ptr.is_null() {
102            None
103        } else {
104            Some(Self(ptr))
105        }
106    }
107
108    /// Retains a +0 borrowed `CVPixelBufferRef` and returns an owned wrapper.
109    ///
110    /// # Safety
111    ///
112    /// A non-null `ptr` must be a live `CVPixelBufferRef` of the exact type for
113    /// the duration of the retain call.
114    #[must_use]
115    pub unsafe fn from_raw_borrowed(ptr: *mut std::ffi::c_void) -> Option<Self> {
116        if ptr.is_null() {
117            None
118        } else {
119            let retained = unsafe { ffi::cv_pixel_buffer_retain(ptr) };
120            unsafe { Self::from_raw(retained) }
121        }
122    }
123
124    /// Wraps a raw `CVPixelBufferRef` by taking ownership without retaining it.
125    ///
126    /// # Safety
127    /// `ptr` must be a non-null, live `CVPixelBufferRef` of the exact type
128    /// carrying one retain transferred to this wrapper.
129    pub const unsafe fn from_ptr(ptr: *mut std::ffi::c_void) -> Self {
130        Self(ptr)
131    }
132
133    /// Borrows the raw +0 `CVPixelBufferRef` while `self` remains alive.
134    #[must_use]
135    pub const fn as_ptr(&self) -> *mut std::ffi::c_void {
136        self.0
137    }
138
139    /// Create a new pixel buffer with the specified dimensions and pixel format
140    ///
141    /// # Arguments
142    ///
143    /// * `width` - Width of the pixel buffer in pixels
144    /// * `height` - Height of the pixel buffer in pixels
145    /// * `pixel_format` - Pixel format type (e.g., 0x42475241 for BGRA)
146    ///
147    /// # Errors
148    ///
149    /// Returns a Core Video error code if the pixel buffer creation fails.
150    ///
151    /// # Examples
152    ///
153    /// ```
154    /// use apple_cf::cv::CVPixelBuffer;
155    ///
156    /// // Create a 1920x1080 BGRA pixel buffer
157    /// let buffer = CVPixelBuffer::create(1920, 1080, 0x42475241)
158    ///     .expect("Failed to create pixel buffer");
159    ///
160    /// assert_eq!(buffer.width(), 1920);
161    /// assert_eq!(buffer.height(), 1080);
162    /// assert_eq!(buffer.pixel_format(), 0x42475241);
163    /// ```
164    pub fn create(width: usize, height: usize, pixel_format: u32) -> Result<Self, i32> {
165        unsafe {
166            let mut pixel_buffer_ptr: *mut std::ffi::c_void = std::ptr::null_mut();
167            let status =
168                ffi::cv_pixel_buffer_create(width, height, pixel_format, &raw mut pixel_buffer_ptr);
169
170            if status == 0 && !pixel_buffer_ptr.is_null() {
171                Ok(Self(pixel_buffer_ptr))
172            } else {
173                Err(status)
174            }
175        }
176    }
177
178    /// Create a pixel buffer from existing memory
179    ///
180    /// # Arguments
181    ///
182    /// * `width` - Width of the pixel buffer in pixels
183    /// * `height` - Height of the pixel buffer in pixels
184    /// * `pixel_format` - Pixel format type (e.g., 0x42475241 for BGRA)
185    /// * `base_address` - Pointer to pixel data
186    /// * `bytes_per_row` - Number of bytes per row
187    ///
188    /// # Safety
189    ///
190    /// The caller must ensure that:
191    /// - `base_address` points to valid memory
192    /// - Memory remains valid for the lifetime of the pixel buffer
193    /// - `bytes_per_row` correctly represents the memory layout
194    ///
195    /// # Errors
196    ///
197    /// Returns a Core Video error code if the pixel buffer creation fails.
198    ///
199    /// # Examples
200    ///
201    /// ```
202    /// use apple_cf::cv::CVPixelBuffer;
203    ///
204    /// // Create pixel data (100x100 BGRA image)
205    /// let width = 100;
206    /// let height = 100;
207    /// let bytes_per_pixel = 4; // BGRA
208    /// let bytes_per_row = width * bytes_per_pixel;
209    /// let mut pixel_data = vec![0u8; width * height * bytes_per_pixel];
210    ///
211    /// // Fill with blue color
212    /// for y in 0..height {
213    ///     for x in 0..width {
214    ///         let offset = y * bytes_per_row + x * bytes_per_pixel;
215    ///         pixel_data[offset] = 255;     // B
216    ///         pixel_data[offset + 1] = 0;   // G
217    ///         pixel_data[offset + 2] = 0;   // R
218    ///         pixel_data[offset + 3] = 255; // A
219    ///     }
220    /// }
221    ///
222    /// // Create pixel buffer from the data
223    /// let buffer = unsafe {
224    ///     CVPixelBuffer::create_with_bytes(
225    ///         width,
226    ///         height,
227    ///         0x42475241, // BGRA
228    ///         pixel_data.as_mut_ptr() as *mut std::ffi::c_void,
229    ///         bytes_per_row,
230    ///     )
231    /// }.expect("Failed to create pixel buffer");
232    ///
233    /// assert_eq!(buffer.width(), width);
234    /// assert_eq!(buffer.height(), height);
235    /// ```
236    pub unsafe fn create_with_bytes(
237        width: usize,
238        height: usize,
239        pixel_format: u32,
240        base_address: *mut std::ffi::c_void,
241        bytes_per_row: usize,
242    ) -> Result<Self, i32> {
243        let mut pixel_buffer_ptr: *mut std::ffi::c_void = std::ptr::null_mut();
244        let status = ffi::cv_pixel_buffer_create_with_bytes(
245            width,
246            height,
247            pixel_format,
248            base_address,
249            bytes_per_row,
250            &raw mut pixel_buffer_ptr,
251        );
252
253        if status == 0 && !pixel_buffer_ptr.is_null() {
254            Ok(Self(pixel_buffer_ptr))
255        } else {
256            Err(status)
257        }
258    }
259
260    /// Fill the extended pixels of a pixel buffer
261    ///
262    /// This is useful for pixel buffers that have been created with extended pixels
263    /// enabled, to ensure proper edge handling for effects and filters.
264    ///
265    /// # Errors
266    ///
267    /// Returns a Core Video error code if the operation fails.
268    pub fn fill_extended_pixels(&self) -> Result<(), i32> {
269        unsafe {
270            let status = ffi::cv_pixel_buffer_fill_extended_pixels(self.0);
271            if status == 0 {
272                Ok(())
273            } else {
274                Err(status)
275            }
276        }
277    }
278
279    /// Create a pixel buffer with planar bytes
280    ///
281    /// # Safety
282    ///
283    /// The caller must ensure that:
284    /// - `plane_base_addresses` points to valid memory for each plane
285    /// - Memory remains valid for the lifetime of the pixel buffer
286    /// - All plane parameters correctly represent the memory layout
287    ///
288    /// # Errors
289    ///
290    /// Returns a Core Video error code if the pixel buffer creation fails.
291    pub unsafe fn create_with_planar_bytes(
292        width: usize,
293        height: usize,
294        pixel_format: u32,
295        plane_base_addresses: &[*mut std::ffi::c_void],
296        plane_widths: &[usize],
297        plane_heights: &[usize],
298        plane_bytes_per_row: &[usize],
299    ) -> Result<Self, i32> {
300        if plane_base_addresses.len() != plane_widths.len()
301            || plane_widths.len() != plane_heights.len()
302            || plane_heights.len() != plane_bytes_per_row.len()
303        {
304            return Err(-50); // paramErr
305        }
306
307        let mut pixel_buffer_ptr: *mut std::ffi::c_void = std::ptr::null_mut();
308        let status = ffi::cv_pixel_buffer_create_with_planar_bytes(
309            width,
310            height,
311            pixel_format,
312            plane_base_addresses.len(),
313            plane_base_addresses.as_ptr(),
314            plane_widths.as_ptr(),
315            plane_heights.as_ptr(),
316            plane_bytes_per_row.as_ptr(),
317            &raw mut pixel_buffer_ptr,
318        );
319
320        if status == 0 && !pixel_buffer_ptr.is_null() {
321            Ok(Self(pixel_buffer_ptr))
322        } else {
323            Err(status)
324        }
325    }
326
327    /// Create a pixel buffer from an `IOSurface`
328    ///
329    /// # Errors
330    ///
331    /// Returns a Core Video error code if the pixel buffer creation fails.
332    pub fn create_with_io_surface(surface: &IOSurface) -> Result<Self, i32> {
333        unsafe {
334            let mut pixel_buffer_ptr: *mut std::ffi::c_void = std::ptr::null_mut();
335            let status = ffi::cv_pixel_buffer_create_with_io_surface(
336                surface.as_ptr(),
337                &raw mut pixel_buffer_ptr,
338            );
339
340            if status == 0 && !pixel_buffer_ptr.is_null() {
341                Ok(Self(pixel_buffer_ptr))
342            } else {
343                Err(status)
344            }
345        }
346    }
347
348    /// Get the Core Foundation type ID for `CVPixelBuffer`
349    #[must_use]
350    pub fn type_id() -> usize {
351        unsafe { ffi::cv_pixel_buffer_get_type_id() }
352    }
353
354    /// Get the data size of the pixel buffer
355    #[must_use]
356    pub fn data_size(&self) -> usize {
357        unsafe { ffi::cv_pixel_buffer_get_data_size(self.0) }
358    }
359
360    /// Check if the pixel buffer is planar
361    #[must_use]
362    pub fn is_planar(&self) -> bool {
363        unsafe { ffi::cv_pixel_buffer_is_planar(self.0) }
364    }
365
366    /// Get the number of planes in the pixel buffer
367    #[must_use]
368    pub fn plane_count(&self) -> usize {
369        unsafe { ffi::cv_pixel_buffer_get_plane_count(self.0) }
370    }
371
372    /// Get the width of a specific plane
373    #[must_use]
374    pub fn width_of_plane(&self, plane_index: usize) -> usize {
375        unsafe { ffi::cv_pixel_buffer_get_width_of_plane(self.0, plane_index) }
376    }
377
378    /// Get the height of a specific plane
379    #[must_use]
380    pub fn height_of_plane(&self, plane_index: usize) -> usize {
381        unsafe { ffi::cv_pixel_buffer_get_height_of_plane(self.0, plane_index) }
382    }
383
384    /// Get the base address of a specific plane (internal use only)
385    ///
386    /// # Safety
387    /// Caller must ensure the buffer is locked before accessing the returned pointer.
388    fn base_address_of_plane_raw(&self, plane_index: usize) -> Option<*mut u8> {
389        unsafe {
390            let ptr = ffi::cv_pixel_buffer_get_base_address_of_plane(self.0, plane_index);
391            if ptr.is_null() {
392                None
393            } else {
394                Some(ptr.cast::<u8>())
395            }
396        }
397    }
398
399    /// Get the bytes per row of a specific plane
400    #[must_use]
401    pub fn bytes_per_row_of_plane(&self, plane_index: usize) -> usize {
402        unsafe { ffi::cv_pixel_buffer_get_bytes_per_row_of_plane(self.0, plane_index) }
403    }
404
405    /// Get the extended pixel information (left, right, top, bottom)
406    #[must_use]
407    pub fn extended_pixels(&self) -> (usize, usize, usize, usize) {
408        unsafe {
409            let mut left: usize = 0;
410            let mut right: usize = 0;
411            let mut top: usize = 0;
412            let mut bottom: usize = 0;
413            ffi::cv_pixel_buffer_get_extended_pixels(
414                self.0,
415                &raw mut left,
416                &raw mut right,
417                &raw mut top,
418                &raw mut bottom,
419            );
420            (left, right, top, bottom)
421        }
422    }
423
424    /// Check if the pixel buffer is backed by an `IOSurface`
425    #[must_use]
426    pub fn is_backed_by_io_surface(&self) -> bool {
427        self.io_surface().is_some()
428    }
429
430    /// Get the width of the pixel buffer in pixels
431    #[must_use]
432    pub fn width(&self) -> usize {
433        unsafe { ffi::cv_pixel_buffer_get_width(self.0) }
434    }
435
436    /// Returns the height of the pixel buffer in pixels.
437    #[must_use]
438    pub fn height(&self) -> usize {
439        unsafe { ffi::cv_pixel_buffer_get_height(self.0) }
440    }
441
442    /// Returns the Core Video pixel format type.
443    #[must_use]
444    pub fn pixel_format(&self) -> u32 {
445        unsafe { ffi::cv_pixel_buffer_get_pixel_format_type(self.0) }
446    }
447
448    /// Returns the number of bytes in each row.
449    #[must_use]
450    pub fn bytes_per_row(&self) -> usize {
451        unsafe { ffi::cv_pixel_buffer_get_bytes_per_row(self.0) }
452    }
453
454    /// Lock the base address for raw access.
455    ///
456    /// This is a native synchronization/mapping operation and does not grant
457    /// Rust-exclusive access to the backing bytes.
458    ///
459    /// # Safety
460    ///
461    /// Every successful call must be paired exactly once with
462    /// [`Self::unlock_raw`] using identical flags. The caller must not mix this
463    /// protocol with a live RAII guard or allow any derived access to outlive
464    /// the matching unlock.
465    ///
466    /// # Errors
467    ///
468    /// Returns a Core Video error code if the lock operation fails.
469    pub unsafe fn lock_raw(&self, flags: CVPixelBufferLockFlags) -> Result<(), i32> {
470        let result = unsafe { raw::CVPixelBufferLockBaseAddress(self.0.cast(), flags.bits()) };
471        if result == 0 {
472            Ok(())
473        } else {
474            Err(result)
475        }
476    }
477
478    /// Unlock the base address after raw access.
479    ///
480    /// # Safety
481    ///
482    /// This call must balance exactly one successful [`Self::lock_raw`] call
483    /// with identical flags. No pointer or reference derived from that mapping
484    /// may be accessed after this call, and the mapping must not belong to an
485    /// RAII guard.
486    ///
487    /// # Errors
488    ///
489    /// Returns a Core Video error code if the unlock operation fails.
490    pub unsafe fn unlock_raw(&self, flags: CVPixelBufferLockFlags) -> Result<(), i32> {
491        let result = unsafe { raw::CVPixelBufferUnlockBaseAddress(self.0.cast(), flags.bits()) };
492        if result == 0 {
493            Ok(())
494        } else {
495            Err(result)
496        }
497    }
498
499    /// Get the base address (internal use only)
500    ///
501    /// # Safety
502    /// Caller must ensure the buffer is locked before accessing the returned pointer.
503    fn base_address_raw(&self) -> Option<*mut u8> {
504        unsafe {
505            let ptr = ffi::cv_pixel_buffer_get_base_address(self.0);
506            if ptr.is_null() {
507                None
508            } else {
509                Some(ptr.cast::<u8>())
510            }
511        }
512    }
513
514    /// Get the `IOSurface` backing this pixel buffer
515    #[must_use]
516    pub fn io_surface(&self) -> Option<IOSurface> {
517        unsafe {
518            let ptr = ffi::cv_pixel_buffer_get_io_surface(self.0);
519            IOSurface::from_raw(ptr)
520        }
521    }
522
523    /// Lock the base address and return a guard for RAII-style access
524    ///
525    /// # Arguments
526    ///
527    /// * `flags` - Lock flags (use `CVPixelBufferLockFlags::READ_ONLY` for read-only access)
528    ///
529    /// # Errors
530    ///
531    /// Returns a Core Video error code if the lock operation fails.
532    ///
533    /// # Examples
534    ///
535    /// ```no_run
536    /// use apple_cf::cv::{CVPixelBuffer, CVPixelBufferLockFlags};
537    ///
538    /// fn read_buffer(buffer: &CVPixelBuffer) {
539    ///     let guard = buffer.lock(CVPixelBufferLockFlags::READ_ONLY).unwrap();
540    ///     // SAFETY: this scope excludes every native and retained alias that
541    ///     // could mutate or remap the pixel bytes.
542    ///     let data = unsafe { guard.as_slice() }.unwrap();
543    ///     println!("Buffer has {} bytes", data.len());
544    ///     // Buffer automatically unlocked when guard drops
545    /// }
546    /// ```
547    pub fn lock(&self, flags: CVPixelBufferLockFlags) -> Result<CVPixelBufferLockGuard<'_>, i32> {
548        unsafe { self.lock_raw(flags)? };
549        Ok(CVPixelBufferLockGuard {
550            buffer: self,
551            flags,
552        })
553    }
554
555    /// Lock the base address for read-only access
556    ///
557    /// This is a convenience method equivalent to `lock(CVPixelBufferLockFlags::READ_ONLY)`.
558    ///
559    /// # Errors
560    ///
561    /// Returns a Core Video error code if the lock operation fails.
562    pub fn lock_read_only(&self) -> Result<CVPixelBufferLockGuard<'_>, i32> {
563        self.lock(CVPixelBufferLockFlags::READ_ONLY)
564    }
565
566    /// Lock the base address for read-write access
567    ///
568    /// This is a convenience method equivalent to `lock(CVPixelBufferLockFlags::NONE)`.
569    ///
570    /// # Errors
571    ///
572    /// Returns a Core Video error code if the lock operation fails.
573    pub fn lock_read_write(&self) -> Result<CVPixelBufferLockGuard<'_>, i32> {
574        self.lock(CVPixelBufferLockFlags::NONE)
575    }
576}
577
578/// RAII guard for locked `CVPixelBuffer` base address
579pub struct CVPixelBufferLockGuard<'a> {
580    buffer: &'a CVPixelBuffer,
581    flags: CVPixelBufferLockFlags,
582}
583
584impl CVPixelBufferLockGuard<'_> {
585    fn non_planar_data_len(&self) -> Option<usize> {
586        if self.buffer.is_planar() {
587            return None;
588        }
589        let len = self.height().checked_mul(self.bytes_per_row())?;
590        (len <= self.data_size() && isize::try_from(len).is_ok()).then_some(len)
591    }
592
593    /// Get the base address of the locked buffer.
594    ///
595    /// Dereferencing the returned pointer is unsafe. The native lock keeps the
596    /// mapping synchronized but does not guarantee Rust aliasing or immutability.
597    #[must_use]
598    pub fn base_address(&self) -> *const u8 {
599        self.buffer
600            .base_address_raw()
601            .unwrap_or(std::ptr::null_mut())
602            .cast_const()
603    }
604
605    /// Get mutable base address (only valid for read-write locks).
606    ///
607    /// Returns `None` if this is a read-only lock.
608    /// Dereferencing the returned pointer requires unique access to the bytes
609    /// across all Rust, native, retained, GPU, and cross-process aliases.
610    pub fn base_address_mut(&mut self) -> Option<*mut u8> {
611        if self.flags.is_read_only() {
612            None
613        } else {
614            self.buffer.base_address_raw()
615        }
616    }
617
618    /// Get the base address of a specific plane.
619    ///
620    /// For multi-planar formats like YCbCr 4:2:0:
621    /// - Plane 0: Y (luminance) data
622    /// - Plane 1: `CbCr` (chrominance) data
623    ///
624    /// Returns `None` if the plane index is out of bounds. Dereferencing the
625    /// returned pointer is unsafe because the lock does not establish Rust
626    /// immutability.
627    pub fn base_address_of_plane(&self, plane_index: usize) -> Option<*const u8> {
628        self.buffer
629            .base_address_of_plane_raw(plane_index)
630            .map(<*mut u8>::cast_const)
631    }
632
633    /// Get the mutable base address of a specific plane.
634    ///
635    /// Returns `None` if this is a read-only lock or the plane index is out of
636    /// bounds. Dereferencing requires unique access across every alias.
637    pub fn base_address_of_plane_mut(&mut self, plane_index: usize) -> Option<*mut u8> {
638        if self.flags.is_read_only() {
639            return None;
640        }
641        self.buffer.base_address_of_plane_raw(plane_index)
642    }
643
644    /// Get the width of the buffer
645    #[must_use]
646    pub fn width(&self) -> usize {
647        self.buffer.width()
648    }
649
650    /// Get the height of the buffer
651    #[must_use]
652    pub fn height(&self) -> usize {
653        self.buffer.height()
654    }
655
656    /// Get bytes per row
657    #[must_use]
658    pub fn bytes_per_row(&self) -> usize {
659        self.buffer.bytes_per_row()
660    }
661
662    /// Get the data size in bytes
663    ///
664    /// This provides API parity with `IOSurfaceLockGuard::data_size()`.
665    #[must_use]
666    pub fn data_size(&self) -> usize {
667        self.buffer.data_size()
668    }
669
670    /// Get the number of planes
671    #[must_use]
672    pub fn plane_count(&self) -> usize {
673        self.buffer.plane_count()
674    }
675
676    /// Get the width of a specific plane
677    #[must_use]
678    pub fn width_of_plane(&self, plane_index: usize) -> usize {
679        self.buffer.width_of_plane(plane_index)
680    }
681
682    /// Get the height of a specific plane
683    #[must_use]
684    pub fn height_of_plane(&self, plane_index: usize) -> usize {
685        self.buffer.height_of_plane(plane_index)
686    }
687
688    /// Get the bytes per row of a specific plane
689    #[must_use]
690    pub fn bytes_per_row_of_plane(&self, plane_index: usize) -> usize {
691        self.buffer.bytes_per_row_of_plane(plane_index)
692    }
693
694    /// Get non-planar data as a byte slice.
695    ///
696    /// Returns `None` for planar buffers, missing base addresses, or lengths
697    /// that cannot be represented by a Rust slice.
698    ///
699    /// # Safety
700    ///
701    /// For the returned reference's lifetime, the mapped range must remain
702    /// allocated, initialized, and immovable, and no Rust or native alias may
703    /// mutate or remap any byte in it. The caller must also prevent any manual
704    /// unlock of this mapping.
705    #[must_use]
706    pub unsafe fn as_slice(&self) -> Option<&[u8]> {
707        let ptr = self.base_address();
708        let len = self.non_planar_data_len()?;
709        if len == 0 {
710            return Some(&[]);
711        }
712        if ptr.is_null() {
713            return None;
714        }
715        Some(unsafe { std::slice::from_raw_parts(ptr, len) })
716    }
717
718    /// Get non-planar data as a mutable byte slice.
719    ///
720    /// Returns `None` for read-only locks, planar buffers, missing base
721    /// addresses, or lengths that cannot be represented by a Rust slice.
722    ///
723    /// # Safety
724    ///
725    /// For the returned reference's lifetime, this caller must have unique
726    /// access to the full mapped range across every Rust, native, retained,
727    /// GPU, and cross-process alias. The mapping must remain allocated,
728    /// initialized, and locked.
729    pub unsafe fn as_slice_mut(&mut self) -> Option<&mut [u8]> {
730        let len = self.non_planar_data_len()?;
731        if len == 0 {
732            return Some(&mut []);
733        }
734        let ptr = self.base_address_mut()?;
735        Some(unsafe { std::slice::from_raw_parts_mut(ptr, len) })
736    }
737
738    /// Get a slice of plane data.
739    ///
740    /// Returns the data for a specific plane as a byte slice.
741    ///
742    /// Returns `None` if the plane index is out of bounds or its byte length
743    /// cannot be represented.
744    ///
745    /// # Safety
746    ///
747    /// For the returned reference's lifetime, the plane must remain allocated,
748    /// initialized, locked, and immutable through every Rust and native alias.
749    #[must_use]
750    pub unsafe fn plane_data(&self, plane_index: usize) -> Option<&[u8]> {
751        if !self.buffer.is_planar() || plane_index >= self.buffer.plane_count() {
752            return None;
753        }
754        let base = self.base_address_of_plane(plane_index)?;
755        let height = self.buffer.height_of_plane(plane_index);
756        let bytes_per_row = self.buffer.bytes_per_row_of_plane(plane_index);
757        let len = height.checked_mul(bytes_per_row)?;
758        if isize::try_from(len).is_err() {
759            return None;
760        }
761        Some(unsafe { std::slice::from_raw_parts(base, len) })
762    }
763
764    /// Get a specific row from a plane as a slice.
765    ///
766    /// Returns `None` if the plane or row index is out of bounds.
767    ///
768    /// # Safety
769    ///
770    /// For the returned reference's lifetime, the row must remain allocated,
771    /// initialized, locked, and immutable through every Rust and native alias.
772    #[must_use]
773    pub unsafe fn plane_row(&self, plane_index: usize, row_index: usize) -> Option<&[u8]> {
774        if !self.buffer.is_planar() || plane_index >= self.buffer.plane_count() {
775            return None;
776        }
777        let height = self.buffer.height_of_plane(plane_index);
778        if row_index >= height {
779            return None;
780        }
781        let base = self.base_address_of_plane(plane_index)?;
782        let bytes_per_row = self.buffer.bytes_per_row_of_plane(plane_index);
783        let plane_len = height.checked_mul(bytes_per_row)?;
784        let offset = row_index.checked_mul(bytes_per_row)?;
785        let end = offset.checked_add(bytes_per_row)?;
786        if end > plane_len || isize::try_from(bytes_per_row).is_err() {
787            return None;
788        }
789        Some(unsafe { std::slice::from_raw_parts(base.add(offset), bytes_per_row) })
790    }
791
792    /// Get a specific non-planar row as a slice.
793    ///
794    /// Returns `None` if the row index is out of bounds.
795    ///
796    /// # Safety
797    ///
798    /// For the returned reference's lifetime, the row must remain allocated,
799    /// initialized, locked, and immutable through every Rust and native alias.
800    #[must_use]
801    pub unsafe fn row(&self, row_index: usize) -> Option<&[u8]> {
802        if row_index >= self.height() {
803            return None;
804        }
805        let len = self.non_planar_data_len()?;
806        let ptr = self.base_address();
807        if ptr.is_null() {
808            return None;
809        }
810        let bytes_per_row = self.bytes_per_row();
811        let offset = row_index.checked_mul(bytes_per_row)?;
812        let end = offset.checked_add(bytes_per_row)?;
813        if end > len || isize::try_from(bytes_per_row).is_err() {
814            return None;
815        }
816        Some(unsafe { std::slice::from_raw_parts(ptr.add(offset), bytes_per_row) })
817    }
818
819    /// Access buffer with a standard `std::io::Cursor`
820    ///
821    /// Returns a cursor over the buffer data that implements `Read` and `Seek`.
822    ///
823    /// # Examples
824    ///
825    /// ```no_run
826    /// use apple_cf::cv::{CVPixelBuffer, CVPixelBufferLockFlags};
827    /// use std::io::{Read, Seek, SeekFrom};
828    ///
829    /// fn read_buffer(buffer: &CVPixelBuffer) {
830    ///     let guard = buffer.lock(CVPixelBufferLockFlags::READ_ONLY).unwrap();
831    ///     // SAFETY: no alias can mutate or remap the bytes while the cursor lives.
832    ///     let mut cursor = unsafe { guard.cursor() }.unwrap();
833    ///
834    ///     // Read first 4 bytes
835    ///     let mut pixel = [0u8; 4];
836    ///     cursor.read_exact(&mut pixel).unwrap();
837    ///
838    ///     // Seek to row 10
839    ///     let offset = 10 * guard.bytes_per_row();
840    ///     cursor.seek(SeekFrom::Start(offset as u64)).unwrap();
841    /// }
842    /// ```
843    ///
844    /// # Safety
845    ///
846    /// The same immutability and mapping guarantees as [`Self::as_slice`] must
847    /// hold for the cursor's lifetime.
848    #[must_use]
849    pub unsafe fn cursor(&self) -> Option<io::Cursor<&[u8]>> {
850        unsafe { self.as_slice() }.map(io::Cursor::new)
851    }
852
853    /// Get raw pointer to buffer data
854    #[must_use]
855    pub fn as_ptr(&self) -> *const u8 {
856        self.base_address()
857    }
858
859    /// Get mutable raw pointer to buffer data (only valid for read-write locks)
860    ///
861    /// Returns `None` if this is a read-only lock.
862    pub fn as_mut_ptr(&mut self) -> Option<*mut u8> {
863        self.base_address_mut()
864    }
865
866    /// Check if this is a read-only lock
867    #[must_use]
868    pub const fn is_read_only(&self) -> bool {
869        self.flags.is_read_only()
870    }
871
872    /// Get the lock options
873    #[must_use]
874    pub const fn options(&self) -> CVPixelBufferLockFlags {
875        self.flags
876    }
877
878    /// Get the pixel format
879    #[must_use]
880    pub fn pixel_format(&self) -> u32 {
881        self.buffer.pixel_format()
882    }
883}
884
885impl Drop for CVPixelBufferLockGuard<'_> {
886    fn drop(&mut self) {
887        let _ = unsafe { self.buffer.unlock_raw(self.flags) };
888    }
889}
890
891impl std::fmt::Debug for CVPixelBufferLockGuard<'_> {
892    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
893        f.debug_struct("CVPixelBufferLockGuard")
894            .field("flags", &self.flags)
895            .field("buffer_size", &(self.buffer.width(), self.buffer.height()))
896            .finish()
897    }
898}
899
900crate::utils::retained::cf_retained!(
901    CVPixelBuffer,
902    retain = ffi::cv_pixel_buffer_retain,
903    release = ffi::cv_pixel_buffer_release,
904);
905
906// SAFETY: `CVPixelBufferRef` is a Core Foundation type whose retain/release
907// operations are thread-safe. Our wrapper only holds the opaque pointer, and
908// native mapping operations are thread-safe. Byte dereferencing has a separate
909// unsafe contract because a lock does not establish Rust aliasing guarantees.
910unsafe impl Send for CVPixelBuffer {}
911unsafe impl Sync for CVPixelBuffer {}
912
913impl fmt::Display for CVPixelBuffer {
914    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
915        write!(
916            f,
917            "CVPixelBuffer({}x{}, format: 0x{:08X})",
918            self.width(),
919            self.height(),
920            self.pixel_format()
921        )
922    }
923}
924
925/// Flags controlling which unused buffers a pool flushes.
926#[repr(transparent)]
927#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
928pub struct CVPixelBufferPoolFlushFlags(u64);
929
930impl CVPixelBufferPoolFlushFlags {
931    /// Flush only buffers that have aged out.
932    pub const NONE: Self = Self(0);
933
934    /// Flush every unused buffer regardless of age.
935    pub const EXCESS_BUFFERS: Self = Self(1);
936
937    /// Create flags from raw `CVOptionFlags` bits.
938    #[must_use]
939    pub const fn from_bits(bits: u64) -> Self {
940        Self(bits)
941    }
942
943    /// Return the raw `CVOptionFlags` bits.
944    #[must_use]
945    pub const fn bits(self) -> u64 {
946        self.0
947    }
948}
949
950impl std::ops::BitOr for CVPixelBufferPoolFlushFlags {
951    type Output = Self;
952
953    fn bitor(self, rhs: Self) -> Self::Output {
954        Self(self.0 | rhs.0)
955    }
956}
957
958impl std::ops::BitOrAssign for CVPixelBufferPoolFlushFlags {
959    fn bitor_assign(&mut self, rhs: Self) {
960        self.0 |= rhs.0;
961    }
962}
963
964impl From<CVPixelBufferPoolFlushFlags> for u64 {
965    fn from(flags: CVPixelBufferPoolFlushFlags) -> Self {
966        flags.bits()
967    }
968}
969
970const CV_RETURN_WOULD_EXCEED_ALLOCATION_THRESHOLD: i32 = -6689;
971const PARAM_ERR: i32 = -50;
972
973#[derive(Debug)]
974struct CVPixelBufferPoolPolicy {
975    max_buffers: Option<usize>,
976    allocation_attributes: Option<CFDictionary>,
977}
978
979// SAFETY: The policy is immutable after construction. Its cached dictionary is
980// immutable and only shared for Core Foundation reads and retain/release.
981#[allow(clippy::non_send_fields_in_send_ty)]
982unsafe impl Send for CVPixelBufferPoolPolicy {}
983unsafe impl Sync for CVPixelBufferPoolPolicy {}
984
985impl CVPixelBufferPoolPolicy {
986    const fn unlimited() -> Self {
987        Self {
988            max_buffers: None,
989            allocation_attributes: None,
990        }
991    }
992
993    fn new(max_buffers: usize) -> Result<Self, i32> {
994        if max_buffers == 0 {
995            return Ok(Self::unlimited());
996        }
997
998        let threshold = i64::try_from(max_buffers).map_err(|_| PARAM_ERR)?;
999        let key = retained_cf_string(
1000            unsafe { raw::kCVPixelBufferPoolAllocationThresholdKey },
1001            "kCVPixelBufferPoolAllocationThresholdKey",
1002        );
1003        let value = CFNumber::from_i64(threshold);
1004        let attributes = CFDictionary::from_pairs(&[(&key, &value)]);
1005
1006        Ok(Self {
1007            max_buffers: Some(max_buffers),
1008            allocation_attributes: Some(attributes),
1009        })
1010    }
1011
1012    const fn max_buffers(&self) -> usize {
1013        match self.max_buffers {
1014            Some(max_buffers) => max_buffers,
1015            None => 0,
1016        }
1017    }
1018}
1019
1020fn retained_cf_string(ptr: raw::CFStringRef, symbol: &'static str) -> CFString {
1021    unsafe { CFString::from_raw_borrowed(ptr.cast_mut().cast()) }
1022        .unwrap_or_else(|| panic!("{symbol} was NULL"))
1023}
1024
1025fn pool_pixel_buffer_attributes(
1026    width: usize,
1027    height: usize,
1028    pixel_format: u32,
1029) -> Result<CFDictionary, i32> {
1030    let width = u64::try_from(width).map_err(|_| PARAM_ERR)?;
1031    let height = u64::try_from(height).map_err(|_| PARAM_ERR)?;
1032    let width_key = retained_cf_string(
1033        unsafe { raw::kCVPixelBufferWidthKey },
1034        "kCVPixelBufferWidthKey",
1035    );
1036    let height_key = retained_cf_string(
1037        unsafe { raw::kCVPixelBufferHeightKey },
1038        "kCVPixelBufferHeightKey",
1039    );
1040    let pixel_format_key = retained_cf_string(
1041        unsafe { raw::kCVPixelBufferPixelFormatTypeKey },
1042        "kCVPixelBufferPixelFormatTypeKey",
1043    );
1044    let io_surface_key = retained_cf_string(
1045        unsafe { raw::kCVPixelBufferIOSurfacePropertiesKey },
1046        "kCVPixelBufferIOSurfacePropertiesKey",
1047    );
1048    let width_value = CFNumber::from_u64(width);
1049    let height_value = CFNumber::from_u64(height);
1050    let pixel_format_value = CFNumber::from_u64(u64::from(pixel_format));
1051    let io_surface_properties = CFDictionary::from_pairs(&[]);
1052    let pairs: [(&dyn AsCFType, &dyn AsCFType); 4] = [
1053        (&width_key, &width_value),
1054        (&height_key, &height_value),
1055        (&pixel_format_key, &pixel_format_value),
1056        (&io_surface_key, &io_surface_properties),
1057    ];
1058    Ok(CFDictionary::from_pairs(&pairs))
1059}
1060
1061/// Opaque handle to a native `CVPixelBufferPoolRef`.
1062pub struct CVPixelBufferPool {
1063    ptr: *mut std::ffi::c_void,
1064    policy: Arc<CVPixelBufferPoolPolicy>,
1065}
1066
1067// SAFETY: Core Video pool retain/release, allocation, and flush operations are
1068// thread-safe. The wrapper's shared allocation policy is immutable and
1069// thread-safe.
1070unsafe impl Send for CVPixelBufferPool {}
1071unsafe impl Sync for CVPixelBufferPool {}
1072
1073impl PartialEq for CVPixelBufferPool {
1074    fn eq(&self, other: &Self) -> bool {
1075        self.ptr == other.ptr
1076    }
1077}
1078
1079impl Eq for CVPixelBufferPool {}
1080
1081impl std::hash::Hash for CVPixelBufferPool {
1082    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
1083        unsafe { ffi::cf_type_hash(self.ptr) }.hash(state);
1084    }
1085}
1086
1087impl CVPixelBufferPool {
1088    /// Adopts a +1 retained native pool with no wrapper allocation threshold.
1089    ///
1090    /// # Safety
1091    ///
1092    /// A non-null `ptr` must be a live `CVPixelBufferPoolRef` carrying one
1093    /// retain transferred to this wrapper. The caller must not release or
1094    /// separately adopt that transferred retain.
1095    pub unsafe fn from_raw(ptr: *mut std::ffi::c_void) -> Option<Self> {
1096        if ptr.is_null() {
1097            None
1098        } else {
1099            Some(Self {
1100                ptr,
1101                policy: Arc::new(CVPixelBufferPoolPolicy::unlimited()),
1102            })
1103        }
1104    }
1105
1106    /// Adopts a +1 retained native pool and applies `max_buffers` to wrapper allocations.
1107    ///
1108    /// A zero threshold means unlimited. Native callers using [`Self::as_ptr`]
1109    /// can bypass this wrapper policy.
1110    ///
1111    /// # Safety
1112    ///
1113    /// A non-null `ptr` must be a live `CVPixelBufferPoolRef` carrying one
1114    /// retain transferred to this wrapper. On an error, ownership remains with
1115    /// the caller.
1116    ///
1117    /// # Errors
1118    ///
1119    /// Returns `paramErr` if `max_buffers` cannot be represented by Core Video.
1120    pub unsafe fn from_raw_with_max_buffers(
1121        ptr: *mut std::ffi::c_void,
1122        max_buffers: usize,
1123    ) -> Result<Option<Self>, i32> {
1124        if ptr.is_null() {
1125            return Ok(None);
1126        }
1127        let policy = Arc::new(CVPixelBufferPoolPolicy::new(max_buffers)?);
1128        Ok(Some(Self { ptr, policy }))
1129    }
1130
1131    /// Retains a +0 borrowed native pool with no wrapper allocation threshold.
1132    ///
1133    /// # Safety
1134    ///
1135    /// A non-null `ptr` must be a live `CVPixelBufferPoolRef` for the duration
1136    /// of the retain call.
1137    #[must_use]
1138    pub unsafe fn from_raw_borrowed(ptr: *mut std::ffi::c_void) -> Option<Self> {
1139        if ptr.is_null() {
1140            None
1141        } else {
1142            let retained = unsafe { raw::CVPixelBufferPoolRetain(ptr.cast()) };
1143            unsafe { Self::from_raw(retained.cast()) }
1144        }
1145    }
1146
1147    /// Retains a +0 borrowed native pool and applies `max_buffers` to wrapper allocations.
1148    ///
1149    /// # Safety
1150    ///
1151    /// A non-null `ptr` must be a live `CVPixelBufferPoolRef` for the duration
1152    /// of the retain call.
1153    ///
1154    /// # Errors
1155    ///
1156    /// Returns `paramErr` if `max_buffers` cannot be represented by Core Video.
1157    pub unsafe fn from_raw_borrowed_with_max_buffers(
1158        ptr: *mut std::ffi::c_void,
1159        max_buffers: usize,
1160    ) -> Result<Option<Self>, i32> {
1161        if ptr.is_null() {
1162            return Ok(None);
1163        }
1164        let policy = Arc::new(CVPixelBufferPoolPolicy::new(max_buffers)?);
1165        let retained = unsafe { raw::CVPixelBufferPoolRetain(ptr.cast()) };
1166        Ok(Some(Self {
1167            ptr: retained.cast(),
1168            policy,
1169        }))
1170    }
1171
1172    /// Wraps a raw `CVPixelBufferPoolRef` by taking ownership without retaining it.
1173    ///
1174    /// # Safety
1175    /// `ptr` must be a non-null, live `CVPixelBufferPoolRef` carrying one retain
1176    /// transferred to this wrapper.
1177    pub unsafe fn from_ptr(ptr: *mut std::ffi::c_void) -> Self {
1178        Self {
1179            ptr,
1180            policy: Arc::new(CVPixelBufferPoolPolicy::unlimited()),
1181        }
1182    }
1183
1184    /// Borrows the raw +0 native pool pointer while `self` remains alive.
1185    ///
1186    /// Allocations performed directly through this pointer bypass the wrapper's
1187    /// configured [`Self::max_buffers`] threshold.
1188    #[must_use]
1189    pub const fn as_ptr(&self) -> *mut std::ffi::c_void {
1190        self.ptr
1191    }
1192
1193    /// Wrapper-enforced allocation threshold, or zero when unlimited.
1194    #[must_use]
1195    pub fn max_buffers(&self) -> usize {
1196        self.policy.max_buffers()
1197    }
1198
1199    /// Create a new pixel buffer pool
1200    ///
1201    /// # Arguments
1202    ///
1203    /// * `width` - Width of pixel buffers in the pool
1204    /// * `height` - Height of pixel buffers in the pool
1205    /// * `pixel_format` - Pixel format type
1206    /// * `max_buffers` - Maximum number of buffers in the pool (0 for unlimited)
1207    ///
1208    /// # Errors
1209    ///
1210    /// Returns a Core Video error code if the pool creation fails.
1211    pub fn create(
1212        width: usize,
1213        height: usize,
1214        pixel_format: u32,
1215        max_buffers: usize,
1216    ) -> Result<Self, i32> {
1217        let policy = Arc::new(CVPixelBufferPoolPolicy::new(max_buffers)?);
1218        let pool_attributes = CFDictionary::from_pairs(&[]);
1219        let pixel_buffer_attributes = pool_pixel_buffer_attributes(width, height, pixel_format)?;
1220        let mut pool_ptr: raw::CVPixelBufferPoolRef = std::ptr::null_mut();
1221        unsafe {
1222            let status = raw::CVPixelBufferPoolCreate(
1223                std::ptr::null(),
1224                pool_attributes.as_ptr().cast(),
1225                pixel_buffer_attributes.as_ptr().cast(),
1226                &raw mut pool_ptr,
1227            );
1228
1229            if status == 0 && !pool_ptr.is_null() {
1230                Ok(Self {
1231                    ptr: pool_ptr.cast(),
1232                    policy,
1233                })
1234            } else {
1235                Err(status)
1236            }
1237        }
1238    }
1239
1240    fn create_pixel_buffer_with_dictionary(
1241        &self,
1242        auxiliary_attributes: Option<&CFDictionary>,
1243    ) -> Result<CVPixelBuffer, i32> {
1244        let mut pixel_buffer_ptr: raw::CVPixelBufferRef = std::ptr::null_mut();
1245        let status = unsafe {
1246            if let Some(attributes) = auxiliary_attributes {
1247                raw::CVPixelBufferPoolCreatePixelBufferWithAuxAttributes(
1248                    std::ptr::null(),
1249                    self.ptr.cast(),
1250                    attributes.as_ptr().cast(),
1251                    &raw mut pixel_buffer_ptr,
1252                )
1253            } else {
1254                raw::CVPixelBufferPoolCreatePixelBuffer(
1255                    std::ptr::null(),
1256                    self.ptr.cast(),
1257                    &raw mut pixel_buffer_ptr,
1258                )
1259            }
1260        };
1261
1262        if status == 0 && !pixel_buffer_ptr.is_null() {
1263            unsafe { CVPixelBuffer::from_raw(pixel_buffer_ptr.cast()) }.ok_or(status)
1264        } else {
1265            Err(status)
1266        }
1267    }
1268
1269    /// Create a pixel buffer while enforcing the configured allocation threshold.
1270    ///
1271    /// # Errors
1272    ///
1273    /// Returns a Core Video error code if the buffer creation fails.
1274    pub fn create_pixel_buffer(&self) -> Result<CVPixelBuffer, i32> {
1275        self.create_pixel_buffer_with_dictionary(self.policy.allocation_attributes.as_ref())
1276    }
1277
1278    /// Flush buffers that have aged out of the pool.
1279    pub fn flush(&self) {
1280        self.flush_with_flags(CVPixelBufferPoolFlushFlags::NONE);
1281    }
1282
1283    /// Flush unused buffers according to native Core Video flags.
1284    pub fn flush_with_flags(&self, flags: CVPixelBufferPoolFlushFlags) {
1285        unsafe { raw::CVPixelBufferPoolFlush(self.ptr.cast(), flags.bits()) };
1286    }
1287
1288    /// Flush every unused buffer regardless of age.
1289    pub fn flush_excess_buffers(&self) {
1290        self.flush_with_flags(CVPixelBufferPoolFlushFlags::EXCESS_BUFFERS);
1291    }
1292
1293    /// Get the Core Foundation type ID for `CVPixelBufferPool`
1294    #[must_use]
1295    pub fn type_id() -> usize {
1296        #[allow(clippy::cast_possible_truncation)]
1297        {
1298            unsafe { raw::CVPixelBufferPoolGetTypeID() as usize }
1299        }
1300    }
1301
1302    /// Create a pixel buffer from the pool with per-call auxiliary attributes.
1303    ///
1304    /// String keys become `CFString` keys and values become `CFNumber` values.
1305    /// A per-call allocation threshold can tighten but not loosen the
1306    /// threshold configured when the wrapper was created.
1307    ///
1308    /// # Errors
1309    ///
1310    /// Returns `paramErr` for an attribute key containing a NUL byte or an
1311    /// unrepresentable threshold, otherwise returns the Core Video allocation
1312    /// status.
1313    pub fn create_pixel_buffer_with_aux_attributes(
1314        &self,
1315        aux_attributes: Option<&HashMap<String, u32>>,
1316    ) -> Result<CVPixelBuffer, i32> {
1317        let Some(aux_attributes) = aux_attributes.filter(|attributes| !attributes.is_empty())
1318        else {
1319            return self.create_pixel_buffer();
1320        };
1321
1322        let threshold_key = retained_cf_string(
1323            unsafe { raw::kCVPixelBufferPoolAllocationThresholdKey },
1324            "kCVPixelBufferPoolAllocationThresholdKey",
1325        );
1326        let mut keys = Vec::with_capacity(aux_attributes.len() + 1);
1327        let mut values = Vec::with_capacity(aux_attributes.len() + 1);
1328        let mut requested_threshold = None;
1329
1330        for (key, value) in aux_attributes {
1331            if key.as_bytes().contains(&0) {
1332                return Err(PARAM_ERR);
1333            }
1334            let key = CFString::new(key);
1335            if key == threshold_key {
1336                requested_threshold = Some(usize::try_from(*value).map_err(|_| PARAM_ERR)?);
1337            } else {
1338                keys.push(key);
1339                values.push(CFNumber::from_u64(u64::from(*value)));
1340            }
1341        }
1342
1343        let effective_threshold = match (self.policy.max_buffers, requested_threshold) {
1344            (Some(configured), Some(requested)) => Some(configured.min(requested)),
1345            (Some(configured), None) => Some(configured),
1346            (None, requested) => requested,
1347        };
1348
1349        if let Some(threshold) = effective_threshold {
1350            let threshold = i64::try_from(threshold).map_err(|_| PARAM_ERR)?;
1351            keys.push(threshold_key);
1352            values.push(CFNumber::from_i64(threshold));
1353        }
1354
1355        let pairs: Vec<(&dyn AsCFType, &dyn AsCFType)> = keys
1356            .iter()
1357            .zip(&values)
1358            .map(|(key, value)| (key as &dyn AsCFType, value as &dyn AsCFType))
1359            .collect();
1360        let attributes = CFDictionary::from_pairs(&pairs);
1361        self.create_pixel_buffer_with_dictionary(Some(&attributes))
1362    }
1363
1364    /// Try to create a pixel buffer without exceeding the allocation threshold.
1365    ///
1366    /// Only `kCVReturnWouldExceedAllocationThreshold` maps to `Ok(None)`;
1367    /// every other Core Video error is preserved.
1368    ///
1369    /// # Errors
1370    ///
1371    /// Returns any Core Video allocation error other than threshold exhaustion.
1372    pub fn try_create_pixel_buffer(&self) -> Result<Option<CVPixelBuffer>, i32> {
1373        match self.create_pixel_buffer() {
1374            Ok(buffer) => Ok(Some(buffer)),
1375            Err(CV_RETURN_WOULD_EXCEED_ALLOCATION_THRESHOLD) => Ok(None),
1376            Err(status) => Err(status),
1377        }
1378    }
1379
1380    /// Copy the pool attributes into an independently owned dictionary.
1381    #[must_use]
1382    pub fn attributes(&self) -> Option<CFDictionary> {
1383        let ptr = unsafe { raw::CVPixelBufferPoolGetAttributes(self.ptr.cast()) };
1384        unsafe { CFDictionary::from_raw_borrowed(ptr.cast_mut().cast()) }
1385    }
1386
1387    /// Copy the pixel-buffer attributes into an independently owned dictionary.
1388    #[must_use]
1389    pub fn pixel_buffer_attributes(&self) -> Option<CFDictionary> {
1390        let ptr = unsafe { raw::CVPixelBufferPoolGetPixelBufferAttributes(self.ptr.cast()) };
1391        unsafe { CFDictionary::from_raw_borrowed(ptr.cast_mut().cast()) }
1392    }
1393}
1394
1395impl Clone for CVPixelBufferPool {
1396    fn clone(&self) -> Self {
1397        let ptr = unsafe { raw::CVPixelBufferPoolRetain(self.ptr.cast()) };
1398        Self {
1399            ptr: ptr.cast(),
1400            policy: Arc::clone(&self.policy),
1401        }
1402    }
1403}
1404
1405impl Drop for CVPixelBufferPool {
1406    fn drop(&mut self) {
1407        if !self.ptr.is_null() {
1408            unsafe { raw::CVPixelBufferPoolRelease(self.ptr.cast()) };
1409        }
1410    }
1411}
1412
1413impl fmt::Debug for CVPixelBufferPool {
1414    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1415        f.debug_struct("CVPixelBufferPool")
1416            .field("ptr", &self.ptr)
1417            .field("max_buffers", &self.max_buffers())
1418            .finish_non_exhaustive()
1419    }
1420}
1421
1422impl fmt::Display for CVPixelBufferPool {
1423    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1424        write!(f, "CVPixelBufferPool")
1425    }
1426}
1427
1428/// Extension trait for `io::Cursor` to add pixel buffer specific operations
1429pub trait PixelBufferCursorExt {
1430    /// Seek to a specific pixel coordinate (x, y)
1431    ///
1432    /// Assumes 4 bytes per pixel (BGRA format).
1433    ///
1434    /// # Errors
1435    ///
1436    /// Returns an I/O error if the seek operation fails.
1437    fn seek_to_pixel(&mut self, x: usize, y: usize, bytes_per_row: usize) -> io::Result<u64>;
1438
1439    /// Read a single pixel (4 bytes: BGRA)
1440    ///
1441    /// # Errors
1442    ///
1443    /// Returns an I/O error if the read operation fails.
1444    fn read_pixel(&mut self) -> io::Result<[u8; 4]>;
1445}
1446
1447impl<T: AsRef<[u8]>> PixelBufferCursorExt for io::Cursor<T> {
1448    fn seek_to_pixel(&mut self, x: usize, y: usize, bytes_per_row: usize) -> io::Result<u64> {
1449        let pos = y * bytes_per_row + x * 4; // 4 bytes per pixel (BGRA)
1450        self.seek(SeekFrom::Start(pos as u64))
1451    }
1452
1453    fn read_pixel(&mut self) -> io::Result<[u8; 4]> {
1454        let mut pixel = [0u8; 4];
1455        self.read_exact(&mut pixel)?;
1456        Ok(pixel)
1457    }
1458}
apple_cf/cv/pixel_buffer.rs

apple_cf/cv/
pixel_buffer.rs
