4 This is a small C library that can be used to create GIF animations.
9 * user-defined palette of any depth from 1 up to 8
10 * each frame has its own (user-specified) delay time
11 * flexible looping options: no loop, N repetitions, infinite loop
12 * optional transparent background
13 * GIF size optimization: only stores frame differences
14 * memory efficient: saves frames to file as soon as possible
15 * small and portable: less than 300 lines of C99
22 * no frame-local palettes (incompatible with size optimization)
23 * no interlacing (bad for compression, useless for animations)
29 There are only three functions declared in "gifenc.h": ge_new_gif(),
30 ge_add_frame() and ge_close_gif().
32 The ge_new_gif() function receives GIF global options and returns a ge_GIF
36 const char *fname, /* GIF file name */
37 uint16_t width, uint16_t height, /* frame size */
38 uint8_t *palette, int depth, /* color table */
39 int bgindex, /* transparent color */
40 int loop /* looping information */
43 The `palette` parameter must point to an array of color data. Each entry is a
44 24-bits RGB color, stored as three contiguous bytes: the first is the red value
45 (0-255), then green, then blue. Entries are stored in a contiguous byte array.
47 The `depth` parameter specifies how many colors are present in the given
48 palette. The number of color entries must be 2 ^ depth, where 1 <= depth <= 8.
50 Example `palette` and `depth` values:
53 0x00, 0x00, 0x00, /* entry 0: black */
54 0xFF, 0xFF, 0xFF, /* entry 1: white */
55 0xFF, 0x00, 0x00, /* entry 2: red */
56 0x00, 0x00, 0xFF, /* entry 3: blue */
58 int depth = 2; /* palette has 1 << 2 (i.e. 4) entries */
60 If `palette` is NULL, entries are taken from a default table of 256 colors. If
61 `depth` < 8, the default table will be truncated to the appropriate size. The
62 default table is composed of the 16 standard VGA colors, plus the 216 web-safe
63 colors (all combinations of RGB with only 6 valid values per channel), plus 24
64 grey colors equally spaced between black and white, excluding both.
66 If `depth` < 0 and `palette` is not NULL, then the default table with 2 ^ -depth
67 colors is used and it is stored in the array at the `palette` address.
69 The `bgindex` parameter specifies the color number to be used as transparent
70 background. If `bgindex` < 0, then transparency is disabled.
72 If the `loop` parameter is zero, the resulting GIF will loop forever. If it is a
73 positive number, the animation will be played that number of times. If `loop`
74 is negative, no looping information is stored in the GIF file (for most GIF
75 viewers, this is equivalent to `loop` == 1, i.e., "play once").
77 The ge_add_frame() function reads pixel data from a buffer and saves the
78 resulting frame to the file associated with the given ge_GIF handler:
80 void ge_add_frame(ge_GIF *gif, uint16_t delay);
82 The `delay` parameter specifies how long the frame will be shown, in hundreths
83 of a second. For example, `delay` == 100 means "show this frame for one second"
84 and `delay` == 25 means "show this frame for a quarter of a second". Note that
85 short delays may not be supported by some GIF viewers: it's recommended to keep
86 a minimum of `delay` == 6. If `delay` == 0, no delay information will be stored
87 for the frame. This can be used when creating still (single-frame) GIF images.
89 Pixel data is read from `gif->frame`, which points to a memory block like this:
91 uint8_t _frame_[gif->width * gif->height];
93 Note that, iif transparency is disabled, the address of `gif->frame` changes
94 between calls to ge_add_frame() (*). For this reason, each frame must be written
95 in its entirety to the current address, even if one only wants to change a few
96 pixels from the last frame. The encoder will automatically detect the difference
97 between two consecutive frames in order to minimize the size of the output. This
98 optimization is not applied when `gif->bgindex` >= 0, in which case it's safe to
99 reuse `gif->frame`'s address and content. Transparent GIFs are still slightly
100 optimized by encoding only the rectangular region containing all opaque pixels.
102 Each byte in the frame buffer represents a pixel. The value of each pixel is an
103 index to a palette entry. For instance, given the example palette above, we can
104 create a frame displaying a red-on-black "F" letter like this:
115 ge_GIF *gif = ge_new_gif("F.gif", 4, 7, palette, depth, -1);
116 memcpy(gif->frame, pixels, sizeof(pixels));
117 ge_add_frame(gif, 0);
120 The function ge_close_gif() finishes writting GIF data to the file associated
121 with the given ge_GIF handler and does memory clean-up. This function must be
122 called once after all desired frames have been added, in order to correctly save
123 the GIF file. After calling this function, the ge_GIF handler cannot be used
126 void ge_close_gif(ge_GIF* gif);
128 (*) The encoder keeps two frame buffers internally, in order to implement the
129 size optimization. The address of `gif->frame` alternates between those two
130 buffers after each call to ge_add_frame().
136 See the file "example.c". It can be tested like this:
138 $ cc -o example gifenc.c example.c
141 That should create an animated GIF named "example.gif".
147 All of the source code and documentation for gifenc is released into the
148 public domain and provided without warranty of any kind.