imgref

imgref is a minimal Rust struct that pairs a pixel buffer with its width, height, and stride, giving graphics code a single value to pass instead of three or four separate arguments. It is designed as a common interchange type so different image crates can hand bitmaps and sub-regions to one another without copying or bespoke glue.

Beyond simply bundling dimensions, imgref supports stride so callers can describe padded buffers and sub-regions (tiles, frames rounded to block sizes) as zero-copy references. It provides ergonomic row and pixel iterators, (x, y) indexing, and owning (ImgVec) versus borrowing (ImgRef) types that mirror Vec and slice semantics.

What You Get

• Img/ImgVec/ImgRef types that bundle a pixel buffer with width, height, and stride
• Zero-copy sub-image slicing with sub_image(x, y, w, h) for tiles and regions
• Efficient pixel and row iterators plus img[(x, y)] and img[row] indexing
• to_contiguous_buf() to flatten a strided region back into a gap-free buffer
• A stable interchange type usable as common ground between independent image crates

Common Use Cases

• Passing an image as one function argument instead of separate width/height/buffer values
• Exchanging pixel buffers between image-processing crates without conversion glue
• Describing padded or block-aligned video frames using stride
• Slicing tiles or sub-regions of an image by reference without copying

Under The Hood

Architecture - The crate centers on a single generic Img<Container> struct holding a buffer plus width, height, and stride, with type aliases ImgVec<Pixel> (owns a Vec), ImgRef<‘a, Pixel> (borrows a slice, and is Copy), and mutable variants. Row and pixel iterators walk the buffer while respecting stride, and sub_image returns a new descriptor pointing into the same backing storage so slicing is allocation-free. to_contiguous_buf copies out a gap-free buffer only when padding must be removed.

Tech Stack - Pure Rust (100% of the codebase), no C or external runtime dependencies, targeting the latest stable Rust. It is distributed solely as a Cargo crate and documented on docs.rs.

Code Quality - Despite modest star count, the crate is battle-tested: over 40 million downloads and 100+ commits since 2017, maintained by the pngquant/gifski author. The code is small, focused, and idiomatic, using generics and Copy semantics deliberately to guide correct usage (e.g. ImgRef instead of &ImgRef).

API Design - The public API is deliberately minimal and ergonomic: constructors like Img::new, accessors width()/height(), (x, y) indexing, rows()/pixels() iterators, and as_ref() to obtain a cheap ImgRef. The README explicitly documents the ownership model and the .as_ref() convention, making the crate easy to adopt as a shared interchange type.