zenpixels/
lib.rs

1//! Pixel format interchange types for Rust image codecs.
2//!
3//! This crate provides the type system for describing pixel data: what the
4//! bytes are ([`PixelFormat`]), what they mean ([`PixelDescriptor`]), and where
5//! they live ([`PixelBuffer`], [`PixelSlice`], [`PixelSliceMut`]).
6//!
7//! No conversion logic lives here. For transfer-function-aware conversion,
8//! gamut mapping, and codec format negotiation, see
9//! [`zenpixels-convert`](https://docs.rs/zenpixels-convert).
10//!
11//! # Core types
12//!
13//! - [`PixelFormat`] — flat enum of byte layouts (`Rgb8`, `Rgba16`, `OklabF32`, etc.)
14//! - [`PixelDescriptor`] — format + transfer function + primaries + alpha mode + signal range
15//! - [`PixelBuffer`] — owned pixel storage with SIMD-aligned allocation
16//! - [`PixelSlice`] / [`PixelSliceMut`] — borrowed views with stride support
17//! - [`Pixel`] — trait mapping concrete types to their descriptor
18//! - [`Cicp`] — ITU-T H.273 color signaling codes
19//! - [`ColorContext`] — ICC profile bytes and/or CICP, `Arc`-shared
20//! - [`ConvertOptions`] — policies for lossy operations (alpha removal, depth reduction)
21//!
22//! # Allocation policy
23//!
24//! All default [`PixelBuffer`] constructors (`new`, `new_simd_aligned`,
25//! `new_typed`, `from_imgvec`) **panic on allocation failure**. This is a
26//! deliberate default: the infallible path lowers to a single `calloc` and
27//! keeps hot construction sites branch-free, which matters for codecs that
28//! allocate one buffer per frame or strip.
29//!
30//! For code that handles untrusted input or must recover from OOM, use the
31//! fallible siblings instead:
32//!
33//! | Panicking                         | Fallible sibling                       |
34//! |-----------------------------------|----------------------------------------|
35//! | [`PixelBuffer::new`]              | [`PixelBuffer::try_new`]               |
36//! | [`PixelBuffer::new_simd_aligned`] | [`PixelBuffer::try_new_simd_aligned`]  |
37//! | `PixelBuffer::<P>::new_typed`     | `PixelBuffer::<P>::try_new_typed`      |
38//!
39//! The fallible siblings return
40//! [`BufferError::AllocationFailed`]
41//! via [`Vec::try_reserve_exact`] + `resize(_, 0)`. They are slightly slower
42//! than the panicking path because the reserve-then-zero pattern cannot be
43//! collapsed into a single `calloc` the way `vec![0; n]` can.
44//!
45//! There is currently **no runtime or compile-time toggle** to make the
46//! default constructors fallible. If a Cargo feature (e.g. `fallible-alloc`)
47//! or a runtime option would better fit your use case, please open an issue
48//! at <https://github.com/imazen/zen/issues> describing the caller and we'll
49//! evaluate adding one. Until then, reach directly for the `try_*` variants.
50//!
51//! # Feature flags
52//!
53//! | Feature | What it enables |
54//! |---------|----------------|
55//! | `std` | Standard library (default; currently a no-op, everything is `no_std + alloc`) |
56//! | `rgb` | [`Pixel`] impls for `rgb` crate types, typed `from_pixels()` constructors |
57//! | `imgref` | `From<ImgRef>` / `From<ImgVec>` conversions (implies `rgb`) |
58//! | `planar` | Multi-plane image types (YCbCr, Oklab, gain maps) |
59
60#![cfg_attr(not(feature = "std"), no_std)]
61#![forbid(unsafe_code)]
62
63extern crate alloc;
64
65whereat::define_at_crate_info!(path = "zenpixels/");
66
67pub mod descriptor;
68pub mod orientation;
69#[cfg(feature = "planar")]
70pub mod planar;
71pub mod policy;
72
73pub mod cicp;
74pub mod color;
75pub mod hdr;
76#[cfg(feature = "icc")]
77pub mod icc;
78pub mod pixel_types;
79pub(crate) mod registry;
80
81pub mod buffer;
82
83// Re-export orientation type at crate root.
84pub use orientation::Orientation;
85
86// Re-export key descriptor types at crate root for ergonomics.
87pub use descriptor::{
88    AlphaMode, ByteOrder, ChannelLayout, ChannelType, ColorModel, ColorPrimaries, PixelDescriptor,
89    PixelFormat, SignalRange, TransferFunction,
90};
91
92// Re-export planar types when the `planar` feature is enabled.
93#[cfg(feature = "planar")]
94pub use planar::{
95    MultiPlaneImage, Plane, PlaneDescriptor, PlaneLayout, PlaneMask, PlaneRelationship,
96    PlaneSemantic, Subsampling, YuvMatrix,
97};
98
99// Re-export buffer types at crate root.
100pub use buffer::{
101    Bgrx, BufferError, InPlacePixels, Pixel, PixelBuffer, PixelSlice, PixelSliceMut, Rgbx,
102};
103
104// Re-export color types at crate root.
105pub use cicp::Cicp;
106pub use color::{
107    ColorAuthority, ColorContext, ColorOrigin, ColorProfileSource, ColorProvenance, NamedProfile,
108};
109
110// Re-export HDR metadata types at crate root.
111pub use hdr::{ContentLightLevel, MasteringDisplay};
112
113// Re-export GrayAlpha pixel types at crate root.
114pub use pixel_types::{GrayAlpha8, GrayAlpha16, GrayAlphaF32};
115
116pub use policy::{AlphaPolicy, ConvertOptions, DepthPolicy, GrayExpand, LumaCoefficients};
117
118// Re-export whereat types for error tracing.
119pub use whereat::{At, ResultAtExt, at};
zenpixels/lib.rs

zenpixels/
lib.rs
