Available Allegro examples

ex12bit — How to fake a 12-bit truecolor mode on an 8-bit card.
ex3buf — Mode-X triple buffering and retrace interrupt simulation.
ex3d — 3d 'bouncy cubes' demo.
exaccel — Using offscreen video memory to store source graphics for VBE/AF.
exalpha — Creating and using 32 bit RGBA sprites.
exbitmap — Loading and displaying PCX and BMP files.
exblend — Using translucency in truecolor modes.
excamera — Viewing a 3d world from an arbitrary camera position.
excolmap — Creating graphical effects with color mapping tables.
exconfig — Using the configuration routines.
excustom — Creating custom GUI objects.
exdata — Accessing the contents of datafiles.
exdbuf — How to use double buffering to avoid flicker.
exexedat — Appending datafiles onto your executable.
exfixed — Using fixed point maths.
exflame — How to write directly to video memory improving performance.
exflip — Comparison of double buffering and page flipping.
exfont — Loading and manipulating fonts.
exgui — Using the GUI routines.
exhello — Simple graphical "hello world" program.
exjoy — Detecting, calibrating and using joystick input.
exkeys — How to get input from the keyboard in different ways.
exlights — One way to do colored lighting effects in a hicolor video mode.
exmem — Drawing onto memory bitmaps and then blitting them to the screen.
exmidi — Playing MIDI music.
exmouse — Getting input from the mouse.
expackf — Using custom PACKFILE vtables.
expal — Palette effects and color cycling.
expat — Using patterned drawing modes and sub-bitmaps.
exquat — A comparison between Euler angles and quaternions.
exrgbhsv — RGB <-> HSV color space conversions.
exrotscl — Demonstrates rotate_scaled_sprite functions.
exsample — Playing digital samples.
exscale — Loading PCX files and bitmap stretching.
exscn3d — Using the 3d scene functions.
exscroll — Mode-X hardware scrolling and split screens.
exshade — Gouraud shaded sprites.
exspline — Constructing smooth movement paths from spline curves.
exsprite — Datafiles access and sprite animation.
exstars — 3d starfield and lightsourced spaceship.
exstream — Playing audio streams.
exswitch — Controlling the console switch mode for background running.
exsyscur — Hardware accelerated mouse cursors.
extimer — Using the timer (delays and interrupts).
extrans — Lighting and translucency effects.
extrans2 — Drawing flipped, translucent and tinted sprites.
extruec — Truecolor pixel format conversions.
exunicod — Using Unicode string functions.
exupdate — Supporting different screen update methods in a single program.
exxfade — Truecolor image loading and fades.
exzbuf — Z-buffered polygons demo.

