📄 gif_lib.html
字号:
<!doctype HTML public "-//W3O//DTD W3 HTML 2.0//EN"><HTML><HEAD><TITLE>gif_lib</TITLE><link rev=made href=mailto:esr@snark.thyrsus.com></HEAD><BODY>Go to <a href="index.html">index page</a>.<CENTER><H1>The GIFLIB Library</H1></CENTER><CENTER><BLOCKQUOTE>Gershon Elber, May 1991<BR>Eric S. Raymond, Sep 1992<BR>Toshio Kuratomi, May 2004<br></BLOCKQUOTE></CENTER>The Graphics Interchange Format(c) is the Copyright property ofCompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServeIncorporated.<P>Gershon wrote: "This library was written because I couldn't findanything 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 amnot sure how long 8 bits per pixel will be enough."<P>This document explains the GIF library code in directory `lib'. Thecode 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 GIFfile format. This document does </em>not</em> explain the GIF fileformat and assumes you know it, at least to the level of the GIF filestructure.<P>When a GIF file is opened, a GIF file descriptor is created whichis a pointer to GifFileType structure as follows:<P><pre><code>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;</code></pre>This structure was copied from gif_lib.h - the header file for the GIFlibrary. Any application program that uses the libgif.a library shouldinclude it. Members beginning with S refer to GIF Screen; others holdproperties of the current image (a GIF file may have more than one image)or point to allocated store used by various routines.<P>The user almost never writes into this structure (exception: it mayoccasionally useful to alter things in the SavedImages array), but can readany of these items at any time it is valid (image information is invaliduntil first image was read/write).<P>As the library needs to keep its own internal data, a Private pointerto hidden data is included. Applications should ignore this item.<P>The library has no static data. This means that it is fully reentrantand any number of GIF files (up to memory limits) can be opened forread/write. Instead of the static data, internal structure pointed by thePrivate pointer is used.<P>The library allocates its own memory dynamically, on opening of files,and releases that once closed. The user is never required to allocateany memory for any of the functions of this library nor to free themdirectly.<P>In order to reduce disk access, the file buffer is increased toFILE_BUFFER_SIZE (defined in gif_lib.h). The library was compiled in largemodel on the PC as the memory allocated per file is quite big: about 17k fordecoding (DGIF_LIB.C), and 32k for encoding (EGIF_LIB.C), excluding theFILE_BUFFER_SIZE.<P>Here is a module summary:<P><DL><DT>egif_lib.c <DD> Encoding routines, all prefixed with E.<P><DT>dgif_lib.c <DD> Decoding routines, all prefixed with D.<P><DT>dev2gif.c <DD> Routines to convert specific device buffers into GIF files.<P><DT>gifalloc.c <DD> Routines for colormap handling and GIF record allocation.<P><DT>gif_font.c <DD> The 8x8 font table for the GIF utility font.<P><DT>gif_err.c <DD> Error handler for the library.<P></DL>The library includes a sixth file of hash-function code which is accessedinternally only.<P><P>Most of the routines return GIF_ERROR (see gif_lib.h) if somethingwent wrong, GIF_OK otherwise. After an error return, the code in thegif_err.c module can be used to do something about it.<P>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 headerof getarg.c for details on its usage.<P><H1>Decoding (dgif_lib.c)</H1>The following functions are used to set up input from a GIF:<P><pre><code>GifFileType *DGifOpenFileName(char *GifFileName)</code></pre>Open a new GIF file using the given GifFileName, and read its Screeninformation.</code></pre>If any error occurs, NULL is returned and the error handler can beused to get the exact error (see gif_err.c).</code></pre>The file is opened in binary mode, and its buffer size is set toFILE_BUFFER_SIZE bytes.</code></pre><pre><code>GifFileType *DGifOpenFileHandle(int GifFileHandle)</code></pre>Open a new GIF file using the given GifFileHandle, and read its Screeninformation.<P>If any error occurs, NULL is returned and the error handler can be used to get the exact error (see gif_err.c).<P>The file is opened in binary mode, and its buffer size is set toFILE_BUFFER_SIZE bytes.<P>Once you have acquired a handle on a GIF, there are two ways to read it in.The high-level function<pre><code>int DGifSlurp(GifFileType)</code></pre>reads the rest of a complete (possibly multi-image) GIF file from theindicated file handle into in-core allocated structures. It returnsGIF_OK on success, GIF_ERROR on failure.<P>Once you have done this, all image, raster, and extension-block data in theGIF 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().<P>If you are handling large images on a memory-limited machine, you may needto use the following functions for sequential read.<P><pre><code>int DGifGetScreenDesc(GifFileType *GifFile)</code></pre>Reads the screen information into the GifFile structure. Note thisroutine is automatically called once a file is opened, and thereforeusually need not be called explicitly.<P>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P><pre><code>int DGifGetRecordType(GifFileType *GifFile, GifRecordType *GifType)</code></pre>As the GIF file can have different records in arbitrary order, thisroutine should be called once the file was open to detect the nextrecord type, and act upon it. It can return these types in GifType:<P><DL><DT> 1. UndefinedRecordType <DD> something is wrong!<P><DT> 2. ScreenDescRecordType <DD> screen information. As the screen info is automatically read in when the file is open, this should not happen.<P><DT> 3. ImageDescRecordType <DD> next record is an image descriptor.<P><DT> 4. ExtensionRecordType <DD> next record is extension block.<P><DT> 5. TerminateRecordType <DD> last record reached, can close the file.<P></DL>The first two types can usually be ignored. The functionreturns GIF_ERROR if something went wrong, GIF_OK otherwise.<pre><code>int DGifGetImageDesc(GifFileType *GifFile)</code></pre>Reads image information into the GifFile structure.Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P><pre><code><A NAME="DGifGetLine">int DGifGetLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen)</A></code></pre>Load a block of pixels from the GIF file. The line can beof any length. More than that, this routine may be interleaved withDGifGetPixel until all pixels have been read.<P>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</P><pre><code>int DGifGetPixel(GifFileType *GifFile, PixelType GifPixel)</code></pre>Loads one pixel from the GIF file. This routine may be interleavedwith <a href="#DGifGetLine">DGifGetLine</a>, until all pixels areread. Because of the overhead per each call, use of this routine isnot recommended.<P>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P><pre><code>int DGifGetComment(GifFileType *GifFile, char *GifComment)</code></pre>Load a comment from the GIF file. Because DGifGetRecordType willonly tell if the record is of type extension, this routine should becalled iff it is known %100 that is must be a comment.<P>For the definition of a comment, see <ahref="#EGifPutComment">EGifPutComment</a>. Returns GIF_ERROR ifsomething went wrong, GIF_OK otherwise.<P><pre><code>int DGifGetExtension( GifFileType *GifFile, int *GifExtCode, ByteType **GifExtension)</code></pre>Loads an extension block from the GIF file. Extension blocksare optional in GIF files. This routine should be followed by<a href="#DGifGetExtensionNext">DGifGetExtensionNext</a>.<P>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P><pre><code><A NAME="DGifGetExtensionNext">int DGifGetExtensionNext(GifFileType *GifFile, ByteType **GifExtension)</A> </code></pre>As extensions may contain more than one block, use this routine tocontinue after DGifGetExtension, until *GifExtension is NULL.<P>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P><pre><code>int DGifGetCode( GifFileType *GifFile, int *GifCodeSize, ByteType **GifCodeBlock)</code></pre>It sometimes may be desired to read the compressed code as iswithout decoding it. This routine does exactly that (withDGifGetCodeNext), and can be used instead of DGifGetLine.<P>This compressed code information can be written out using theEGifPutCode/EGifPutCodeNext sequence (see gifpos.c for example).Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P><pre><code>int DGifGetCodeNext(GifFileType *GifFile, ByteType **GifCodeBlock)</code></pre>See DGifGetCode above.<P> <pre><code>int DGifGetLZCodes(GifFileType *GifFile, int *GifCode)</code></pre>This routine can be called instead of DGifGetLine/DGifGetPixel orDGifGetCode/DGifGetCodeNext to get the 12 bits LZ codes of the images.It will be used mainly for debugging purposes (see GifText.c forexample).<P>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P><pre><code>int DGifCloseFile(GifFileType *GifFile)</code></pre>Close GIF file and free all memory allocated for it. GifFile shouldnot be used after this routine has been called.<P>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P><H1>Encoding (egif_lib.c)</H1>There are two ways to write out a GIF. The high-level function<P><pre>int EGifSpew(GifFileType *GifFile, int GifFileHandle)</pre>Writes a complete (possibly multi-image) GIF file to the indicated filehandle from in-core allocated structures created by a previous DGifSlurp()or equivalent operations. Its arguments are a GIF file descriptor (asabove) and an ordinary output file descriptor.<P>The file is written with a GIF87 stamp unless it contains one of the fourspecial extension blocks defined in GIF89, in which case it is writtenwith a GIF89 stamp.<P>If you are handling large images on a memory-limited machine, you may needto use the following functions for sequential write.<P><pre><code>GifFileType *EGifOpenFileName(char *GifFileName, int GifTestExistance)</code></pre>Open a new GIF file using the given GifFileName. If GifTestExistanceis TRUE, and file exists, the file is not destroyed, and NULLreturned.<P>If any error occurs, NULL is returned and the error handler can beused to get the exact error (see gif_err.c).<P>The file is opened in binary mode, and its buffer size is set toFILE_BUFFER_SIZE bytes.<P><pre><code>GifFileType *EGifOpenFileHandle(int GifFileHandle)</code></pre>Open a new GIF file using the given GifFileHandle.<P>If any error occurs, NULL is returned and the error handler can beused to get the exact error (see gif_err.c).<P>The file is opened in binary mode, and its buffer size is set toFILE_BUFFER_SIZE bytes.<P><pre><code>void EGifSetGifVersion(char *Version)</code></pre>Sets the GIF version of all files opened, until another call to thisroutine is made. Version is a 3 characters string of the form "87a"or "89a". No test is made to validate this string.<P><pre><code>int EGifPutScreenDesc(GifFileType *GifFile, int GifWidth, int GifHeight, int GifColorRes, int GifBackGround, ColorMapObject *GifColorMap)</code></pre>Update the GifFile Screen parameters, in GifFile structure and in⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -