<commit_before><?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE article PUBLIC 
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "docbook/docbookx.dtd" [
<!ENTITY homepage      "http://catb.org/~esr/">
<!ENTITY email         "<EMAIL>">
]>
<article><title>The GIFLIB Library</title>

<articleinfo>

<author>
  <firstname>Eric</firstname>
  <othername>Steven</othername>
  <surname>Raymond</surname>
  <affiliation>
    <orgname><ulink url="&homepage;">
    Thyrsus Enterprises</ulink></orgname> 
    <address>
    <email>&email;</email>
    </address>
  </affiliation>
</author>
<copyright>
  <year>2012</year>
  <holder role="mailto:&email;"><NAME></holder> 
</copyright>

</articleinfo>

<!--
<NAME>, May 1991
<NAME>, Sep 1992
<NAME>, May 2004
-->

<sect1><title>Introduction</title>

<para>The Graphics Interchange Format(c) is the Copyright property of
CompuServe Incorporated.  GIF(sm) is a Service Mark property of CompuServe
Incorporated.</para>

<para>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."</para>

<para>This document explains the GIF library code in directory `lib'.  The
code 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 GIF
file format.  This document does <emphasis>not</emphasis> explain the GIF file
format and assumes you know it, at least to the level of the GIF file
structure.</para>

<para>When a GIF file is opened, a GIF file descriptor is created which
is a pointer to GifFileType structure as follows:</para>

<programlisting>
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;
</programlisting>

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

<para>The user almost never writes into this structure (exception: it may
occasionally useful to alter things in the SavedImages array), but can read
any of these items at any time it is valid (image information is invalid
until first image was read).</para>

<para>As the library needs to keep its own internal data, a Private pointer
to hidden data is included. Applications should ignore this item.</para>

<para>The library has no static data. This means that it is fully reentrant
and any number of GIF files (up to memory limits) can be opened for
read/write. Instead of the static data, internal structure pointed by the
Private pointer is used.</para>

<para>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 nor to free them
directly.</para>

<para>In order to reduce disk access, the file buffer is increased to
FILE_BUFFER_SIZE (defined in gif_lib.h).</para>

<para>Here is a module summary:</para>

<variablelist>
<varlistentry>
<term>egif_lib.c</term>
<listitem>
<para>Encoding routines, all prefixed with E.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>dgif_lib.c</term>
<listitem>
<para>Decoding routines, all prefixed with D.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>gifalloc.c</term>
<listitem>
<para>Routines for colormap handling and GIF record allocation.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>gif_font.c</term>
<listitem>
<para>The 8x8 font table for the GIF utility font.</para>
</listitem>
</varlistentry>
</variablelist>

<para>The library includes a sixth file of hash-function code which is accessed
internally only.</para>

<para>Most of the routines return GIF_ERROR (see gif_lib.h) if something
went wrong, GIF_OK otherwise.  After an error return, the code in the
gif_err.c module can be used to do something about it.</para>

<para>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 header
of getarg.c for details on its usage.</para>

</sect1>
<sect1><title>Decoding (dgif_lib.c)</title>

<para>The following functions are used to set up input from a GIF:</para>

<programlisting id="DGifOpenFileName">
GifFileType *DGifOpenFileName(char *GifFileName)
</programlisting>

<para>Open a new GIF file using the given GifFileName, and read its Screen
information.</para>

<para>If any error occurs, NULL is returned and the error handler can be
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<programlisting id="DGifOpenFileHandle">
GifFileType *DGifOpenFileHandle(int GifFileHandle)
</programlisting>

<para>Open a new GIF file using the given GifFileHandle, and read its Screen
information.</para>

<para>If any error occurs, NULL is returned and the error handler can be 
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<para>Once you have acquired a handle on a GIF, there are two ways to
read it in.  The high-level function</para>

<programlisting id="DGifSlurp">
int DGifSlurp(GifFileType)
</programlisting>

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

<para>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().</para>

<para>If you are handling large images on a memory-limited machine, you may need
to use the following functions for sequential read.</para>

<programlisting id="DGifGetScreenDesc">
int DGifGetScreenDesc(GifFileType *GifFile)
</programlisting>

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

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

<programlisting id="DGifGetRecordType">
int DGifGetRecordType(GifFileType *GifFile, GifRecordType *GifType)
</programlisting>

<para>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:</para>

<variablelist>
<varlistentry>
<term>1. UndefinedRecordType </term>
<listitem>
<para>something is wrong!</para>
</listitem>
</varlistentry>

<varlistentry>
<term>2. ScreenDescRecordType </term>
<listitem>
<para>screen information.  As the screen info is automatically read in when the file is open, this should not happen.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>3. ImageDescRecordType </term>
<listitem>
<para> next record is an image descriptor.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>4. ExtensionRecordType</term>
<listitem>
<para> next record is extension block.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>5. TerminateRecordType</term>
<listitem>
<para>last record reached, can close the file.</para>
</listitem>
</varlistentry>
</variablelist>

<para>The first two types can usually be ignored. The function
returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="DGifGetImageDesc">
int DGifGetImageDesc(GifFileType *GifFile)
</programlisting>

<para>Reads image information into the GifFile structure.
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="DGifGetLine">
int DGifGetLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen)
</programlisting>

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

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

<programlisting>
int DGifGetPixel(GifFileType *GifFile, PixelType GifPixel)
</programlisting>

<para>Loads one pixel from the GIF file.  This routine may be interleaved
with <link linkend="DGifGetLine">DGifGetLine()</link>, until all pixels are
read.  Because of the overhead per each call, use of this routine is
not recommended.</para>

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

<programlisting id="DGifGetComment">
int DGifGetComment(GifFileType *GifFile, char *GifComment)
</programlisting>

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

<para>For the definition of a comment, see <link
linkend="EGifPutComment">EGifPutComment()</link>.  Returns GIF_ERROR
if something went wrong, GIF_OK otherwise.</para>

<programlisting>
int DGifGetExtension(
        GifFileType *GifFile,
        int *GifExtCode,
        ByteType **GifExtension)
</programlisting>

<para>Loads an extension block from the GIF file.  Extension blocks
are optional in GIF files.  This routine should be followed by
<link linkend="DGifGetExtensionNext">DGifGetExtensionNext</link>.</para>

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

<para><programlisting id="DGifGetExtensionNext">
int DGifGetExtensionNext(GifFileType *GifFile, ByteType **GifExtension)
</programlisting>

As extensions may contain more than one block, use this routine to
continue after DGifGetExtension, until *GifExtension is NULL.</para>

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

<programlisting>
int DGifGetCode(
        GifFileType *GifFile, 
        int *GifCodeSize, ByteType **GifCodeBlock)
</programlisting>

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

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

<programlisting id="DGifGetCodeNext">
int DGifGetCodeNext(GifFileType *GifFile, ByteType **GifCodeBlock)
</programlisting>

<para>See DGifGetCode above.</para>
	  
<programlisting id="DGifGetLZCodes">
int DGifGetLZCodes(GifFileType *GifFile, int *GifCode)
</programlisting>

<para>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).</para>

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

<programlisting id="DGifCloseFile">
int DGifCloseFile(GifFileType *GifFile)
</programlisting>

<para>Close GIF file and free all memory allocated for it. GifFile should
not be used after this routine has been called.</para>

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

<para>There is one more way to read from a GIF file: through a
function hook. Initialize with </para>

<programlisting id="DGifOpen">
GifFileType *DGifOpen(void *userPtr, InputFunc readFunc)
</programlisting>

<para>and see the library header file for the type of InputFunc.</para>

</sect1>
<sect1><title>Encoding (egif_lib.c)</title>

<para>There are two ways to write out a GIF.  The high-level function</para>

<programlisting id="EGifSpew">
int EGifSpew(GifFileType *GifFile, int GifFileHandle)
</programlisting>

<para>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 arguments are a GIF file descriptor (as
above) and an ordinary output file descriptor.</para>

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

<para>If you are handling large images on a memory-limited machine, you may need
to use the following functions for sequential write.</para>

<programlisting id="EGifOpenFileName">
GifFileType *EGifOpenFileName(char *GifFileName, bool GifTestExistance)
</programlisting>

<para>Open a new GIF file using the given GifFileName.  If GifTestExistance
is TRUE, and file exists, the file is not destroyed, and NULL
returned.</para>

<para>If any error occurs, NULL is returned and the error handler can be
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<programlisting id="EGifOpenFileHandle">
GifFileType *EGifOpenFileHandle(int GifFileHandle)
</programlisting>

<para>Open a new GIF file using the given GifFileHandle.</para>

<para>If any error occurs, NULL is returned and the error handler can be
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<programlisting id="EGifSetGifVersion">
void EGifSetGifVersion(char *Version)
</programlisting>

<para>Sets the GIF version of all files opened, until another call to this
routine is made.  Version is a 3 characters string of the form "87a"
or "89a".  No test is made to validate this string.</para>

<programlisting>
int EGifPutScreenDesc(GifFileType *GifFile,
        int GifWidth, int GifHeight,<commit_msg>Document new behavior.<commit_after><?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE article PUBLIC 
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "docbook/docbookx.dtd" [
<!ENTITY homepage      "http://catb.org/~esr/">
<!ENTITY email         "<EMAIL>">
]>
<article><title>The GIFLIB Library</title>

<articleinfo>

<author>
  <firstname>Eric</firstname>
  <othername>Steven</othername>
  <surname>Raymond</surname>
  <affiliation>
    <orgname><ulink url="&homepage;">
    Thyrsus Enterprises</ulink></orgname> 
    <address>
    <email>&email;</email>
    </address>
  </affiliation>
</author>
<copyright>
  <year>2012</year>
  <holder role="mailto:&email;"><NAME></holder> 
</copyright>

</articleinfo>

<!--
<NAME>, May 1991
<NAME>, Sep 1992
<NAME>, May 2004
-->

<sect1><title>Introduction</title>

<para>The Graphics Interchange Format(c) is the Copyright property of
CompuServe Incorporated.  GIF(sm) is a Service Mark property of CompuServe
Incorporated.</para>

<para>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."</para>

<para>This document explains the GIF library code in directory `lib'.  The
code 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 GIF
file format.  This document does <emphasis>not</emphasis> explain the GIF file
format and assumes you know it, at least to the level of the GIF file
structure.</para>