With Allegro comes quite a bunch of examples, which go from the simple introductory `Hello world' to more complicated programs featuring truecolor blending effects. This chapter describes these examples which you can find in the allegro/examples folder. You don't have to go through them in the same order as this documentation, but doing so you will learn the basic functions and avoid missing any important bit of information.

Example exhello

This is a very simple program showing how to get into graphics mode and draw text onto the screen.

See also: END_OF_MAIN, SCREEN_H, SCREEN_W, acquire_screen, allegro_error, allegro_init, allegro_message, clear_to_color, desktop_palette, font, install_keyboard, key, makecol, readkey, release_screen, screen, set_gfx_mode, set_palette, textout_centre_ex.

Example exmem

This program demonstrates the use of memory bitmaps. It creates a small temporary bitmap in memory, draws some circles onto it, and then blits lots of copies of it onto the screen.

See also: BITMAP, END_OF_MAIN, SCREEN_H, SCREEN_W, acquire_screen, allegro_error, allegro_init, allegro_message, blit, circle, clear_bitmap, create_bitmap, desktop_palette, destroy_bitmap, install_keyboard, palette_color, readkey, release_screen, screen, set_gfx_mode, set_palette.

Example expal

This program demonstrates how to manipulate the palette. It draws a set of concentric circles onto the screen and animates them by cycling the palette.

See also: END_OF_MAIN, PALETTE, RGB, SCREEN_H, SCREEN_W, acquire_screen, allegro_error, allegro_init, allegro_message, black_palette, circlefill, install_keyboard, install_mouse, keypressed, release_screen, screen, set_gfx_mode, set_palette, show_mouse.

Example expat

This program demonstrates the use of patterned drawing and sub-bitmaps.

See also: BITMAP, END_OF_MAIN, acquire_bitmap, allegro_error, allegro_init, allegro_message, bitmap_mask_color, blit, clear_to_color, create_bitmap, create_sub_bitmap, desktop_palette, destroy_bitmap, drawing_mode, font, install_keyboard, makecol, masked_blit, palette_color, readkey, rectfill, release_bitmap, screen, set_gfx_mode, set_palette, solid_mode, text_height, text_length, textout_ex.

Example exflame

This program demonstrates how to write directly to video memory. It implements a simple fire effect, first by calling getpixel() and putpixel(), then by accessing video memory directly a byte at a time, and finally using block memory copy operations.

See also: END_OF_MAIN, PALETTE, SCREEN_H, SCREEN_W, acquire_screen, allegro_error, allegro_init, allegro_message, bmp_read_line, bmp_unwrite_line, bmp_write_line, clear_keybuf, font, getpixel, install_keyboard, keypressed, line, makecol, putpixel, release_screen, rest, screen, set_gfx_mode, set_palette, textout_ex.

Example exdbuf

This program demonstrates the use of double buffering. It moves a circle across the screen, first just erasing and redrawing directly to the screen, then with a double buffer.

See also: BITMAP, END_OF_MAIN, SCREEN_H, SCREEN_W, acquire_screen, allegro_error, allegro_init, allegro_message, blit, circlefill, clear_keybuf, clear_to_color, create_bitmap, desktop_palette, destroy_bitmap, font, install_keyboard, install_timer, keypressed, makecol, release_screen, retrace_count, screen, set_gfx_mode, set_palette, textprintf_ex.

Example exflip

This program moves a circle across the screen, first with a double buffer and then using page flips.

See also: BITMAP, END_OF_MAIN, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, blit, circlefill, clear_keybuf, clear_to_color, create_bitmap, create_video_bitmap, desktop_palette, destroy_bitmap, font, install_keyboard, install_timer, keypressed, makecol, retrace_count, screen, set_gfx_mode, set_palette, show_video_bitmap, textprintf_ex.

Example exfixed

This program demonstrates how to use fixed point numbers, which are signed 32-bit integers storing the integer part in the upper 16 bits and the decimal part in the 16 lower bits. This example also uses the unusual approach of communicating with the user exclusively via the allegro_message() function.

See also: END_OF_MAIN, allegro_init, allegro_message, fixdiv, fixed, fixmul, fixsqrt, fixtof, ftofix, itofix.

Example exfont

This is a very simple program showing how to load and manipulate fonts.

See also: END_OF_MAIN, FONT, SCREEN_H, SCREEN_W, acquire_screen, allegro_error, allegro_init, allegro_message, clear_to_color, desktop_palette, destroy_font, extract_font_range, font, install_keyboard, key, load_font, makecol, merge_fonts, readkey, release_screen, screen, set_gfx_mode, set_palette, textout_centre_ex.

Example exmouse

This program demonstrates how to get mouse input. The first part of the test retrieves the raw mouse input data and displays it on the screen without using any mouse cursor. When you press a key the standard arrow-like mouse cursor appears. You are not restricted to this shape, and a second key press modifies the cursor to be several concentric colored circles. They are not joined together, so you can still see bits of what's behind when you move the cursor over the printed text message.

See also: BITMAP, END_OF_MAIN, SCREEN_H, SCREEN_W, acquire_screen, allegro_error, allegro_init, allegro_message, bitmap_mask_color, circle, clear_keybuf, clear_to_color, create_bitmap, desktop_palette, destroy_bitmap, font, get_mouse_mickeys, install_keyboard, install_mouse, install_timer, key, keypressed, makecol, mouse_b, mouse_w, mouse_x, mouse_y, mouse_z, palette_color, poll_mouse, readkey, release_screen, screen, set_gfx_mode, set_mouse_sprite, set_mouse_sprite_focus, set_palette, show_mouse, textout_centre_ex, textout_ex, textprintf_centre_ex, textprintf_ex, textprintf_right_ex, vsync.

Example extimer

This program demonstrates how to use the timer routines. These can be a bit of a pain, because you have to be sure you lock all the memory that is used inside your interrupt handlers. The first part of the example shows a basic use of timing using the blocking function rest(). The second part shows how to use three timers with different frequencies in a non blocking way.

See also: END_OF_FUNCTION, END_OF_MAIN, LOCK_FUNCTION, LOCK_VARIABLE, SCREEN_W, allegro_error, allegro_init, allegro_message, clear_to_color, desktop_palette, font, install_int, install_int_ex, install_keyboard, install_timer, key, keypressed, makecol, readkey, rest, screen, set_gfx_mode, set_palette, textprintf_centre_ex.

Example exkeys

This program demonstrates how to access the keyboard. The first part shows the basic use of readkey(). The second part shows how to extract the ASCII value. Next come the scan codes. The fourth test detects modifier keys like alt or shift. The fifth test requires some focus to be passed. The final step shows how to use the global key array to read simultaneous key presses. The last method to detect key presses are keyboard callbacks. This is demonstrated by installing a keyboard callback, which marks all pressed keys by drawing to a grid.

See also: END_OF_FUNCTION, END_OF_MAIN, LOCK_FUNCTION, SCREEN_H, SCREEN_W, acquire_screen, allegro_error, allegro_init, allegro_message, blit, clear_keybuf, clear_to_color, desktop_palette, font, install_keyboard, install_timer, key, key_shifts, keyboard_lowlevel_callback, keypressed, makecol, readkey, rectfill, release_screen, rest, scancode_to_name, screen, set_gfx_mode, set_palette, textout_ex, textprintf_centre_ex, textprintf_ex, ureadkey, usprintf, ustrzncpy.

Example exjoy

This program uses the Allegro library to detect and read the value of a joystick. The output of the program is a small target sight on the screen which you can move. At the same time the program will tell you what you are doing with the joystick (moving or firing).

See also: BITMAP, END_OF_MAIN, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, blit, calibrate_joystick, calibrate_joystick_name, circle, clear_bitmap, clear_keybuf, create_bitmap, default_palette, destroy_bitmap, drawing_mode, font, install_joystick, install_keyboard, joy, key, keypressed, num_joysticks, palette_color, poll_joystick, putpixel, readkey, screen, set_gfx_mode, set_palette, textout_centre_ex, textprintf_centre_ex, textprintf_ex.

Example exsample

This program demonstrates how to play samples. You have to use this example from the command line to specify as first parameter a WAV or VOC sound file to play. If the file is loaded successfully, the sound will be played in an infinite loop. While it is being played, you can use the left and right arrow keys to modify the panning of the sound. You can also use the up and down arrow keys to modify the pitch.

See also: END_OF_MAIN, SAMPLE, SCREEN_H, SCREEN_W, adjust_sample, allegro_error, allegro_init, allegro_message, clear_to_color, desktop_palette, destroy_sample, font, install_keyboard, install_sound, install_timer, key, load_sample, makecol, play_sample, poll_keyboard, rest, screen, set_display_switch_mode, set_gfx_mode, set_palette, textprintf_centre_ex.

Example exmidi

This program demonstrates how to play MIDI files.

See also: END_OF_MAIN, MIDI, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, clear_to_color, desktop_palette, destroy_midi, font, get_filename, get_midi_length, install_keyboard, install_sound, install_timer, key, keypressed, load_midi, makecol, midi_pause, midi_pos, midi_resume, midi_time, play_midi, readkey, rectfill, rest, screen, set_display_switch_mode, set_gfx_mode, set_palette, text_height, text_length, textprintf_centre_ex.

Example exgui

This program demonstrates how to use the GUI routines. From the simple dialog controls that display a text or a bitmap to more complex multiple choice selection lists, Allegro provides a framework which can be customised to suit your needs.

See also: DATAFILE, DIALOG, END_OF_MAIN, MENU, active_menu, alert, allegro_error, allegro_init, allegro_message, d_bitmap_proc, d_box_proc, d_button_proc, d_check_proc, d_clear_proc, d_ctext_proc, d_edit_proc, d_icon_proc, d_keyboard_proc, d_list_proc, d_menu_proc, d_radio_proc, d_rtext_proc, d_shadow_box_proc, d_slider_proc, d_text_list_proc, d_text_proc, d_textbox_proc, d_yield_proc, do_dialog, gui_bg_color, gui_fg_color, gui_mg_color, install_keyboard, install_mouse, install_timer, key, load_datafile, makecol, position_dialog, replace_filename, screen, set_dialog_color, set_gfx_mode, set_palette, unload_datafile, ustrtok, ustrzcat, ustrzcpy, uszprintf.

Example excustom

A follow up of the exgui.c example showing how to customise the default Allegro framework. In this case a dialog procedure animates a graphical clock without disrupting other GUI dialogs. A more simple option shows how to dynamically change the font used by all GUI elements.

See also: BITMAP, DATAFILE, DIALOG, END_OF_MAIN, FONT, allegro_error, allegro_init, allegro_message, blit, circle, circlefill, clear_to_color, create_bitmap, d_button_proc, d_check_proc, d_clear_proc, d_edit_proc, desktop_palette, destroy_bitmap, do_dialog, fixcos, fixed, fixmul, fixsin, fixtoi, font, install_keyboard, install_mouse, install_timer, itofix, key, line, load_datafile, makecol, object_message, replace_filename, screen, set_gfx_mode, set_palette, unload_datafile.

Example exunicod

This program demonstrates the use of the 16-bit Unicode text encoding format with Allegro. The example displays a message translated to different languages scrolling on the screen using an external font containing the required characters to display those messages.

Note how the Allegro unicode string functions resemble the functions you can find in the standard C library, only these handle Unicode on all platforms.

See also: BITMAP, DATAFILE, END_OF_MAIN, FONT, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, blit, clear_to_color, create_bitmap, destroy_bitmap, font, install_int_ex, install_keyboard, install_timer, keypressed, load_datafile, replace_filename, rest, screen, set_gfx_mode, set_uformat, set_window_title, text_height, text_length, textout_ex, uconvert_ascii, unload_datafile, ustrcat, ustrcpy, ustrsize, ustrsizez.

Example exbitmap

This program demonstrates how to load and display a bitmap file. You have to use this example from the command line to specify as first parameter a graphic file in one of Allegro's supported formats. If the file is loaded successfully, it will be displayed until you press a key.

See also: BITMAP, END_OF_MAIN, PALETTE, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, blit, destroy_bitmap, install_keyboard, load_bitmap, readkey, screen, set_gfx_mode, set_palette.

Example exscale

This example demonstrates how to use PCX files, palettes and stretch blits. It loads a PCX file, sets its palette and does some random stretch_blits. Don't worry - it's VERY slowed down using vsync().

See also: BITMAP, END_OF_MAIN, PALETTE, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, blit, destroy_bitmap, install_keyboard, keypressed, load_pcx, replace_filename, screen, set_gfx_mode, set_palette, stretch_blit, vsync.

Example exconfig

This is a very simple program showing how to use the Allegro configuration (ini file) routines. A first look at the example shows nothing more than a static graphic and the wait for a key press. However, the way this graphic is displayed is configured through a custom exconfig.ini file which is loaded manually. From this file the example obtains parameters like fullscreen/windowed mode, a specific graphic resolution to set up, which graphic to show, how to blit it on the screen, etc.

See also: BITMAP, END_OF_MAIN, RGB, SCREEN_H, SCREEN_W, allegro_init, allegro_message, blit, clear_bitmap, destroy_bitmap, font, get_config_argv, get_config_int, get_config_string, install_keyboard, line, load_bitmap, makecol, pop_config_state, push_config_state, readkey, screen, set_color_depth, set_config_file, set_gfx_mode, set_palette, stretch_blit, textout_centre_ex, textprintf_centre_ex, ustrdup, ustricmp.

Example exdata

This program demonstrates how to access the contents of an Allegro datafile (created by the grabber utility). The example loads the file `example.dat', then blits a bitmap and shows a font, both from this datafile.

