Eric Steven Raymond Thyrsus Enterprises

&email;

2012 Eric S. Raymond 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: egif_lib.c Encoding routines, all prefixed with E. dgif_lib.c Decoding routines, all prefixed with D. gifalloc.c Routines for colormap handling and GIF record allocation. gif_font.c The 8x8 font table for the GIF utility font. 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 iff 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 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. E_GIF_ERR_OPEN_FAILED Message printed using PrintGifError: "Failed to open given file" IO error result when attempt to open the given GIF file. E_GIF_ERR_WRITE_FAILED Message printed using PrintGifError: "Failed to Write to given file" IO error result when attempt to write to the given GIF file. E_GIF_ERR_HAS_SCRN_DSCR Message printed using PrintGifError: "Screen Descriptor already been set" Attempt to write second screen descriptor to same GIF file. GIF file should have exactly one screen descriptor which should be set directly after the file is opened. E_GIF_ERR_HAS_IMAG_DSCR Message printed using PrintGifError: "Image Descriptor is still active" Image descriptor should be sent before and image dump, and no second image descriptor should be sent before current image dump ended. This error occurred probably because current image was not complete. E_GIF_ERR_NO_COLOR_MAP Message printed using PrintGifError: "Neither Global Nor Local color map" An image must have either global (screen) or local (image) color map. Neither were given in this case. E_GIF_ERR_DATA_TOO_BIG Message printed using PrintGifError: "#Pixels bigger than Width * Height" The number of pixels dumped for this image is bigger than specified by image Height times image Width. E_GIF_ERR_NOT_ENOUGH_MEM Message printed using PrintGifError: "Fail to allocate required memory" Once an attemp is made to open GIF file, special structures are allocated to hold internal data for it. If allocation fails this error is returned. E_GIF_ERR_DISK_IS_FULL Message printed using PrintGifError: "Write failed (disk full?)" Writing encoded data failed. E_GIF_ERR_CLOSE_FAILED Message printed using PrintGifError: "Failed to close given file" Closing file failed. E_GIF_ERR_NOT_WRITEABLE Message printed using PrintGifError: "Given file was not opened for write" GIF files can be opened both for read (DGIF part of library) and write (EGIF part of library). This error occurs when a file is opened for read (using DGIF) is given to one of the encoding (EGIF) routines. D_GIF_ERR_OPEN_FAILED Message printed using PrintGifError: "Failed to open given file" IO error result when attempt to open the given GIF file. D_GIF_ERR_READ_FAILED Message printed using PrintGifError: "Failed to read from given file" IO error result when attempt to write to the given GIF file. D_GIF_ERR_NOT_GIF_FILE Message printed using PrintGifError: "Data is not a GIF file" GIF files should have special stamp identifies them as such, If that stamp is not found, this error is issued. D_GIF_ERR_NO_SCRN_DSCR Message printed using PrintGifError: "No screen descriptor detected" Each GIF file should have screen descriptor in its header. This error will be generated if no such descriptor was found. D_GIF_ERR_NO_IMAG_DSCR Message printed using PrintGifError: "No image descriptor detected" Each image should have image descriptor in its header. This error will be generated if no such descriptor was found. D_GIF_ERR_NO_COLOR_MAP Message printed using PrintGifError: "Neither global nor local color map" An image must have either global (screen) or local (image) color map. Neither were given in this case. D_GIF_ERR_WRONG_RECORD Message printed using PrintGifError: "Wrong record type detected" Each record in a GIF file has a special identifier in its header. If the record has an unrecognized identifier, this error is generated. D_GIF_ERR_DATA_TOO_BIG Message printed using PrintGifError: "Number of pixels bigger than width * height" The number of pixels dumped for this image is bigger than specified by image Height times image Width. D_GIF_ERR_NOT_ENOUGH_MEM Message printed using PrintGifError: "Failed to allocate required memory" Once an attemp is made to open GIF file, special structures are allocated to hold internal data for it. If allocation fails this error is returned. D_GIF_ERR_CLOSE_FAILED Message printed using PrintGifError: "Failed to close given file" Closing file failed. D_GIF_ERR_NOT_READABLE Message printed using PrintGifError: "Given file was not opened for read" GIF files can be opened both for read (DGIF part of library) and write (EGIF part of library). This error occurs when a file is opened for write (using EGIF) is given to one of the decoding (DGIF) routines. D_GIF_ERR_IMAGE_DEFECT Message printed using PrintGifError: "Image is defective, decoding aborted" This error is generated, once the decoding failed - probably image is defect. D_GIF_ERR_EOF_TOO_SOON Message printed using PrintGifError: "Image EOF detected, before image complete" This error is generated once EOF errorname is detected in encoded image before all the pixels (Width * Height) has be decoded. These functions are not part of the core GIF library. They are part of the getarg library that supports the utilities. void PrintGifError(void) Print a one-line diagnostic on the last giflib error to stderr. bool GAGetArgs(int argc, char **argv, char *CtrlStr, ...) Main routine of this module. Given argc & argv as received by the main procedure, the command line CtrlStr, and the addresses of all parameters, parse the command line, and update the parameters. The CtrlStr defines what types of variables should follow. Look at the beginning of getarg.c for exact usage. Returns false if successful, returns true on failure. void GAPrintErrMsg(int Error) If an error occurred in GAGetARgs, this routine may be used to print one line diagnostic to stderr. void GAPrintHowTo(char *CtrlStr) Given the same CtrlStr as for GAGetArgs, can be used to print a one line 'how to use'. 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) Reads the screen information into the GifFile structure. Note this routine is automatically called once a file is opened, and therefore usually need not be called explicitly. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int DGifGetRecordType(GifFileType *GifFile, GifRecordType *GifType) As the GIF file can have different records in arbitrary order, this routine should be called once the file was open to detect the next record type, and act upon it. It can return these types in GifType: 1. UndefinedRecordType something is wrong! 2. ScreenDescRecordType screen information. As the screen info is automatically read in when the file is open, this should not happen. 3. ImageDescRecordType next record is an image descriptor. 4. ExtensionRecordType next record is extension block. 5. TrailerRecordType last record reached, can close the file. The first two types can usually be ignored. The function returns GIF_ERROR if something went wrong, GIF_OK otherwise. int DGifGetImageDesc(GifFileType *GifFile) Reads image information into the GifFile structure. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int DGifGetLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen) Load a block of pixels from the GIF file. The line can be of any length. More than that, this routine may be interleaved with DGifGetPixel until all pixels have been read. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int DGifGetPixel(GifFileType *GifFile, PixelType GifPixel) Loads one pixel from the GIF file. This routine may be interleaved with DGifGetLine(), until all pixels are read. Because of the overhead per each call, use of this routine is not recommended. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int DGifGetComment(GifFileType *GifFile, char *GifComment) Load a comment from the GIF file. Because DGifGetRecordType will only tell if the record is of type extension, this routine should be called iff it is known %100 that is must be a comment. 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) Loads an extension block from the GIF file. Extension blocks are optional in GIF files. This routine should be followed by DGifGetExtensionNext. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int DGifGetExtensionNext(GifFileType *GifFile, ByteType **GifExtension) As extensions may contain more than one block, use this routine to continue after DGifGetExtension, until *GifExtension is NULL. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int DGifGetCode( GifFileType *GifFile, int *GifCodeSize, ByteType **GifCodeBlock) It sometimes may be desired to read the compressed code as is without decoding it. This routine does exactly that (with DGifGetCodeNext), and can be used instead of DGifGetLine. 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) See DGifGetCode above. int DGifGetLZCodes(GifFileType *GifFile, int *GifCode) This routine can be called instead of DGifGetLine/DGifGetPixel or DGifGetCode/DGifGetCodeNext to get the 12 bits LZ codes of the images. It will be used mainly for debugging purposes (see GifText.c for example). Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int DGifCloseFile(GifFileType *GifFile, int *ErrorCode) Write a termination block to the GIF, close the GIF file and free all memory allocated for managing it. GifFile should not be used after this routine has been called. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. When GIF_ERROR is returned, the diagnostic error code is left in ErrorCode. The GifFile structure is unconditionally freed. (Note: In versions before 5.1.0, the ErrorCode argument was absent and the GifFile structure was not freed so that the diagnostic error code will remain accessible in GifFile->Error. This behavior was changed because it caused problems for the implementation of library wrappers in dynamic languages.) 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, bool GifTestExistance, int *ErrorCode) Open a new GIF file using the given GifFileName (in binary mode, if under Windows). If GifTestExistance is TRUE, and file exists, the file is not destroyed, and NULL returned. If any error occurs, NULL is returned and the ErrorCode is set. GifFileType *EGifOpenFileHandle(int GifFileHandle, int *ErrorCode) Open a new GIF file using the given GifFileHandle. If any error occurs, NULL is returned and ErrorCode is set. The file is opened in binary mode, and its buffer size is set to FILE_BUFFER_SIZE bytes. char *EGifGetGifVersion(GifFileType *GifFile) That version computation is available through this function. void EGifSetGifVersion(GifFileType *GifFile, bool gif89) Set the GIF type, to GIF89 if the argument is true and GIF87 if it is false. The default type is GIF87. This function may be called aftert the GifFile record is allocated but before EGifPutScreenDesc(). int EGifPutScreenDesc(GifFileType *GifFile, const int GifWidth, const GifHeight, const int GifColorRes, const int GifBackGround, ColorMapObject *GifColorMap) Update the GifFile Screen parameters, in GifFile structure and in the real file. If error occurs, returns GIF_ERROR (see gif_lib.h), otherwise GIF_OK. This routine should be called immediately after the GIF file was opened. int EGifPutImageDesc(GifFileType *GifFile, const int GifLeft, const int GifTop, const int GifWidth, const GifHeight, const bool GifInterlace, ColorMapObject *GifColorMap) Update GifFile Image parameters, in GifFile structure and in the real file. if error occurs returns GIF_ERROR (see gif_lib.h), otherwise GIF_OK. This routine should be called each time a new image must be dumped to the file. int EGifPutLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen) Dumps a block of pixels out to the GIF file. The slab can be of any length. More than that, this routine may be interleaved with EGifPutPixel(), until all pixels have been sent. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int EGifPutPixel(GifFileType *GifFile, const PixelType GifPixel) Dumps one pixel to the GIF file. This routine may be interleaved with EGifPutLine(), until all pixels were sent. Because of the overhead for each call, use of this routine is not recommended. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int EGifPutComment(GifFileType *GifFile, char *GifComment) Uses extension GIF records to save a string as a comment is the file. The extension code is 'C' (for Comment). Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int EGifPutExtension( GifFileType *GifFile, const int GifExtCode, const int GifExtLen, void *GifExtension) Dumps the given extension block into the GIF file. Extension blocks are optional in GIF file. Extension blocks of more than 255 bytes or more than one block are not supported in this function. Please use EGifPutExtensionFirst, EGifPutExtensionBlock, and EGifPutExtensionTrailer if your extension blocks may fall into this category. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int EGifPutExtensionLeader( GifFileType * GifFile, const int GifExtCode) Dumps the beginning of a GIF extension block to a GIF file. Extension blocks are optional in GIF files. This function outputs the type code information necessary for a GIF extension block. Further blocks of the GIF Extension should be dumped using EGifPutExtensionBlock. When finished with this extension block, EGifPutExtensionTrailer should be called to output the block termination. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. int EGifPutExtensionBlock( GifFileType * GifFile, const int GifExtLen, const VoidPtr GifExtension) Dumps a subblock of a GIF extension to a GIF File; should be used only following an initializing call to EGifPutExtensionLeader(). Extension blocks are optional in GIF files. This function will write the Extension Data in GifExtension to the file as a subblock of the preceding Extension Block. Repeat calling of this function until all data subblocks have been output. Note that EGifPutExtensionLeader needs to be called before any calls to this function. EGifPutExtensionTrailer 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 EGifPutExtensionTrailer( GifFileType * GifFile, const VoidPtr GifExtension) Dumps the GIF extension block terminator to a GIF File to end the current Extension block. Note that a call to EGifPutExtensionLeader 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) It sometimes may be desired to write the compressed code as is without decoding it. For example a filter for a GIF file that change only screen size (GifPos), does not need the exact pixel values. Piping out the compressed image as is makes this process much faster. 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) See EGifPutCode above. int EGifCloseFile(GifFileType *GifFile) Write a termination block to the GIF, close the GIF file, and free all memory allocated for managing it. GifFile should not be used after this routine has been called. Returns GIF_ERROR if something went wrong, GIF_OK otherwise. When GIF_ERROR is returned, the diagnostic error code is left in ErrorCode. The GifFile structure is unconditionally freed. (Note: In versions before 5.1.0, the ErrorCode argument was absent and the GifFile structure was not freed so that the diagnostic error code will remain accessible in GifFile->Error. This behavior was changed because it caused problems for the implementation of library wrappers in dynamic languages.) 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: New functions DGifSavedExtensionToGCB() and EGifGCBToSavedExtension() make it easy to read and edit GIF89 graphics control blocks in saved images. A few changes in behavior were introduced in 5.0: The library is now fully re-entrant and thread-safe. All functions exported by this library now have DGif, EGif, or Gif as a name prefix. The default GIF version to write is now computed at write time from the types of an image's extension blocks. (Formerly EGifSpew() behaved this way, but the sequential-writing code didn't.) The result of this computation is available through the new function EGifGetGifVersion(). GIF file openers and closers - DGifOpenFileName(), DGifOpenFileHandle(), DGifOpen(), DGifClose(), EGifOpenFileName(), EGifOpenFileHandle(), EGifOpen(), and EGifClose() - all now take a final integer address argument. If non-null, this is used to pass back an error code when the function returns NULL. EGifSlurp() and EGifSpew() read and write extension blocks trailing after the last image, handle interlaced images properly. EGifPutExtensionFirst() has been replaced by EGifPutExtensionLeader(); the difference is the new function doesn't take an optional block, it just writes a block leader. EGifPutExtensionNext() has been replaced by EGifPutExtensionBlock(); the difference is that the new function does not take and then discard a function code argument. EGifPutExtensionLast() has been replaced by EGifPutExtensionTrailer(); all it does is write the terminator block. Split your old EGifPutExtensionLast() calls into EGifPutExtensionBlock() followed by EGifPutExtensionTrailer(). Some undocumented functions have been renamed. AddExtensionBlock() is now GifAddExtensionBlock(), and takes an additional function code argument. ApplyTranslation() is now GifApplyTranslation(); FreeExtension() has become GifFreeExtensions() and takes a different argument type; MakeSavedImage() is now GifMakeSavedImage(), FreeSavedImages() is now GifFreeSavedImages(), and BitSize() is now GifBitSize(). Three documented functions - MakeMapObject(), FreeMapObject(), and UnionColorMap() - have been renamed to GifMakeMapObject(), GifFreeMapObject(), and GifUnionColorMap() respectively. Library error handling no longer uses a static cell to store the last error code registered; that made the library thread-unsafe. For functions other than GIF file openers, the Error code is now put in an Error member of the GifFileType structure. The GifError() and GifLastError() functions that referenced that static cell are gone, and the GifErrorString() function introduced in the 4.2 release now takes an explicit error code argument. 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.