<para>When a GIF file is opened, a GIF file descriptor is created which
is a pointer to GifFileType structure as follows:</para>

<programlisting>
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;
</programlisting>

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

<para>The user almost never writes into this structure (exception: it may
occasionally useful to alter things in the SavedImages array), but can read
any of these items at any time it is valid (image information is invalid
until first image was read).</para>

<para>As the library needs to keep its own internal data, a Private pointer
to hidden data is included. Applications should ignore this item.</para>

<para>The library has no static data. This means that it is fully reentrant
and any number of GIF files (up to memory limits) can be opened for
read/write. Instead of the static data, internal structure pointed by the
Private pointer is used.</para>

<para>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 nor to free them
directly.</para>

<para>In order to reduce disk access, the file buffer is increased to
FILE_BUFFER_SIZE (defined in gif_lib.h).</para>

<para>Here is a module summary:</para>

<variablelist>
<varlistentry>
<term>egif_lib.c</term>
<listitem>
<para>Encoding routines, all prefixed with E.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>dgif_lib.c</term>
<listitem>
<para>Decoding routines, all prefixed with D.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>gifalloc.c</term>
<listitem>
<para>Routines for colormap handling and GIF record allocation.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>gif_font.c</term>
<listitem>
<para>The 8x8 font table for the GIF utility font.</para>
</listitem>
</varlistentry>
</variablelist>