See also: DATAFILE, END_OF_MAIN, allegro_error, allegro_init, allegro_message, blit, font, install_keyboard, load_datafile, makecol, readkey, replace_filename, screen, set_color_conversion, set_gfx_mode, set_palette, textout_ex, unload_datafile.

Example exsprite

This example demonstrates how to use datafiles, various sprite drawing routines and flicker-free animation.

Why is the animate() routine coded in that way? As you probably know, VIDEO RAM is much slower than "normal" RAM, so it's advisable to reduce VRAM blits to a minimum. Drawing sprite on the screen (meaning in VRAM) and then clearing a background for it is not very fast. This example uses a different method which is much faster, but require a bit more memory.

First the buffer is cleared (it's a normal BITMAP), then the sprite is drawn on it, and when the drawing is finished this buffer is copied directly to the screen. So the end result is that there is a single VRAM blit instead of blitting/clearing the background and drawing a sprite on it. It's a good method even when you have to restore the background. And of course, it completely removes any flickering effect.

When one uses a big (ie. 800x600 background) and draws something on it, it's wise to use a copy of background somewhere in memory and restore background using this "virtual background". When blitting from VRAM in SVGA modes, it's probably, that drawing routines have to switch banks on video card. I think, I don't have to remind how slow is it.

Note that on modern systems, the above isn't true anymore, and you usually get the best performance by caching all your animations in video ram and doing only VRAM->VRAM blits, so there is no more RAM->VRAM transfer at all anymore. And usually, such transfers can run in parallel on the graphics card's processor as well, costing virtually no main cpu time at all. See the exaccel example for an example of this.

See also: BITMAP, DATAFILE, END_OF_FUNCTION, END_OF_MAIN, LOCK_FUNCTION, LOCK_VARIABLE, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, blit, circle, clear_bitmap, clear_keybuf, create_bitmap, destroy_bitmap, draw_sprite, draw_sprite_h_flip, draw_sprite_v_flip, draw_sprite_vh_flip, fixed, font, hline, install_int_ex, install_keyboard, install_sound, install_timer, itofix, key, keypressed, load_datafile, makecol, palette_color, pivot_sprite, pivot_sprite_v_flip, play_sample, rectfill, replace_filename, rest, screen, set_gfx_mode, set_palette, text_height, textout_centre_ex, unload_datafile, vsync.

Example exrotscl

This example demonstrates rotate_scaled_sprite functions.

See also: BITMAP, END_OF_MAIN, SCREEN_H, SCREEN_W, allegro_init, allegro_message, blit, clear_to_color, create_bitmap, destroy_bitmap, draw_trans_sprite, fixed, font, ftofix, install_keyboard, key, keypressed, load_bitmap, makeacol, makecol, readkey, rest, rotate_scaled_sprite, rotate_scaled_sprite_lit, rotate_scaled_sprite_trans, screen, set_alpha_blender, set_color_conversion, set_color_depth, set_gfx_mode, set_trans_blender, textout_centre_ex.

Example exexedat

This program demonstrates how to access the contents of an Allegro datafile (created by the grabber utility) linked to the executable by the exedat tool. It is basically the exdata example with minor modifications.

You may ask: how do you compile, append and exec your program?

Answer: like this...

1) Compile your program like normal. Use the magic filenames with '#' to load your data where needed.

