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.

The default path is infallible for speed — see the allocation policy for the rationale and for guidance on when to reach for the try_* sibling.

Panics

Panics if allocation fails. Use try_new for fallible allocation when handling untrusted sizes or when OOM must be recoverable.

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).

The default path is infallible for speed — see the allocation policy for the rationale and for guidance on when to reach for the try_* sibling.

Panics

Panics if allocation fails. Use try_new_simd_aligned for fallible allocation when handling untrusted sizes or when OOM must be recoverable.

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.

The default path is infallible for speed — see the allocation policy for the rationale and for guidance on when to reach for the try_* sibling.

Panics

Panics if allocation fails. Use try_new_typed for fallible allocation when handling untrusted sizes or when OOM must be recoverable.

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 PixelBuffer

pub fn transform_in_place<F>(&mut self, f: F)

where F: for<'a> FnOnce(InPlacePixels<'a>) -> PixelSliceMut<'a>,

Run a layout-changing in-place transform over this buffer and atomically adopt the transform’s output geometry, descriptor, and color context.

This is the only supported way to rewrite a buffer into a different byte layout in place (lane drops, channel reorders, orientation bakes, load-bearing reductions — the zenpixels-convert in-place family is built on it). The closure receives the buffer’s backing bytes (from the aligned base, including stride padding) plus the current description, rewrites the pixels, and returns a PixelSliceMut re-describing the same memory (built with PixelSliceMut::new, so the new geometry is validated). On return, this buffer’s own width / height / stride / descriptor / color context are updated in the same call — the buffer and its bytes can never disagree, which is the staleness hazard this method exists to prevent.

Panics

Panics if the returned view does not start at this buffer’s aligned base or does not fit inside the original allocation — both indicate a bug in the transform, not a recoverable condition (the bytes may already be partially rewritten).

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.

Note: this is a view; transforms that change the buffer’s layout cannot be expressed through it (a re-described view would leave this buffer’s own descriptor stale). For layout-changing in-place transforms, use PixelBuffer::transform_in_place, which adopts the new description atomically.

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, or if the destination allocation size (aligned_stride(w) * h + min_alignment - 1) overflows usize. On 64-bit targets the overflow case is unreachable for u32 dimensions; on 32-bit targets it can be reached with adversarial inputs and panics eagerly here rather than producing a deferred slice-bounds panic.

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.

impl PixelBufferLoadBearingExt for PixelBuffer

fn reduce_to_load_bearing_format_in_place( &mut self, force_alpha_restructuring: bool, )

Run the load-bearing analysis and rewrite this buffer in place to the narrowest justified format, adopting the narrowed descriptor and tight row stride (width * bytes_per_pixel) in the same call. When no reduction applies the buffer is unchanged – compare PixelBuffer::descriptor before/after to detect it.