Crate blazediff_png 

Full-spec PNG codec with byte-exact decode parity to libspng’s SPNG_FMT_RGBA8 path (the blazediff reference decoder configuration: tRNS applied, adler32 ignored, CRCs unverified) and round-trip-verified encoding.

• Decode: every format spng accepts — bit depths 1/2/4/8/16, all five color types, palette + tRNS, gray/RGB tRNS color-keying, Adam7 interlacing — decoded to RGBA8 byte-identically to spng, with the same accept/reject behavior on malformed inputs. One deliberate exception: a gray tRNS key is masked to the bit depth as the PNG spec requires, which spng does not do (see the README).
• Decode formats: decode_with targets any spng SPNG_FMT_* (RGBA8/RGBA16/RGB8/GA8/GA16/G8/native PNG/RAW) with optional tRNS / gamma / sBIT transforms, each byte-identical to spng_decode_image — see DecodeFormat / DecodeOptions.
• Encode: all PNG color type / bit depth combinations, optional Adam7, real deflate levels (libdeflate) plus a stored-block level 0; verified by decode(encode(x)) == x and spng cross-decode.
• Fast: single-threaded and SIMD-first — whole-buffer libdeflate inflate, in-place sequential defiltering, autovectorizable row expansion, and NEON-accelerated encode-filter kernels.
• Metadata: decode_with_metadata / encode_with_metadata capture and emit every ancillary chunk spng exposes (text, color management, timing, physical dimensions, EXIF, suggested palettes, explicit palette/transparency) plus unknown-chunk passthrough — verified field by field against spng_get_*. The plain decode stays metadata-free for the pixel hot path.

let bytes = std::fs::read("image.png").unwrap();
let image = blazediff_png::decode(&bytes).unwrap();
let png = blazediff_png::encode(&image, &blazediff_png::EncodeOptions::default()).unwrap();

Structs

Chrm

Chromaticities (cHRM), stored as the raw chrm_int form: each field is the spec’s value × 100000.

DecodeOptions

Decode configuration: the output format plus the optional sample transforms, mirroring spng’s SPNG_DECODE_TRNS / _GAMMA / _USE_SBIT.

Decoded

Decoded pixels plus the layout needed to interpret data. Returned by crate::decode_with.

DecodedPng

An image plus all of its non-pixel chunk data, from decode_with_metadata.

EncodeOptions

PNG encode tuning. Mirrors the knobs spng exposes via spng_set_option that the libdeflate backend can honor:

FilterSet

Bitmask over the five PNG row filters the adaptive heuristic may choose from, mirroring spng’s SPNG_IMG_FILTER_CHOICE. The encoder picks the lowest sum-of-absolute-differences filter within the set for each row; a singleton set forces that filter with no scan. Compose with |:

Iccp

Embedded ICC profile (iCCP); profile is the decompressed bytes.

Image

Decoded image: RGBA8, 4 bytes per pixel, row-major.

Image16

True 16-bit image: RGBA16 host-order, 4 u16 channels per pixel, row-major. The input type for encode16, and the natural pairing with decode_with at DecodeFormat::Rgba16.

ImageRef

Borrowed RGBA8 view, the input for the streaming encode entry points (encode_ref / encode_to). Lets a caller encode straight from an existing buffer without handing ownership to an Image.

Metadata

All non-pixel chunk data for one image. Default is “no metadata”.

Offs

Image offset (oFFs).

Palette

Explicit palette (PLTE) for encoding: entry order is preserved verbatim, overriding the encoder’s first-seen auto-derivation.

Phys

Physical pixel dimensions (pHYs).

Sbit

Significant bits (sBIT). Only the channels relevant to the image’s color type are meaningful; the rest are zero (matching spng’s struct).

Splt

Suggested palette (sPLT). Multiple are allowed per image.

SpltEntry

One suggested-palette entry (sPLT). Samples are 16-bit regardless of the chunk’s sample depth (8-bit entries are stored as-is in the low byte).

Text

A textual annotation (tEXt / zTXt / iTXt). text is always the decompressed content; language_tag / translated_keyword are iTXt only (empty otherwise).

Time

Last-modification time (tIME), UTC.

UnknownChunk

An ancillary chunk the codec does not model, preserved verbatim.

Enums

Bkgd

Background color (bKGD), tagged by the image’s color type.

ColorMode

DecodeFormat

Output pixel layout for crate::decode_with, one variant per spng SPNG_FMT_*. Rgba8 is the historical default (crate::decode).

Filter

Location

Position of an unknown chunk relative to the critical chunks, mirroring spng’s enum spng_location.

PngError

TextKind

Which textual chunk a Text entry came from / is written as.

Trns

Transparency (tRNS), tagged by color type.

Functions

decode

Decode a PNG to RGBA8, byte-identical to libspng’s FMT_RGBA8 + tRNS output for every input spng accepts, rejecting the inputs spng rejects. The exception is a gray tRNS key with bits above the bit depth, which is masked per the PNG spec.

decode_with

Decode a PNG to an arbitrary DecodeFormat with optional tRNS / gamma / sBIT transforms, byte-identical to libspng’s spng_decode_image(fmt, flags). decode is the Rgba8 + tRNS special case.

decode_with_metadata

Decode a PNG to RGBA8 and capture every ancillary chunk spng exposes (text, color management, timing, physical dimensions, EXIF, suggested palettes, and unknown chunks), with the same accept/reject behavior as decode. Heavier than decode — use that when only pixels are needed.

encode

Encode an RGBA8 image to PNG. The requested color mode must represent the image losslessly (decode(encode(x)) == x always holds); EncodeOptions::default auto-picks the smallest lossless mode.

encode16

Encode a true 16-bit Image16 to PNG, carrying full 16-bit precision (unlike encode, which byte-replicates an 8-bit source). The color mode must be a 16-bit one — Gray16/GrayAlpha16/Rgb16/Rgba16 or Auto; EncodeOptions::default auto-picks the smallest lossless 16-bit mode.

encode16_with_metadata

encode16 with caller-supplied ancillary chunks, mirroring encode_with_metadata.

encode_ref

encode from a borrowed ImageRef — same output, no Image ownership required. The hot path (Rgba8 + Filter::None + level 0, non-interlaced, no metadata) is written straight from the borrowed rows with no intermediate raw or zlib buffer.

encode_to

Stream a PNG encode straight into out instead of returning a Vec. For the stored RGBA8 hot path this keeps peak memory at roughly the input size: the deflate stored blocks are written directly to the sink with no full-size intermediate buffer. Other modes build a Vec and write it through. Wrap a File in a BufWriter — the stored path issues many small writes.

encode_with_metadata

Encode an RGBA8 image to PNG, emitting the supplied metadata chunks in spec-valid positions. When meta.palette is set and the resolved color mode is indexed, that palette (and meta.transparency) is used verbatim instead of the auto-derived one.