= al4anim =

al4anim is a simple animation library for Allegro 4.
Copyright (C) 2010 Brandon McCaig

This file is part of al4anim.

al4anim is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

al4anim is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with al4anim.  If not, see <http://www.gnu.org/licenses/>.


== Introduction ==

al4anim was initially written by Brandon McCaig in response to a request
for help on http://www.allegro.cc. He decided to turn it into a library
in case it could be useful to himself or others later.

== Build Instructions ==

al4anim was originally written and tested in GNU/Linux. The Makefile
should work for most similar environments, particularly unices. There are
no directions to build for Windows at this time, though it should suffice
to bake the source directly into your project if you must.

Using GNU build tools, you should be able to build the code by running
make.

$ make

al4anim can be built into a shared or static library (or both). The
default will be to build both. You can choose either or by specifying
'dynamic' or 'static' as the target instead of 'library'.

$ make dynamic
$ make static

You can build the example program by specifying the 'example' target.
Alternatively, you can specify the 'all' target, which will attempt to
build everything.

$ make all

== Installing The Library ==

You need to copy include/a4a_animation.h and lib/libal4anim.a into paths
where your compiler expects them. In GNU/Linux, a good candidate is into
/usr, such as /usr/include and /usr/lib. Another candiate is /usr/local,
such as /usr/local/include and /usr/local/lib. Not all distributions
configure ld to search /usr/local, however, so you may need to add an
entry to /etc/ld.so.conf[.d] and run `ldconfig` as root to update the
cache.

Alternatively, you can use the shell environment by setting CPATH to
al4anim's include directory (where a4a_animation.h is) and LD_LIBRARY_PATH
to al4anim's lib directory (where libal4anim.a is). You can also just pass
the necessary arguments to your compiler. For example, with gcc, you can
pass -I/path/to/al4anim/include and -L/path/to/al4anim/lib. Which option
you choose will largely depend on your system configuration and your
privileges on it.

There is now a rudimentary 'install' target in the Makefile, but it's
certainly use-at-own-risk. :P It will attempt to copy the librar(y/ies) to
PREFIX/lib. The default for PREFIX is /usr because that just happens to
work out on my system. /usr/local could also work, but at least on Fedora
it seems you have to manually add /usr/local to /etc/ld.so.conf.d and it
seems that using /usr instead as a default should just work. It might not
be best practice though. If you want something else, specify it to make:

$ make install

# OR

$ make PREFIX=/usr/local install

The 'install' target also tries to run ldconfig to update the linker
cache. You will need root privileges to run this (as you will to install
into /usr or /usr/local) so you'll need to elevate privileges to do this.
Again, use at own risk. :) I entirely encourage you to manually install
if you're comfortable doing so.

== Uninstalling ==

To uninstall, you basically have to undo the things that you had to do to
install. Remove the header file(s) and library files(s) from whereever
they were copied. The default for the Makefile is to /usr/include and
/usr/lib. There is a 'distclean' target in the Makefile that will attempt
to remove these for you (will need privilege escalation for the default
PREFIX, but you can change the prefix the same as you did with the
'install' target.

$ make distclean

# OR

$ make PREFIX=/usr/local distclean

== Using The Library ==

Once al4anim is properly installed on your system, you can use the
library! You will need to include a4a_animation.h in any header or source
files that reference al4anim's data types or subroutines. You will also
need to link to al4anim. With gcc, you can do that with the -l option:
-lal4anim.

For example, using gcc, your command line might be something like:

gcc -o game `allegro-config --libs` -lal4anim

If you wish to use al4anim with PNG files then you will need a few more
libraries as dependencies.

* loadpng
* libpng
* zlib

Your command line with gcc might then look like:

gcc -o game `allegro-config --libs` -lal4anim -lldpng -lpng -lz

The order of libraries matters. Apparently you should keep them at the end
of the command line. I can't say for sure, but it seems to work for me.
Take a look at the Makefile to see the command(s) that work for me.

== I Can't Get It Installed; Can I Still Use It? ==

Probably, yes. You can just copy include/a4a_animation.h and
src/a4a_animation.c into your own project and build them as if they were
part of your project all along.

== Example Program ==

The example program was written using sprites that were attached by the
OP to the thread on http://www.allegro.cc. Since we don't know about the
ownership or licensing of those files they are not distributed as part of
al4anim. If you wish to run the example program then you will need to
retreive those files from http://www.allegro.cc:

http://www.allegro.cc/forums/thread/605346/886764#target

Those files should be placed in a 'media' directory.

If you don't want to (or can't) retreive those files then you should be
able to use any animation files that you want. Just modify src/main.c to
use your own files instead of the originals.

