			INTRODUCTION TO GIFLIB

   This is the READ.ME file for GIFLIB, a package of portable tools and
library routines for working with GIF images.  You can surf to the latest
version from //www.ccil.org/~esr/home.html.

   The Graphics Interchange Format(c) specification is the copyrighted
property of CompuServe Incorporated.  GIF(sm) is a service mark property of
CompuServe Incorporated.  CompuServe's policy has been to encorage widespread
use of the format by making the specification freely available, and many
graphics programs in both the freeware and commercial worlds can programs can
use it.

   This package has been released by its author for free re-use.  Use and
copy as you see fit.  If you make useful changes, add new tools, or find and
fix bugs, please send your mods to the maintainers for general distribution.

   The tools directory includes programs to clip, rotate, scale, and position
GIF images.  It includes an X11 viewer, and code to dump GIFs to an
Epson-compatible printer in graphics mode, and several conversion utilities.

   The library includes program-callable entry points for reading and writing
GIF files, an 8x8 utility font for embedding text in GIFs, and an error
handler.  GIF manipulation can be done at a relatively low level by
sequential I/O (which automatically does/undoes image compression) or at
a higher level by slurping an entire GIF into allocated core.

   See the ./doc directory for more information on GIFLIB's capabilities.
See the file ./INSTALL for installation instructions.  Note: I have not
converted the docs into nroff or tex, this is to leave them in a form DOS
programmers can still use.

   Note: this library presently only speaks the 87a version of the GIF
standard.  The differences between GIF87 and GIF89 are minor: in the latter,
the interpretation of some extension block types is defined.

				SUMMARY

The library contains two groups of C functions.  One group does sequential
I/O on the stream-oriented GIF format.  The other supports grabbing an
entire GIF into allocated core, operating on it in core, and then writing
the modified in-core GIF out to disk.  Unless you are on a 286 or some
other very memory-limited machine running under DOS, you probably want
to use the second group.

Here is a summary of the utilities in this package:

			Conversion Utilities

gif2bgi    -- display GIFs on IBM PC displays using the BGI (Borland) driver
gif2epsn   -- dump images saved as GIF files on Epson type printers
gif2herc   -- display GIFs on IBM PC displays using the Hercules graphic card
gif2iris   -- display GIFs under SGI NeWs window system
gif2ps     -- print GIF file on laser printers supporting PostScript
gif2rgb    -- convert images saved as GIF to 24-bit RGB image(s)
gif2rle    -- convert images saved as GIF to RLE (utah raster toolkit) format
gif2x11    -- display images saved as GIF files under X window system

raw2gif    -- convert raw 8-bit image data into GIF files
rgb2gif    -- convert 24 bit images to a GIF image using color quantization
rle2gif    -- convert images saved as RLE (utah raster toolkit) to GIF format

			Test Pattern Generators

gifbg      -- generate a single-color test pattern GIF
gifcolor   -- generate color test patterns
gifwedge   -- create a test GIF image resembling a color monitor test pattern

			Image Manipulation Components

gifasm     -- assemble multiple GIFs into one, or burst a multiple-mage GIF
gifclip    -- clip or crop a GIF image
gifclrmp   -- modify GIF image colormaps
gifcomb    -- combine 2 GIF images of exactly the same size into one
giffix     -- clumsily attempts to fix truncated GIF images
gifflip    -- flip GIF image along X or Y axis or rotate by 90 degrees
gifinter   -- convert between interlaced and non interlaced images
gifovly    -- generate one composite GIF from a multiple-image GIF
gifpos     -- change a GIF's screen size or recondition it.
gifrotat   -- rotate a GIF through any desired angle
gifrsize   -- resize a GIF by deletion or duplication of bits

			Report Generators

giftext    -- print (text only) general information about a GIF

			GIF Composition Tools

icon2gif   -- converter/deconverter to/from an editable text format
text2gif   -- generate GIF images out of regular text in 8x8 font
gifinto    -- end-of-pipe fitting for GIF-processing pipelines
gifcompose -- use giflib tools to compose images

			C Code Templates

giffiltr  -- template code for filtering a GIF sequentially
gifspnge  -- template code for filtering a GIF with in-core operations

				HISTORY

   This package was originally written by Gershon Elber <gershon@cs.utah.edu>
in 1990 on an IBM PC under MS-DOS using Borland Turbo C.  He made it portable
to several UNIX environments.  This 2.1 version features substantial changes
and additions by Eric S. Raymond <esr@snark.thyrsus.com>.

This was Mr. Elber's original READ.ME:

------------------------------------------------------------------------------
	This is a package I wrote so that images can be generated as easy as
possible using GIF format. I needed such routines, and since I did not find
anything like this (at list not free) I decided to write one...
	I will NOT be hold responsible for any damage of any kind it may
cause you. Use it at your own risk.
	In order to compile it, please read the file COMPILE.ME. I uses TC++
2.0 so other compiler owners are on their own. The package has been ported to
unix machine on various platforms (see compile.me).
	You will find .\doc with documents on all the utilities and the library
itself.
	Only one of the images on .\pic was actually generated by me -
solid2.gif, which is binary image rendered using a solid modeller I have
developed named IRIT. The other two were released to usenet few month ago.
I do not think so, but let me know if I violate anything here.
	Few final remarks. While 'playing' with the GIF format, I found few
holes in it, or in some of its implementations:
1. There is no explicit way one can specify comments in images, which can be
   extremely useful. I used one of the extensions block to implements that.
   The problem is that some of the gif viewer I tested (no names) died on
   extension block (!?), so I decided not to use them in any of the utilities
   although the library do support it, and if you are going to use only it
   you can safely use the comments calls. Any better solution?
2. Some viewer even ignore the fact that one GIF file can hold few images.
   I consider this property extremely useful (some of the utilities actually
   manipulate exactly that - gifasm for example), and fully support it. I
   think that a failure of a view program (or any GIF manipulator) here,
   should be considered a bug.
3. One problem in the GIF format, I dont have simple solution to: it is the
   limit of only 8bits per color. The importance of bigger width, is not only
   for higher image quality. One can save other pixel properties in addition,
   such as coverage (alpha channel as it is called in the rle utah raster
   toolkit). The only solution I can thing of, is to generate few GIF files
   in parallel - one for the pixel color, and the other for coverage. The
   coverage property is extremely useful for utilities such as gifbg - back
   ground color generator, and which can be composed with the image using
   gifcomb.
------------------------------------------------------------------------------

My major contribution was the DGifSlurp/EGifSpew function pair for enabling
non-sequential operations on GIF images.  I've also added a few useful tools
(icon2gif, gifovly, gifcompose).  Finally, I've hacked the code for UNIX
portability, fixing a few bugs in the process.

					Eric S. Raymond
					esr@snark.thyrsus.com.
				(WWW: http://www.ccil.org/~esr/home.html)
