gif_lib.html

giflib-4.1.6.tar.gz,最新的GIF 解码库

the real file.  If error occurs, returns GIF_ERROR (see gif_lib.h),
otherwise GIF_OK.<P>

This routine should be called immediately after the GIF file was
opened.<P>

<pre><code>
int EGifPutImageDesc(GifFileType *GifFile,
        int GifLeft, int GifTop,
        int Width, int GifHeight,
        int GifInterlace,
        ColorMapObject *GifColorMap)
</code></pre>

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

This routine should be called each time a new image must be
dumped to the file.<P>

<pre><code><A NAME="EGifPutLine">
int EGifPutLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen)
</A> </code></pre>

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
<a href="#EGifPutPixel"></a>, until all pixels have been sent.<P>

Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P>

<pre><code><A NAME="EGifPutPixel">
int EGifPutPixel(GifFileType *GifFile, PixelType GifPixel)
</A></code></pre>

Dumps one pixel to the GIF file.  This routine may be interleaved with
<a href="#EGifPutLine">EGifPutLine</a>, until all pixels were sent.
Because of the overhead for each call, use of this routine is not
recommended.<P>

Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P>

<pre><code><A NAME="EGifPutComment">
int EGifPutComment(GifFileType *GifFile, char *GifComment)
</A></code></pre>

Uses extension GIF records to save a string as a comment is the file.
The extension code is 'C' (for Comment).<P>

Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P>

<pre><code>
int EGifPutExtension(
        GifFileType *GifFile,
        int GifExtCode,
        int GifExtLen,
        void *GifExtension)
</code></pre>

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, EGifPutExtensionNext, and EGifPutExtensionLast
if your extension blocks may fall into this category.<P>

Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P>

<pre><code>
int EGifPutExtensionFirst(
        GifFileType * GifFile,
        int GifExtCode,
        int GifExtLen,
        const VoidPtr GifExtension)
</code></pre>
Dumps the beginning of a GIF extension block to a GIF file.  Extension blocks
are optional in GIF files.  This function outputs the meta information
necessary to a GIF extension block and the extension data described in the
GifExtension argument.<P>

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

Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P>

<pre><code>
int EGifPutExtensionNext(
        GifFileType * GifFile,
        int GifExtCode,
        int GifExtLen,
        const VoidPtr GifExtension)
</code></pre>
Dumps a subblock of a GIF extension to a GIF File.  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.<P>

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

Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P>

<pre><code>
int EGifPutExtensionLast(
        GifFileType * GifFile,
        int GifExtCode,
        int GifExtLen,
        const VoidPtr GifExtension)
</code></pre>
Dumps an optional GIF extension data subblock and the GIF extension block
terminator to a GIF File.  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.  Then it will output the GIF
extension block terminator to end the current Extension block.  As a special
case, if GifExtLen is zero, the function will assume there isn't another
data block to output and will simply write the block terminator.<P>

Note that a call to EGifPutExtensionFirst is needed to open the GIF
Extension Block prior to calling this function.<P>

Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P>

<pre><code>
int EGifPutCode(
        GifFileType *GifFile,
        int *GifCodeSize,
        ByteType **GifCodeBlock)
</code></pre>

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

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

Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P>

<pre><code>
int EGifPutCodeNext(GifFileType *GifFile, ByteType **GifCodeBlock)
</code></pre>

See EGifPutCode above.<P>

<pre><code>
int EGifCloseFile(GifFileType *GifFile)
</code></pre>

Close a GIF file and free all memory allocated for it.  gif-file$
should not be used, once this routine was called.<P>

Returns GIF_ERROR if something went wrong, GIF_OK otherwise.<P>

<H1>Color map handling and allocation routines</H1>

<pre><code>
ColorMapObject *MakeMapObject(int ColorCount, GifColorType *ColorMap)
</code></pre>

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

<pre><code>
void FreeMapObject(ColorMapObject *Object)
</code></pre>

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

<pre><code>
ColorMapObject *UnionColorMap(
        ColorMapObject *ColorIn1, ColorMapObject *ColorIn2,
        GifPixelType ColorTransIn2[])
</code></pre>

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

<pre><code>
SavedImage *GifAttachImage(GifFileType *GifFile)
</code></pre>

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.
</code></pre>

<H1>The GIF Utility Font</H1>

The 8x8 utility font used in text2gif and gifcolor lives in the library
module gif_font.c, in a table called AsciiTable.  The library header file
includes suitable externs and defines.<P>

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:<P>

<pre><code>
void DrawText(
        SavedImage *Image,
        const int x, const int y,
        const char *legend,
        const int color)
</code></pre>

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

<pre><code>
void DrawBox(SavedImage *Image,
        const int x, const int y,
        const int w, const int h,
        const int color)
</code></pre>

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

<pre><code>
void DrawRectangle(SavedImage *Image,
        const int x, const int y,
        const int w, const int h,
        const int color)
</code></pre>

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

<pre><code>
void DrawBoxedText(SavedImage *Image,
        const int x, const int y,
        const char *legend,
        const int border,
        const int bg, const int fg)
</code></pre>

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

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

<H1>Error Handling (egif_lib.c)</H1>

<pre><code>
void PrintGifError(void)
</code></pre>

Print a one-line diagnostic on the last giflib error to stderr.<P>

<pre><code>
int GifLastError(void)
</code></pre>

Return the number of the last giflib error, and clear the error.
The error types are defined in gif_lib.h.<P>

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

<H1>Device Specific (XXX2gif.c)</H1>

<pre><code>
int DumpScreen2Gif(char *FileName, int ReqGraphDriver, int ReqGraphMode1,
						       int ReqGraphMode2)
</code></pre>

Dumps the whole device buffer as specified by GraphDriver and
GraphMode (as defined in TC 2.0 graphics.h) into FileName as GIF file.
Current devices supported:<P>

<pre>
	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.
</pre>


<H1>Command Line Parsing</H1>

<pre><code>
int GAGetArgs(int argc, char **argv, char *CtrlStr, ...)
</code></pre>

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

The CtrlStr defines what types of variables should follow. Look at the
beginning of getarg.c for exact usage.<P>

Returns 0 if successful, error number (as defined by getarg.h) otherwise.<P>

<pre><code>
void GAPrintErrMsg(int Error)
</code></pre>

If an error occurred in GAGetARgs, this routine may be used to print
one line diagnostic to stderr.<P>

<pre><code>
void GAPrintHowTo(char *CtrlStr)
</code></pre>

Given the same CtrlStr as for GAGetArgs, can be used to print a one line
'how to use'. <P>

<H1>Skeletons of GIF filters</H1>

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
gifspnge.c in util.<P>

A sequential filter skeleton will usually look like the example file
giffiltr.c in util.<P>

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

<HR>
<ADDRESS>Eric S. Raymond <A HREF="mailto:[e-mail]">&lt;[e-mail]&gt;</A></ADDRESS>
</BODY>
</HTML>