<para>The library includes a sixth file of hash-function code which is accessed
internally only.</para>

<para>Most of the routines return GIF_ERROR (see gif_lib.h) if something
went wrong, GIF_OK otherwise.  After an error return, the code in the
gif_err.c module can be used to do something about it.</para>

<para>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 header
of getarg.c for details on its usage.</para>

</sect1>
<sect1><title>Decoding (dgif_lib.c)</title>

<para>The following functions are used to set up input from a GIF:</para>

<programlisting id="DGifOpenFileName">
GifFileType *DGifOpenFileName(char *GifFileName)
</programlisting>

<para>Open a new GIF file using the given GifFileName, and read its Screen
information.</para>

<para>If any error occurs, NULL is returned and the error handler can be
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<programlisting id="DGifOpenFileHandle">
GifFileType *DGifOpenFileHandle(int GifFileHandle)
</programlisting>

<para>Open a new GIF file using the given GifFileHandle, and read its Screen
information.</para>

<para>If any error occurs, NULL is returned and the error handler can be 
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<para>Once you have acquired a handle on a GIF, there are two ways to
read it in.  The high-level function</para>

<programlisting id="DGifSlurp">
int DGifSlurp(GifFileType)
</programlisting>

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

<para>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().</para>

<para>If you are handling large images on a memory-limited machine, you may need
to use the following functions for sequential read.</para>

<programlisting id="DGifGetScreenDesc">
int DGifGetScreenDesc(GifFileType *GifFile)
</programlisting>

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

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

<programlisting id="DGifGetRecordType">
int DGifGetRecordType(GifFileType *GifFile, GifRecordType *GifType)
</programlisting>

<para>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:</para>

<variablelist>
<varlistentry>
<term>1. UndefinedRecordType </term>
<listitem>
<para>something is wrong!</para>
</listitem>
</varlistentry>

<varlistentry>
<term>2. ScreenDescRecordType </term>
<listitem>
<para>screen information.  As the screen info is automatically read in when the file is open, this should not happen.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>3. ImageDescRecordType </term>
<listitem>
<para> next record is an image descriptor.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>4. ExtensionRecordType</term>
<listitem>
<para> next record is extension block.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>5. TerminateRecordType</term>
<listitem>
<para>last record reached, can close the file.</para>
</listitem>
</varlistentry>
</variablelist>

