GIFAllegS	Ver 1.03
Relased Nov 21, 2004
For All Allegro Platforms
(A Stars Dev Company Production)  

Copyright (c) Martin Zolnieryk aka Hard Rock 2003-2004 

Stars Dev Company Website:    http://starsdev.cjb.net
Stars Dev Developer Section:   http://starsdev.cjb.net/developer/


Table of Contents
--------------------------------------------------------
1.0 - About
   1.1 - License
   1.2 - Features
   1.3 - Compatibility
   1.4 - Installation
   1.5 - Instructions for non animated gifs
   1.6 - Instructions for animated gifs
   1.7 - Instructions For memory gifs
   1.8 - Instructions For Saving gifs
2.0 - Bugs
3.0 - Whats new
4.0 - To Do List
5.0 - Closing, More information,Contact
--------------------------------------------------------

1.0 About
---------
GIFAllegS is Image Library for Allegro that loads and returns GIF's. Currently it can load GIF's from data files, and supports(should) all bits depths from 2-8 as well as supporting Interlaced Images. It can also load animated gifs from files or datafiles. Saving GIFs has also been added now that the LZW patent has expired.


Why the S at the end? Well there are a few gif loaders already out,and I didnt want to take the name GIFAlleg and then have someone else taking that same name (there are a lot of XXXAllegs, you've got your PNGAlleg, your JPGAlleg etc etc), so I added an S. What does the S stand for?  Super? Stars? Simple? SomeLongWord? You make the call.


1.1 License
-----------
This code is freeware, use it for whatever you want. Just credit it in any program you use it for please!


1.2 Features
------------
-Supports All bit depths from 2-8 of GIFS
-Supports Interlaced Images
-Can load GIF's in datafiles!
-Can load Animated Gifs
-Limited Support for loading gifs from memory
-Colour Conversion sensitive, will react to set_colour_coversion.
-Can save gifs
-Can save animated gifs




1.3 Compatibility
---------------------------------
The gif loader has been mainly tested under mingw and allegro 4.0.x and MSVC, and windows. It has also been reported to work under Linux and allegro 4.1.x.


If you find a gif that will not load correctly 
please email me it at hard_rock_2@yahoo.com and I will add support for that GIF.

1.4 Installation
---------------------------------
Installation is very simple. Compile and link sgif.c with your program and include sgif.h in any file that requires access to the gif library. Done!

There is one global variable in the library and that is:
extern int gif_a_settings;

Current you can give it the following defines, you may use the | operator to combine them:

#define GIF_A_IGNOREBACKGROUND 1
Whenever an animated gif is loaded, it will by default be transparent with this flag enabled.
//Gif gif_a_setttings these values
#define GIF_A_NOGLOBALPAL      2 
When Saving a gif, local palettes will be used, meaning each image will have its own palette
#define GIF_A_SAVEINTERLACED   4 
When Saving a gif, it will be saved interlaced
#define GIF_A_NOTRANS          8 
No Tranpsarent Colour used when saving/loading gifs. Reccomended for saving gifs



Also you may set the background for saving by using this fuction
#define GIF_SETBACKGROUND(a)
where a is your background value from 0 - 255.




1.5 Instruction For Non-Animated Gifs
--------------------------------------
To load gifs you can use :
BITMAP *load_gif(const char *filename, RGB *pal);

However you may want to use load_bitmap instead, that add this near the beggining of your code:
register_bitmap_file_type("gif", load_gif, save_gif);

If you want grabber support, add this code near the beggining of your code:
register_datafile_object(DAT_GIF, load_gif_datafile, destroy_gif_datafile);

Now any datafile entry with "GIF " will create a GIF structure. Containing two fields, it is important to note a POINTER to the Structure is returned, rather than a structure. 

typedef struct GIF_STRUCT
{
BITMAP *image;
PALETTE pal;
}GIF;


image is the picture, pal is the palette. 

Only want the image? simply do:
image = (BITMAP *)((GIF *)datafile[0].dat)->image;

And thats it! There you go!

1.6 Instructions for Animated GIFs
----------------------------------
Animated gifs are handled a little differently. To load an animated gif you call:

GIF_ANIM *load_gif_animated(const char *filename);

This returns the following structure:

typedef struct GIF_ANIM_STRUCT
{
GIF_FRAME *frames;
int num_frames;
char local_pal;
int timepassed;
....
}GIF_ANIM;

There are more variables, however the only ones you will commonly use are shown. num_frames is self explanatory.
local_pal holds 1 if each image uses a different palette, and otherwise is 0. timepassed if used, simply tells you how much time has gone through, or if it is 0 or a negative number tells you it is looping over.

Now frames is a linked list with all the gif images stored in it, the frames struct is as follows:

typedef struct GIF_FRAME_STRUCT
{
BITMAP *image;
PALETTE pal;
unsigned short int delay;
struct GIF_FRAME_STRUCT *next;
}GIF_FRAME;


The bitmap is stored as the current colour depth your are in,following colour conversion rules set by you and is not neccesarily in 8 bit. The palette is only included becuase the image itself is palette based, and under 8 bit mode, each image can have a different palette. It contains the palette for that image.

Now delay is how many 1/100 of a second that the gif recomends you wait between frames, and next points to the next image. Once next == NULL you are at the end of all the images. image should be self explanatory.

In order to delete this allocated memory, and avoid a leak, you may use this function:

void free_gifa(GIF_ANIM *gif_a);

which will free up the memory. 

Using it in a datafile is equally easy. Adding the following line:

register_datafile_object(DAT_GIFA, load_gif_anim_datafile, destroy_gif_anim_datafile);

Any datafile entry with "GIFA" will create a GIF_ANIM structure. Containing two fields, it is important to note a POINTER to the Structure is returned, rather than a structure. 


What happens if you want to load only a single frame on an animated gif? Use this function:
BITMAP *load_gif_animated_frame(const char *filename,RGB *pal,int frame);
Where frame starts at 1. If the frame number does not exist NULL will be returned.

Also for those who wish for more control, one can load an animated gif using a callback with this function:
int load_gif_animated_call(const char *filename, int(*callback)(GIF_FRAME *));
Remember that the gif frame will be deleted after, the callback, as will the palette within it, but the image will not be deleted. So you are responsible for later deleting the image, and copying the palette if you require it.


If you dont want to play with linked lists to get certain animated images here are a few helper funtions:

BITMAP * get_gifa_bitmapt(GIF_ANIM* ga,     int timepassed);
GIF_FRAME * get_gifa_framet(GIF_ANIM * ga,  int timepassed);
Simply pass the amount of time since the last draw, and the gif loader will calculate how much time has changed and return the correct image (with frameskip!). You may wish to check ga->timepassed, becuase if it is 0 or a negative number it means that the image is now repeating.


GIF_FRAME * get_gifa_framen(GIF_ANIM * ga,  int number);
BITMAP * get_gifa_bitmapn(GIF_ANIM * ga,    int number);
These both grab the specified frame number, the top returns a GIF_FRAM while the bottom only returns the image.


Happy animated gifing :)

