Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
A simple animation library for Allegro 4.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
= 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.