== API ==

All symbols are prefixed with a4a_, meaning Allegro 4 Animation library.

a4a_animation_t * a4a_animation_create(
        a4a_sprite_type_t,
        int,
        int,
        ...)
a4a_animation_t * a4a_animation_createa(
        a4a_sprite_type_t,
        int,
        int,
        char * [])
a4a_animation_t * a4a_animation_createb(
        int,
        int,
        int,
        BITMAP * [])
a4a_animation_t * a4a_animation_createf(
        a4a_sprite_type_t,
        int,
        int,
        const char *)
a4a_animation_t * a4a_animation_createv(
        a4a_sprite_type_t,
        int,
        int,
        va_list)

    Creates a new animation, loading the respective frames. Returns a
    pointer to an a4a_animation_t. The first three arguments are the same
    for all except for *createb: the type of animation (specifies the
    source image type using an a4a_sprite_type_t enumeration), the
    frame rate in ticks, and the number of frames. The forth argument
    specifies the frame image filenames.
    
    The default accepts a variable number of C strings. The 'a' version
    accepts an array of C strings instead. The 'f' version accepts a
    printf-style format string. A single data argument is passed to
    snprintf, the frame number in the set (i+1). The 'v' version accepts a
    va_list.
    
    The 'b' version is rather different in that it doesn't load the
    bitmaps for you, but expects you to pass an array of pre-loaded bitmap
    pointers. The first argument is the frame rate in ticks, the second is
    the number of frames, the third is an integer boolean indicating
    whether or not the bitmaps are owned by the animation, and the last
    argument is a pointer to an array of bitmap pointers. :) The array of
    bitmaps is duplicated up to num_frames in length (so a stack array can
    be used), but the bitmap pointers themselves are copied. This means
    that if you destroy the original bitmaps then the animation bitmaps
    will become invalid, so you shouldn't destroy the bitmaps until after
    you've destroyed the animation. If the 'own_frames' parameter is
    non-zero (boolean true) then the animation will itself destroy the
    bitmaps when it is destroyed (so you should not destroy them yourself,
    nor should you use them after the animation is destroyed).

void a4a_animation_destroy(a4a_animation_t **)

    Destroys an animation that was created with a4a_animation_create*.
    This frees the memory used for the frame images and for the structure
    itself. Expects a pointer to a pointer to an a4a_animation_t. After
    freeing the memory it sets the pointer to the animation to 0 (NULL).

BITMAP * a4a_animation_begin(a4a_animation_t *, int)

    The first argument is a pointer to the animation to begin. The
    second argument is the total tick count in the application so far
    (given by an Allegro timer). The tick count is stored for future
    reference. Returns the first frame in the animation as an Allegro
    BITMAP pointer.

BITMAP * a4a_animation_frame(a4a_animation_t *, int)

    The first argument is a pointer to the animation. The second argument
    is the total tick count for the application so far (given by an
    Allegro timer). The tick count is used as an offset from the starting
    time given with a4a_animation_begin. The current frame based on this
    offset is returned as an Allegro BITMAP pointer.

== Getting Updates, Reporting Bugs, Contributing, Providing Feedback ==

al4anim is offically hosted on GitHub:

http://github.com/bamccaig/al4anim

You can clone the repository using Git to get the updated source code.
You can use the GitHub Web site to search for more information, look for
bugs or issues, report bugs or issues, or contribute your own code.