1.7 Instructions For Memory Gifs
--------------------------------
I wont go into detail on how to use this, becuase chances are if your using these methods, you already know how it works. Heres the function list:

void *load_gif_animated_memory(void * fp);
BITMAP *load_gif_memory(void*, RGB *pal);          

The other routines do not have memory versions becuase im not conviced that these routines are really that usefull. If for some reason you require more feel free to add them :).

1.8 Instructions For Saving Gifs
---------------------------------
*****It is reccomended to set GIF_A_NOTRANS on gif_a_settings when saving gifs********


Although GIFAllegS supports saving both normal gifs and animated gifs, this was more an extra feature and not much work went into it. Also gifs have colour restriction of 8 bits which leads me to GifAllegS restrictions:

-Can Only Save 8 bit gifs(nothing lower)
-If you pass a 15/16/24/32 bitmap to be saved, it wont colour convert properly.

So for best results, you will have to convert the bitmap to 8 bits yourself, and then pass it to save_gif. If no palette is specified the default palette will be used.

Animated GIF saving is equally restrictive. Although technically it supports multiply bitmap sizes, saved gifs do not erase the background and draw all bitmaps in the top right corner. So youll most likely need to use all same sized bitmaps.

To save a animated gif, youll need to create a GIF_ANIM struct, filling in these fields:

