This is a small C library that can be used to read GIF files.
- 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
- CMake integration
- no support for GIF files that don't have a global color table
- no direct support for the plain text extension (rarely used)
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
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);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);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.
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.
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);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);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;
}
}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.
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.
All of the source code and documentation for gifdec is released into the public domain and provided without warranty of any kind.