Crate oxideav_webp

Expand description

§oxideav-webp

Pure-Rust WebP image codec — clean-room scaffold built against RFC 9649 (WebP Image Format).

Round 1 landed the structural RIFF/WEBP container walker (container::parse). Round 2 added typed field decoding for the VP8X extended-format header (vp8x::Vp8xHeader::parse). Round 3 added typed field decoding for the §2.7.1.1 ANIM / §2.7.1.2 ALPH metadata chunks. Round 4 added typed field decoding for the per-frame §2.7.1.1 ANMF header. Round 5 added the builder side of the RIFF/WEBP container — the inverse of the walker — so external encoders can wrap a VP8 / VP8L payload in a well-formed file. Round 6 adds a typed §2.5 VP8 chunk handle (vp8_chunk::WebpLossyChunk) that lets container-layer callers route the VP8 payload to a downstream VP8 decoder without oxideav-webp taking a runtime dependency on oxideav-vp8.

alph::AlphHeader::parse — the ALPH info byte (Rsv|P|F|C).
alph::decode_alpha — the §2.7.1.2 alpha-bitstream decode (round 110): both compression methods (raw + headerless VP8L, the latter lifting alpha from the GREEN channel) and the four inverse filters (none / horizontal / vertical / gradient) with the documented left-most / top-most edge cases, producing the full-resolution alpha plane. decode_alpha_plane is the container-level entry point: walk the file, take dimensions from VP8X (or the VP8 keyframe), find the ALPH chunk, decode.
anim::AnimHeader::parse — the ANIM 6-byte payload (BGRA background colour + u16 loop count).
anmf::AnmfHeader::parse — the ANMF 16-byte per-frame header (frame X / Y / width / height / duration plus Reserved|B|D info byte).
build::build_chunk — generic §2.3 chunk writer (FourCC + Size + payload + odd-size pad).
build::build_vp8x_chunk — §2.7.1 Figure 7 typed VP8X payload writer.
build::build_webp_file — §2.4 file writer for simple (VP8 / VP8L) and extended (VP8X + VP8 / VP8L) layouts.
vp8_chunk::WebpLossyChunk — typed §2.5 VP8 chunk handle. Peeks the RFC 6386 §9.1 keyframe header (width / height / version / first_partition_size / scale fields) and exposes the chunk payload via vp8_chunk::WebpLossyChunk::bitstream for routing to an external VP8 decoder.
vp8l_chunk::WebpLosslessChunk — typed §2.6 VP8L chunk handle. Peeks the §3.4 / §7.1 5-byte VP8L image-header (0x2F signature + 14-bit width-1 + 14-bit height-1 + alpha_is_used bit + 3-bit version) and exposes the chunk payload via vp8l_chunk::WebpLosslessChunk::bitstream for routing to an external VP8L decoder.
vp8l_stream::TransformList — the §4 transform-presence loop (round 99): each present transform’s leading fixed fields, stopping at the first §5 entropy-coded body.
vp8l_prefix::PrefixCode — the §6.2.1 prefix-code reader (round 104): reads a single canonical prefix code’s lengths off the wire (simple or normal code length code) and decodes symbols one at a time. This is the first piece of the §5 / §6 entropy machinery the §4 transform bodies and the main image stream both consume.
meta_prefix::MetaPrefixHeader — the §5.2.3 color-cache info, §6.2.2 meta-prefix dispatch, and §6.2 5-prefix-code-group reader (round 106). Surfaces either a fully-built single meta_prefix::PrefixCodeGroup (the common case: single meta-Huffman group, or any non-ARGB role) or, when an ARGB image selects an entropy image, the entropy-image dimensions plus the bit position at which the §5.2-encoded entropy image starts (for the next round to resume from once §5.2 LZ77 + color-cache decode lands).
vp8l_decode::decode_image — the §5.2 LZ77 backward-reference + §5.2.3 color-cache per-pixel ARGB decode loop (round 107). Runs the §6.2.3 GREEN symbol dispatch (literal / LZ77 length+distance / color-cache code) over a single meta_prefix::PrefixCodeGroup and produces a vp8l_decode::DecodedImage of ARGB pixels in scan-line order (before any §4 inverse transform). Includes the §5.2.2 prefix→value transform, the 120-element distance map, and the §5.2.3 0x1e35a7bd color cache.
vp8l_decode::decode_argb — the §6.2.2 multi-group ARGB decode (round 108). Reads the round-106 meta_prefix::MetaPrefixHeader for the ARGB role and, when the meta-prefix bit selects multiple groups, decodes the §6.2.2 entropy image (vp8l_decode::decode_entropy_image → vp8l_decode::MetaPrefixIndex), derives num_prefix_groups = max(entropy image) + 1, reads that many prefix-code groups, and runs the §6.2.3 loop selecting a group per pixel block via meta_index[(y >> prefix_bits) * block_width + (x >> prefix_bits)]. Single-group images degrade to the round-107 path. Per §6.2.2 each block’s meta-prefix code is the red+green channels of its entropy-image pixel ((argb >> 8) & 0xffff).
vp8l_transform::decode_lossless — the §4 inverse-transform passes (round 109). Reads the §4 transform list (each transform’s fixed fields and its §5-encoded body), decodes the main ARGB image at the (color-indexing-subsampled) width, then applies the four inverse transforms in reverse read order: §4.1 predictor (14 prediction modes + border rules over the block grid), §4.2 color (per-block ColorTransformElement add-back), §4.3 subtract-green (add green into red/blue), and §4.4 color-indexing (palette lookup plus ≤16-color pixel un-bundling). The container-level entry point, decode_lossless_image, walks the file, extracts the VP8L chunk, and decodes to a vp8l_decode::DecodedImage. Bit-exact against the lossless-1x1, lossless-color-indexing-paletted, and lossless-32x32-rgba (SUBTRACT_GREEN + PREDICTOR + CROSS_COLOR + color cache) fixture PNGs.
vp8_decode::decode_lossy_rgba — the §2.5 VP8 (lossy) decode path (round 124). Routes the VP8 chunk payload to the oxideav-vp8 sibling crate’s oxideav_vp8::decode_vp8 entry point, which reconstructs the loop-filtered I420 key-frame, then converts it to interleaved RGBA via nearest-neighbour chroma up-sampling and the RFC 6386 §9.2 ITU-R BT.601 full-range YCbCr→RGB matrix.
decode_webp_image / decode_webp — the top-level still-image entry points (round 111). They walk the container, decode a §2.6 / §3.4 VP8L lossless image (simple or VP8X-extended) through the full §4–§6 chain, optionally override its alpha from a §2.7.1.2 ALPH chunk, and return interleaved 8-bit [R, G, B, A] pixels (DecodedWebp) — the oxideav_core::PixelFormat::Rgba layout the workspace’s image crates share. As of round 124 a §2.5 VP8 lossy file is also decoded (via oxideav-vp8), with a §2.7.1.2 ALPH chunk layering the alpha plane over the opaque VP8 picture.

