Struct PixelSlice 

#[non_exhaustive]
pub struct PixelSlice<'a, P = ()> { /* private fields */ }

Borrowed view of pixel data.

Represents a contiguous region of pixel rows, possibly a sub-region of a larger buffer. All rows share the same stride.

The type parameter P tracks the pixel format at compile time:

• PixelSlice<'a, Rgb<u8>> — known to be RGB8 pixels
• PixelSlice<'a> (= PixelSlice<'a, ()>) — type-erased, format in descriptor

Use new_typed() to create a typed slice, or erase() / try_typed() to convert between typed and erased forms.

Optionally carries ColorContext to track source color metadata through the processing pipeline.

Implementations

impl<'a> PixelSlice<'a>

pub fn new( data: &'a [u8], width: u32, rows: u32, stride_bytes: usize, descriptor: PixelDescriptor, ) -> Result<PixelSlice<'a>, At<BufferError>>

Create a new pixel slice with validation.

stride_bytes is the byte distance between the start of consecutive rows.

Errors

Returns an error if the data is too small, the stride is too small, or the data is not aligned for the channel type.

impl<'a, P> PixelSlice<'a, P>

pub fn erase(self) -> PixelSlice<'a>

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

This is a zero-cost operation that just changes the type parameter.

pub fn try_typed<Q>(self) -> Option<PixelSlice<'a, Q>>

where Q: Pixel,

Try to reinterpret as a typed pixel slice.

Succeeds if the descriptors are layout-compatible (same channel type and layout). Transfer function and alpha mode are metadata, not layout constraints.

pub fn with_descriptor(self, descriptor: PixelDescriptor) -> PixelSlice<'a, P>

Replace the descriptor with a layout-compatible one.

Use after a transform that changes pixel metadata without changing the buffer layout (e.g., transfer function change, alpha mode change, signal range expansion).

For per-field updates, prefer the specific setters: with_transfer(), with_primaries(), with_signal_range(), with_alpha_mode().

Panics

Panics if the new descriptor is not layout-compatible (different channel_type or layout). Use reinterpret() for genuine layout changes.

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

Reinterpret the buffer with a different physical layout.

Unlike with_descriptor(), this allows changing channel_type and layout. The new descriptor must have the same bytes_per_pixel() as the current one.

Use cases: treating RGBA8 data as BGRA8, RGBX8 as RGBA8.

pub fn with_transfer(self, tf: TransferFunction) -> PixelSlice<'a, P>

Return a copy with a different transfer function.

pub fn with_primaries(self, cp: ColorPrimaries) -> PixelSlice<'a, P>

Return a copy with different color primaries.

pub fn with_signal_range(self, sr: SignalRange) -> PixelSlice<'a, P>

Return a copy with a different signal range.

pub fn with_alpha_mode(self, am: Option<AlphaMode>) -> PixelSlice<'a, P>

Return a copy with a different alpha mode.

pub fn width(&self) -> u32

Image width in pixels.

pub fn rows(&self) -> u32

Number of rows in this slice.

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>) -> PixelSlice<'a, P>

Return a copy of this slice with a color context attached.

pub fn is_contiguous(&self) -> bool

Whether rows are tightly packed (no stride padding).

When true, the entire pixel data is contiguous in memory and as_contiguous_bytes() returns Some.

pub fn as_contiguous_bytes(&self) -> Option<&'a [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.

Use this to avoid collect_contiguous_bytes() copies when passing pixel data to FFI or other APIs that need a flat buffer.

pub fn as_strided_bytes(&self) -> &'a [u8]

Raw backing bytes including inter-row stride padding.

Returns a &[u8] covering all rows with stride padding between them. Includes trailing padding after the last row when the backing buffer is large enough (e.g., from a full allocation), but not for sub-row views where the last row may be trimmed.

Use with stride() for APIs that accept a byte buffer plus a stride value (GPU uploads, codec writers, etc).

pub fn contiguous_bytes(&self) -> Cow<'a, [u8]>

Get the raw pixel bytes, copying only if stride padding exists.

Returns Cow::Borrowed when rows are contiguous (zero-copy), Cow::Owned when stride padding must be stripped.

pub fn row(&self, y: u32) -> &[u8]

Pixel bytes for row y (no padding, exactly width * bpp bytes).

Panics

Panics if y >= rows.

pub fn row_with_stride(&self, y: u32) -> &[u8]

Full stride bytes for row y (including any padding).

Panics

Panics if y >= rows or if the underlying data does not contain a full stride for this row (can happen on the last row of a cropped view).

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

Borrow a sub-range of rows.

Panics

Panics if y + count > rows.

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

Zero-copy crop view. Adjusts the data pointer and width; stride remains the same as the parent.

Panics

Panics if the crop region is out of bounds.

impl<'a, P> PixelSlice<'a, P>

where P: Pixel,

pub fn new_typed( data: &'a [u8], width: u32, rows: u32, stride_pixels: u32, ) -> Result<PixelSlice<'a, P>, At<BufferError>>

Create a typed pixel slice.

stride_pixels is the number of pixels per row (>= width). The byte stride is stride_pixels * size_of::<P>().

Compile-time safety

Includes a compile-time assertion that size_of::<P>() matches P::DESCRIPTOR.bytes_per_pixel(), catching bad Pixel impls.

Trait Implementations

impl<P> Debug for PixelSlice<'_, P>

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

Formats the value using the given formatter.

impl<'a, P> From<PixelSlice<'a, P>> for PixelSlice<'a>

where P: Pixel,

fn from(typed: PixelSlice<'a, P>) -> PixelSlice<'a>

Converts to this type from the input type.

impl<'a, P> From<PixelSliceMut<'a, P>> for PixelSlice<'a, P>

Consume a mutable pixel slice and produce an immutable one (zero-copy).

fn from(mut_slice: PixelSliceMut<'a, P>) -> PixelSlice<'a, P>

Converts to this type from the input type.