2) Once you compressed your program, run "exedat foo.exe data.dat"

3) Finally run your program.

Note that appending data to the end of binaries may not be portable across all platforms supported by Allegro.

See also: DATAFILE, END_OF_MAIN, allegro_error, allegro_init, allegro_message, blit, font, install_keyboard, line, load_datafile, makecol, readkey, screen, set_color_conversion, set_gfx_mode, set_palette, textout_ex, unload_datafile.

Example extrans

This program demonstrates how to use the lighting and translucency functions. The first part of the example will show a dark screen illuminated by a spotlight you can move with your mouse. After a key press the example shows the full bitmap and the spotlight changes to be a reduced version of the background with 50% of translucency.

The translucency effect is easy to do in all color depths. However, the lighting effect has to be performed in a different way depending on whether the screen is in 8bit mode or another color depth. This is because additive drawing mode uses a different set of routines for truecolor modes.

See also: BITMAP, COLOR_MAP, END_OF_MAIN, PALETTE, RGB, RGB_MAP, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, bitmap_color_depth, blit, circlefill, clear_bitmap, clear_keybuf, color_map, create_bitmap, create_bitmap_ex, create_light_table, create_rgb_table, create_trans_table, destroy_bitmap, draw_trans_sprite, drawing_mode, install_keyboard, install_mouse, install_timer, keypressed, load_bitmap, mouse_x, mouse_y, poll_mouse, rectfill, replace_filename, rest, rgb_map, screen, set_alpha_blender, set_gfx_mode, set_palette, set_trans_blender, set_write_alpha_blender, stretch_blit.

Example extrans2

This program demonstrates how to draw trans and lit sprites and flip them at the same time, using draw_sprite_ex() function. It displays several images moving around using different drawing modes while you can press space key to change the flipping orientation.

See also: BITMAP, END_OF_MAIN, allegro_error, allegro_init, allegro_message, blit, clear_bitmap, create_bitmap, destroy_bitmap, draw_sprite_ex, font, install_keyboard, install_timer, key, load_bitmap, makecol, replace_filename, rest, screen, set_color_depth, set_gfx_mode, set_trans_blender, stretch_blit, textout_ex.

Example extruec

This program shows how to specify colors in the various different truecolor pixel formats. The example shows the same screen (a few text lines and three coloured gradients) in all the color depth modes supported by your video card. The more color depth you have, the less banding you will see in the gradients.

See also: END_OF_MAIN, PALETTE, RGB, SCREEN_H, SCREEN_W, acquire_screen, allegro_init, clear_to_color, font, generate_332_palette, install_keyboard, key, makecol, readkey, release_screen, screen, set_color_depth, set_gfx_mode, set_palette, textout_centre_ex, textout_ex, textprintf_ex, vline.

Example excolmap

This program demonstrates how to create custom graphic effects with the create_color_table function. Allegro drawing routines are affected by any color table you might have set up. In the first part of this example, a greyscale color table is set. The result is that a simple rectfill call, instead of drawing a rectangle with color zero, uses the already drawn pixels to determine the pixel to be drawn (read the comment of return_grey_color() for a precise description of the algorithm). In the second part of the test, the color table is changed to be an inverse table, meaning that any pixel drawn will be shown as its color values had been inverted.

See also: BITMAP, COLOR_MAP, END_OF_MAIN, PALETTE, RGB, RGB_MAP, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, blit, circlefill, clear_keybuf, color_map, create_bitmap, create_color_table, create_rgb_table, destroy_bitmap, drawing_mode, font, generate_332_palette, install_keyboard, keypressed, makecol, rectfill, rest, rgb_map, screen, set_gfx_mode, set_palette, textout_centre_ex, vsync.

Example exrgbhsv

This program shows how to convert colors between the different color-space representations. The central area of the screen will display the current color. On the top left corner of the screen, three sliders allow you to modify the red, green and blue value of the color. On the bottom right corner of the screen, three sliders allow you to modify the hue, saturation and value of the color. The color bars beneath the sliders show what the resulting color will look like when the slider is dragged to that position.

Additionally this example also shows how to "inherit" the behaviour of a GUI object and extend it, here used to create the sliders.

See also: BITMAP, DIALOG, END_OF_MAIN, PALETTE, RGB, RGB_MAP, allegro_error, allegro_init, allegro_message, clear_to_color, create_bitmap_ex, create_rgb_table, d_bitmap_proc, d_box_proc, d_slider_proc, d_text_proc, destroy_bitmap, do_dialog, font, generate_332_palette, get_color_depth, hsv_to_rgb, install_keyboard, install_mouse, install_timer, key, makecol, makecol32, makecol8, object_message, rgb_map, rgb_to_hsv, screen, set_color, set_color_depth, set_gfx_mode, set_palette, textout_ex, vline, vsync.

