Topic : Allegro Tutorial
Author : Gillius
Page : 1 Next >>
Go to page :

Allegro Tutorial

This tutorial requires an understanding of C, provided in the previous tutorial. This teaches the beginnings of using the Allegro library. Once a basic understanding is achieved, using the library is as simple as reading the library docs, which is what I learned from, and learned very well. Allegro is one of the best documented libs I have ever seen. And it is for this reason that this tutorial will be fairly short. The real learning will come from the next tutorial on how to use Allegro in a game.

How is this more than restating the manual? Well basically a lot of areas are pieced together where they need to be. The bulk of new info comes from the Learning Allegro section, which basically are random tips of what to learn, and things I don't feel the documentation covers well or points out.

This tutorial applies to the latest Allegro 4.0.0.

The latest Allegro library needs to be installed, and can be found at:

Starting Allegro
First thing is to include the header file:

#include <allegro.h>
Before doing anything with Allegro, you must initalize it:


Before initializing other functions, it is best to setup the current .CFG file, which is created by Allegro's included setup program, or by your program. It defaults to allegro.cfg, but if you want to change it to the name of your application/game, use this command:


If you want timing functions, or use the mouse/music/movies/etc which require the timing functions, install the timer. This is very important to keep your program running the same speed on all computers.


Next if you want to install the keyboard, do so now:


While Allegro has the keyboard, none of the C library commands will work on the keyboard.

Next step is installing the mouse, if needed, returns 0 on error (no buttons):

int buttons = install_mouse();

This returns the number of buttons on the mouse. The left button is #0, right is #1, and middle button is #2. This is important when detecting which button is pressed.

If you want the joystick, install it (returns non-zero on error):

if (install_joystick(JOY_TYPE_AUTODETECT)) {
  allegro_message("Joystick Error: %s", allegro_error);
  return 1; //exit to DOS

All of the different joysticks are listed in the Allegro docs, but autodetect will pull info from the .CFG file if loaded, or it will pick a generic joystick type. Allegro_error is a global char* which contains an error message from most functions when they give an error.

If you want sound drivers, install them now:

  allegro_message("Sound Error: %s", allegro_error);
  return 1;

If you don't want sound or MIDI music, replace the driver name with DIGI_NONE or MIDI_NONE, respectively. The NULL parameter refers to a char*, which was an old feature in Allegro, and is only there for compatability now. Nothing you put in there will have any effect. At this time you may also wish to set the volume levels, which could come from the .CFG file (this discussed later in the tutorial):

set_volume(255, 255); //digital and music to max levels

The last thing you do is initialize graphics. This is because the other functions will output text mode errors, which cannot be displayed in graphics mode. Another good reason for this is that if a problem occurs, video is most likely the incompatable part.

The first thing to do is set the color depth, and the screen size. I strongly recommend that the screen size be placed in constants in alleg.h or some global include file -- this has the advantage of being able to change these 2 constants and never having to change any code, and the application will adjust, if you base all your calculations on these constants, so you can have on-the-fly resolution changes.

set_color_depth(8); //256 color mode (8 bits mode)
//in a global file, scrx is: const int scrx = 640;
//in a global file, scry is: const int srcy = 480;
if (set_gfx_mode(GFX_AUTODETECT, scrx, scry, 0, 0) {
  printf("Video Error: %s", allegro_error); //screen would still be in text mode on error
  return 1;

You could also support multiple screen modes (for example if a card didn't support a certain resolution or color depth) by nesting if statements like the one above, to test all acceptable modes.

Now Allegro is set up and ready to go. Remember to add the line END_OF_MAIN() right after your main functions ending brace.

The Allegro documentation is written so well that it would be hopelessly redundant trying to write a tutorial for all of its hundreds of functions. So basically this section here is some Allegro tips on where to start playing around with Allegro and what methods I found to be good, and what I found that sucked. More advanced issues working with Allegro are in the game tutorial.

The first thing to do for learning Allegro is getting some cool graphics and musics off the net to play around with. Then try making a few small projects with Allegro, such as:

A ball screensaver project -- create a bouncing ball, start with a drawn circle, then move to a .bmp file of a better ball (perhaps a beach ball) and bounce that. If you want to expand the project some more, have a MIDI file play in the background, or have a sound effect (.wav file) when the ball hits the sides. If you want to get really fancy, add in some keyboard controls and gravity to the ball and let the user "nudge" the ball in directions, using geometric vectors, sin and cos to calculate the position.

Allegro Tips
A few random raves that the Allegro docs don't cover, plus what to waste your time on, and what to certainly not even try. . .

I see sooooo many Allegro programmers not using these features and they are the best in there, espically from a user point of view. Use datafiles whenever you can. There is nothing more annoying to me than having 100s of little .BMP files taking up valuable slack space on the hard drive, slowing it down. Datafiles are compressed and can knock those .BMPs to 1/4 of their size! Plus it's a lot faster to program since they load into an array -- no need to type in all the filenames into load_bitmap()!

Also on this issue, use the packfile functions to read and save everything you do (with the exception of .CFG files of course.) They take no time to learn since they perfectly emulate the C-style file functions, and give all the benefits of compressed data.

Although this is a very controversial subject in today's Pentium II and Pentium III world, fixed numbers might be something to consider when using them in a game, where floating accuracy is not needed. This has the advantage of using integer math. If you ever plan to run your game on a 486, definately use these, and also fixed point is very friendly to old (pre-Athlon)AMD and Cyrix processors. On the latest processors, though, double precision floating point variables were tested to be faster than fixed point (see fixtest.cpp for the test results). Also Allegro fixed point trig is fairly inaccurate and is noticeable over a distance of more than 200 pixels or so. I recommend using double type variables if you are planning on running the program on "today's" computers.

I've never used the 3D routines on Allegro. I would think you would be wasting your time. If you really want to do 3D, move to Windows and do Direct3D and OpenGL. The only good reason I could see for doing this would be to make some simple 3D rotating logo perhaps on the title screen or something small like that. I wouldn't base an application off the 3D functions. I suggest the Allegro GL library which you can find on as a library extension.

I would say the same thing about GUI. If you look at the GUI in my Project V2143 game, you will see that it looks nice, but I will warn you that I've spend literally 3x as much time on that GUI as I did on the game. I could probably do it in Windows in 1/4 of the time. If you want a GUI-heavy application, use Windows. It's not worth the trouble. I really should have made the map editor in Windows. . . Learn from my mistake.

RLE sprites and compiled sprites are usually not worth the trouble, since their speed boost is exteremely small. This boost may increase on lower class machines, but I haven't seen any yet.

Read the FAQ on making screenshots. For some reason I've seen a lot of Allegro programmers saying they can't do screenshots yet. It's just a simple one-line statement that works anywhere anytime:

save_bitmap("screen.pcx", BUFFER, pal);

Where BUFFER is the BITMAP* to your double buffer, and pal is the current pallete (use a dummy pallette if in truecolor mode.) Even if you aren't double buffering you can still save the screen.

And by the way, a final note about the BUFFER. Usually you don't

Page : 1 Next >>