FAQ: MSVC++ allegro tutorial

Well, it's been a while, so I'll repost this. It is something I wrote by accident and it kind of turned into a tutorial. ;) Hope it helps:

>>

There's a few basics that kinda get skipped in most tuts, but can be gleaned from the documentation. I found this the hard way:

Typically speaking, you want to play sounds, set the video mode, and show pictures. At least to start. Here's how, with basic file formats (.bmp or .pcx etc and .wav or .mid etc).

First, you'll need some variables. For pictures, they are type BITMAP. I like to make a buffer bitmap to in memory that I then blit to the screen, because screen memory is slower than RAM memory. That way I just paste once to the video memory every cycle.

BITMAP *Buffer;

You'll also want a palette variable, just in case we were interested in color depths low enough to use palettes. (This is necessary for higher color depths only for compatibility with functions that handle both.. you'll see in a bit.)

PALETTE *Pal;

Next, you'll want to store you're sound file.

SOUND *SndFx;

Now in main you'll want to set some stuff up. First install Allegro.
allegro_init();

Next, you want to set the color depth for your video mode/window mode. Default is 8 bit. I like something a little bit higher, like true color 24 bit. 16 and 32 are your other choices. 32 allows for Alpha blending hardware acceleration, but otherwise is the same as 24. 24 bit color depth means each pixel has 24 bits to describe its color. That's 8 bits for every color. The average human eye can only see 256 shades of any given color, 256 being quite conveniently 8 bits.

set_color_depth(24); // where 24 is the color depth in bits.

Now we can set the video mode. Here's full screen, autodetect (Direct X accelerated by default, if possible).

set_gfx_mode(GFX_AUTODETECT, 800, 600, 0, 0);

The first two numbers are the resolution (800 by 600). The second two numbers are there for platform compatibility. They have no meaning in Windows. (In other OS's this determines how much extra video memory you have. In Windows you will have three video pages no matter what, which is to say in this case 800*3 by 600*3. More on that later.)

By default, your basic video screen page (the visible one) is known as the variable: screen

Just like we set up the video, now we set up the audio.
install_sound(DIGI_AUTODETECT, MIDI_AUTODETECT, 0);

The zero at the end is for compatibility sake again. Ignore. While we're at it, let's install the keyboard input handler as well. (All this setup stuff is so that you don't have to use Allegro's way for any one thing should you so desire not to.)

install_keyboard();

Now we're ready to throw a picture into the Buffer, then flush it onto the screen.

First load the file from disk into the Buffer:
Buffer = load_bitmap("MyPicture.bmp", Pal);

The load_bitmap function allocates all the memory for Buffer, so don't worry about that. (Also, remember that Pal variable from earlier? Here's where we use it. We can ignore it from now on, all it did was help make load_bmp() work for all color depths.)

Now, we'll flush that onto the screen. There are many ways to "blit" it there, but because I don't know how big your image file is, I'll use the simple draw_sprite function. In the documentation, look under "Blitting and sprites" for tons of more options (like scaling, rotating, etc). (Note that anything hot pink is transparent when using the draw_sprite function. That is red value 255, green value 0, and blue value 255.)

draw_sprite(screen, Buffer, 0, 0);

Now I've placed our buffer image (a bitmap or "sprite") at the top left corner of the screen. That's what the 0,0 means. In computer graphics, numbers go up the lower and more right they are. In geometry, the computer screen is represented by the fourth quadrant. This is not, however, the case when you start getting into 3D graphics, where the center of the screen is 0,0,0.

Now, let's play that sound. First load it, then play it.

SndFx = load_sample("MySound.wav"); // or .voc

play_sample(SndFx, 255, 128, 1000, 0);

play_sample's first parameter is the sound we want played. The second is the volume, a range from 0 to 255. In our case, we set the volume all the way up, which is actually pretty standard as this is the "wave" volume in Windows and is not usually very ear piercing. The next value is the "pan" range, or, the level of sound intensity of the left speaker compared to the right. The pan ranges from 0 (min/left) to 255 (max/right) and 128 will be balanced. Next is frequency, which is relative rather than absolute: 1000 represents the frequency that the sample was recorded at, 2000 is twice this, etc. Finally, there is a loop flag. If the loop flag is set, the sample will repeat until you call stop_sample(). Any of these values can be manipulated while the sound is playing by calling adjust_sample(), thus the train can pan from right to left, starting quiet, then getting loud, then trailing off again, changing its pitch ever so slightly with distance.

OK, demo over. Now we just want to pause until the user presses, say, the escape key.

textout(screen, font, "Press ESCape to quit.", 1, 1, makecol(255,255,255));

// Looping until the ESCape key is pressed.
while(! key[KEY_ESC]) ;

Textout() is pretty easy to get, the last parameter is a function that helps us make a color in any color depth easily. The parameters are red_value, green_value, blue_value from 0 to 255. 255,255,255 is white.

The while loop does literally nothing until the escape key is pressed, at which point it exits.

Finally, we must clean up. We deallocate all that memory we allocated, "shutdown" allegro thus restoring the video mode, and exit the program.

destroy_bitmap(Buffer);
destroy_sample(SndFx);
allegro_exit();
return 0;
} // End of main function.
END_OF_MAIN();

The END_OF_MAIN() function makes Allegro cross platform by getting rid of OS specific stuff like WinMain(). So, here is our final program.

PHP Code:

#include <allegro.h> // Create memory buffer and palette. BITMAP *Buffer; PALETTE *Pal; // Variable for the sound effect. SOUND *SndFx; int main() { // Initialize Allegro. allegro_init(); // Where 24 is the color depth in bits. set_color_depth(24); // Set the resolution to 640 by 480 with SAFE autodetection. set_gfx_mode(GFX_SAFE, 640, 480, 0, 0); // Setup the sound routines. install_sound(DIGI_AUTODETECT, MIDI_AUTODETECT, 0); // Installing the keyboard handler. install_keyboard(); // Load the picture from disk into the Buffer. Buffer = load_bitmap("MyPicture.bmp", Pal); // Draw or "flush" buffer onto the screen. draw_sprite(screen, Buffer, 0, 0); // Load and play the sound. SndFx = load_sample("MySound.wav"); // or .voc play_sample(SndFx, 255, 128, 1000, 0); // Pause program until escape pressed. textout(screen, font, "Press ESCape to quit.", 1, 1, makecol(255,255,255)); while(! key[KEY_ESC]) ; // Shut down and clean up. destroy_bitmap(Buffer); destroy_sample(SndFx); allegro_exit(); return 0; } // End of main function. // Some Allegro magic to deal with WinMain(). END_OF_MAIN();

As a final note, there is no error checking in that program. If, for instance, the bitmap or wav files don't exist, the program will simply shut down and not work. This could easily be avoided, but I will leave it to you to make the necessary modifications.

Hopefully this is enough to really get you going. From here, the documentation located in the Allegro\docs directory (double clidk allegro.htm) should be enough to fill in most of the blanks.

So sorry this was kind of a long post, but I hope it helps you out. If you have any questions, feel free to ask.

<<

I replied again with a tutorial on double buffer animation (flicker free) later on in the original post located here, should you be interested. :p

For anything else, you should be able to find some nice tutorials at www.allegro.cc You may also want to check out the "pixelate" section.

-Justin