Allegro Quick Reference

Allegro Quick Reference

Public domain. Version 2005-12-17.

Translated to Japanese by Ohsawa Hirotaka.

General
Graphics
Bitmap Commands
Video Modes
Double-Buffering
Colors
Timers
Text Output
Keyboard Input
Mouse Input
Sound Output
Collision Detection
Translucency
Angles and Math
Examples
Technical Information


  putpixel   (bmp, x, y, color)
  getpixel   (bmp, x, y, color)
  line       (bmp, x1, y1, x2, y2, color)
  triangle   (bmp, x1, y1, x2, y2, x3, y3, color)
  polygon    (bmp, sides, vertex[sides * 2], color)
  rect       (bmp, x1, y1, x2, y2, color)
  rectfill   (bmp, x1, y1, x2, y2, color)
  circle     (bmp, x, y, radius, color)
  circlefill (bmp, x, y, radius, color)
  ellipse    (bmp, x, y, xradius, yradius, color)
  ellipsefill(bmp, x, y, xradius, yradius, color)
  arc        (bmp, x, y, angle1, angle2, radius, color)
  floodfill  (bmp, x, y, color)

All graphics commands take integer arguments. See the sections on

Angles

Colors

3. Bitmap Commands:


  BITMAP *bmp;
  bmp = create_bitmap(width, height)
  bmp = load_bitmap("filename.bmp|pcx|tga|lbm", 0)
  destroy_bitmap(bmp)
  clear(bmp)
  clear_to_color(bmp, color)
  draw_sprite(bmp, sprite, x, y)
  draw_sprite_v_flip(bmp, sprite, x, y)
  draw_sprite_h_flip(bmp, sprite, x, y)
  draw_sprite_vh_flip(bmp, sprite, x, y)
  rotate_sprite(bmp, sprite, x, y, angle)
  stretch_sprite(bmp, sprite, x, y, spritew, spriteh)
  blit(source_bmp, dest_bmp, xsrc, ysrc, xdest, ydest, width, height)
  stretch_blit(src, dest, xsrc, ysrc, srcw, srch, xdest, ydest, destw, desth)

Pronounce the first variable as "bitmap pointer to bmp". A bitmap pointer is simply a reference to some memory which has been created dynamically. Bitmap dimensions can be determined through 'bmp->w' and 'bmp->h'.

Make sure the video mode is set up before calling any of the bitmap functions, or your bitmap will be in the wrong color depth. The operating system will automatically reclaim an application's memory on exit, so you do not necessarily need to call destroy_bitmap(...) on every bitmap that has been created or loaded. However, it is very important that you call destroy_bitmap(...) on temporary bitmaps created within procedures, or else your application will run out of memory and die a painful death.

Bitmaps created with create_bitmap(...) will initially contain random pixels. If you don't want the user to be looking at randomly colored pixels, then the bitmap should be cleared before drawing commands are used with it.

Draw_sprite draws a sprite bitmap onto a larger bitmap, typically the screen or a buffer. To make part of a sprite transparent, the special "mask color" can be used. In truecolor modes, the mask color is RGB(255, 0, 255) - or maximum red and blue, zero green. In 8-bit mode, the mask color is color 0. Both draw_sprite and rotate_sprite draw the sprite with (x, y) as the upper left coordinate. To have a sprite revolve around its center, rather than the upper-left, use the following formula:

    rotate_sprite(bmp, sprite, x-sprite->w/2, y-sprite->h/2, angle)

Blit is an image-copying function that stands for "BLock Image Transfer". The parameters are fairly straightforward: it copies a rectangle of pixels from somewhere on a source bitmap to a different location on a destination bitmap. Stretch_blit allows for the source and destination rectangles to be of different sizes, which produces a stretching effect.

You may also wish to make an intermediate loading function which will quit with an error if a bitmap is not found:

  BITMAP *load_image(char *filename) {
    BITMAP *result = load_bitmap(filename, 0);
    if (!result) {
      set_gfx_mode(GFX_TEXT, 0, 0, 0, 0);
      printf("Could not load resource: %s\n", filename);
      exit(0);
    }
    return result;
  }

The C++ stream 'cout' could be used in place of printf(...), but printf is good practice for the Allegro text output commands, which take the same formatting strings as printf. See Section

'Text Output'

'Colors'

4. Video Modes:


 set_color_depth(depth)
 set_gfx_mode(GFX_AUTODETECT|GFX_AUTODETECT_WINDOWED, screen_width, screen_height, 0, 0);


 int scr_width = 640, scr_height = 480;

 int depth_select(int depth) {
   set_color_depth(depth);
   return set_gfx_mode(GFX_AUTODETECT, scr_width, scr_height, 0, 0) == 0;
 }

 int main() {
   allegro_init();
   depth_select(32) || depth_select(24) || depth_select(16) || depth_select(15); 
 }

