See readme.txt for a general introduction, copyright details, and
information about how to install Allegro and link your program with it.
int install_allegro(int system_id, int *errno_ptr, int (*atexit_ptr)());
Initialises the Allegro library. You must call either this or
allegro_init() before doing anything other than using the Unicode
routines. If you want to use a text mode other than UTF-8, you can set
it with set_uformat() before you call this. The available system ID codes
will vary from one platform to another, but you will almost always want
to pass SYSTEM_AUTODETECT. Alternatively, SYSTEM_NONE installs a stripped
down version of Allegro that won't even try to touch your hardware or do
anything platform specific: this can be useful for situations where you
only want to manipulate memory bitmaps, such as the text mode datafile
tools or the Windows GDI interfacing functions. The errno_ptr and
atexit_ptr parameters should point to the errno variable and atexit
function from your libc: these are required because when Allegro is
linked as a DLL, it doesn't have direct access to your local libc data.
atexit_ptr may be NULL, in which case it is your responsibility to call
allegro_exit manually. Currently this function always returns zero. If no
system driver can be used, the program will abort.
Macro which initialises the Allegro library. This is the same thing as
calling install_allegro(SYSTEM_AUTODETECT, &errno, atexit).
Closes down the Allegro system. This includes returning the system to
text mode and removing whatever mouse, keyboard, and timer routines have
been installed. You don't normally need to bother making an explicit call
to this function, because allegro_init() installs it as an atexit()
routine so it will be called automatically when your program exits.
extern char allegro_id;
Text string containing a date and version number for the library, in case
you want to display these somewhere.
extern char allegro_error[ALLEGRO_ERROR_SIZE];
Text string used by set_gfx_mode() and install_sound() to report error
messages. If they fail and you want to tell the user why, this is the
place to look for a description of the problem.
extern int os_type;
Set by allegro_init() to one of the values:
OSTYPE_UNKNOWN - unknown, or regular MSDOS
OSTYPE_WIN3 - Windows 3.1 or earlier
OSTYPE_WIN95 - Windows 95
OSTYPE_WIN98 - Windows 98
OSTYPE_WINME - Windows ME
OSTYPE_WINNT - Windows NT
OSTYPE_WIN2000 - Windows 2000
OSTYPE_WINXP - Windows XP
OSTYPE_OS2 - OS/2
OSTYPE_WARP - OS/2 Warp 3
OSTYPE_DOSEMU - Linux DOSEMU
OSTYPE_OPENDOS - Caldera OpenDOS
OSTYPE_LINUX - Linux
OSTYPE_FREEBSD - FreeBSD
OSTYPE_UNIX - Unknown Unix variant
OSTYPE_BEOS - BeOS
OSTYPE_QNX - QNX
OSTYPE_MACOS - MacOS
extern int os_version;
extern int os_revision;
The major and minor version of the Operating System currently running.
Set by allegro_init(). If Allegro for some reason was not able to
retrieve the version of the Operating System, os_version and
os_revision will be set to -1. For example: Under Win98 SE (v4.10.2222)
os_version will be set to 4 and os_revision to 10.
extern int os_multitasking;
Set by allegro_init() to either TRUE or FALSE depending on whether your
Operating System is multitasking or not.
void allegro_message(const char *msg, ...);
Outputs a message, using a printf() format string. This function must
only be used when you aren't in graphics mode, eg. before calling
set_gfx_mode(), or after a set_gfx_mode(GFX_TEXT). On platforms that have
a text mode console (DOS, Unix and BeOS) it will print the string to the
console, attempting to work around codepage differences by reducing any
accented characters to 7 bit ASCII approximations, or under Windows it
will bring up a GUI message box.
void set_window_title(const char *name);
On platforms that are capable of it, this routine alters the window title
for your Allegro program. Note that Allegro cannot set the window title
when running in a DOS box under Windows.
int set_window_close_button(int enable);
On platforms that are capable of it, this routine disables or enables the
window close button for your Allegro program. You can call it before the
window is created if you wish. If the close button is successfully
disabled, this function returns zero.
On platforms where the close button either does not exist or cannot be
disabled, this function returns -1. If this happens, you may wish
to use set_window_close_hook() to handle the close event yourself.
When enabling the close button, the function will return the same value
for your platform as when disabling. That means it will return non-zero
if the button cannot be disabled, even though you are not trying to
Note that Allegro cannot manipulate the close button of a DOS box in
void set_window_close_hook(void (*proc)());
On platforms that have a close button, this routine installs a hook
function to handle the close event. In other words, when the user clicks
the close button on your program's window, the function you specify here
will be called.
This function should not generally attempt to exit the program or save
any data itself. The function could be called at any time, and there is
usually a risk of conflict with the main thread of the program. Instead,
you should set a flag during this function, and test it on a regular
basis in the main loop of the program.
Pass NULL to this function to restore the close button's default
functionality. On Windows and BeOS, the following message will appear:
Warning: forcing program shutdown may lead to data loss and unexpected
results. It is preferable to use the exit command inside the window.
This message will be translated into your selected language if a
translation is available in language.dat (see get_config_text()).
If the user clicks [Yes], the program will exit immediately in the same
style as Ctrl+Alt+End (see three_finger_flag).
In other operating systems, the program will exit immediately without
prompting the user.
Note that Allegro cannot intercept the close button of a DOS box in
On platforms that can run Allegro programs in a window on an existing
desktop, returns the currently selected desktop color depth (your program
is likely to run faster if it uses this same depth). On platforms where
this information is not available or does not apply, returns zero.
int get_desktop_resolution(int *width, int *height);
On platforms that can run Allegro programs in a window on an existing
desktop, this retrieves the current desktop resolution (e.g. you may want
to call this function before creating a large window because, with some
windowed drivers, a window cannot be created if it is larger than the
desktop). Returns zero on success, or a negative number if this
information is not available or does not apply, in which case the values
stored in width and height are unspecified.
On systems that support this, gives up the rest of the current scheduler
timeslice. Also known as the "play nice with multitasking" option.
Detects the CPU type, setting the following global variables. You don't
normally need to call this, because allegro_init() will do it for you.
extern char cpu_vendor;
Contains the CPU vendor name, if known (empty string on non-Intel
extern int cpu_family;
Contains the Intel CPU type, where applicable: 3=386, 4=486, 5=Pentium,
extern int cpu_model;
Contains the Intel CPU submodel, where applicable. On a 486
(cpu_family=4), zero or one indicates a DX chip, 2 an SX, 3 a 487 (SX) or
486 DX, 4 an SL, 5 an SX2, 7 a DX2 write-back enhanced, 8 a DX4 or DX4
overdrive, 14 a Cyrix, and 15 is unknown. On a Pentium chip
(cpu_family=5), 1 indicates a Pentium (510\66, 567\66), 2 is a Pentium
P54C, 3 is a Pentium overdrive processor, 5 is a Pentium overdrive for
IntelDX4, 14 is a Cyrix, and 15 is unknown.
extern int cpu_capabilities;
Contains CPU flags indicating what features are available on the current
CPU. The flags can be any combination of these:
CPU_ID - Indicates that the "cpuid" instruction is available. If this
is set, then all Allegro CPU variables are 100% reliable,
otherwise there may be some mistakes.
CPU_FPU - An x87 FPU is available.
CPU_MMX - Intel MMX instruction set is available.
CPU_MMXPLUS - Intel MMX+ instruction set is available.
CPU_SSE - Intel SSE instruction set is available.
CPU_SSE2 - Intel SSE2 instruction set is available.
CPU_3DNOW - AMD 3DNow! instruction set is available.
CPU_ENH3DNOW - AMD Enhanced 3DNow! instruction set is available.
CPU_CMOV - Pentium Pro "cmov" instruction is available.
You can check for multiple features by OR-ing the flags together.
For example, to check if the CPU has an FPU and MMX instructions
available, you'd do:
if ((cpu_capabilities & (CPU_FPU | CPU_MMX)) == (CPU_FPU | CPU_MMX))
printf("CPU has both an FPU and MMX instructions!\n");