Example exshade

This program demonstrates how to draw Gouraud shaded (lit) sprites. In an apparently black screen, a planet like sprite is drawn close to the middle of the screen. In a similar way to how the first test of extrans works, you move the cursor on the screen with the mouse. Attached to this mouse you can imagine a virtual spotlight illuminating the scene around. Depending on where the mouse is, the Gouraud shaded sprite will show the direction of the light.

See also: BITMAP, COLOR_MAP, END_OF_MAIN, PALETTE, RGB, RGB_MAP, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, blit, clear_bitmap, color_map, create_bitmap, create_light_table, create_rgb_table, destroy_bitmap, draw_gouraud_sprite, font, install_keyboard, install_mouse, keypressed, line, load_bitmap, mouse_x, mouse_y, palette_color, poll_mouse, replace_filename, rgb_map, screen, set_gfx_mode, set_palette, set_trans_blender, show_mouse, textout_ex.

Example exblend

This program demonstrates how to use the translucency functions in truecolor video modes. Two image files are loaded from disk and displayed moving slowly around the screen. One of the images will be tinted to different colors. The other image will be faded out with a varying alpha strength, and drawn on top of the other image.

See also: BITMAP, END_OF_MAIN, PALETTE, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, blit, circle, clear_bitmap, clear_keybuf, create_bitmap, destroy_bitmap, draw_lit_sprite, draw_trans_sprite, fixcos, fixsin, fixtoi, font, install_keyboard, install_timer, itofix, keypressed, load_bitmap, makecol, replace_filename, retrace_count, screen, set_color_conversion, set_color_depth, set_gfx_mode, set_trans_blender, textprintf_ex, vsync.

Example exxfade

This program demonstrates how to load and display bitmap files in truecolor video modes, and how to crossfade between them. You have to use this example from the command line to specify as parameters a number of graphic files. Use at least two files to see the graphical effect. The example will crossfade from one image to another with each key press until you press the ESC key.

See also: BITMAP, END_OF_MAIN, PALETTE, SCREEN_H, SCREEN_W, allegro_error, allegro_exit, allegro_init, allegro_message, blit, create_bitmap, destroy_bitmap, draw_trans_sprite, install_keyboard, keypressed, line, load_bitmap, readkey, rest, screen, set_color_conversion, set_color_depth, set_gfx_mode, set_palette, set_trans_blender, vsync.

Example exalpha

This program demonstrates how to use the 32 bit RGBA translucency functions to store an alpha channel along with a bitmap graphic. Two images are loaded from disk. One will be used for the background and the other as a sprite. The example generates an alpha channel for the sprite image, composing the 32 bit RGBA bitmap during runtime, and draws it at the position of the mouse cursor.

See also: BITMAP, END_OF_MAIN, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, blit, clear_keybuf, create_bitmap, destroy_bitmap, draw_trans_sprite, drawing_mode, font, getb, getg, getpixel, getr, install_keyboard, install_mouse, install_timer, keypressed, load_bitmap, makecol, mouse_x, mouse_y, putpixel, rectfill, replace_filename, screen, set_alpha_blender, set_color_conversion, set_color_depth, set_gfx_mode, set_multiply_blender, set_write_alpha_blender, solid_mode, stretch_blit, textprintf_ex.

Example exlights

This program shows one way to implement colored lighting effects in a hicolor video mode. Warning: it is not for the faint of heart! This is by no means the simplest or easiest to understand method, I just thought it was a cool concept that would be worth demonstrating.

The basic approach is to select a 15 or 16 bit screen mode, but then draw onto 24 bit memory bitmaps. Since we only need the bottom 5 bits of each 8 bit color in order to store 15 bit data within a 24 bit location, we can fit a light level into the top 3 bits. The tricky bit is that these aren't actually 24 bit images at all: they are implemented as 8 bit memory bitmaps, and we just store the red level in one pixel, green in the next, and blue in the next, making the total image be three times wider than we really wanted. This allows us to use all the normal 256 color graphics routines for drawing onto our memory surfaces, most importantly the lookup table translucency, which can be used to combine the low 5 bits of color and the top 3 bits of light in a single drawing operation. Some trickery is needed to load 24 bit data into this fake 8 bit format, and of course it needs a custom routine to convert the resulting image while copying it across to the hardware screen.

This program chugs slightly on my p133, but not significantly worse than any double buffering in what amounts to a 1920x640, 256 color resolution. The light blending doesn't seem to slow it down too badly, so I think this technique would be quite usable on faster machines and in lower resolution hicolor modes. The biggest problem is that although you keep the full 15 bit color resolution, you only get 3 bits of light, ie. 8 light levels. You can do some nice colored light patches, but smooth gradients aren't going to work too well :-)

See also: BITMAP, COLOR_MAP, END_OF_MAIN, PALETTE, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, bitmap_color_depth, blit, bmp_unwrite_line, bmp_write_line, circlefill, clear_bitmap, clear_keybuf, color_map, create_bitmap_ex, destroy_bitmap, draw_trans_sprite, fixatan2, fixsqrt, fixtoi, getb_depth, getg_depth, getpixel, getr_depth, hsv_to_rgb, install_keyboard, install_mouse, install_timer, itofix, key, keypressed, line, load_bitmap, makecol, mouse_x, mouse_y, poll_mouse, replace_filename, retrace_count, screen, select_palette, set_color_conversion, set_color_depth, set_gfx_mode.

Example ex3d

This program demonstrates how to use the 3d matrix functions. It isn't a very elegant or efficient piece of code, but it does show the stuff in action. It is left to the reader as an exercise to design a proper model structure and rendering pipeline: after all, the best way to do that sort of stuff varies hugely from one game to another.

The example first shows a screen resolution selection dialog. Then, a number of bouncing 3d cubes are animated. Pressing a key modifies the rendering of the cubes, which can be wireframe, the more complex transparent perspective correct texture mapped version, and many other.

