Struct PixelBuffer 

#[non_exhaustive]
pub struct PixelBuffer<P = ()> { /* private fields */ }

Owned pixel buffer with format metadata.

Wraps a Vec<u8> with an optional alignment offset so that pixel rows start at the correct alignment for the channel type. The backing vec can be recovered with into_vec for pool reuse.

The type parameter P tracks pixel format at compile time, same as PixelSlice.

Implementations

impl PixelBuffer

pub fn new(width: u32, height: u32, descriptor: PixelDescriptor) -> PixelBuffer

Allocate a zero-filled buffer for the given dimensions and format.

Panics

Panics if allocation fails. Use try_new for fallible allocation.

pub fn try_new( width: u32, height: u32, descriptor: PixelDescriptor, ) -> Result<PixelBuffer, At<BufferError>>

Try to allocate a zero-filled buffer for the given dimensions and format.

Returns BufferError::InvalidDimensions if the total size overflows, or BufferError::AllocationFailed if allocation fails.

pub fn new_simd_aligned( width: u32, height: u32, descriptor: PixelDescriptor, simd_align: usize, ) -> PixelBuffer

Allocate a SIMD-aligned buffer for the given dimensions and format.

Row stride is a multiple of lcm(bpp, simd_align), ensuring every row start is both pixel-aligned and SIMD-aligned when the buffer itself starts at a SIMD-aligned address.

simd_align must be a power of 2 (e.g. 16, 32, 64).

Panics

Panics if allocation fails. Use try_new_simd_aligned for fallible allocation.

pub fn try_new_simd_aligned( width: u32, height: u32, descriptor: PixelDescriptor, simd_align: usize, ) -> Result<PixelBuffer, At<BufferError>>

Try to allocate a SIMD-aligned buffer for the given dimensions and format.

Returns BufferError::InvalidDimensions if the total size overflows, or BufferError::AllocationFailed if allocation fails.

pub fn from_vec( data: Vec<u8>, width: u32, height: u32, descriptor: PixelDescriptor, ) -> Result<PixelBuffer, At<BufferError>>

Wrap an existing Vec<u8> as a pixel buffer.

The vec must be large enough to hold aligned_stride(width) * height bytes (plus any alignment offset). Stride is computed from the descriptor – rows are assumed tightly packed.

Errors

Returns BufferError::InsufficientData if the vec is too small.

impl<P> PixelBuffer<P>

where P: Pixel,

pub fn new_typed(width: u32, height: u32) -> PixelBuffer<P>

Allocate a typed zero-filled buffer for the given dimensions.

The descriptor is derived from P::DESCRIPTOR.

Panics

Panics if allocation fails. Use try_new_typed for fallible allocation.

pub fn try_new_typed( width: u32, height: u32, ) -> Result<PixelBuffer<P>, At<BufferError>>

Try to allocate a typed zero-filled buffer for the given dimensions.

Returns BufferError::InvalidDimensions if the total size overflows, or BufferError::AllocationFailed if allocation fails.

impl<P> PixelBuffer<P>

pub fn erase(self) -> PixelBuffer

Erase the pixel type, returning a type-erased buffer.

pub fn try_typed<Q>(self) -> Option<PixelBuffer<Q>>

where Q: Pixel,

Try to reinterpret as a typed pixel buffer.

Succeeds if the descriptors are layout-compatible.

pub fn with_descriptor(self, descriptor: PixelDescriptor) -> PixelBuffer<P>

Replace the descriptor with a layout-compatible one.

See PixelSlice::with_descriptor() for details.

pub fn reinterpret( self, descriptor: PixelDescriptor, ) -> Result<PixelBuffer<P>, At<BufferError>>

Reinterpret the buffer with a different physical layout.

See PixelSlice::reinterpret() for details.

pub fn with_transfer(self, tf: TransferFunction) -> PixelBuffer<P>

Return a copy with a different transfer function.

pub fn with_primaries(self, cp: ColorPrimaries) -> PixelBuffer<P>

Return a copy with different color primaries.

