# [−][src]Crate gif

# GIF en- and decoding library

GIF en- and decoder written in Rust (API Documentation).

# GIF encoding and decoding library

This library provides all functions necessary to de- and encode GIF files.

## High level interface

The high level interface consists of the two types `Encoder` and `Decoder`. They as builders for the actual en- and decoders and can be used to set various options beforehand.

### Decoding GIF files

    // Open the file
    use std::fs::File;
    use gif::SetParameter;
    let mut decoder = gif::Decoder::new(File::open("tests/samples/sample_1.gif").unwrap());
    // Configure the decoder such that it will expand the image to RGBA.
    decoder.set(gif::ColorOutput::RGBA);
    // Read the file header
    let mut decoder = decoder.read_info().unwrap();
    while let Some(frame) = decoder.read_next_frame().unwrap() {
        // Process every frame
    }

### Encoding GIF files

The encoder can be used so save simple computer generated images:

    use gif::{Frame, Encoder, Repeat, SetParameter};
    use std::fs::File;
    use std::borrow::Cow;

    let color_map = &[0xFF, 0xFF, 0xFF, 0, 0, 0];
    let (width, height) = (6, 6);
    let mut beacon_states = [[
        0, 0, 0, 0, 0, 0,
        0, 1, 1, 0, 0, 0,
        0, 1, 1, 0, 0, 0,
        0, 0, 0, 1, 1, 0,
        0, 0, 0, 1, 1, 0,
        0, 0, 0, 0, 0, 0,
    ], [
        0, 0, 0, 0, 0, 0,
        0, 1, 1, 0, 0, 0,
        0, 1, 0, 0, 0, 0,
        0, 0, 0, 0, 1, 0,
        0, 0, 0, 1, 1, 0,
        0, 0, 0, 0, 0, 0,
    ]];
    let mut image = File::create("tests/samples/beacon.gif").unwrap();;
    let mut encoder = Encoder::new(&mut image, width, height, color_map).unwrap();
    encoder.set(Repeat::Infinite).unwrap();
    for state in &beacon_states {
        let mut frame = Frame::default();
        frame.width = width;
        frame.height = height;
        frame.buffer = Cow::Borrowed(&*state);
        encoder.write_frame(&frame).unwrap();
    }

`Frame::from_*` can be used to convert a true color image to a paletted image with a maximum of 256 colors:

    use std::fs::File;

    // Get pixel data from some source
    let mut pixels: Vec<u8> = vec![0; 30_000];
    // Create frame from data
    let frame = gif::Frame::from_rgb(100, 100, &mut *pixels);
    // Create encoder
    let mut image = File::create("target/indexed_color.gif").unwrap();
    let mut encoder = gif::Encoder::new(&mut image, frame.width, frame.height, &[]).unwrap();
    // Write frame to file
    encoder.write_frame(&frame).unwrap();

## C API

The C API is unstable and widely untested. It can be activated using the feature flag `c_api`.

## Structs

Decoder | GIF decoder
Encoder | GIF encoder.
Frame | A GIF frame
MemoryLimit | Memory limit in bytes. `MemoryLimit::Some(0)` means that there is no memory limit set.
Reader | GIF decoder
StreamingDecoder | GIF decoder which supports streaming

## Enums

Block | Known GIF block types
ColorOutput | Output mode for the image data
Decoded | Indicates whether a certain object has been decoded
DecodingError | Decoding error.
DisposalMethod | Disposal method
Extension | Known GIF extensions
ExtensionData | Extension data.
Extensions | Configures how extensions should be handled
Repeat | Number of repetitions

## Traits

Parameter | Configuration parameter trait.
SetParameter | Implemented for objects that have parameters.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)