See also: BITMAP, COLOR_MAP, END_OF_MAIN, MATRIX, PALETTE, POLYTYPE_ATEX, POLYTYPE_ATEX_LIT, POLYTYPE_ATEX_MASK, POLYTYPE_ATEX_MASK_LIT, POLYTYPE_ATEX_MASK_TRANS, POLYTYPE_ATEX_TRANS, POLYTYPE_FLAT, POLYTYPE_GCOL, POLYTYPE_GRGB, POLYTYPE_PTEX, POLYTYPE_PTEX_LIT, POLYTYPE_PTEX_MASK, POLYTYPE_PTEX_MASK_LIT, POLYTYPE_PTEX_MASK_TRANS, POLYTYPE_PTEX_TRANS, RGB, RGB_MAP, SCREEN_H, SCREEN_W, V3D, allegro_error, allegro_exit, allegro_init, allegro_message, apply_matrix, bitmap_color_depth, bitmap_mask_color, blit, clear_bitmap, clear_to_color, color_map, create_bitmap, create_light_table, create_rgb_table, create_trans_table, desktop_palette, destroy_bitmap, fixed, fixtoi, font, get_transformation_matrix, gfx_mode_select_ex, install_keyboard, install_mouse, install_timer, itofix, key, keypressed, line, palette_color, persp_project, polygon_z_normal, quad3d, readkey, rect, retrace_count, rgb_map, screen, set_color_depth, set_gfx_mode, set_palette, set_projection_viewport, set_trans_blender, textout_ex, textprintf_ex, vsync.

Example excamera

This program demonstrates how to use the get_camera_matrix() function to view a 3d world from any position and angle. The example draws a checkered floor through a viewport region on the screen. You can use the keyboard to move around the camera or modify the size of the viewport. The keys that can be used with this example are displayed between brackets at the top of the screen.

See also: BITMAP, END_OF_MAIN, MATRIX_f, POLYTYPE_FLAT, SCREEN_H, SCREEN_W, V3D_f, allegro_error, allegro_init, allegro_message, apply_matrix_f, blit, clear_to_color, clip3d_f, create_bitmap, desktop_palette, destroy_bitmap, font, get_camera_matrix_f, get_vector_rotation_matrix_f, install_int_ex, install_keyboard, install_timer, key, key_shifts, makecol, persp_project_f, poll_keyboard, polygon, polygon3d_f, rect, screen, set_clip_rect, set_gfx_mode, set_palette, set_projection_viewport, textprintf_ex, vsync.

Example exquat

Euler angles are convenient for storing and creating 3D orientations. However, this program demonstrates that they are not good when interpolating between two different orientations. The problem is solved by using Allegro's quaternion operations.

In this program, two cubes are rotated between random orientations. Notice that although they have the same beginning and ending orientations, they do not follow the same path between orientations.

One cube is being rotated by directly incrementing or decrementing the Euler angles from the starting point to the ending point. This is an intuitive notion, but it is incorrect because it does not cause the object to turn around a single unchanging axis of rotation. The axis of rotation wobbles resulting in the object spinning in strange ways. The object will eventually end up in the orientation that the user intended, but it gets there in a way that is unattractive. Imagine if this method was used to update the position of a camera in a game! Sometimes it would swing wildly and disorient the player.

The other cube is animated using quaternions. This results in a much more pleasing animation because the cube turns around a single axis of rotation.

See also: BITMAP, END_OF_MAIN, MATRIX_f, QUAT, acquire_bitmap, allegro_error, allegro_init, allegro_message, apply_matrix_f, blit, circle, clear_keybuf, clear_to_color, create_bitmap, desktop_palette, destroy_bitmap, font, get_camera_matrix_f, get_rotation_matrix, get_rotation_matrix_f, get_rotation_quat, install_keyboard, keypressed, line, matrix_mul_f, palette_color, persp_project_f, quat_interpolate, quat_to_matrix, readkey, release_bitmap, rest, screen, set_gfx_mode, set_palette, set_projection_viewport, textout_ex.

Example exstars

This program draws a 3D star field (depth-cued) and a polygon starship (controllable with the keyboard cursor keys), using the Allegro math functions.

See also: BITMAP, END_OF_MAIN, MATRIX, PALETTE, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, apply_matrix, blit, clear_bitmap, create_bitmap, cross_product, destroy_bitmap, dot_product, fixed, fixmul, fixtof, fixtoi, font, get_rotation_matrix, get_transformation_matrix, get_translation_matrix, install_keyboard, install_timer, itofix, key, normalize_vector, palette_color, persp_project, poll_keyboard, putpixel, rectfill, screen, set_gfx_mode, set_palette, set_projection_viewport, textout_centre_ex, textprintf_centre_ex, triangle, vsync.

Example exscn3d

This program demonstrates how to use scanline sorting algorithm in Allegro (create_scene, clear_scene, ... functions). It also provides an example of how to use the 3D clipping function. The example consists of a flyby through a lot of rotating 3d cubes.

See also: BITMAP, END_OF_FUNCTION, END_OF_MAIN, LOCK_FUNCTION, LOCK_VARIABLE, MATRIX_f, PALETTE, POLYTYPE_GCOL, SCREEN_H, SCREEN_W, V3D_f, allegro_error, allegro_exit, allegro_init, allegro_message, apply_matrix_f, bitmap_color_depth, blit, clear_bitmap, clear_scene, clip3d_f, create_bitmap, create_scene, desktop_palette, destroy_bitmap, destroy_scene, font, get_rotation_matrix_f, get_translation_matrix_f, gfx_mode_select_ex, install_int, install_keyboard, install_mouse, install_timer, key, matrix_mul_f, palette_color, persp_project_f, polygon_z_normal_f, render_scene, scene_polygon3d_f, screen, set_color_depth, set_gfx_mode, set_palette, set_projection_viewport, textprintf_ex.

Example exzbuf

This program demonstrates how to use Z-buffered polygons and floating point 3D math routines. It also provides a simple way to compute fps (frames per second) using a timer. After selecting a screen resolution through the standard GUI dialog, the example shows two 3D cubes rotating and intersecting each other. Rather than having full polygons incorrectly overlap other polygons due to per-polygon sorting, each pixel is drawn at the correct depth.