Both the §2.5 VP8 lossy and §2.6 VP8L lossless image-data paths now decode end-to-end (the lossy path through the oxideav-vp8 sibling crate). The §2.7.1.2 ALPH alpha bitstream is also decoded end-to-end (alph::decode_alpha / decode_alpha_plane). VP8 / VP8L bitstream encode remains framing-only — the builders take an externally pre-computed codec payload.

Re-exports§

pub use registry::WebpDecoder;

Modules§

alph: Typed parser for the ALPH chunk info byte per RFC 9649 §2.7.1.2 (Figure 10).
anim: Typed parser for the ANIM chunk payload per RFC 9649 §2.7.1.1 (Figure 8).
anim_encode: Animation encoder — the published-0.1.5 build_animated_webp surface, rebuilt clean-room on top of the in-crate §3.7 VP8L lossless encoder and the §2.7.1.1 ANIM / ANMF container framing.
anmf: Typed parser for the per-frame ANMF chunk header per RFC 9649 §2.7.1.1 (Figure 9).
build: RIFF/WEBP container builder helpers per RFC 9649 §2.3–§2.7.
container: RIFF/WEBP container walker per RFC 9649 (WebP Image Format).
decoder: Published-API oxideav_webp::decoder module — the published decode surface grouped under its qualified path.
demux: Published-API oxideav_webp::demux module — metadata extraction grouped under its qualified path.
encoder: Published-API oxideav_webp::encoder module — RIFF-wrapped output factories.
encoder_anim: Published-API oxideav_webp::encoder_anim module — animation encoder surface grouped under its qualified path.
encoder_vp8: Published-API oxideav_webp::encoder_vp8 module — VP8 lossy factory façade, plus the §6 / §9 quality-knob types reproduced on top of the workspace oxideav-vp8 sibling crate’s public surface.
error: Published-API oxideav_webp::error module — Result type alias plus the WebpError re-export.
meta_prefix: VP8L (WebP-Lossless) §5.2.3 color-cache info + §6.2.2 meta-prefix header reader + §6.2 5-prefix-code-group reader.
registry: oxideav-core integration — Decoder trait impl, Frame / Error conversions, and the register entry point.
riff: Published-API oxideav_webp::riff module — re-export shim over the in-crate RIFF/WEBP container walker / builder.
vp8_chunk: Typed §2.5 VP8 chunk handle.
vp8_decode: §2.5 VP8 (lossy) bitstream decode → interleaved RGBA.
vp8l: Published-API oxideav_webp::vp8l module — the §3.4 / §4–§6 VP8L lossless surface grouped under its qualified path.
vp8l_chunk: Typed §2.6 VP8L chunk handle.
vp8l_decode: VP8L (WebP-Lossless) §5.2 LZ77 backward-reference + §5.2.3 color-cache per-pixel ARGB decode loop.
vp8l_encode: VP8L (WebP-Lossless) §3.8 / §3.7 encoder.
vp8l_prefix: VP8L (WebP-Lossless) §6.2.1 prefix-code reader + canonical decoder.
vp8l_stream: VP8L (WebP-Lossless) bit-reader + §4 transform-list header reader.
vp8l_transform: VP8L (WebP-Lossless) §4 inverse-transform passes.
vp8x: Typed parser for the VP8X chunk payload per RFC 9649 §2.7.1 (Extended File Format → Figure 7).

