= The giflib API =

== Overview ==

A detailed description of the API can be found in the doc/ subdirectory.

=== Input  ===

Use DGifOpenFileHandle() or DGifOpenFileName() to get a read handle 
on a GIF file. Or use DGifOpen() to set up a read function hook.

Use DGifSlurp() to read a GIF image into code from the handle or via
the read hook.  look in the image structure members for the RGB
bits.

Use DGifClose() to free the read handle.

=== Output ===

Use EGifOpenFileHandle() or EGifOpenFileName() to get a write handle
on a GIF file. Or use EGifOpen() to set up a write function hook.

Use EGifSpew() to write a GIF image from appropriately populated
structures in core to the file described by the write handle or via
the write hook.

Use EGifClose() to free the write handle.

=== Errors ===

You may find the functions GifError() and GifErrorString()
useful for error handling.

=== Forward and Backward compatibility ===

If you need to write code that operates with multiple versions 
of the library, there are some useful version #defines in the
library header.  See the details in the library documentation.

=== Legacy ==

The other entry points are primarily historical.

Except for some details of extension-block handling and the addition
of read/write function hooks, the DGifSlurp()/EGifSpew() interface has
been stable since 1990.  It is expected to remain so.

== Roadmap and deprecation list ==

Some features will be removed in giflib 5.0:

* In the SavedImage struct: int Function will be removed.  Use
  SavedImage.ExtensionBlocks[x].Function instead.

* In gifalloc.c: MakeExtension is deprecated as well.  Use
  AddExtensionBlock instead, but note that it will change in 5.0 to
  take an additional function code argument.  (This and the previous
  int Function were deprecated because they only handle one Extension
  per image.  The new code handles multiple extensions.)

* Do not use GifBooleanType.  This is legacy from before the C
  language got booleans. It is still in the .h file, but will be 
  removed in 5.0.

* Similarly, do not use the VoidPtr macro; it is legacy from when not
  all C compilers had void *, and will be removed in 5.0

* The bool args to EGifOpenFileName() and EGifPutImageDesc() have become
  true C99 bools; in 5.0 the TRUE and FALSE macros will go away.

Some API calls will be renamed in 5.0:

* DrawText (and the Windows name for it created to avoid some
  collision, DrawGifText) will become GifDrawText. The other
  Draw* functions will also become GifDraw*.