See also: BITMAP, END_OF_FUNCTION, END_OF_MAIN, LOCK_FUNCTION, LOCK_VARIABLE, MATRIX_f, PALETTE, POLYTYPE_GCOL, SCREEN_H, SCREEN_W, V3D_f, ZBUFFER, allegro_error, allegro_exit, allegro_init, allegro_message, apply_matrix_f, bitmap_color_depth, blit, clear_bitmap, clear_zbuffer, create_bitmap, create_zbuffer, desktop_palette, destroy_bitmap, destroy_zbuffer, font, get_transformation_matrix_f, gfx_mode_select_ex, install_int, install_keyboard, install_mouse, install_timer, keypressed, palette_color, persp_project_f, polygon_z_normal_f, quad3d_f, readkey, screen, set_color_depth, set_gfx_mode, set_palette, set_palette_range, set_projection_viewport, set_zbuffer, textprintf_ex, vsync.

Example exscroll

This program demonstrates how to use hardware scrolling. The scrolling should work on anything that supports virtual screens larger than the physical screen.

See also: BITMAP, END_OF_MAIN, RGB, SCREEN_H, SCREEN_W, acquire_bitmap, allegro_init, allegro_message, clear_keybuf, create_sub_bitmap, desktop_palette, destroy_bitmap, install_keyboard, keypressed, rectfill, release_bitmap, rest, screen, scroll_screen, set_color, set_gfx_mode, set_palette, vline.

Example ex3buf

This program demonstrates the use of triple buffering. Several triangles are displayed rotating and bouncing on the screen until you press a key. Note that on some platforms you can't get real hardware triple buffering. The Allegro code remains the same, but most likely the graphic driver will emulate it. Unfortunately, in these cases you can't expect the animation to be completely smooth and flicker free.

See also: BITMAP, END_OF_MAIN, SCREEN_H, SCREEN_W, acquire_bitmap, allegro_error, allegro_init, allegro_message, clear_bitmap, clear_keybuf, create_video_bitmap, desktop_palette, destroy_bitmap, enable_triple_buffer, fixcos, fixed, fixmul, fixsin, fixtoi, font, gfx_capabilities, install_keyboard, install_mouse, install_timer, itofix, keypressed, poll_scroll, release_bitmap, request_video_bitmap, screen, set_gfx_mode, set_palette, textout_ex, triangle, ustrzcpy.

Example ex12bit

This program sets up a 12-bit mode on any 8-bit card, by setting up a 256-colour palette that will fool the eye into grouping two 8-bit pixels into one 12-bit pixel. In order to do this, you make your 256-colour palette with all the combinations of blue and green, assuming green ranges from 0-15 and blue from 0-14. This takes up 16x15=240 colours. This leaves 16 colours to use as red (red ranges from 0-15). Then you put your green/blue in one pixel, and your red in the pixel next to it. The eye gets fooled into thinking it's all one pixel.

The example starts setting a normal 256 color mode, and construct a special palette for it. But then comes the trick: you need to write to a set of two adjacent pixels to form a single 12 bit dot. Two eight bit pixels is the same as one 16 bit pixel, so after setting the video mode you need to hack the screen bitmap about, halving the width and changing it to use the 16 bit drawing code. Then, once you have packed a color into the correct format (using the makecol12() function below), any of the normal Allegro drawing functions can be used with this 12 bit display!

Things to note:

