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.
