<?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         "esr@thyrsus.com">
]>
<article><title>Introduction to GIFLIB</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;">Eric S. Raymond</holder> 
</copyright>

</articleinfo>

<para>GIFLIB is a package of portable tools and library routines for
working with GIF images.</para>

<para>The Graphics Interchange Format(c) specification is the copyrighted
property of CompuServe Incorporated.  GIF(sm) is a service mark
property of CompuServe Incorporated.</para>

<para>This package has been released under an X Consortium-like open-source
license.  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.</para>

<para>The util directory includes programs to clip, rotate, scale, and
position GIF images.  These are no replacement for an interactive graphics
editor, but they can be very useful for scripted image generation or
transformation.</para>

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

<para>This library speaks both GIF87a and GIF89.  The differences
between GIF87 and GIF89 are minor: in the latter, the interpretation
of some extension block types is defined.  The library never needs to
actually interpret these, but <ulink
url="giftext.html">giftext</ulink> notices them.</para>

<sect1><title>Utilities</title>

<para>Here is a summary of the utilities in this package.  If you're looking
at this page through a web browser, each utility name should be a
hotlink to HTML documentation.</para>

<sect2><title>Viewers</title>

<variablelist>
<varlistentry>
<term><ulink url="gif2x11.html">gif2x11</ulink></term>
<listitem>
<para>display images saved as GIF files under X window system.</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>
<sect2><title>Conversion Utilities</title>

<variablelist>
<varlistentry>
<term><ulink url="gif2rgb.html">gif2rgb</ulink></term>
<listitem>
<para>convert images saved as GIF to 24-bit RGB image(s)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="raw2gif.html">raw2gif</ulink></term>
<listitem>
<para>convert raw 8-bit image data into GIF files</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="rgb2gif.html">rgb2gif</ulink></term>
<listitem>
<para>convert 24 bit images to a GIF image using color quantization</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>
<sect2><title>Test Pattern Generators</title>

<variablelist>
<varlistentry>
<term><ulink url="gifbg.html">gifbg</ulink></term>
<listitem>
<para>generate a single-color test pattern GIF</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="gifcolor.html">gifcolor</ulink></term>
<listitem>
<para>generate color test patterns</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="gifwedge.html">gifwedge</ulink></term>
<listitem>
<para>create a test GIF image resembling a color monitor test pattern</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>
<sect2><title>Image Manipulation Components</title>

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

</sect2>
<sect2><title>Report Generators</title>

<variablelist>
<varlistentry>
<term><ulink url="giftext.html">giftext</ulink></term>
<listitem>
<para>print (text only) general information about a GIF</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="gifhisto.html">gifhisto</ulink></term>
<listitem>
<para>generate color-frequency histogram from a GIF</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>
<sect2><title>GIF Composition Tools</title>

<variablelist>
<varlistentry>
<term><ulink url="icon2gif.html">icon2gif</ulink></term>
<listitem>
<para>converter/deconverter to/from an editable text format</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="text2gif.html">text2gif</ulink></term>
<listitem>
<para>generate GIF images out of regular text in 8x8 font</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="gifinto.html">gifinto</ulink></term>
<listitem>
<para>end-of-pipe fitting for GIF-processing pipelines</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="gifcompose.html">gifcompose</ulink></term>
<listitem>
<para>use giflib tools to compose images</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>
<sect2><title>C Code Templates</title>

<variablelist>
<varlistentry>
<term><ulink url="giffiltr.html">giffiltr</ulink></term>
<listitem>
<para>template code for filtering a GIF sequentially</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="gifspnge.html">gifspnge</ulink></term>
<listitem>
<para>template code for filtering a GIF with in-core operations</para>
</listitem>
</varlistentry>
</variablelist>

<para>Under MS-DOS, most filters will print the current input scan line number
(counting up) whenever they read image input, and will print output image line
number (counting down) when they dump output.  Utilities that only read or
write always print in increasing order.  Utilities (like GifPos that only
change positions) that copy the image as a block of compressed data will print
nothing --- they cannot identify a scan line number, and are enough faster that
the feedback to the user doesn't seem necessary.</para>

</sect2>
</sect1>
<sect1><title>Library Functions</title>

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

<para>Unless you are on extremely memory-limited machine you probably want
to use the second group.</para>

<para>Detailed documentation on the library entry points is in <ulink
url="gif_lib.html">gif_lib.html</ulink>. Library error codes are
described in <ulink url="liberror.html">liberror.html</ulink></para>

</sect1>
<sect1><title>The GIF Standard</title>

<para>The doc subdirectory includes flat-ASCII descriptions of <ulink
url="gif89.txt">GIF89 format</ulink> and <ulink url="lzgif.txt">Lempel-Ziv
Compression</ulink>.</para>

</sect1>
<sect1><title>Package Status</title>

<para>GIFLIB's current maintainer is Eric S. Raymond.  You can find his home
page at <ulink url="&homepage;">http://www.ccil.org/esr</ulink>.</para>

<para>GIFLIB is not under active development, but bug fixes are being
accepted.</para>

</sect1>
</article>
