图形交换格式 （Graphics Interchange Format）(c)是CompuServe 公司的版权财产。GIF(sm)是CompuServe 公司的一个 服务标记 （Service Mark）财产。

此文档说明了`lib'目录中的GIF 库代码。 这些代码被组织到了一个服务库当中， 这个服务库也 被`util' 目录 中的那些工具程序所使用。 它可被任何需要读/写 GIF 文件格式的程序使用。 此文档 并不会 讲解 GIF 文件的格式， 我们假设妳已经知道了这种格式，最少 是知道了 GIF文件 的基本结构。

当某个GIF文件被打开时，会对应地创建一个GIF文件描述器，它是对于以下所示GifFileType结构体的一个指针：

typedef struct GifFileType {

GifWord SWidth, SHeight; /* 虚拟画布 的尺寸 */

GifWord SColorResolution; /* 我们可以生成的颜色的数目 */

GifWord SBackGroundColor; /* 虚拟画布 的背景色 */

GifByteType AspectByte; /* 用来计算像素 的外观比例 */

ColorMapObject *SColorMap; /* 全局颜色 表（ colormap ），如果不存在则为 NULL 。 */

int ImageCount; /* 当前图片 的号码 (针对两种接口) */

GifImageDesc Image; /* 当前图片(针对低级接口) */

SavedImage *SavedImages; /* 图片序列(针对高级接口) */

int ExtensionBlockCount; /* 在最后一张图片之后的扩展数目 */

ExtensionBlock *ExtensionBlocks; /* 在最后一张图片之后的扩展 */

int Error; /* 最后 一次报告的错误情况 */

void *UserData; /* 用于附加用户 的额外数据的钩子 (TVT) */

void *Private; /* 不要碰这一块！ */

} GifFileType;

以上结构体代码是从gif_lib.h中复制出来的 - 这是GIF 库的头文件。任何一个使用libgif.a 库的程序都应当包含它。以S开头的成员变量代表着GIF屏幕；其它成员变量记录着关于当前图片的信息(一个GIF文件中可以有多张图片)或者指向那些由各种各样的代码所使用的存储空间。

用户几乎从不向这个结构体中写入数据(例外：某些时候，可能需要修改SavedImages数组和之后的成员变量的内容)，但是可以在该结构体处于有效状态的任何时候读取其中的任何内容(在第一张图片被读取之后，Image才是有效的；SavedImages信息只有在调用了DGifSlurp()之后才有效)。

因为这个库需要保存它自己的内部数据，所以包含了一个指向隐藏数据的Private指针。在妳自己的程序中应当无视这个成员变量。

这个库会在打开文件的时候动态地申请它自己的内存，并且在关闭文件时释放对应的内存。用户不需要为这个库中的任何函数分配内存，并且几乎不需要直接释放它们。后一句里说的是“几乎”，因为，在文件关闭失败时，可能需要手动调用一次free()；参考DGifClose()和EGifClose()的文档以了解细节。

以下是各个模块的摘要说明：

egif_lib.c

用于编码的函数集，全部以E开头。

dgif_lib.c

用于解码的函数集，全部以D开头。

gifalloc.c

这些函数用于处理颜色表以及GIF记录的分配。

gif_font.c

用于GIF 工具字体的8x8字体表。

这个库中还有第6个文件，其中是计算散列值的代码，只在内部使用。

大部分函数（参考gif_lib.h）在出现某种错误时会返回GIF_ERROR，否则就返回GIF_OK。发生了错误之后，所有以一个GifFileType指针作为参数的函数都会将 Error 成员变量的值设置成某个错误号，该错误号可以使用 gif_err.c 中的函数GifErrorString()来翻译成一个更适合人理解的字符串。

使用以下函数来从一个GIF 文件中读取内容：

打开名为GifFileName 的GIF 文件，并且读取它的屏幕（Screen）信息。

如果发生了任何错误，则会返回NULL，并且设置对应的错误码ErrorCode(如果该变更不为NULL的话)。

打开指定的文件编号FileHandle 对应的GIF 文件，并且读取它的屏幕信息。

如果发生了任何错误，则会返回NULL，并且设置对应的错误码ErrorCode(如果该变更不为NULL的话)。

当妳获取到一个GIF 文件的把柄（handle）之后，可使用高级函数

从指定的文件把柄中将剩余的完整（可能是包含多张图片的文件）GIF 文件读取到内部分配的结构体中。如果成功则会返回GIF_OK，失败则会返回GIF_ERROR；如果失败，则会设置Error 成员变量的值。

当妳做完这一步之后，该GIF 中的所有图片、光栅图（raster）和扩展块数据都可以通过SavedImages 成员来访问到（参考gif_lib.h中的结构体）。当妳对该图片做了修改之后，使用EGifSpew()函数将它输出。

有一个细节，单是看那些结构体的话未必能搞清楚，就是：扩展块和子块是如何存储的。每个ExtensionBlock结构体都代表着一个扩展数据块。功能（function）代码为0的那些块，代表着追加到之前的功能代码不为0的块数据的延续。

妳可以通过一个函数钩子来读取GIF 文件中的数据。像这样使用

参考库中的头文件以了解InputFunc 的类型。

GIFLIB 库报告的错误可分为两大类：编码器(以E_GIF_ERR开头)和解码器(以D_GIF_ERR开头)。此文档简要地说明一下这些错误。

D_GIF_ERR_NOT_GIF_FILE

使用PrintGifError的时候会输出这样的错误信息："Data is not a GIF file" GIF文件有着特殊的文件头以便于识别，如果找不到对应的文件头，则会报告这个错误。