323 lines
10 KiB
C
323 lines
10 KiB
C
/*
|
|
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 <stdio.h>
|
|
|
|
#include <stdint.h>
|
|
#include <sys/types.h>
|
|
|
|
#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 */
|