Crate zenpixels 

Pixel format interchange types for Rust image codecs.

This crate provides the type system for describing pixel data: what the bytes are (PixelFormat), what they mean (PixelDescriptor), and where they live (PixelBuffer, PixelSlice, PixelSliceMut).

No conversion logic lives here. For transfer-function-aware conversion, gamut mapping, and codec format negotiation, see zenpixels-convert.

Core types

• PixelFormat — flat enum of byte layouts (Rgb8, Rgba16, OklabF32, etc.)
• PixelDescriptor — format + transfer function + primaries + alpha mode + signal range
• PixelBuffer — owned pixel storage with SIMD-aligned allocation
• PixelSlice / PixelSliceMut — borrowed views with stride support
• Pixel — trait mapping concrete types to their descriptor
• Cicp — ITU-T H.273 color signaling codes
• ColorContext — ICC profile bytes and/or CICP, Arc-shared
• ConvertOptions — policies for lossy operations (alpha removal, depth reduction)

Allocation policy

All default PixelBuffer constructors (new, new_simd_aligned, new_typed, from_imgvec) panic on allocation failure. This is a deliberate default: the infallible path lowers to a single calloc and keeps hot construction sites branch-free, which matters for codecs that allocate one buffer per frame or strip.

For code that handles untrusted input or must recover from OOM, use the fallible siblings instead:

Panicking	Fallible sibling
PixelBuffer::new	PixelBuffer::try_new
PixelBuffer::new_simd_aligned	PixelBuffer::try_new_simd_aligned
PixelBuffer::<P>::new_typed	PixelBuffer::<P>::try_new_typed

The fallible siblings return BufferError::AllocationFailed via Vec::try_reserve_exact + resize(_, 0). They are slightly slower than the panicking path because the reserve-then-zero pattern cannot be collapsed into a single calloc the way vec![0; n] can.

There is currently no runtime or compile-time toggle to make the default constructors fallible. If a Cargo feature (e.g. fallible-alloc) or a runtime option would better fit your use case, please open an issue at https://github.com/imazen/zen/issues describing the caller and we’ll evaluate adding one. Until then, reach directly for the try_* variants.

Feature flags

Feature	What it enables
std	Standard library (default; currently a no-op, everything is no_std + alloc)
rgb	Pixel impls for rgb crate types, typed from_pixels() constructors
imgref	From<ImgRef> / From<ImgVec> conversions (implies rgb)
planar	Multi-plane image types (YCbCr, Oklab, gain maps)

Re-exports

pub use orientation::Orientation;

pub use descriptor::AlphaMode;

pub use descriptor::ByteOrder;

pub use descriptor::ChannelLayout;

pub use descriptor::ChannelType;

pub use descriptor::ColorModel;

pub use descriptor::ColorPrimaries;

pub use descriptor::PixelDescriptor;

pub use descriptor::PixelFormat;

pub use descriptor::SignalRange;

pub use descriptor::TransferFunction;

pub use buffer::Bgrx;

pub use buffer::BufferError;

pub use buffer::Pixel;

pub use buffer::PixelBuffer;

pub use buffer::PixelSlice;

pub use buffer::PixelSliceMut;

pub use buffer::Rgbx;

pub use cicp::Cicp;

pub use color::ColorAuthority;

pub use color::ColorContext;

pub use color::ColorOrigin;

pub use color::ColorProfileSource;

pub use color::ColorProvenance;

pub use color::NamedProfile;

pub use hdr::ContentLightLevel;

pub use hdr::MasteringDisplay;

pub use pixel_types::GrayAlpha8;

pub use pixel_types::GrayAlpha16;

pub use pixel_types::GrayAlphaF32;

pub use policy::AlphaPolicy;

pub use policy::ConvertOptions;

pub use policy::DepthPolicy;

pub use policy::GrayExpand;

pub use policy::LumaCoefficients;

Modules

buffer

Opaque pixel buffer abstraction.

cicp

CICP (Coding-Independent Code Points) color description.

color

Color profile types for CMS integration.

descriptor

Pixel format descriptor types.

hdr

HDR metadata types.

icc

Lightweight ICC profile inspection and identification.

orientation

EXIF orientation as an element of the D4 dihedral group.

pixel_types

Custom pixel types for gray+alpha formats.

policy

Conversion policy types for explicit control over lossy operations.

Macros

at

Start tracing an error with crate metadata for repository links.

Structs

At

An error with location tracking - wraps any error type.

Traits

ResultAtExt

Extension trait for adding location tracking to Result<T, At<E>>.

Functions

at

Wrap any value in At<E> and capture the caller’s location.