Gershon Elber, May 1991
Eric S. Raymond, Sep 1992
Toshio Kuratomi, May 2004
Gershon wrote: "This library was written because I couldn't find anything similar and I wanted one. I was inspired by the RLE Utah tool kit, which I hoped to port to an IBM PC, but found it to be too machine specific, and its compression ratio too low. I compromised on the GIF format, but I am not sure how long 8 bits per pixel will be enough."
This document explains the GIF library code in directory `lib'. The code is collected into libgif.a which is used in all the utilities in `util'. It can be used in any application needs to read/write the GIF file format. This document does not explain the GIF file format and assumes you know it, at least to the level of the GIF file structure.
When a GIF file is opened, a GIF file descriptor is created which is a pointer to GifFileType structure as follows:
typedef struct GifFileType {
    int SWidth, SHeight,			       /* Screen dimensions. */
	SColorResolution, 		 /* How many colors can we generate? */
	SBackGroundColor;		/* I hope you understand this one... */
    ColorMapObject *SColorMap;			      /* NULL if not exists. */
    int ImageCount;				  /* Number of current image */
    GifImageDesc Image;			   /* Block describing current image */
    struct SavedImage *SavedImages;	/* Use this to accumulate file state */
    VoidPtr Private;	  /* The regular user should not mess with this one! */
} GifFileType;
The user almost never writes into this structure (exception: it may occasionally useful to alter things in the SavedImages array), but can read any of these items at any time it is valid (image information is invalid until first image was read/write).
As the library needs to keep its own internal data, a Private pointer to hidden data is included. Applications should ignore this item.
The library has no static data. This means that it is fully reentrant and any number of GIF files (up to memory limits) can be opened for read/write. Instead of the static data, internal structure pointed by the Private pointer is used.
The library allocates its own memory dynamically, on opening of files, and releases that once closed. The user is never required to allocate any memory for any of the functions of this library nor to free them directly.
In order to reduce disk access, the file buffer is increased to FILE_BUFFER_SIZE (defined in gif_lib.h). The library was compiled in large model on the PC as the memory allocated per file is quite big: about 17k for decoding (DGIF_LIB.C), and 32k for encoding (EGIF_LIB.C), excluding the FILE_BUFFER_SIZE.
Here is a module summary:
Most of the routines return GIF_ERROR (see gif_lib.h) if something went wrong, GIF_OK otherwise. After an error return, the code in the gif_err.c module can be used to do something about it.
In addition, a module to parse command line arguments is supplied. This module is called getarg.c and its headers are in getarg.h. See the header of getarg.c for details on its usage.
GifFileType *DGifOpenFileName(char *GifFileName)
GifFileType *DGifOpenFileHandle(int GifFileHandle)
If any error occurs, NULL is returned and the error handler can be used to get the exact error (see gif_err.c).
The file is opened in binary mode, and its buffer size is set to FILE_BUFFER_SIZE bytes.
Once you have acquired a handle on a GIF, there are two ways to read it in. The high-level function
int DGifSlurp(GifFileType)
Once you have done this, all image, raster, and extension-block data in the GIF is accessable in the SavedImages member (see the structures in fif_lib.h). When you have modified the image to taste, write it out with EGifSpew().
If you are handling large images on a memory-limited machine, you may need to use the following functions for sequential read.
int DGifGetScreenDesc(GifFileType *GifFile)
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int DGifGetRecordType(GifFileType *GifFile, GifRecordType *GifType)
int DGifGetImageDesc(GifFileType *GifFile)
int DGifGetLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen)
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int DGifGetPixel(GifFileType *GifFile, PixelType GifPixel)
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int DGifGetComment(GifFileType *GifFile, char *GifComment)
For the definition of a comment, see EGifPutComment. Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int DGifGetExtension(
        GifFileType *GifFile,
        int *GifExtCode,
        ByteType **GifExtension)
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int DGifGetExtensionNext(GifFileType *GifFile, ByteType **GifExtension)
 Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int DGifGetCode(
        GifFileType *GifFile, 
        int *GifCodeSize, ByteType **GifCodeBlock)
This compressed code information can be written out using the EGifPutCode/EGifPutCodeNext sequence (see gifpos.c for example). Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int DGifGetCodeNext(GifFileType *GifFile, ByteType **GifCodeBlock)
int DGifGetLZCodes(GifFileType *GifFile, int *GifCode)
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int DGifCloseFile(GifFileType *GifFile)
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int EGifSpew(GifFileType *GifFile, int GifFileHandle)Writes a complete (possibly multi-image) GIF file to the indicated file handle from in-core allocated structures created by a previous DGifSlurp() or equivalent operations. Its arguments are a GIF file descriptor (as above) and an ordinary output file descriptor.
The file is written with a GIF87 stamp unless it contains one of the four special extension blocks defined in GIF89, in which case it is written with a GIF89 stamp.
If you are handling large images on a memory-limited machine, you may need to use the following functions for sequential write.
GifFileType *EGifOpenFileName(char *GifFileName, int GifTestExistance)
If any error occurs, NULL is returned and the error handler can be used to get the exact error (see gif_err.c).
The file is opened in binary mode, and its buffer size is set to FILE_BUFFER_SIZE bytes.
GifFileType *EGifOpenFileHandle(int GifFileHandle)
If any error occurs, NULL is returned and the error handler can be used to get the exact error (see gif_err.c).
The file is opened in binary mode, and its buffer size is set to FILE_BUFFER_SIZE bytes.
void EGifSetGifVersion(char *Version)
int EGifPutScreenDesc(GifFileType *GifFile,
        int GifWidth, int GifHeight,
        int GifColorRes, int GifBackGround,
        ColorMapObject *GifColorMap)
