This is the text version of the documentation, which is autogenerated from
the HTML version.

,-------------------------------------------------------------------------.
| algif - Allegro GIF Addon                                               |
`-------------------------------------------------------------------------'

Version 1.2
by Elias Pschernig
Download - http://prdownloads.sourceforge.net/algif/algif_1.2.zip?download
algif homepage - http://algif.sf.net
Allegro homepage - http://alleg.sf.net

,-------------------------------------------------------------------------.
| Contents                                                                |
`-------------------------------------------------------------------------'

Not present in the .txt output.
,-------------------------------------------------------------------------.
| Introduction                                                            |
`-------------------------------------------------------------------------'

This is a simple addon to Allegro which allows reading and writing of GIF
animations. It provides functionality both to integrate with Allegro's
load_bitmap and save_bitmap functions, as well as reading full animations.
The .gif specification can be found here: http://www.w3.org/Graphics/GIF
/spec-gif89a.txt
First of all, .gif may not be the right file format for you. It is severely
limited, with no alpha channel, and only a maximum of 256 colors per frame.
You may be better off using .png, which doesn't have any of these limits
and compresses better. And there also exists an addon to use it with
Allegro.
Having said that, .gif still is a common format for small animated pictures
on websites - and therefore very well suited for small pixel animations in
games, since you can use the same files you display on your website
directly as in-game animations.
There are lots of other ways besides algif to read .gif files into an
Allegro program. Some are:

 * http://www.allegro.cc/depot/project-screenshots.php?id=648&

 * http://angband.oook.cz/file.php?dir=10&file=load_gif.c

The reason I released algif is, I wrote the code for it a long time ago, so
never had a need to look at one of the other libraries - and maybe it has a
useful feature which the others don't have.

,-------------------------------------------------------------------------.
| HOW TO USE                                                              |
`-------------------------------------------------------------------------'

The first, and hardest step, is to compile it. This may seem very simple:
gcc -c *.c
ar -rcs libalgif.a *.o
Or simply compile the .c files along with your project.
But in practice, it is much harder. You may prefer to use a makefile, in
which case you can try the provided one, it was tested with a recent mingw
and linux distribution.
The makefile also has an install target, so if you type "make install", it
will copy the libalgif.a to /usr/local/lib or $MINGDIR/lib and algif.h to
/usr/local/include or $MINGDIR/include.
And last, put include <algif.h> at the top of the source files where you
want to use functions out of it, and link your program against it. With
gcc, just add -lalgif as option.
That should be it. If it doesn't work, contact me.

,-------------------------------------------------------------------------.
| API - Standard use                                                      |
`-------------------------------------------------------------------------'

These are the standard functions you will need when loading gif animations
in your programs.


algif_init
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

void algif_init (void);
This function calls register_bitmap_file_type to make "gif" one of
Allegro's supported bitmap formats. After you call this, you can load .gif
pictures with load_bitmap, and save them with save_bitmap.
Additionally, it will register a new datafile type with the id "GIF ". To
create such datafiles, you first need to recompile grabber/dat with the GIF
plugin. The ->dat member of GIF datafile objects will point to a
GIF_ANIMATION (see below).


load_gif
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

BITMAP *load_gif (char const *filename, RGB * pal);
This will load all the frames stored in a .gif into a single BITMAP,
following the semantics of Allegro's load_bitmap. After calling algif_init,
this function will be automatically used for .gif files by load_bitmap.
Note that this function uses Allegro's select_palette internally, so if you
are using select_palette yourself, you need to restore the palette
afterwards.


save_gif
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

int save_gif (AL_CONST char *filename, BITMAP *bmp, AL_CONST RGB * pal);
This will save a BITMAP as a gif image, following the semantics of
Allegro's save_bitmap. After calling algif_init, this function will be
automatically used for .gif files by save_bitmap.


algif_load_animation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

int algif_load_animation (const char *filename, BITMAP ***frames, int **durations);
This will load a gif animation into an array of BITMAP pointers, and the
frame durations into an integer array. A pointer to the BITMAPs is written
to *frames, a pointer to the durations to *durations. Each bitmap will have
the size of the complete animation. The bitmaps will all use Allegro's
current color depth. Returns the number of stored frames, 0 on error. The
durations are given in 1/100th seconds. You are responsible for freeing all
the bitmaps as well as the arrays yourself.
Example:
BITMAP **frames = NULL;
int *durations = NULL;
int n = algif_load_animation ("my.gif", &frames, &durations);
if (n)
{
    ...
    for (i = 0; i < n; i++)
        destroy_bitmap (frames[i]);
    free (frames);
    free (durations);
}

,-------------------------------------------------------------------------.
| API - Advanced use                                                      |
`-------------------------------------------------------------------------'