Structs§

AnimEncoderOptions: Options for build_animated_webp_with_options.
AnimFrame: A single animation frame to encode.
DecodedWebp: A fully decoded still WebP image: 8-bit RGBA pixels plus dimensions.
DeltaConfig: Tuning knobs for the inter-frame delta path.
WebpFileMetadata: File-level metadata chunks, each carrying the raw chunk payload bytes when present.
WebpFrame: A single decoded WebP frame: a flat RGBA pixel buffer plus its size and (for animations) its display duration.
WebpImage: A fully decoded WebP file: one frame for a still image, N frames for an animation, plus the file-level metadata and animation parameters.
WebpMetadata: Borrowed file-level metadata for the encode side — the §2.7.1.4 ICCP, §2.7.1.5 EXIF, and §2.7.1.5 XMP payloads to embed, each None to omit the corresponding chunk.
WebpMetadataOwned: Owned file-level metadata — the registry-side counterpart of the borrowed WebpMetadata.

Enums§

AnimFrameMode: How a single animation frame’s pixels are compressed into its ANMF “Frame Data” bitstream subchunk.
DownsampleKernel: Multi-scale SSIM downsample kernel selector for the (blocked) delta path.
Error: Crate-local error type.
UnsupportedKind: Which image kind decode_webp declined to decode.
WebpError: The published-API error type for the flat decode_webp / extract_metadata decode paths.

Constants§