This routine should be called immediately after the GIF file was opened.
int EGifPutImageDesc(GifFileType *GifFile,
        int GifLeft, int GifTop,
        int Width, int GifHeight,
        int GifInterlace,
        ColorMapObject *GifColorMap)
This routine should be called each time a new image must be dumped to the file.
int EGifPutLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen)
 Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int EGifPutPixel(GifFileType *GifFile, PixelType GifPixel)
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int EGifPutComment(GifFileType *GifFile, char *GifComment)
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int EGifPutExtension(
        GifFileType *GifFile,
        int GifExtCode,
        int GifExtLen,
        void *GifExtension)
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int EGifPutExtensionFirst(
        GifFileType * GifFile,
        int GifExtCode,
        int GifExtLen,
        const VoidPtr GifExtension)
Further blocks of the GIF Extension should be dumped using EGifPutExtensionNext. When finished with this extension block, EGifPutExtensionLast should be called to output the block termination.
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int EGifPutExtensionNext(
        GifFileType * GifFile,
        int GifExtCode,
        int GifExtLen,
        const VoidPtr GifExtension)
Note that EGifPutExtensionFirst needs to be called before any calls to this function. EGifPutExtensionLast should be called to finish the Extension block after all data subblocks have been output.
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int EGifPutExtensionLast(
        GifFileType * GifFile,
        int GifExtCode,
        int GifExtLen,
        const VoidPtr GifExtension)
Note that a call to EGifPutExtensionFirst is needed to open the GIF Extension Block prior to calling this function.
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int EGifPutCode(
        GifFileType *GifFile,
        int *GifCodeSize,
        ByteType **GifCodeBlock)
This routine does exactly that (with EGifPutCodeNext), and can be used instead of EGifPutLine. You'll usually use this with the DGifGetCode/DgifGetCodeNext routines, which reads the compressed code, while EGifPutCode/EGifPutCodeNext write it out. See gifpos.c for example.
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
int EGifPutCodeNext(GifFileType *GifFile, ByteType **GifCodeBlock)
int EGifCloseFile(GifFileType *GifFile)
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.
ColorMapObject *MakeMapObject(int ColorCount, GifColorType *ColorMap)
void FreeMapObject(ColorMapObject *Object)
ColorMapObject *UnionColorMap(
        ColorMapObject *ColorIn1, ColorMapObject *ColorIn2,
        GifPixelType ColorTransIn2[])
SavedImage *GifAttachImage(GifFileType *GifFile)
The GIF utility font support includes entry points for drawing legends on in-core images, drawing boxes and rectangles, and boxing text. These entry points are as follows:
void DrawText(
        SavedImage *Image,
        const int x, const int y,
        const char *legend,
        const int color)
void DrawBox(SavedImage *Image,
        const int x, const int y,
        const int w, const int h,
        const int color)
void DrawRectangle(SavedImage *Image,
        const int x, const int y,
        const int w, const int h,
        const int color)
void DrawBoxedText(SavedImage *Image,
        const int x, const int y,
        const char *legend,
        const int border,
        const int bg, const int fg)
This function interprets some characters in the legend string specially. A tab (\t) is interpreted as a command to center the following text in the box. A carriage return (\r) is interpreted as a request for a line break.
void PrintGifError(void)
int GifLastError(void)
Note it is the user's responsibility to call the file closing routine, so the file will be closed (if was opened), and allocated memory will be released.
int DumpScreen2Gif(char *FileName, int ReqGraphDriver, int ReqGraphMode1,
						       int ReqGraphMode2)
1. Hercules. 2. EGA, EGA64, EGAMONO (all modes - see TC graphics.h). 3. VGA (all modes - see TC graphics.h). 4. SVGA_SPECIAL. This mode is special and not supported by Borland graphics.h. ReqGraphDriver must be equal to 999, and ReqGraphMode is ignored. This modes assumes 800 by 600 in 16 colors. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. 5. SGI 4D using gl graphic library - window dump. 6. X11 window dump.
int GAGetArgs(int argc, char **argv, char *CtrlStr, ...)
The CtrlStr defines what types of variables should follow. Look at the beginning of getarg.c for exact usage.
Returns 0 if successful, error number (as defined by getarg.h) otherwise.
void GAPrintErrMsg(int Error)
void GAPrintHowTo(char *CtrlStr)
A sequential filter skeleton will usually look like the example file giffiltr.c in util.
Please look at the utilities in the util directory for more ideas once you feel comfortable with these skeletons. Also try to follow the coding standards of this package if you want the maintainer to officially add your new utility to it.