Allegro - Perl interface to Allegro multimedia library
use Allegro; # Create Allegro object $al = Allegro->new() or die "Couldn't initialize Allegro"; # Create Display object (screen) $disp = $al->Display(width => 640, height => 480) or die "Couldn't set graphics mode " . $al->error; for $file (@ARGV) { # Load image into bitmap $bmp = $disp->Bitmap(file => $file) or die "Couldn't load $file"; # Clear display bitmap $disp->clear(); # Copy image bitmap to display $disp->blit($bmp); $al->sleep(10); }
Allegro is a game programming library for C/C++ developers distributed freely, supporting the following platforms: DOS, Unix (Linux, FreeBSD, Irix, Solaris, Darwin), Windows, QNX, BeOS and MacOS X new!. It provides many functions for graphics, sounds, player input (keyboard, mouse and joystick) and timers. It also provides fixed and floating point mathematical functions, 3d functions, file management functions, compressed datafile and a GUI. [from the Allegro website]
This module provides an object-oriented Perl interface to Allegro.
The entire Allegro API is not implemented. The configuration routines, 3d routines, FLIC, RLE and compiled sprites, audio streams, and GUI are not implemented by this module. They may be in the future.
This module provides both a Perl-based object oriented interface as well as a thin wrapper around the Allegro C library. It is suggested that you use the Perl interface, but the C wrapper routrines are available. See PROCEDURAL INTERFACE below.
The Allegro Perl module is a collection of packages corresponding to various objects. These objects map loosely to the Allegro API. Objects include things such as Bitmaps, Timers, Datafiles, the Keyboard, Mouse, etc.
There is a general hierarchy of objects used. Some objects may be able to create sub-objects that are associated with them. The hierarchy is rooted by the Allegro module which can create various sub-objects.
To create a sub-object, the following syntax is used:
$al = Allegro->new; $disp = $al->Display(mode => 'window');
The Display here is the name of a class provided by the Allegro module. Display is a sub-object of the global Allegro object. Display can create one sub-object: the Bitmap object.
Display
$bmp = $disp->Bitmap(width => 640, height => 480);
Bitmap here is a sub-object of $disp. Bitmap objects may be sub-objects of either Allegro or Display, but Display is preferred. See Allegro::Display below.
Bitmap
$disp
The following is a list of all Allegro objects.
Allegro is the base Allegro object. Only one Allegro instance may be created at a time. If Allegro::new is called more than once, the previously created instance will be retured.
Allegro does not have a parent object. Therefore it must be created by a call to Allegro->new() instead of the form used for other Allegro objects.
Allegro->new()
Allegro::Bitmap is a bitmap object, corresponding to Allegro's BITMAP structure. A Bitmap may be created with either an Allegro or Display object call to ->Bitmap, but Display is preferred.
BITMAP
->Bitmap
Allegro datafiles may be read into a Allegro::Datafile object. This will create a collection of Allegro objects for each included file.
An Allegro::Display object corresponds the the screen bitmap pointer in Allegro. Creating a Display object will either create a new window on the desktop or enter full screen mode. Bitmap objects may be created from the returned Display instance.
screen
Allegro::Font is a font that may be used for text drawing. This corresponds to Allegro's FONT type. Allegro does not provide any routines for loading fonts directly, but they may be loaded via a Datafile object.
FONT
Allegro::Joystick corresponds to a single joystick installed on the system. Each returned instance contains methods to read joystick buttons and axes, as well as calibration methods.
Allegro::Keyboard accesses the keyboard, providing methods to check for key presses and do buffered keyboard reading. Only one Keyboard object may exist at once.
MIDI objects are not yet implemented.
Allegro::Mouse provides an object to access the current mouse position and button status. Only one mouse object may be created.
The Allegro::Palette object provides methods to read and write color palettes that may be used with Allegro's 8-bit indexed color modes. Each 8-bit Bitmap object will include a Palette object.
The Allegro::Sound is used to initialize the sound card drivers and set the global volume.
Allegro::Sample is a digital sample object. This corresponds to Allegro's SAMPLE abstract type, and provides methods to play digital sounds.
SAMPLE
Allegro::Timer objects provide access to Allegro's timer callbacks. Each object corresponds to one timer callback.
The Allegro object is described below. Other objects are fully documented in their respective manual pages.
The Allegro object is the ancestor of all objects created by the Allegro module. It can only be created once, and then further calls to new will result in the original object being returned.
Creating an Allegro object will initialize the Allegro library. This may involve accessing the hardware. For instance, this will check the DISPLAY environment variable and connect to X under Unix, try to access a spare virtual terminal under Linux, or create a (non-yet visible) window in Microsoft Windows. Use driver => none in new to avoid this.
DISPLAY
none
This method creates a new Allegro instance, which can then be used to create sub-objects, as well as initialize various other Allegro subsystems.
$al = Allegro->new(driver => 'auto');
driver is the driver to use for the Allegro system driver. Currently only auto and none are valid options. auto will pick whatever is convenient or use allegro.cfg, which none will use the special SYSTEM_NONE() driver from Allegro. This driver will not allow any hardware access. It is only useful for reading and writing memory bitmaps and datafiles. The default is auto.
auto
SYSTEM_NONE()
This method releasing all access to the hardware and frees any memory Allegro is using internally. Any Allegro objects that are still in existance are considered invalid after this call, and may not be used safely.
This will be called automatically when Perl exits; it does not need to be called explicitly.
$al->sleep($seconds);
Sleeps for a number of seconds. $seconds may be a floating point number. This should be used in place of Perl's builtin sleep function, since Allegro's timer system and the Timer module may cause the builtin to work improperly.
This may be exported and used as a replacement for the builtin sleep.
This method will return a text error message relating to the last failure by Allegro, most notably failure to set a graphics mode.
This method provides a portable way to send an error message to the user. It will destroy the current display (by switching to a "text" mode).
In addition the the object oriented interface described above, the thinly wrapped C routines used by the object-oriented interface are available. Knowledge of the Allegro API is assumed in the reference below. Most functions behave exactly as their C counterparts.
The entire Allegro API has not been included. Since it is troublesome to access C structs and global variables directly in Perl, a number of get/set functions were added.
All of Allegro's (semi) opague data types have been turned into blessed objects via a T_PTROBJ typemap. This means that functions which return a pointer to some Allegro type will return a blessed hash reference. For example, al_load_bitmap will return an object of the type BITMAPPtr, which can then be passed to al_save_bitmap or blit. To get a NULL pointer, you will need to use the provided AL_NULL_BITMAP() and AL_NULL_PALETTE() constants.
T_PTROBJ
BITMAPPtr
Any functions taking or returning Allegro's fixed type will instead take and return regular Perl floating values. These will be converted back and forth to fixed automatically. Take care not to pass a number out of the fixed point range to these functions.
fixed
All of the Allegro functions are in the Allegro package. They are not exported by default. They can be exported with a :functions tag. The defines are prefixed with AL_, and are also in Allegro. These can be exported with :defines.
:functions
AL_
:defines
This example loads a bitmap and displays it on the screen. Error checking has been omitted.
use Allegro qw(:functions :defines); al_allegro_init(); al_install_keyboard(); al_set_color_depth(24); al_set_gfx_mode(AL_GFX_AUTODETECT(), 640, 480, 0, 0); $screen = al_get_screen(); $b = al_load_bitmap("test.bmp", AL_NULL_PALETTE()); blit($b, $screen, 0, 0, 0, 0, al_get_bitmap_width($b), al_get_bitmap_height($b)); al_readkey();
Below is a list of all available Allegro functions. Unless noted these will simply call the low level C library function without any modification or verification. Therefore you need to be more careful than with the OO interface, as it is easy to crash Perl with a bad call to Allegro.
The following functions behave exactly as their C counterparts. See the Allegro documentation for details.
The following functions have been added to help access various Allegro global variables or provide a Perl-friendly interface to Allegro functions.
This is similar to the real install_allegro, with the default values for the errno and atexit pointers.
Identical to allegro_init.
Returns allegro_error[].
Returns a text string (ALLEGRO_VERSION_STR).
Returns the font pointer.
Returns the screen pointer.
Returns the screen width, height, virtual width, virtual height.
($w, $h, $vw, $vh) = al_get_screen_size();
Returns gfx_capabilites.
Identical to allegro_message.
Returns bitmap width and height.
($w, $h) = al_get_bitmap_size($bmp);
Returns bmp->clip, bmp->cl, bmp->cr, bmp->ct, bmp->cb.
($enable, $l, $r, $t, $b) = al_get_bitmap_clip($bmp);
Returns RLE sprite width and height.
($w, $h) = al_get_rle_size($rle);
Returns the color depth of an RLE sprite.
Takes points as al_polygon(bmp, color, x1, y1, x2, y2, x3, y3, x4, y4, ...) and calls polygon.
Returns mouse_x, mouse_y, mouse_z, mouse_b.
($x, $y, $z, $b) = al_get_mouse_info();
Returns the ascii and scancode values from ureadkey.
($ascii, $scan) = al_readkey();
Calls simulate_ukeypress.
Returns a value from the key[] array.
Returns key_shifts.
Returns the number of objects in a datafile.
Returns the datafile type.
dat may be either a pointer to a datafile object or a pointer to an array of datafile objects.
i is the index into the array, or -1 if dat is a datafile pointer.
-1
Returns the data pointer. dat and i are as in al_get_datafile_type.
Returns the specified datafile property.
dat and i are as above. str is a string specifying the property. See the Allegro documentation for valid datafile properties.
Returns num_joysticks.
Returns joy[i].flags, joy[i].num_sticks, joy[i].num_buttons, or undef if i is out of range.
($flags, $sticks, $buttons) = al_get_joystick_info($i);
Returns joy[i].button[b].b and joy[i].button[b].name, or undef if i or b are out of range.
($status, $name) = al_get_joystick_button($i, $b);
Returns joy[i].stick[s].flags, joy[i].stick[s].num_axis, and joy[i].stick[s].name, or undef if i or s are out of of range.
($flags, $axes, $name) = al_get_joystick_info($i, $s);
Returns analog position, digital position, and name of specified axis.
Analog is joy[i].stick[s].axis[a].pos. Digital is -1 for left/up, 1 for right/down, or 0 for centered (based on joy[i].stick[s].axis[a].d1 and d2). Name is joy[i].stick[s].axis[a].name.
1
0
($a, $d, $name) = al_get_joystick_info($i, $s, $a);
Sets freeze_mouse_flag to status.
Returns midi_pos, midi_loop_start, midi_loop_end.
($pos, $start, $end) = al_get_midi_info();
Mallocs a new palette and returns it.
Frees a previously allocated palette.
Sets pal's index i to the specified color. Colors are 0-255 instead of Allegro's 0-63.
Returns pal's red, green, blue values for index i. Colors are 0-255 instead of Allegro's 0-63.
($r, $g, $b) = al_get_palette_color($pal, $i);
Timers: the timer functions below use Allegro's timer system, but will not automatically call a Perl subroutine when fired.
They must be checked via al_get_timer_updates. See lib/Allegro/Timer.pm for an example.
Initializes a new timer. Returns an id to be used by the other timer routines below.
Starts a previously initialized timer.
id is the timer id and inteval is the time between timer updates. Returns true on success, false on failure.
Stops a timer.
id is the timer id.
Gets the number of times the timer code needs to be run.
Decrements the update count. This should be called after each run of the timer code.
Returns an AL_ID from the specified (four-letter) string.
Destroys a previously created COLOR_MAP.
Sets color_map.
Retrieves color_map.
Allocates and returns a COLOR_MAP created by create_blender_table() based on the current truecolor blender mode that is set.
The following are directly from the Allegro header files.
Allegro has many contributors, a list of which can be found on the Allegro website.
This Perl module and accompanying documentation is by Colin O'Leary <colino@cpan.org>.
Copyright 2003 by Colin O'Leary. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The Allegro library is copyright its authors, and is giftware. See http://alleg.sf.net for more information.
First official release.
First snapshot released; semi-complete.
Original version; created by h2xs 1.21 with options -A -n Allegro
To install Allegro, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Allegro
CPAN shell
perl -MCPAN -e shell install Allegro
For more information on module installation, please visit the detailed CPAN module installation guide.