The horizontal width is halved, so you get resolutions like 320x480, 400x600, and 512x768.
Because each dot is spread over two actual pixels, the display will be darker than in a normal video mode.
Any bitmap data will obviously need converting to the correct 12 bit format: regular 15 or 16 bit images won't display correctly...
Although this works like a truecolor mode, it is actually using a 256 color palette, so palette fades are still possible!
This code only works in linear screen modes (don't try Mode-X).

See also: BITMAP, END_OF_MAIN, MATRIX, PALETTE, RGB, allegro_error, allegro_init, allegro_message, apply_matrix, blit, circle, clear_bitmap, clear_keybuf, clear_to_color, create_bitmap, create_bitmap_ex, destroy_bitmap, ellipsefill, fade_out, fixcos, fixed, fixsin, fixtoi, font, get_rotation_matrix, getpixel, install_keyboard, itofix, keypressed, line, makecol, masked_blit, putpixel, rest, screen, set_clip_rect, set_color, set_gfx_mode, set_palette, text_height, text_length, textout_ex, textprintf_ex.

Example exaccel

This program demonstrates how to use an offscreen part of the video memory to store source graphics for a hardware accelerated graphics driver. The example loads the `mysha.pcx' file and then blits it several times on the screen. Depending on whether you have enough video memory and Allegro supports the hardware acceleration features of your card, your success running this example may be none at all, sluggish performance due to software emulation, or flicker free smooth hardware accelerated animation.

See also: BITMAP, END_OF_MAIN, PALETTE, SCREEN_H, SCREEN_W, acquire_bitmap, allegro_error, allegro_init, allegro_message, blit, clear_bitmap, create_video_bitmap, destroy_bitmap, font, gfx_capabilities, install_keyboard, install_timer, keypressed, load_bitmap, readkey, release_bitmap, replace_filename, screen, set_gfx_mode, set_palette, show_video_bitmap, textout_ex, textprintf_ex.

Example exspline

This program demonstrates the use of spline curves to create smooth paths connecting a number of node points. This can be useful for constructing realistic motion and animations.

The technique is to connect the series of guide points p1..p(n) with spline curves from p1-p2, p2-p3, etc. Each spline must pass though both of its guide points, so they must be used as the first and fourth of the spline control points. The fun bit is coming up with sensible values for the second and third spline control points, such that the spline segments will have equal gradients where they meet. I came up with the following solution:

For each guide point p(n), calculate the desired tangent to the curve at that point. I took this to be the vector p(n-1) -> p(n+1), which can easily be calculated with the inverse tangent function, and gives decent looking results. One implication of this is that two dummy guide points are needed at each end of the curve, which are used in the tangent calculations but not connected to the set of splines.

Having got these tangents, it becomes fairly easy to calculate the spline control points. For a spline between guide points p(a) and p(b), the second control point should lie along the positive tangent from p(a), and the third control point should lie along the negative tangent from p(b). How far they are placed along these tangents controls the shape of the curve: I found that applying a 'curviness' scaling factor to the distance between p(a) and p(b) works well.

One thing to note about splines is that the generated points are not all equidistant. Instead they tend to bunch up nearer to the ends of the spline, which means you will need to apply some fudges to get an object to move at a constant speed. On the other hand, in situations where the curve has a noticeable change of direction at each guide point, the effect can be quite nice because it makes the object slow down for the curve.

See also: END_OF_MAIN, SCREEN_W, acquire_screen, alert, allegro_error, allegro_init, allegro_message, calc_spline, circlefill, clear_keybuf, clear_to_color, desktop_palette, fixatan2, fixcos, fixed, fixmul, fixsin, fixsqrt, fixtof, fixtoi, font, ftofix, install_keyboard, install_mouse, install_timer, itofix, key, keypressed, line, makecol, mouse_b, mouse_x, mouse_y, palette_color, poll_mouse, readkey, release_screen, screen, set_gfx_mode, set_palette, show_mouse, spline, textout_centre_ex, textprintf_centre_ex, textprintf_ex, vsync, xor_mode.

Example exsyscur

This program demonstrates the use of hardware accelerated mouse cursors.

See also: END_OF_MAIN, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, clear_to_color, enable_hardware_cursor, font, gfx_capabilities, install_keyboard, install_mouse, install_timer, makecol, readkey, screen, select_mouse_cursor, set_gfx_mode, show_mouse, text_height, textprintf_centre_ex.

Example exupdate

This program demonstrates how to support double buffering, page flipping, and triple buffering as options within a single program, and how to make things run at a constant rate no matter what the speed of your computer. You have to use this example from the command line to specify as first parameter a number which represents the type of video update you want: 1 for double buffering with memory bitmaps, 2 for page flipping, 3 for triple buffering and 4 for double buffering with system bitmaps. After this, a dialog allows you to select a screen resolution and finally you will see a kaleidoscopic animation, along with a frames per second counter on the top left of the screen.

See also: BITMAP, END_OF_FUNCTION, END_OF_MAIN, LOCK_FUNCTION, LOCK_VARIABLE, PALETTE, SCREEN_H, SCREEN_W, acquire_bitmap, allegro_error, allegro_init, allegro_message, bitmap_color_depth, blit, clear_bitmap, create_bitmap, create_system_bitmap, create_video_bitmap, desktop_palette, destroy_bitmap, enable_triple_buffer, fixcos, fixed, fixmul, fixsin, fixtoi, font, ftofix, generate_332_palette, gfx_capabilities, gfx_mode_select_ex, install_int_ex, install_keyboard, install_mouse, install_timer, keypressed, line, makecol, poll_scroll, release_bitmap, request_video_bitmap, screen, set_color_depth, set_gfx_mode, set_palette, show_video_bitmap, textout_ex, textprintf_ex, triangle, vsync, xor_mode.

Example exswitch

This program shows how to control the console switching mode, and let your program run in the background. These functions don't apply to every platform and driver, for example you can't control the switching mode from a DOS program.

Yes, I know the fractal drawing is very slow: that's the point! This is so you can easily check whether it goes on working in the background after you switch away from the app.

Depending on the type of selected switching mode, you will see whether the contents of the screen are preserved or not.

See also: BITMAP, END_OF_FUNCTION, END_OF_MAIN, LOCK_FUNCTION, LOCK_VARIABLE, PALETTE, SCREEN_H, SCREEN_W, acquire_bitmap, acquire_screen, allegro_error, allegro_exit, allegro_init, allegro_message, bitmap_color_depth, blit, clear_to_color, create_sub_bitmap, desktop_palette, destroy_bitmap, font, get_display_switch_mode, gfx_mode_select_ex, install_int, install_keyboard, install_mouse, install_timer, keypressed, makecol, palette_color, putpixel, readkey, rectfill, release_bitmap, release_screen, screen, set_color_depth, set_display_switch_callback, set_display_switch_mode, set_gfx_mode, set_palette, textout_centre_ex, textprintf_centre_ex.

Example exstream

This program shows how to use the audio stream functions to transfer large blocks of sample data to the sound card. In this case, the sample data is generated during runtime, and the resulting sound reminds of a car engine when you are accelerating.

See also: AUDIOSTREAM, END_OF_MAIN, SCREEN_H, SCREEN_W, allegro_error, allegro_init, allegro_message, clear_to_color, desktop_palette, font, free_audio_stream_buffer, get_audio_stream_buffer, install_keyboard, install_sound, install_timer, keypressed, makecol, play_audio_stream, readkey, screen, set_display_switch_mode, set_gfx_mode, set_palette, stop_audio_stream, textprintf_centre_ex, voice_start, voice_stop.

Example expackf

This program demonstrates the use of the packfile functions, with some simple tests.

The first test uses the standard packfile functions to transfer a bitmap file into a block of memory, then reads the bitmap out of the block of memory, using a custom packfile vtable.

The second test reads in a bitmap with another custom packfile vtable, which uses libc's file stream functions.

The third test demonstrates seeking with a custom vtable.

The fourth test reads two bitmaps, and dumps them back into a single file, using a custom vtable again.

See also: ASSERT, BITMAP, END_OF_MAIN, PACKFILE, PACKFILE_VTABLE, SCREEN_H, SCREEN_W, alert, allegro_error, allegro_init, allegro_message, blit, clear_bitmap, destroy_bitmap, file_size_ex, font, install_keyboard, key, load_bmp_pf, load_pcx, load_pcx_pf, load_tga_pf, pack_fclose, pack_fopen, pack_fopen_vtable, pack_fread, pack_fseek, readkey, save_bmp_pf, save_tga_pf, screen, set_color_depth, set_gfx_mode, text_height, textprintf_centre_ex, textprintf_ex.

Back to contents