Normally, you should not need to use these functions directly - the other
functions are wrappers around them which are easier to use. But in case you
need more control, or need to write out .gif animations, you may use them.
See the descriptions of GIF_ANIMATION, GIF_FRAME and GIF_PALETTE for
details on the values you can access/have to fill in.


algif_load_raw_animation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

GIF_ANIMATION *algif_load_raw_animation (char const *filename);
Loads a .gif file into a GIF_ANIMATION structure.


algif_create_raw_animation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

GIF_ANIMATION *algif_create_raw_animation (int frames_count);
Allocates an empty GIF_ANIMATION with the specified number of frames.


destroy_gif_animation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

void destroy_gif_animation (GIF_ANIMATION * gif);
Deystroys a .gif animation, including all frames and bitmaps.


algif_save_raw_animation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

int algif_save_raw_animation (const char *filename, GIF_ANIMATION *gif);
Saves a .gif animation. No optimizations are applied - if you want small
gifs, you need to take care yourself to only include changed bitmap areas
and only use as many palettes and colors as necessary. No comments or other
invisible headers will be added.
Returns 0 on success.


algif_render_frame
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

void algif_render_frame (GIF_ANIMATION *gif, BITMAP *bitmap, int frame, int xpos, int ypos);
This is the worker function which handles conversion of a GIF_ANIMATION to
real bitmaps. You need to call it for every frame, starting with frame 0,
and always specify the same x and y position. This guarantees that the
right offsets and disposal methods are applied. In regular programs, you
will never use this - use load_gif or algif_load_animation instead.


GIF_ANIMATION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This struct contains the following documented fields:

 * int width, height; - Dimensions of the complete animation.

 * int frame_count; - Number of frames.

 * int background_color; - The background color index.

 * GIF_PALETTE palette; - The global palette.

 * GIF_FRAME *frames; - The frames.

The background color is read/written - but not otherwise used by algif.


GIF_FRAME
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This struct contains the following documented fields:

 * BITMAP *bitmap_8_bit; - The bitmap, in 8-bit format.

 * GIF_PALETTE palette; - The local palette for this frame.

 * int xoff, yoff; - Offset of this frame into the animation.

 * int duration; - Duration of the frame in 1/100th seconds.

 * int disposal_method; - Disposal method of this frame.

 * int transparent_index; - The transparent color for this frame.

The disposal method has the same numeric value as in the .gif. It specifies
how to dispose the frame. The values are: 0 - do not dispose (i.e.,
whatever the application wants) 1 - keep (it is used as background for the
next frame) 2 - background (before displaying the next frame, clear with
background color) 3 - previous (before displaying the next frame, restore
to previous frame)
The transparent_index is set to -1 if it is not enabled while loading, and
will cause the frame to be saved without the transparency flag when saving.
Normally, you should not need to deal with disposal method and transparent
index yourself, algif handles it for you.


GIF_PALETTE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


 * int colors_count; - Number of colors present.

 * RGB colors[256]; - RGB triplets, where every color is from 0 to 255.

