gif_lib.doc

dll处理软件

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

	  Load block of pixels from the GIF file. The line length can be
	of any length. More than that, this routine may be interleaved with
	DGifGetPixel, until all pixels were read.
	  Returns ERROR if something went wrong, 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 were read. Because of the overhead
	per each call, the usage of this routine is not recommended.
	  Returns ERROR if something went wrong, OK otherwise.

int DGifGetComment(GifFileType *GifFile, char *GifComment);

	  Load comment from the GIF file. Because DGifGetRecordType will
	only tell this records is of type extension, this routine should be
	called iff it is known %100 that is must be a comment.
	  For definition of comment, see EGifPutComment.
	  Returns ERROR if something went wrong, OK otherwise.

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

	  Loads the given extension block from the GIF file. Extension blocks
	are optional in GIF file. This routine should be follows by
	DGifGetExtensionNext - see below
	  Returns ERROR if something went wrong, 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 ERROR if something went wrong, 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 do 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 ERROR if something went wrong, 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 may be used mainly for debugging purposes (see GifText.c for
	example).
	  Returns ERROR if something went wrong, OK otherwise.


int DGifCloseFile(GifFileType *GifFile);

	  Close GIF file and free all memory allocated for it. GifFile should
	not be used, once this routine was called.
	  Returns ERROR if something went wrong, OK otherwise.



ERROR HANDLING (EGIF_LIB.C)
---------------------------

void PrintGifError(void)

	  Print one line diagnostic on the last gif_lib error to stderr.


int GifLastError(void)

	  Return last gif_lib error, and clear the error.
	  Note it is the user responsibility to call the file closing routine,
	so the file will be closed (if was opened), and memory will be released
	(if was allocated).
	  The different error types are defined in gif_lib.h.


DEVICE SPECIFIC (XXX2GIF.C)
---------------------------

int DumpScreen(char *FileName, int ReqGraphDriver, int ReqGraphMode);

	  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:
	1. Hercules.
	  Returns ERROR if something went wrong, OK otherwise.


COMMAND LINE PARSING (GETARG.C)
-------------------------------

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

	  Main routine of this module. Given the 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 0 if successful, error number (as defined by getarg.h)
	otherwise.


void GAPrintErrMsg(int Error);

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


void GAPrintHowTo(char *CtrlStr);

	  Given same CtrlStr as for GAGetArgs, can be used to print a
	one line 'how to use'


Skeleton of GIF filter
----------------------

	This completes the functions, application can access. An application
skeleton usually will look like (assuming it is a filter - read GIF file,
modifies it, and write new GIF file) the following example, which only copy
a GIF file from stdin to stdout. Please give a pick to the utilities on the
util directory to get more idea once you fill comfortable with this skeleton.
Also try to follow the coding standards of this package if you want me to
officially add your new utility to it.

#include "getarg.h"

main(... )
{
    GifFile *GifFileIn, *GifFileOut;

    GAGetArgs( argc, argv, CtrlStr, ... );	    /* Process command line */

    /* Use the stdin as input (note this also read screen descriptor in: */
    if ((GifFileIn = DGifOpenFileHandle(0)) == NULL)
	QuitGifError(GifFileIn, GifFileOut);

    /* Use the stdout as output: */
    if ((GifFileOut = EGifOpenFileHandle(1)) == NULL)
	QuitGifError(GifFileIn, GifFileOut);
    /* And dump out its screen information: */
    if (EGifPutScreenDesc(GifFileOut,
	GifFileIn -> SWidth, GifFileIn -> SHeight,
	GifFileIn -> SColorResolution, GifFileIn -> SBackGroundColor,
	GifFileIn -> SBitsPerPixel, GifFileIn -> SColorMap) == ERROR)
	QuitGifError(GifFileIn, GifFileOut);

    /* Scan the content of the input GIF file and load the image(s) in: */
    do {
	if (DGifGetRecordType(GifFileIn, &RecordType) == ERROR)
	    QuitGifError(GifFileIn, GifFileOut);

	switch (RecordType) {
	    case IMAGE_DESC_RECORD_TYPE:
		if (DGifGetImageDesc(GifFileIn) == ERROR)
		    QuitGifError(GifFileIn, GifFileOut);
		/* Put image descriptor to out file: */
		if (EGifPutImageDesc(GifFileOut,
		    GifFileIn -> ILeft, GifFileIn -> ITop,
		    GifFileIn -> IWidth, GifFileIn -> IHeight,
		    GifFileIn -> IInterlace, GifFileIn -> IBitsPerPixel,
		    GifFileIn -> IColorMap) == ERROR)
		    QuitGifError(GifFileIn, GifFileOut);

		/* Now read image itself in decoded form as we dont really   */
		/* care what we have there, and this is much faster.	     */
		if (DGifGetCode(GifFileIn, &CodeSize, &CodeBlock) == ERROR ||
		    EGifPutCode(GifFileOut, CodeSize, CodeBlock) == ERROR)
		    QuitGifError(GifFileIn, GifFileOut);
		while (CodeBlock != NULL) {
		    if (DGifGetCodeNext(GifFileIn, &CodeBlock) == ERROR ||
			EGifPutCodeNext(GifFileOut, CodeBlock) == ERROR)
		    QuitGifError(GifFileIn, GifFileOut);
		}
		break;
	    case EXTENSION_RECORD_TYPE:
		/* Skip any extension blocks in file: */
		if (DGifGetExtension(GifFileIn, &ExtCode, &Extension) == ERROR)
		    QuitGifError(GifFileIn, GifFileOut);
		if (EGifPutExtension(GifFileOut, ExtCode, Extension[0],
							Extension) == ERROR)
		    QuitGifError(GifFileIn, GifFileOut);

		/* No support to more than one extension blocks, so discard: */
		while (Extension != NULL) {
		    if (DGifGetExtensionNext(GifFileIn, &Extension) == ERROR)
			QuitGifError(GifFileIn, GifFileOut);
		}
		break;
	    case TERMINATE_RECORD_TYPE:
		break;
	    default:		     /* Should be traps by DGifGetRecordType */
		break;
	}
    }
    while (RecordType != TERMINATE_RECORD_TYPE);

    if (DGifCloseFile(GifFileIn) == ERROR)
	QuitGifError(GifFileIn, GifFileOut);
    if (EGifCloseFile(GifFileOut) == ERROR)
	QuitGifError(GifFileIn, GifFileOut);
}


/******************************************************************************
* Close both input and output file (if open), and exit.			      *
******************************************************************************/
static void QuitGifError(GifFileType *GifFileIn, GifFileType *GifFileOut)
{
    PrintGifError();
    if (GifFileIn != NULL) DGifCloseFile(GifFileIn);
    if (GifFileOut != NULL) EGifCloseFile(GifFileOut);
    exit(1);
}