GIF decoder
===========

This is a small C library that can be used to read GIF files.

Features
--------

  * support for all standard GIF features
  * support for Netscape Application Extension (looping information)
  * other extensions may be easily supported via user hooks
  * small and portable: less than 500 lines of C99
  * public domain


Limitations
-----------

  * no support for GIF files that don't have a global color table
  * no direct support for the plain text extension (rarely used)


Documentation
-------------

0. Essential GIF concepts

GIF  animations  are  stored  in  files as  a  series  of  palette-based
compressed frames.

In order to display the animation, a  program must lay the frames on top
of a  fixed-size canvas,  one after  the other. Each  frame has  a size,
position and  duration. Each  frame can  have its own  palette or  use a
global palette defined in the beginning of the file.

In order to  properly use extension hooks, it's  necessary to understand
how GIF files store variable-sized data. A GIF block of variable size is
a sequence  of sub-blocks. The first  byte in a sub-block  indicates the
number of data bytes to follow. The  end of the block is indicated by an
empty sub-block: one  byte of value 0x00. For instance,  a data block of
600 bytes is stored as 4 sub-blocks:

  255, <255 data bytes>, 255, <255 data bytes>, 90, <90 data bytes>, 0

1. Opening and closing a GIF file

The function `gd_open_gif()` tries to open a GIF file for reading.

    gd_GIF *gd_open_gif(const char *fname);

If this function fails, it returns NULL.

If `gd_open_gif()` succeeds, it returns  a GIF handler (`gd_GIF *`). The
GIF handler  can be passed to  the other gifdec functions  to decode GIF
metadata and frames.

To close  the GIF file  and free memory after  it has been  decoded, the
function `gd_close_gif()` must be called.

    void gd_close_gif(gd_GIF *gif);

2. Reading GIF attributes

Once a GIF file has been successfully opened, some basic information can
be read directly from the GIF handler:

    gd_GIF *gif = gd_open_gif("animation.gif");
    printf("canvas size: %ux%u\n", gif->width, gif->height);
    printf("number of colors: %d\n", gif->palette->size);

3. Reading frames

The function `gd_get_frame()` decodes one frame from the GIF file.

    int gd_get_frame(gd_GIF *gif);

This function returns 0 if there are no more frames to read.

The decoded frame  is stored in `gif->frame`, which is  a buffer of size
`gif->width * gif->height`, in bytes. Each byte value is an index to the
palette at `gif->palette`.

Since GIF files often only store  the rectangular region of a frame that
changed  from the  previous frame,  this function  will only  update the
bytes in `gif->frame`  that are in that region. For  GIF files that only
use  the global  palette, the  whole state  of the  canvas is  stored in
`gif->frame`  at all  times,  in the  form of  an  indexed color  image.
However, when  local palettes are  used, it's  not enough to  keep color
indices from previous frames. The color RGB values themselves need to be
stored.

For this  reason, in order  to get the whole  state of the  canvas after
a  new  frame  has  been  read, it's  necessary  to  call  the  function
`gd_render_frame()`, which writes all pixels to a given buffer.

    void gd_render_frame(gd_GIF *gif, uint8_t *buffer);

The buffer  size must  be at  least `gif->width *  gif->height *  3`, in
bytes. The function `gd_render_frame()` writes  the 24-bit RGB values of
all canvas pixels in it.

4. Frame duration

GIF animations  are not  required to  have a  constant frame  rate. Each
frame can  have a different duration,  which is stored right  before the
frame in a Graphic Control Extension  (GCE) block. This type of block is
read  by gifdec  into a  `gd_GCE` struct  that is  a member  of the  GIF
handler. Specifically,  the unsigned integer `gif->gce.delay`  holds the
current frame duration,  in hundreths of a second. That  means that, for
instance, if  `gif->gce.delay` is `50`,  then the current frame  must be
displayed for half a second.

5. Looping

Most GIF  animations are supposed  to loop automatically, going  back to
the first frame  after the last one is displayed.  GIF files may contain
looping instruction in the form of a non-negative number. If this number
is  zero,  the  animation  must loop  forever.  Otherwise,  this  number
indicates how many times the animation  must be played. When `gifdec` is
decoding a GIF file, this number is stored in `gif->loop_count`.