5. Double Buffering:

Drawing directly to the screen invariably results in flicker. Due to the undesirable nature of flicker, programmers historically developed complicated methods of erasing old pixels while simultaneously drawing new pixels to the screen. Today, those methods are both inefficient (in terms of code complexity) and counter-intuitive. Double-buffering solves all these problems, and makes the act of erasing old images a thing of the past.

Double Buffering Method:

    Create a bitmap which is not visible, but is the same size as the screen. This is called the "back buffer".
    Do
        Clear the back buffer.
        Draw all graphics to the back buffer.
        Copy the back buffer to the screen (or the "front buffer").
    Repeat until the program is ended.

Using the double buffer method, all graphics are always redrawn to the newly cleared buffer, during every single frame. So there is a fundamental change from the QBASIC-style of program that would draw the background to the screen, forget about the background, and move objects around, restoring the background colors as the objects move. In the double-buffered rendering method, the background is ALWAYS copied entirely to the buffer, all objects are then drawn to the buffer, and the final resulting image is copied to the screen.

When used for rendering anything other than 3d graphics, the double buffer method often ends up being faster than drawing directly to the screen, because memory bitmaps can be accessed faster than video bitmaps.

Double-buffering with a black background:


 init_all();      /* choose a video mode and install keyboard */ 
 BITMAP *buffer = create_bitmap(scr_width, scr_height);
 while (!key[KEY_ESC]) {
   clear(buffer);
   /* ...draw all objects... */
   blit(buffer, screen, 0, 0, 0, 0, buffer->w, buffer->h);
 }

Double-buffering with a full-screen bitmapped background:


 init_all();      /* choose a video mode and install keyboard */
 BITMAP *buffer = create_bitmap(scr_width, scr_height);
 BITMAP *background = load_bitmap("background.bmp", 0);
 while (!key[KEY_ESC]) {
   blit(background, buffer, 0, 0, 0, 0, background->w, background->h);
   /* ...draw all objects... */
   blit(buffer, screen, 0, 0, 0, 0, buffer->w, buffer->h);
 }

For information on how Allegro's keyboard input routines work, see the section

'Keyboard Input'

6. Colors:


 makecol(red, green, blue)
 getr(color)
 getg(color)
 getb(color)
 hsv_to_rgb(hue, sat, lum, &r, &g, &b)
 rgb_to_hsv(r, g, b, &hue, &sat, &lum) 
 bitmap_mask_color(bmp)


 black       = makecol( 0,   0,   0   ) =  0 
 grey        = makecol( 128, 128, 128 )
 white       = makecol( 255, 255, 255 )
 red         = makecol( 255, 0,   0   )
 green       = makecol( 0,   255, 0   )
 blue        = makecol( 0,   0,   255 )
 yellow      = makecol( 255, 255, 0   )
 orange      = makecol( 255, 128, 0   )
 cyan        = makecol( 0,   255, 255 )
 purple      = makecol( 255, 0,   255 )
 light blue  = makecol( 128, 128, 255 )
 pink        = makecol( 255, 128, 128 )
 light green = makecol( 128, 255, 128 )
 dark purple = makecol( 128, 0,   128 )


 for (int y = 0; y < image->h; y++) {
   for (int x = 0; x < image->w; x++) {
     int color = getpixel(image, x, y);
     int r = getr(color) + 100;
     int g = getg(color) + 100;
     int b = getb(color) + 100;
     if (r > 255) { r = 255; }
     if (g > 255) { g = 255; }
     if (b > 255) { b = 255; }
     putpixel(image, x, y, makecol(r, g, b)); 
   }
 }

7. Timers:


 volatile double elapsed_time = 0;
 void __inc_elapsed_time() { elapsed_time += .001; }
 END_OF_FUNCTION(__inc_elapsed_time);

 int main() {
   allegro_init();
   install_timer();

   LOCK_VARIABLE(elapsed_time);
   LOCK_FUNCTION(__inc_elapsed_time);
   install_int_ex(__inc_elapsed_time, BPS_TO_TIMER(1000)); 
   return 0;
 }

 END_OF_MAIN();

Somewhat cumbersome, but the above code gives a timer accurate to a couple milliseconds. Just check elapsed_time for the floating-point time in seconds. BPS_TO_TIMER(1000) means to make a timer function that runs 1000 times per second, and .001 is the reciprocal of 1000. Note that timers of higher resolutions are not worth making, because Windows will cause the time to be rounded off to the nearest 5 milliseconds, regardless of how fast you try to make a timer.

