Allegro:Tutorials:Basics

From GPWiki

Basics of Allegro

The first thing you need to know about allegro is that your main sub should always look like this:

int main(int argc, char *argv[]) 
{
}
END_OF_MAIN()

You always must put END_OF_MAIN() right after your main function bracket.

Initializing Allegro

To initialize allegro you call allegro_init(). This function will return a Non-Zero number if it fails to intialize.

if (allegro_init()!=0) {//Failed to Init Allegro} 

To use the keyboard in your application, call install_keyboard(). This will return 0 on success or a negitive number if it fails.

if (install_keyboard()<0) {//Failed} 

To Initialize the allegro timer call install_timer(). This will return 0 on success or a negitive number if it fails.

if (install_timer()<0) {//Failed} 

Before you initialize the screen you can call set_color_depth(). This will set the color depth for the screen and any surfaces created after this call.

set_color_depth(16); //Vaild Depths - 8, 15, 16, 24, 32 

Once set_color_depth() is called. You then call set_gfx_mode to set the screen to what you want. Dont worry about Virtual Width and Height right now, just leave those to equal 0.

set_gfx_mode(Mode, width, height, virtual_width, virtual_height);

Graphics Modes:
GFX_AUTODETECT
GFX_AUTODETECT_FULLSCREEN
GFX_AUTODETECT_WINDOWED
GFX_SAFE

Set_gfx_mode() will return 0 on success or a negitive number if it fails. If set_gfx_mode() fails, it will store the error in allegro_error.

Allegro Provides you with a MessageBox Api, allegro_message(). You can only call this when set_gfx_mode is not set. So if you want to have allegro Display a MessageBox, then you must call set_gfx_mode(GFX_TEXT, 0, 0, 0, 0).

set_gfx_mode(GFX_TEXT, 0, 0, 0, 0);
allegro_message("Error setting graphics mode\n%s\n", allegro_error);

Allegro Bitmaps

With allegro, all the surfaces you need are stored as BITMAP. You can only load/use bitmaps after you call set_gfx_mode().

BITMAP *image;

Always declare it using *Variable. If you want to declare a Vector list of surfaces then...

vector<BITMAP *> Surfaces;

When ever you create a bitmap it's always best to remove it when you are done using it, or else it consumes memory.

destroy_bitmap(image);
 
vector<BITMAP *>::iterator b;
for( b = Surfaces.begin(); b != Surfaces.end(); b++ )
    destroy_bitmap( (*b) );
Surfaces.clear();

A BITMAP by default is a memory bitmap stored in system ram. You can specify a width and height with...

image=create_bitmap(Width, Height);

To load a bitmap from file you call load_bitmap():

PALETTE pal;
tBitmap=load_bitmap(Path.c_str(), pal);

You dont need to worry about pal, unless you're working with 8-bit bitmaps. The pal argument may be NULL. In this case, the palette data are simply not returned.

I'm not going to get into 8-bit bitmaps. I may later on make a tutorial on how to use them.

Drawing Bitmaps

void blit(BITMAP *source, BITMAP *dest, int source_x, int source_y, int dest_x, int dest_y, int width, int height); 
 
void masked_blit(BITMAP *source, BITMAP *dest, int source_x, int source_y, int dest_x, int dest_y, int width, int height); 
 
void draw_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y);

These functions allow you to draw BITMAPs to other BITMAPs or the screen. masked_blit() and draw_sprite() will draw bitmaps but with RGB(255,0,255) as the transparent color in truecolor modes, and palette index 0 in 8 bit mode. NOTE: There is no way to chance the transparent color unless you edit the allegro source code.

See the Allegro manual for more bitmap functions. (flipped/scaled/rotated/etc)

When you draw things to the screen, you first want to draw everything to a Buffer.

BITMAP *buffer;

buffer=create_bitmap(ScreenWidth, ScreenHeight);

Blit everything you want to be drawn to the buffer and then blit buffer to the screen.

blit(buffer, screen, 0, 0, 0, 0, SCREEN_W, SCREEN_H);

Keyboard

install_keyboard() needs to be called after allegro_init() if you want to use the keyboard.

You can check if a key is pressed by using the key[] array.

if( key[ KEY_SPACE ] )
    player->fire();

Mouse

install_mouse() needs to be called after allegro_init() if you want to use the mouse.

The position of the mouse can be found inside mouse_x and mouse_y. Check for pressed buttons with mouse_b

if( mouse_b & 1 )
{
    printf("The mouse is at %d,%d\n", mouse_x, mouse_y );
}

Using Allegro's Timer

Call install_timer() after allegro_init() to init the timer.

The way the timer in allegro works, is that you first need to declare a few varables.

unsigned char sticks=0;
unsigned char SecondTick=0;

After you call init_allegro and install_timer() you can then setup the timer.

LOCK_VARIABLE(sticks);
LOCK_FUNCTION(Seconds_Tick);
install_int_ex(&Seconds_Tick, SECS_TO_TIMER(1));

Seconds_Tick is a function which I will exaplain in a little bit.

What install_int_ex() is doing here. Its setting Seconds_Tick() to be called every second. If SECS_TO_TIMER() had a 2 rather then a 1, then it would call Seconds_Tick() every 2 seconds.

Theres also MSEC_TO_TIMER() which would call Seconds_Tick() everytime its been that ammount of Milliseconds.

Once you have all of that done, you then need to make a function above main().

void Seconds_Tick(void)
{
    sticks++;
}
END_OF_FUNCTION(Seconds_Tick);

Now your timer is done. Every Second it will pass into that function and do whatever is in there.

Added May 17, 2005