The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated.

This document explains the GIF library code in directory `lib'. The code is collected into a service library 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.

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."

During his first spell of maintainership between 1989 and 1994, Eric S. Raymond (aka "ESR") ported the code to Unix, wrote the high-level DGIfSlurp()/EGifSpew() interface, rationalized the internal data structures, and did a lot of general cleanup and refactoring to improve the code quality.

Between 1994 and 2012 Toshio Kuratomi fixed various tool bugs, build-recipe problems and rare segfaults. He partially untangled the somewhat misdesigned extension-block handling in earlier versions. The core code was very stable during this period.

During his second spell of maintainership, ESR fixed the extension API, made the library re-entrant and thread-safe, wrote a regression-test suite, greatly improved the documentation, and discarded a lot of obsolete code.

When a GIF file is opened, a GIF file descriptor is created which is a pointer to GifFileType structure as follows:

typedef struct GifFileType {
    GifWord SWidth, SHeight;         /* Size of virtual canvas */
    GifWord SColorResolution;        /* How many colors can we generate? */
    GifWord SBackGroundColor;        /* Background color for virtual canvas */
    GifByteType AspectByte;	     /* Used to compute pixel aspect ratio */
    ColorMapObject *SColorMap;       /* Global colormap, NULL if nonexistent. */
    int ImageCount;                  /* Number of current image (both APIs) */
    GifImageDesc Image;              /* Current image (low-level API) */
    SavedImage *SavedImages;         /* Image sequence (high-level API) */
    int ExtensionBlockCount;         /* Count extensions past last image */
    ExtensionBlock *ExtensionBlocks; /* Extensions past last image */    
    int Error;			     /* Last error condition reported */
    void *UserData;                  /* hook to attach user data (TVT) */
    void *Private;                   /* Don't mess with this! */
} GifFileType;

This structure was copied from gif_lib.h - the header file for the GIF library. Any application program that uses the libgif.a library should include it. Members beginning with S refer to the GIF screen; others hold properties of the current image (a GIF file may have more than one image) or point to allocated store used by various routines.

The user almost never writes into this structure (exception: it may occasionally be useful to alter things in the SavedImages array and Trailing member), but can read any of these items at any time it is valid (Image information is invalid until the first image has been read; read; SavedImages information is valid only after a DGifSlurp() call).

As the library needs to keep its own internal data, a Private pointer to hidden data is included. Applications should ignore this.

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, and is almost never required to free them directly. The "almost" in the latter clause is because one manual free() call may be required on a failed file close; see the documentation of DGifClose() and EGifClose() for details.

Here is a module summary:

The library includes a sixth file of hash-function code which is accessed internally only.

Most of the routines return GIF_ERROR (see gif_lib.h) if something went wrong, GIF_OK otherwise. After an error return, all routines that take a pointer-to-GifFileType argument set the Error member with a code that can be interpreted into an explanatory string with the function GifErrorString() in gif_err.c. (The exception to this is the DGifClose() and EGifClose() routines, which deallocate that structure and must therefore return any error code through a pointer argument.)

The following functions are used to set up input from a GIF:

GifFileType *DGifOpenFileName(char *GifFileName, int *ErrorCode)

Open a new GIF file (in binary mode, if under Windows) using the given GifFileName, and read its Screen information.

If any error occurs, NULL is returned and ErrorCode is set (if non-NULL).

GifFileType *DGifOpenFileHandle(int FileHandle, int *ErrorCode)

Open a new GIF file using the given FileHandle, and read its Screen information.

If any error occurs, NULL is returned and ErrorCode is set (if non-NULL).

Once you have acquired a handle on a GIF, the high-level function

int DGifSlurp(GifFileType)

reads the rest of a complete (possibly multi-image) GIF file from the indicated file handle into in-core allocated structures. It returns GIF_OK on success, GIF_ERROR on failure; on failure, the Error member will be set.

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 gif_lib.h). When you have modified the image to taste, write it out with EGifSpew().

One detail that may not be clear from just looking at the structures is how extension blocks and sub-blocks are stored. Each ExtensionBlock structure represents an extension data block. Those with a zero function code represent continuation data blocks attached to previous blocks with nonzero function codes.

You can read from a GIF file through a function hook. Initialize with

GifFileType *DGifOpen(void *userPtr, InputFunc readFunc, int *ErrorCode)

and see the library header file for the type of InputFunc.

There is also a set of deprecated functions for sequential I/O, described in a later section.

The high-level function

int EGifSpew(GifFileType *GifFile)

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 argument is a GIF file descriptor, which imnplicitly points to storage previously allocated by DGifSlurp().

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.

EGifSpew() finishes by closing the GIF (writing a termination record to it) and deallocating the associated storage.

You can write to a GIF file through a function hook. Initialize with

GifFileType *EGifOpen(void *userPtr, OutputFunc writeFunc, int *ErrorCode)

and see the library header file for the type of OutputFunc.

There is also a set of deprecated functions for sequential I/O, described in a later section.

ColorMapObject *GifMakeMapObject(int ColorCount, GifColorType *ColorMap)

Allocate storage for a color map object with the given number of RGB triplet slots. If the second argument is non-NULL, initialize the color table portion of the new map from it. Returns NULL if memory is exhausted or if the size is not a power of 2 <= 256.

void GifFreeMapObject(ColorMapObject *Object)

Free the storage occupied by a ColorMapObject that is no longer needed.

ColorMapObject *GifUnionColorMap(
        ColorMapObject *ColorIn1, ColorMapObject *ColorIn2,
        GifPixelType ColorTransIn2[])

Create the union of two given color maps and return it. If the result won't fit into 256 colors, NULL is returned, the allocated union otherwise. ColorIn1 is copied as it to ColorUnion, while colors from ColorIn2 are copied if they didn't exist before. ColorTransIn2 maps the old ColorIn2 into ColorUnion color map table.

SavedImage *GifAttachImage(GifFileType *GifFile)

Add an image block to the SavedImages array. The image block is initially zeroed out. This image block will be seen by any following EGifSpew() calls.

GIF89 added a graphics control extension block, but versions of GIFLIB before 5.0 weren't much help in reading or modifying them. This lack has been remedied with the following structure and functions:

typedef struct GraphicsControlBlock {
    int DisposalMode;
#define DISPOSAL_UNSPECIFIED      0       /* No disposal specified. */
#define DISPOSE_DO_NOT            1       /* Leave image in place */
#define DISPOSE_BACKGROUND        2       /* Set area too background color */
#define DISPOSE_PREVIOUS          3       /* Restore to previous content */
    bool UserInputFlag;      /* User confirmation required before disposal */
    int DelayTime;           /* pre-display delay in 0.01sec units */
    int TransparentColor;    /* Palette index for transparency, -1 if none */
#define NO_TRANSPARENT_COLOR	-1
} GraphicsControlBlock;

int DGifSavedExtensionToGCB(GifFileType *GifFile, 
			    int ImageIndex, 
			    GraphicsControlBlock *GCB);
int EGifGCBToSavedExtension(const GraphicsControlBlock *GCB, 
			    GifFileType *GifFile, 
			    int ImageIndex);

With these functions you can extract the data from a graphics control extension associated with a saved image into a GraphicsControlBlock, modify it, and write it back out. Note that if the specified saved image doesn't have a graphics control extension, DGifSavedExtensionToGCB() will fill the GCB with default values and return GIF_ERROR (which can be ignored); EGifGCBToSavedExtension() will create a new leading extension block.

int GifErrorString(int ErrCode)

Returns a sting describing the specified GIFLIB error code. Return NULL if the argument is not a valid error code.

The 8x8 utility font used in the (obsolete, no longer installed) gifecho and gifcolor lives in the library module gif_font.c, in a table called GifAsciiTable. The library header file includes suitable externs and defines.

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 GifDrawText8x8(
        SavedImage *Image,
        const int x, const int y,
        const char *legend,
        const int color)

Draw text using the 8x8 utility font on the saved image. Upper left corner of the text is at image pixel (x, y). Use the specified color index.

void GifDrawBox(SavedImage *Image,
        const int x, const int y,
        const int w, const int h,
        const int color)

Draw a box on the saved image. Upper left corner of the box is at image pixels (x, y), width is w, height is h. Use the specified color index.

void GifDrawRectangle(SavedImage *Image,
        const int x, const int y,
        const int w, const int h,
        const int color)

Draw a (filled) rectangle on the saved image. Upper left corner of the box is at image pixels (x, y), width is w, height is h. Use the specified color index.

void GifDrawBoxedText8x8(SavedImage *Image,
        const int x, const int y,
        const char *legend,
        const int border,
        const int bg, const int fg)

Draw text on a filled rectangle. The rectangle will be sized to fit the text, with upper left hand corner at (x, y) on the saved image. The `border' argument specifies a pixel margin around the text. The `bg' argument is the color table index to fill the rectangle with; `fg' is the color table index to draw the text with.

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.

Errors as reported from the GIFLIB library are divided to two major categories: the encoder (errors prefixed by E_GIF_ERR), and the decoder (errors prefixed by D_GIF_ERR). This document explains them briefly.

These functions are not part of the core GIF library. They are part of the getarg library that supports the utilities.

void PrintGifError(void)

bool GAGetArgs(int argc, char **argv, char *CtrlStr, ...)

void GAPrintErrMsg(int Error)

void GAPrintHowTo(char *CtrlStr)

If you are handling large images on an extremely memory-limited machine, you may need to use the following functions for sequential read and write. It's better to avoid them and use the simpler DGifSlurp()/EGifSpew() interface.

int DGifGetScreenDesc(GifFileType *GifFile)

int DGifGetRecordType(GifFileType *GifFile, GifRecordType *GifType)

int DGifGetImageDesc(GifFileType *GifFile)

int DGifGetLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen)

int DGifGetPixel(GifFileType *GifFile, PixelType GifPixel)

int DGifGetExtension(
        GifFileType *GifFile,
        int *GifExtCode,
        ByteType **GifExtension)

int DGifGetExtensionNext(GifFileType *GifFile, ByteType **GifExtension)

int DGifGetCode(
        GifFileType *GifFile, 
        int *GifCodeSize, ByteType **GifCodeBlock)

int DGifGetCodeNext(GifFileType *GifFile, ByteType **GifCodeBlock)

int DGifGetLZCodes(GifFileType *GifFile, int *GifCode)

int DGifCloseFile(GifFileType *GifFile, int *ErrorCode)

const char * DGifGetGifVersion(GifFileType *GifFile)

GifFileType *EGifOpenFileName(char *GifFileName, bool GifTestExistance, int *ErrorCode)

GifFileType *EGifOpenFileHandle(int GifFileHandle, int *ErrorCode)

char *EGifGetGifVersion(GifFileType *GifFile)

void EGifSetGifVersion(GifFileType *GifFile, bool gif89)

int EGifPutScreenDesc(GifFileType *GifFile,
        const int GifWidth, const GifHeight,
        const int GifColorRes, const int GifBackGround,
        ColorMapObject *GifColorMap)

int EGifPutImageDesc(GifFileType *GifFile,
        const int GifLeft, const int GifTop,
        const int GifWidth, const GifHeight,
        const bool GifInterlace,
        ColorMapObject *GifColorMap)

int EGifPutLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen)

int EGifPutPixel(GifFileType *GifFile, const PixelType GifPixel)

int EGifPutComment(GifFileType *GifFile, char *GifComment)

int EGifPutExtension(
        GifFileType *GifFile,
        const int GifExtCode,
        const int GifExtLen,
        void *GifExtension)

int EGifPutExtensionLeader(
        GifFileType * GifFile,
        const int GifExtCode)

int EGifPutExtensionBlock(
        GifFileType * GifFile,
        const int GifExtLen,
        const VoidPtr GifExtension)

int EGifPutExtensionTrailer(
        GifFileType * GifFile,
        const VoidPtr GifExtension)

int EGifPutCode(
        GifFileType *GifFile,
        int *GifCodeSize,
        ByteType **GifCodeBlock)

int EGifPutCodeNext(GifFileType *GifFile, ByteType **GifCodeBlock)

int EGifCloseFile(GifFileType *GifFile)

Except for some details of extension-block handling and the addition of read/write function hooks, the DGifSlurp()/EGifSpew() interface has been stable since 1990. It is expected to remain so.

However, the signatures of the file-opener functions were changed in 5.0 in order to make the library fully reentrant and thread-safe - earlier library versions did not feature the final pointer-to-error-code argument in DGifOpen() and friends. For the same reason, the static storage queried by GifLastError() in older versions is gone, and that function abolished.

The library header contains some version #defines you can use if you need to condition your code so it can compile with different library versions

Versions up to 4.1.6 defined a GIF_LIB_VERSION macro that was string-valued with a tricky format to parse. This macro has been retired.

Versions after 4.1.6 define integer-valued GIFLIB_MAJOR, GIFLIB_MINOR, and GIFLIB_RELEASE macros for the three components of the version. See the NEWS file in the GIFLIB distribution to track API changes.

The following functions are entirely new:

A few changes in behavior were introduced in 5.0:

If you are developing on a virtual-memory OS such as most flavors of UNIX, or are otherwise sure of having enough memory to keep all of GIFs you need to operate in core, writing a filter is trivial. See the file gifsponge.c in util.

A sequential filter skeleton will usually look like the example file giffilter.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.

Some features of the original GIF specification have not stood the test of time. This library mostly ignores them, but they are described here for completeness.

The GIF standard fails to be explicit about a small but crucial detail: the unsigned two-byte integer fields in it are little-endian.

The GIF format seems to have been designed with the idea that viewers would render multiple images in a GIF on a common canvas, giving an effect like a picture wall. The 'logical screen descriptor block' (LSDB), 6 bytes right after the 6-byte GIF stamp and version header at the beginning of a GIF file, includes both two-byte canvas width and canvas height fields and a canvas background color. Each image, besides height and width, also has 'left' and 'top' cordinates specifying where it is to be placed on the canvas.

GIFLIB can read and set these fields; the gifpos and giftool utilities will enable you to script such changes. But browsers and modern image viewers ignore them. Nowadays multiple-image GIFs are generally used either as animations in which each sub-image is a frame or as image libraries, with the GIF client handling compositing into some canvas about which the GIF format holds no information.

Another feature of the LSDB that is generally ignored is the pixel aspect ratio byte. Until 5.0, GIFLIB ignored this flag on input and zeroed it on output; now it is read and preserved if present. The GIF standard doesn't give a rationale for it, but it seems likely that the designers intended it for representing image captures from the analog television of the day, which had rectangular pixel-equivalents.

Yet another ignored feature of both the LSDB and sub-images is the sort flag, which is supposed to signal whether the colors in the associated color map are sorted by decreasing importance in case the display device can only render a limited number of them. This feature reflected the high cost of dual-port memory at the time the GIF specification was written in the late 1980s. That kind of limit disappeared in the mid-1990s. Until 5.0, GIFLIB ignored this flag on input and zeroed it on output; now it is read and preserved if present.

Finally, the plaintext extension block. This is an extension block that contains instructions for overlaying text captions on a following image. GIFLIB treats these blocks as raw data, not attempting to parse out the location and text data.