A more advanced way of tracking time can often be useful for games: declare the global variables 'last_time' and 'dt' as floating-point values. Each pass through the main game-logic loop, compute 'dt' as the difference of elapsed_time and last_time, and then set last_time to elapsed_time. Then, objects can be moved at a constant speed regardless of processor speed by adding velocity times dt to the current object position:

     x += 100 * dt;

Where 100 is the velocity in pixels/second.

If 'dt' is consistantly used for moving objects, then taking a program like

exbounce.cpp

8. Text Output:


 textprintf_ex(bmp, font, x, y, color, -1, string, ...)
 textprintf_centre_ex(bmp, font, x, y, color, -1, string, ...) 
 textprintf_right_ex(bmp, font, x, y, color, -1, string, ...)

%f	- print a float value
%i	- print an integer value
%.2f	- print a float value with 2 digits after the decimal
%4.2f	- print a float value with 4 digits before the decimal and two after
%04i	- print an integer with 4 digits before the decimal
%s	- print a string (from a character pointer)


 int ival = 10;
 double fval = 15.1;
 char *str = "Hello World";
 textprintf(bmp, font, 0, 0, makecol(255, 0, 0), "Red Text");
 int white = makecol(255, 255, 255);
 textprintf_centre(bmp, font, scr_width/2, scr_height/2, white, "Centered");
 textprintf(bmp, font, 0, 10, white, "An integer: %i", 10);
 textprintf(bmp, font, 0, 20, white, "Integer padded with zeros: %03i", ival);
 textprintf(bmp, font, 0, 30, white, "A float: %f", fval);
 textprintf(bmp, font, 0, 40, white, "2 digits after decimal: %.2f", 23.2134);
 textprintf(bmp, font, 0, 50, white, "A string: %s", str);

9. Keyboard Input:


 install_keyboard() 
 int keypressed()
 int readkey()
 key[]

    char ch = readkey() % 256;


 if (key[KEY_LEFT]) { /* do something if left arrow is held */ }
 if (!key[KEY_ENTER]) { /* do something if enter is not held */ }


 KEY_A     -    KEY_Z
 KEY_0     -    KEY_9
 KEY_F1    -    KEY_F12

 KEY_ESC        KEY_MINUS      KEY_ENTER      KEY_EQUALS     KEY_TAB
 KEY_BACKSPACE  KEY_OPENBRACE  KEY_CLOSEBRACE KEY_LCONTROL   KEY_RCONTROL
 KEY_COLON      KEY_TILDE      KEY_QUOTE      KEY_LSHIFT     KEY_RSHIFT
 KEY_BACKSLASH  KEY_COMMA      KEY_STOP       KEY_SLASH      KEY_ASTERISK
 KEY_ALT        KEY_SPACE      KEY_CAPSLOCK   KEY_NUMLOCK    KEY_SCRLOCK
 KEY_HOME       KEY_END        KEY_PGUP       KEY_PGDN       KEY_MINUS_PAD 
 KEY_MENU       KEY_PLUS_PAD   KEY_INSERT     KEY_DEL        KEY_PRTSCR
 KEY_UP         KEY_DOWN       KEY_RIGHT      KEY_LEFT       KEY_PAUSE

10. Mouse Input:


 install_mouse()
 mouse_x
 mouse_y
 mouse_b
 set_mouse_speed(xspeed, yspeed)


 if (mouse_b) { /* any mouse button is pressed */ }
 if (mouse_b & 1) { /* left mouse button is held */ }
 if (mouse_b & 2) { /* right mouse button is held */ }
 if (mouse_b & 4) { /* center mouse button is held */ }


 BITMAP *cursor = load_bitmap("cursor.bmp", 0);
 while (!key[KEY_ESC]) {
   clear(buffer);
   draw_sprite(buffer, cursor, mouse_x, mouse_y);
   blit(buffer, screen, 0, 0, 0, 0, buffer->w, buffer->h); 
 }


 int mouse_clicked, last_button, current_button=0;
 while (not exited) {
   last_button = current_button;
   current_button = mouse_b;
   mouse_clicked = (current_button && !last_button);
   if (mouse_clicked) {
     /* happens once per click as mouse is pressed down */
   }
   /* more code */
 }

11. Sound Output:


 install_sound(DIGI_AUTODETECT, MIDI_AUTODETECT, 0) 
 SAMPLE *sample = load_sample("filename.wav|voc")
 play_sample(sample, volume, pan, frequency, loop)
 stop_sample(sample)
 destroy_sample(sample)
 MIDI *midi = load_midi("filename.mid")
 play_midi(midi, loop)
 destroy_midi(midi)
 set_volume(sample_volume, midi_volume)

