/* 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. */ #ifndef GIFDEC_H #define GIFDEC_H #include #include #include #ifdef __cplusplus extern "C" { #endif typedef struct gd_Palette { int size; uint8_t colors[0x100 * 3]; } gd_Palette; typedef struct gd_GCE { uint16_t delay; uint8_t tindex; uint8_t disposal; int input; int transparency; } gd_GCE; typedef struct gd_GIF { FILE *fd; off_t anim_start; uint16_t width, height; uint16_t depth; uint16_t loop_count; gd_GCE gce; gd_Palette *palette; gd_Palette lct, gct; 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 ); void (*comment)(struct gd_GIF *gif); void (*application)(struct gd_GIF *gif, char id[8], char auth[3]); uint16_t fx, fy, fw, fh; uint8_t bgindex; uint8_t *canvas, *frame; } gd_GIF; gd_GIF *gd_open_gif(const char *fname); gd_GIF *gd_open_gif_f(FILE *f); int gd_get_frame(gd_GIF *gif); void gd_render_frame(gd_GIF *gif, uint8_t *buffer); int gd_is_bgcolor(gd_GIF *gif, uint8_t color[3]); void gd_rewind(gd_GIF *gif); void gd_close_gif(gd_GIF *gif); #ifdef __cplusplus } #endif #endif /* GIFDEC_H */