README

   1 GIF encoder
   2 ===========
   3
   4 This is a small C library that can be used to create GIF animations.
   5
   6 Features
   7 --------
   8
   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
  16   * public domain
  17
  18
  19 Limitations
  20 -----------
  21
  22   * no frame-local palettes (incompatible with size optimization)
  23   * no interlacing (bad for compression, useless for animations)
  24
  25
  26 Documentation
  27 -------------
  28
  29 There   are  only   three  functions   declared  in   "gifenc.h":  ge_new_gif(),
  30 ge_add_frame() and ge_close_gif().
  31
  32 The  ge_new_gif() function  receives GIF  global  options and  returns a  ge_GIF
  33 handler:
  34
  35     ge_GIF *ge_new_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 */
  41     );
  42
  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.
  46
  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.
  49
  50 Example `palette` and `depth` values:
  51
  52     uint8_t palette[] = {
  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 */
  57     };
  58     int depth = 2;          /* palette has 1 << 2 (i.e. 4) entries */
  59
  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.
  65
  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.
  68
  69 The `bgindex`  parameter specifies the  color number  to be used  as transparent
  70 background. If `bgindex` < 0, then transparency is disabled.
  71
  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").
  76
  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:
  79
  80     void ge_add_frame(ge_GIF *gif, uint16_t delay);
  81
  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.
  88
  89 Pixel data is read from `gif->frame`, which points to a memory block like this:
  90
  91     uint8_t _frame_[gif->width * gif->height];
  92
  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.
 101
 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:
 105
 106     uint8_t pixels[] = {
 107         2, 2, 2, 2,
 108         2, 0, 0, 0,
 109         2, 0, 0, 0,
 110         2, 2, 2, 0,
 111         2, 0, 0, 0,
 112         2, 0, 0, 0,
 113         2, 0, 0, 0
 114     };
 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);
 118     ge_close_gif(gif);
 119
 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
 124 anymore.
 125
 126     void ge_close_gif(ge_GIF* gif);
 127
 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().
 131
 132
 133 Example
 134 -------
 135
 136 See the file "example.c". It can be tested like this:
 137
 138 $ cc -o example gifenc.c example.c
 139 $ ./example
 140
 141 That should create an animated GIF named "example.gif".
 142
 143
 144 Copying
 145 -------
 146
 147 All of the source code and documentation for gifenc is released into the
 148 public domain and provided without warranty of any kind.