pub fn with_signal_range(self, sr: SignalRange) -> PixelBuffer<P>

Return a copy with a different signal range.

pub fn with_alpha_mode(self, am: Option<AlphaMode>) -> PixelBuffer<P>

Return a copy with a different alpha mode.

pub fn has_alpha(&self) -> bool

Whether this buffer carries meaningful alpha data.

pub fn is_grayscale(&self) -> bool

Whether this buffer is grayscale (Gray or GrayAlpha layout).

pub fn into_vec(self) -> Vec<u8>

Consume the buffer and return the backing Vec<u8> for pool reuse.

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

Zero-copy access to the raw pixel bytes when rows are tightly packed.

Returns Some(&[u8]) if stride == width * bpp (no padding), None if rows have stride padding.

pub fn copy_to_contiguous_bytes(&self) -> Vec<u8>

Copy pixel data to a new contiguous byte Vec without stride padding.

Returns exactly width * height * bytes_per_pixel bytes in row-major order. For buffers already tightly packed (stride == width * bpp), this is a single memcpy. For padded buffers, this strips the padding row by row.

pub fn width(&self) -> u32

Image width in pixels.

pub fn height(&self) -> u32

Image height in pixels.

pub fn stride(&self) -> usize

Byte stride between row starts.

pub fn descriptor(&self) -> PixelDescriptor

Pixel format descriptor.

pub fn color_context(&self) -> Option<&Arc<ColorContext>>

Source color context (ICC/CICP metadata), if set.

pub fn with_color_context(self, ctx: Arc<ColorContext>) -> PixelBuffer<P>

Set the color context on this buffer.

pub fn as_slice(&self) -> PixelSlice<'_, P>

Borrow the full buffer as an immutable PixelSlice.

pub fn as_slice_mut(&mut self) -> PixelSliceMut<'_, P>

Borrow the full buffer as a mutable PixelSliceMut.

pub fn rows(&self, y: u32, count: u32) -> PixelSlice<'_, P>

Borrow a range of rows as an immutable PixelSlice.

Panics

Panics if y + count > height.

pub fn rows_mut(&mut self, y: u32, count: u32) -> PixelSliceMut<'_, P>

Borrow a range of rows as a mutable PixelSliceMut.

Panics

Panics if y + count > height.

pub fn crop_view(&self, x: u32, y: u32, w: u32, h: u32) -> PixelSlice<'_, P>

Zero-copy sub-region view (immutable).

Panics

Panics if the crop region is out of bounds.

pub fn crop_copy(&self, x: u32, y: u32, w: u32, h: u32) -> PixelBuffer<P>

Copy a sub-region into a new, tightly-packed PixelBuffer.

Panics

Panics if the crop region is out of bounds.

Trait Implementations

impl<P> Debug for PixelBuffer<P>

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

Formats the value using the given formatter.

impl<P> From<PixelBuffer<P>> for PixelBuffer

where P: Pixel,

fn from(typed: PixelBuffer<P>) -> PixelBuffer

Converts to this type from the input type.

impl PixelBufferConvertExt for PixelBuffer

fn convert_to( &self, target: PixelDescriptor, ) -> Result<PixelBuffer, At<ConvertError>>

Convert pixel data to a different layout and depth.

fn try_add_alpha(&self) -> Result<PixelBuffer, At<ConvertError>>

Add an alpha channel. Allocates a new PixelBuffer.

fn try_widen_to_u16(&self) -> Result<PixelBuffer, At<ConvertError>>

Widen to U16 depth (lossless, ×257). Allocates a new PixelBuffer.

fn try_narrow_to_u8(&self) -> Result<PixelBuffer, At<ConvertError>>

Narrow to U8 depth (lossy, rounded). Allocates a new PixelBuffer.

fn linearize(&self) -> Result<PixelBuffer, At<ConvertError>>

Convert to linear-light F32, preserving channel layout and primaries.

fn delinearize( &self, transfer: TransferFunction, ) -> Result<PixelBuffer, At<ConvertError>>

Apply a transfer function to a linear-light buffer.