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
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:
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.
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.
These are the standard functions you will need when loading gif animations in your programs.
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).
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.
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.
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);
}
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.
GIF_ANIMATION *algif_load_raw_animation (char const *filename);
Loads a .gif file into a GIF_ANIMATION structure.
GIF_ANIMATION *algif_create_raw_animation (int frames_count);
Allocates an empty GIF_ANIMATION with the specified number of frames.
void destroy_gif_animation (GIF_ANIMATION * gif);
Deystroys a .gif animation, including all frames and bitmaps.
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.
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.
This struct contains the following documented fields:
The background color is read/written - but not otherwise used by algif.
This struct contains the following documented fields:
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.
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.
381 bytes
This is allegro/misc/alex.xpm, converted to .gif. Look how much smaller the file is.
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.
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.
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.
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.
This is an equally simple example, this time for algif_load_animation. It loads a GIF animation and loops it forever.
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.
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.
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.
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.
Initial version.
Maintenance release, no functional change.
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.
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.