The function `gd_rewind()` must be called to go back to the start of the
GIF file without closing and reopening it.

    void gd_rewind(gd_GIF *gif);

6. Putting it all together

A simplified skeleton of a GIF viewer may look like this:

    gd_GIF *gif = gd_open_gif("some_animation.gif");
    char *buffer = malloc(gif->width * gif->height * 3);
    for (unsigned looped = 1;; looped++) {
        while (gd_get_frame(gif)) {
            gd_render_frame(gif, buffer);
            /* insert code to render buffer to screen
                and wait for delay time to pass here  */
        }
        if (looped == gif->loop_count)
            break;
        gd_rewind(gif);
    }
    free(buffer);
    gd_close_gif(gif);

7. Transparent Background

GIFs can mark a certain color in the palette as the "Background Color".
Pixels having this  color are usually treated as  transparent pixels by
applications.

The function `gd_is_bgcolor()`  can be used to check whether  a pixel in
the canvas currently has background color.

    int gd_is_bgcolor(gd_GIF *gif, uint8_t color[3]);

Here's an example of how to use it:

    gd_render_frame(gif, buffer);
    color = buffer;
    for (y = 0; y < gif->height; y++) {
        for (x = 0; x < gif->width; x++) {
            if (gd_is_bgcolor(gif, color))
                transparent_pixel(x, y);
            else
                opaque_pixel(x, y, color);
            color += 3;
        }
    }

8. Reading streamed metadata with extension hooks

Some  metadata blocks  may occur  any number  of times  in GIF  files in
between frames.  By default, gifdec  ignore these blocks.  However, it's
possible to  setup callback functions  to handle each type  of extension
block, by changing some GIF handler members.

Whenever a Comment Extension block is found, `gif->comment()` is called.

    void (*comment)(struct gd_GIF *gif);

As defined in  the GIF specification, "[t]he  Comment Extension contains
textual information which is not part  of the actual graphics in the GIF
Data Stream." Encoders  are recommended to only include  "text using the
7-bit ASCII character set" in GIF comments.

The actual comment is stored as  a variable-sized block and must be read
from  the file  (using the  file descriptor  `gif->fd`) by  the callback
function. Here's an example, printing the comment to stdout:

    void
    comment(gd_GIF *gif)
    {
        uint8_t sub_len, byte, i;
        do {
            read(gif->fd, &sub_len, 1);
            for (i = 0; i < sub_len; i++) {
                read(gif->fd, &byte, 1);
                printf("%c", byte);
            }
        } while (sub_len);
        printf("\n");
    }
    
    /* ... */
    
    /* Somewhere on the main path of execution. */
    gif->comment = comment;


Whenever a Plain  Text Extension block is  found, `gif->plain_text()` is
called.

    void (*plain_text)(
        struct gd_GIF *gif, uint16_t tx, uint16_t ty,
        uint16_t tw, uint16_t th, uint8_t cw, uint8_t ch,
        uint8_t fg, uint8_t bg
    );

According to the GIF specification, "[t]he Plain Text Extension contains
textual  data and  the parameters  necessary to  render that  data as  a
graphic  [...]". This  is  a  rarely used  extension  that requires  the
decoder to actually render text on the canvas. In order to support this,
one  must  read the  relevant  specification  and implement  a  suitable
callback function to setup as `gif->plain_text`.

The actual  plain text is stored  as a variable-sized block  and must be
read from the file by the callback function.


Whenever   an   unknown   Application    Extension   block   is   found,
`gif->application()` is called.

    void (*application)(struct gd_GIF *gif, char id[8], char auth[3]);

Application  Extensions  are  used  to  extend  GIF  with  extraofficial
features.  Currently,  gifdec  only  supports  the  so-called  "Netscape
Application  Extension",  which  is  commonly used  to  specify  looping
behavior. Other Application Extensions may be supported via this hook.

The application  data is stored  as a  variable-sized block and  must be
read from the file by the callback function.


Example
-------

The file "example.c" is  a demo GIF player based on  gifdec and SDL2. It
can be tested like this:

    $ cc `pkg-config --cflags --libs sdl2` -o gifplay gifdec.c example.c
    $ ./gifplay animation.gif

That should display the animation. Press SPACE to pause and Q to quit.

Copying
-------

All of the source code and documentation for gifdec is released into the
public domain and provided without warranty of any kind.