1. Not work.
2. Sound horrible.

12. Collision Detection:


 Pseudo-code for collision-detection routine:

 For every object in the game
   For every other object
     Check if first object collides with second
     If so, process the collision:
        first.collide_event(second)
        second.collide_event(first)
     End If
   Next
 Next

The simplest form of collision detection can be done by treating every object in the game as a rectangle and checking if any rectangles collide.

Two rectangles of coordinates (xmin1, ymin1)-(xmax1, ymax1) and (xmin2, ymin2)-(xmax2, ymax2) are overlapping if the following is true:


 if (xmin1 < xmax2 && ymin1 < ymax2 && xmin2 < xmax1 && ymin2 < ymax1) { 
   /* objects collided */
 }

This condition works in three dimensions as well, and the rule for remembering it is: "The mins are less than the maxes". If any minimum value for one rectangle is less than the other rectangle's maximum value for the same dimension, then the two rectangles collided. This equation can be derived by considering the coordinates of the overlapping region of the two rectangles.

Normally, the coordinate minimums and maximums are computed inside a check_collide(a, b) type routine, and are based on the sprite's width and height. That function would presumably return either true or false, depending on whether the two sprites collide.

The rectangle-bounded collision detection often works very well; try it before giving up and using guess-math to determine if, say two Mortal Kombat style fighters are in contact. However, if two sprites contain great amounts of empty space, then collisions can occur when they shouldn't; a player's missiles explode without actually touching a boss, a player skims close to an enemy and finds his ship has been annihilated because he moved through the enemy's bounding box. If these sorts of things become too obvious, then another bounding shape is called for. In 2D, checking whether individual pixels actually overlap is quite fast. This is called "pixel-perfect" collision and is demonstrated in

experfect.cpp

13. Translucency:


 set_trans_blender(0, 0, 0, opacity)
 draw_trans_sprite(bmp, sprite, x, y)
 drawing_mode(DRAW_MODE_TRANS, 0, 0, 0) 
   /* ...any graphics commands... */
 drawing_mode(DRAW_MODE_SOLID, 0, 0, 0)

 /* Other useful blenders are:
    set_add_blender(0, 0, 0, opacity) - lightening effect, useful for particles. 
    set_multiply_blender(0, 0, 0, 255) - multiply, often used for lightmaps. */

Set_trans_blender should always be called before drawing translucent graphics. Opacity is an integer value from 0...255 representing the solidity of the drawn object. Normal graphics commands (those in the

'Graphics'


 set_trans_blender(0, 0, 0, 128);
 drawing_mode(DRAW_MODE_TRANS, 0, 0, 0);
 circlefill(buffer, 160, 100, 80, makecol(0, 255, 0));
 circlefill(buffer, 220, 200, 80, makecol(0, 255, 255));
 circlefill(buffer, 100, 200, 80, makecol(0, 0, 255));
 drawing_mode(DRAW_MODE_SOLID, 0, 0, 0);

14. Angles and Math:


 #include <math.h>
 #define DEGREES(x) int((x)/360.0*0xFFFFFF)
 #define RADIANS(x) int((x)/2/M_PI*0xFFFFFF)


 arc(bmp, x, y, DEGREES(45), DEGREES(180), radius, color);
   - or -
 arc(bmp, x, y, RADIANS(M_PI/4), RADIANS(M_PI), radius, color);


 #include <math.h>
 double angle = atan2(y2-y1, x2-x1);


 #include <math.h>
 double x = cos(angle) * radius;
 double y = sin(angle) * radius;

15. Examples:

Example programs are provided with Allegro. Additional examples are also available with this quick reference (

download examples

exbitmap.cpp:  Truecolor bitmaps and double buffering example.
exbounce.cpp:  Double buffering with moving sprites example.
exmag.cpp:     Magnification effect, uses 8-bit (palettized) color. 
exmouse.cpp:   Detecting mouse input and drawing mouse sprite.
experfect.cpp: Pixel-perfect collision.
expixel.cpp:   Double-buffering and getpixel()/putpixel().
explasma.cpp:  Panning background example with double buffering.
exrotate.cpp:  Rotating sprite with double buffering.
exshade.cpp:   2D polygon rendering via polygon3d_f(...).
extext.cpp:    Time routines and text output.
extrans.cpp:   Translucency via draw_trans_sprite().

16. Technical Information:

Allegro is available:

http://www.talula.demon.co.uk/allegro

http://www.delorie.com/djgpp

http://www.mingw.org/

 % cd allegro
 % fix mingw32
 % set MINGDIR=(Full path to Mingw installation) 
 % make
 % make install

 g++ source_file[s].cpp -o out.exe -O3 -Wall -lalleg -s