CODEC_ID_VP8: Stable codec identifier the VP8 lossy encoder registers under in the codec registry — the published "webp_vp8" name. The encoder itself is blocked on the oxideav-vp8 Phase-2 lossy encoder (workspace task #1041); the id is reserved so consumers can look it up today and the registry slots in the factory once the encoder lands.
CODEC_ID_VP8L: Stable codec identifier the VP8L lossless encoder registers under in the codec registry — the published "webp_vp8l" name.

Functions§

build_animated_webp: Build an animated .webp from frames, defaulting all encoder options (infinite loop, transparent-black background, no metadata).
build_animated_webp_with_options: Assemble a complete animated RIFF/WEBP file from frames per RFC 9649 §2.7.1.1.
build_vp8x_chunk: Build the 10-byte §2.7.1 VP8X chunk payload (flags + reserved + canvas dims). Convenience wrapper over build::build_vp8x_chunk returning the crate-wide Error.
build_webp_file: Assemble a RIFF/WEBP file around a single bitstream payload per RFC 9649 §2.4 + §2.5 / §2.6 / §2.7. Convenience wrapper over build::build_webp_file returning the crate-wide Error.
decode_alpha_plane: Walk a RIFF/WEBP buffer and, if it carries a §2.7.1.2 ALPH chunk, fully decode the alpha bitstream to a width * height plane of 8-bit alpha values in scan order.
decode_lossless_image: Walk a RIFF/WEBP buffer, extract its §2.6 / §3.4 VP8L chunk, and fully decode it to ARGB pixels.
decode_webp: Decode a WebP file to the published flat-RGBA WebpImage shape.
decode_webp_image: Decode a still WebP file to a typed DecodedWebp (RGBA + dims).
encode_vp8l_argb: Encode an ARGB image to a bare §2.6 / §3.4 VP8L bitstream — the chunk payload (image-header + image stream), with no RIFF/WEBP wrapper.
encode_vp8l_argb_with: Encode an ARGB image to a bare §2.6 / §3.4 VP8L bitstream with the §3.4 alpha_is_used header bit set explicitly by the caller.
encode_vp8l_argb_with_metadata: Encode an ARGB image to a complete .webp file carrying a §2.6 VP8L lossless bitstream, embedding any supplied file-level metadata.
encode_webp_lossless: Encode an interleaved 8-bit RGBA image to a complete RIFF/WEBP file carrying a §2.6 simple-lossless VP8L chunk.
extract_lossless_chunk: Walk a RIFF/WEBP buffer and, if it carries a §2.6 simple-lossless VP8L chunk (or a §2.7 extended-lossless file with a VP8L chunk alongside VP8X), return a typed vp8l_chunk::WebpLosslessChunk handle whose bitstream slice can be routed to an external VP8L decoder.
extract_lossy_chunk: Walk a RIFF/WEBP buffer and, if it carries a §2.5 simple-lossy VP8 chunk (or a §2.7 extended-lossy file with a VP8 chunk alongside VP8X), return a typed vp8_chunk::WebpLossyChunk handle whose bitstream slice can be routed to an external VP8 decoder.
extract_metadata: Read the file-level metadata chunks (ICC / Exif / XMP) without decoding any pixels.
parse_alph_header: Decode the §2.7.1.2 ALPH chunk info byte to a typed alph::AlphHeader.
parse_anim_header: Decode the §2.7.1.1 ANIM chunk payload to a typed anim::AnimHeader.
parse_anmf_header: Decode the §2.7.1.1 ANMF per-frame header to a typed anmf::AnmfHeader.
parse_container: Walk a RIFF/WEBP container per RFC 9649 §2.3–§2.7 and return the structural chunk list. This is the round-1 surface: it does not decode any payload.
parse_vp8x_header: Decode the §2.7.1 VP8X chunk payload to a typed vp8x::Vp8xHeader.
read_vp8l_transform_list: Walk a RIFF/WEBP buffer, extract its §2.6 / §3.4 VP8L chunk, and read the §4 transform-presence list that follows the 5-byte VP8L image-header.
register: Install the WebP decoder factory and the .webp extension hint into ctx per round 112.
register_codecs: Install only the WebP codec factories into ctx — the per-codec Decoder / Encoder impls under the "webp", "webp_vp8l", and "webp_vp8" ids.
register_containers: Install only the WebP container hooks into ctx — the .webp file-extension mapping that lets a demuxer-discovery pass route a .webp file back to the WebP codec id.