Note that this is different from Allegro palettes which use RGB to only
hold values from 0 to 63. The number of colors in a .gif palette always is
a power of 2, so if you want small gifs, it helps using 64 colors instead
of 65, but not using 65 colors instead of 128. If colors_count is 0, no
global/local palette is present in the .gif file.

,-------------------------------------------------------------------------.
| Example gifs                                                            |
`-------------------------------------------------------------------------'



alex.gif
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

381 bytes
This is allegro/misc/alex.xpm, converted to .gif. Look how much smaller the
file is.


allefant.gif
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

6172 bytes
Just a gif animation I drew. Look how extremely small the file size is,
given it is a 16 frame animation with 256x64 pixel.


dispose.gif
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

475 bytes
A gif animation demonstrating the different disposal methods for frames.
The first frame in the upper left corner has a disposal method of "keep",
so it just stays there when the second frame in the upper right corner is
displayed. That frame has a disposal method of "previous", so when its
duration is over, the animation reverts to the previous state where only
the upper left frame is displayed. The third frame in the lower left corner
is draw on top of it. It has a disposal method of "background", so before
displaying the forth frame, its area is cleared to transparent. The last
frame has no disposal method specified, since the last frame is never
disposed and the animation starts all over when looping.


rgb.gif
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

3257 bytes
This is a gif which contains more than 256 colors ("truecolor gif"). As you
can see, instead of compressing the file, it is blown up now to use more
space than any other existing bitmap format would use for the same picture
- but it shows how well algif can handle the .gif palettes.

,-------------------------------------------------------------------------.
| Example programs                                                        |
`-------------------------------------------------------------------------'



load_gif
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a simple example demonstrating load_gif. It will load alex.gif (or
a gif given on the command line) by calling Allegro's load_bitmap, and
display the bitmap. Since algif_init registers GIF as a known type, calling
load_bitmap on a .gif file has the same effect as calling load_gif.


load_animation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is an equally simple example, this time for algif_load_animation. It
loads a GIF animation and loops it forever.


load_raw_animation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This example is here to demonstrate access to the raw GIF data. It loads a
GIF, and displays global and per-frame information about it. Use cursor
left/right to change the current frame.


save_raw_animation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In case you want to save gif animations, this shows how it is done. It
creates two of the example gifs, dispose.gif and rgb.gif, then saves them
as files.

,-------------------------------------------------------------------------.
| Miscellaneous                                                           |
`-------------------------------------------------------------------------'



TODO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are a few things I can think of, which I don't need personally. If at
least one person requests one of them, I will add it. If there are other
requests, I will consider them as well of course. For some, like e.g.
providing a version ready for MSVC or OSX users, I'd need help.

 * Grabber plugin

 * Better build process/autotools/libtool/dynamic library/...

 * Better support for MSVC/OSX/djgpp/...

 * Support for GIF comments

 * Support for GIF text

 * Automatic optimization (cropping, palette ordering)

 * Make it work without Allegro



BUGS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Well, still quite a lot I guess. Please report. Release 1.0 meant, the base
functinoality (loading a gif into allegro) worked. The lib will yet have to
stabilize now.


Version history
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


___________________________________________________________________________
Version 1.0

Initial version.

___________________________________________________________________________
Version 1.1

Maintenance release, no functional change.

___________________________________________________________________________
Version 1.2 (Feb 2005)


 * Jonny Cook reported problems with C++, added now extern "C" to algif.h

 * Peter Wang fixed some bugs in save_gif

 * Peter Wang fixed handling of palettes in load_gif



License and disclaimer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


___________________________________________________________________________
Notes

There was a patent on the LZW algorithm used with GIF files, but to my
knowledge, this patent is expired by now, and therefore everyone is free to
use the algorithm.. you should still check yourself though before using
this code.
The algif addon itself is put under the MIT license.

___________________________________________________________________________
MIT license

Copyright (c) 2000-2004 algif contributors
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.