<para>The first two types can usually be ignored. The function
returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="DGifGetImageDesc">
int DGifGetImageDesc(GifFileType *GifFile)
</programlisting>

<para>Reads image information into the GifFile structure.
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="DGifGetLine">
int DGifGetLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen)
</programlisting>

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

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

<programlisting>
int DGifGetPixel(GifFileType *GifFile, PixelType GifPixel)
</programlisting>

<para>Loads one pixel from the GIF file.  This routine may be interleaved
with <link linkend="DGifGetLine">DGifGetLine()</link>, until all pixels are
read.  Because of the overhead per each call, use of this routine is
not recommended.</para>

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

<programlisting id="DGifGetComment">
int DGifGetComment(GifFileType *GifFile, char *GifComment)
</programlisting>

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

<para>For the definition of a comment, see <link
linkend="EGifPutComment">EGifPutComment()</link>.  Returns GIF_ERROR
if something went wrong, GIF_OK otherwise.</para>

<programlisting>
int DGifGetExtension(
        GifFileType *GifFile,
        int *GifExtCode,
        ByteType **GifExtension)
</programlisting>

<para>Loads an extension block from the GIF file.  Extension blocks
are optional in GIF files.  This routine should be followed by
<link linkend="DGifGetExtensionNext">DGifGetExtensionNext</link>.</para>

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

<para><programlisting id="DGifGetExtensionNext">
int DGifGetExtensionNext(GifFileType *GifFile, ByteType **GifExtension)
</programlisting>

As extensions may contain more than one block, use this routine to
continue after DGifGetExtension, until *GifExtension is NULL.</para>

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

<programlisting>
int DGifGetCode(
        GifFileType *GifFile, 
        int *GifCodeSize, ByteType **GifCodeBlock)
</programlisting>

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

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

<programlisting id="DGifGetCodeNext">
int DGifGetCodeNext(GifFileType *GifFile, ByteType **GifCodeBlock)
</programlisting>

<para>See DGifGetCode above.</para>
	  
<programlisting id="DGifGetLZCodes">
int DGifGetLZCodes(GifFileType *GifFile, int *GifCode)
</programlisting>

<para>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).</para>

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

<programlisting id="DGifCloseFile">
int DGifCloseFile(GifFileType *GifFile)
</programlisting>

<para>Close GIF file and free all memory allocated for it. GifFile should
not be used after this routine has been called.</para>

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

<para>There is one more way to read from a GIF file: through a
function hook. Initialize with </para>

<programlisting id="DGifOpen">
GifFileType *DGifOpen(void *userPtr, InputFunc readFunc)
</programlisting>

<para>and see the library header file for the type of InputFunc.</para>

</sect1>
<sect1><title>Encoding (egif_lib.c)</title>

<para>There are two ways to write out a GIF.  The high-level function</para>

<programlisting id="EGifSpew">
int EGifSpew(GifFileType *GifFile, int GifFileHandle)
</programlisting>

<para>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 arguments are a GIF file descriptor (as
above) and an ordinary output file descriptor.</para>

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

<para>If you are handling large images on a memory-limited machine, you may need
to use the following functions for sequential write.</para>

<programlisting id="EGifOpenFileName">
GifFileType *EGifOpenFileName(char *GifFileName, bool GifTestExistance)
</programlisting>

<para>Open a new GIF file using the given GifFileName.  If GifTestExistance
is TRUE, and file exists, the file is not destroyed, and NULL
returned.</para>

<para>If any error occurs, NULL is returned and the error handler can be
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<programlisting id="EGifOpenFileHandle">
GifFileType *EGifOpenFileHandle(int GifFileHandle)
</programlisting>

<para>Open a new GIF file using the given GifFileHandle.</para>

<para>If any error occurs, NULL is returned and the error handler can be
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<programlisting id="EGifSetGifVersion">
void EGifSetGifVersion(char *Version)
</programlisting>

<para>Sets the GIF version of all files opened, until another call to this
routine is made.  Version is a 3 characters string of the form "87a"
or "89a".  No test is made to validate this string. </para>

<para>Before this call is made, or after it has been made with a
zero-length string as argument, the library computes the right version
to use by looking at the GIF's extension blocks. (Older versions of
the library defaulted to GIF87)</para>

<programlisting>
int EGifPutScreenDesc(GifFileType *GifFile,
        int GifWidth, int GifHeight,
{'fraction_non_alphanumeric': 0.08878025434158349, 'fraction_numerical': 0.0038287980309038698, 'mean_word_length': 4.925258254000405, 'pattern_counts': {'":': 0, '<': 599, '<?xml version=': 2, '>': 599, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6367691', 'n_tokens_mistral': 9166, 'n_tokens_neox': 8702, 'n_words': 3632}