typedef struct GIF_ANIM_STRUCT
{
GIF_FRAME *frames;
int frame_color;
int frame_width;
int frame_height;
....
}GIF_ANIM;

The other fields are not relevant to saving a Animated GIF, and are used for loading and displaying them.

Once these are filled, you can then point frames to a linked list of GIF_FRAMES and in the last field simply set it to NULL. In GIF_FRAMES, you will need to fill out these fields

typedef struct GIF_FRAME_STRUCT
{
BITMAP *image;
PALETTE pal;
unsigned short int delay;
struct GIF_FRAME_STRUCT *next;
}GIF_FRAME;

(All of them) make sure that in the last frame next is NULL to prevent crashing. pal will need to be set for each image, otherwise youll get a black rectangle instead of an animated gif.

2.0 Bugs
---------------------------------
I dont know of any. My codes Perfect.
Okay, I'm Lying again, theres probably a flaw here and
there, they just havent been found yet. So please, report any bugs you find to me!(Memory leaks, crashes, non working gifs etc)

3.0 Whats New
-------------
GIFAllegS 1.03 March 14, 2005
-----------------------------
+Fixed minor bug with misnamed inline macro, thanks to 
Frederic for reporting this.

GIFAllegS 1.02 Nov 21, 2004
-----------------------------
+Added support for (or rather, the ability to ignore) gifs with text and comments in them. Thanks to Chris Jones again for bringing this up.

GIFAllegS 1.01 Sept 21, 2004
-----------------------------
(A big thanks goes to Chris Jones for reporting these flaws)
+Fixed problem with gifs not loading in correct colour in high res modes
+Fixed incorrect save_gif Definition (RGB now a const parameter)
+Fixed save_gif palette bug.



GIFAllegS 1.00 August 20, 2004
----------------------------
+Save GIF funtion
+Save Animated GIF funtion
+Save Interlaced Images/Local Colour Tables/Transparency
+Fixed Load animated Gifs with Callback option added, currently not well thought out.
+Added more gif_a_settings options
+GIF_ANIM now tells wether each bitmap has a different palette
+Added some GIF_ANIM helper functions
+Now more then 2x faster then previous builds in loading gifs!

GIFAllegS 0.91
----------------------------
+Included Header File this time
+Fixed Bug where images greater then 256x256 wouldnt load properly
+Fixed 2Bit images 

GIFAllegS 0.9 July 15, 2004
-----------------------------
+Fixed Colour 0 as Trans Bug
+By Fixing above bug, most animated gifs display properly now
+Local Colour Tabled Gifs now load.
+Fixed Bug where non transparent animated gifs displayed incorrectly
+Load single frame of animated gif function added
+Animated Gifs supported with Datafiles
+Support for loading animated gifs from memory
+Add option to ignore background colour
-While able to load gif from callback, usage is not reccomended due to memory leaks

GIFAllegS 0.8BETA July 10,2004
------------------------------
+Added Support For Memory Gifs
+Added Support For Animated GIFS,Interlaced
+Lots of new functions

-Added Tons Of Warnings
-Doent Load Local Colour Tables animated gifs,crashes
-Not much Error Checking
-No Support For Animated gifs from Data Files
-Very Messy

GIFAllegS 0.45
--------------
+Fixed Tons of Warnings
+Code Looks Neater
+Actually Compiles Now
+Now GIF_DATA is used for internal work, GIF is returned and only contains two fields.
-Memory Code not included, although working, isn't safe, wont be shipped till version 0.5

GIFAllegS 0.4
-------------
+First Public Release of GIFAllegS

4.0 To Do List
--------------
Right now im pretty confident that gif allegs is done, and I wont be working on it, but there some thing that are still left to be added, so maybe in the future ill add them (probably not).

To Do's
-------
-Bug Fixes
-More Error Checking
-Library Support
-Grabber Plugin
-Debugging build



5.0 Contact, More Stuff
-----------------------
Thanks Goes to Mark Nelson, Paul Bartrum,Connelly Barnes, Steven H. Don, and Arturo San Emeterio Campos either for their code, or tutorials.

The Stars Website:
http://starsdev.cjb.net


Mirrors:
http://stars.hybd.net


I can be reached for comments, questions, bug reporting,or anything else at:
hard_rock_2@yahoo.com


Thank you.
Martin aka. Hard Rock