Skip to main content

Crate oxideav_gif

Crate oxideav_gif 

Source
Expand description

Pure-Rust GIF87a / GIF89a codec.

Decode a byte stream with decode and produce a GifImage. Use decode_first_frame when you only need the cover frame — it short-circuits at the first image-bearing block and skips the per-block dispatch overhead for everything that follows. Construct or modify a GifImage and serialise it with encode.

§Implemented (per CompuServe specifications)

  • Header, Logical Screen Descriptor, Global / Local Color Tables (§17–§19, §21).
  • Image Descriptor + Table-Based Image Data, including the LZW variable-length-code compression scheme of Appendix F (§20, §22).
  • Graphic Control Extension — disposal method, user-input flag, transparent colour index, delay time (§23).
  • Comment, Plain Text, and Application Extensions (§24, §25, §26).
  • Trailer (§27).
  • Four-pass interlace transform (Appendix E) on both decode and encode.
  • Multi-frame compositing onto the §18 Logical Screen using the §23 Disposal Method state machine — see [compose] for the eager Vec<ComposedFrame> form, playback::Playback for the lazy iterator form (one canvas at a time, plus a NETSCAPE2.0 loop-count-aware playback::LoopingFrameIter).

§Application-extension structured views

The CompuServe spec defines no concrete §26 Application Extensions. The app_ext module layers typed parsers on top of the raw Application block for the five ecosystem-defined shapes that achieved cross-decoder de-facto interoperability:

These accessors layer on top of the raw block list — the Application block stays in GifImage::blocks regardless, preserving byte-stable round-trip.

§§7 Required Version enforcement on encode

The CompuServe spec’s §7 (“Version Numbers”) requires encoders to label a stream with the earliest version that covers every block in it. Per-block “Required Version” entries are 87a for §20 Image Descriptor / §21 Local Color Table / §22 Table-Based Image Data and 89a for §23 Graphic Control / §24 Comment / §25 Plain Text / §26 Application Extensions.

encode enforces this on the encoder side: a GifImage declared Version::Gif87a that contains any 89a-only block is rejected with Error::InvalidInput before any bytes go to the wire — the alternative (“a GIF87a header followed by 89a-only block payloads”) would be structurally invalid.

Two recovery helpers ride on top: GifImage::required_version returns the minimum version that covers the current block list, and GifImage::upgrade_version_if_needed bumps the declared version up to that minimum in one call. The upgrade helper never downgrades: a caller’s explicit choice of Version::Gif89a for an 87a-compatible payload is preserved.

§§24 Comment Extension accessors

The CompuServe spec (§24.a) allows any number of Comment Extensions in the Data Stream and recommends (§24.e.i) that they contain 7-bit ASCII text and (§24.e.ii) that they appear at the beginning or end of the stream. GifImage::comments iterates the payloads in source order; GifImage::concatenated_comment returns every payload joined with a single LF (or None when no Comment Extension is present). GifImage::comments_are_7bit_ascii and GifImage::comments_in_recommended_position surface the §24.e recommendations as boolean queries so a caller that wants to honour them strictly can gate on them; the encoder itself never enforces a recommendation.

§Plain Text rendering

The §25 Plain Text Extension leaves font choice to the decoder (§25.e). [compose] / playback render Plain Text blocks against a crate-local clean-room 8×8 monospace bitmap font (see font) using the §23.c.viii transparent-index handling for the background colour. Out-of-range characters fall back to space per §25.e.

§Standalone vs registry-integrated

With the default registry Cargo feature on, the crate exposes oxideav_core::Decoder / oxideav_core::Encoder trait impls plus a registry::register entry point against oxideav-core. With the feature off the crate ships only the standalone decode / encode / [compose] API plus the local GifImage / Error types, with no oxideav-core dep in the tree. Image-library consumers should depend on oxideav-gif with default-features = false.

Re-exports§

pub use builder::AnimationBuilder;
pub use compose::compose;
pub use compose::ComposedFrame;
pub use compose::RgbaCanvas;
pub use decoder::decode;
pub use decoder::decode_first_frame;
pub use decoder::decode_lenient;
pub use encoder::encode;
pub use error::Error;
pub use error::Result;
pub use image::Application;
pub use image::Block;
pub use image::DisposalMethod;
pub use image::Frame;
pub use image::GifImage;
pub use image::GraphicControl;
pub use image::PlainText;
pub use image::Rgb;
pub use image::Version;
pub use playback::FrameIter;
pub use playback::LoopingFrameIter;
pub use playback::Playback;
pub use playback::PlaybackFrame;
pub use registry::register;
pub use registry::register_codecs;
pub use registry::register_containers;
pub use registry::GifDecoder;
pub use registry::GifEncoder;
pub use registry::CODEC_ID_STR;

Modules§

app_ext
Structured parsing for well-known GIF Application Extensions (§26).
builder
High-level assembly of an animated GifImage.
compose
Multi-frame compositing per GIF89a §18 + §23.
decoder
GIF87a / GIF89a top-level decoder.
encoder
GIF87a / GIF89a top-level encoder.
error
Error type returned by decode/encode entry points.
font
Minimal 8×8 bitmap font for the GIF89a §25 Plain Text Extension.
image
In-memory representation of a parsed or to-be-encoded GIF stream.
interlace
Appendix E — interlaced row ordering.
lzw
Variable-Length-Code LZW per Appendix F of the GIF89a specification.
playback
Animation playback iterators over a parsed crate::GifImage.
registry
oxideav-core integration layer for oxideav-gif.