Using Allegro



See readme.txt for a general introduction, copyright details, and information about how to compile Allegro.

All the Allegro functions, variables, and data structures are defined in allegro.h. You should include this in your programs, and link with liballeg.a. To do this you should:

- Put the following line at the beginning of all C or C++ files that use Allegro:

#include <allegro.h>

- If you compile from the command line or with a makefile, add '-lalleg' to the end of the gcc command, eg:

gcc foo.c -o foo.exe -lalleg

- If you are using Rhide, go to the Options/Libraries menu, type 'alleg' into the first empty space, and make sure the box next to it is checked.

- If you aren't using some parts of Allegro's functionality, you can slightly reduce your compilation times by defining any of the following preprocessor symbols before including allegro.h:

alleg_mouse_unused
alleg_timer_unused
alleg_keyboard_unused
alleg_joystick_unused
alleg_gfx_driver_unused
alleg_palette_unused
alleg_graphics_unused
alleg_vidmem_unused
alleg_flic_unused
alleg_sound_unused
alleg_file_unused
alleg_datafile_unused
alleg_math_unused
alleg_gui_unused

Please note that these defines will not affect your executable size, though! See towards the end of this file for information about how to remove unused code at the linking stage.

int allegro_init();
Initialises the Allegro library. It doesn't actually do very much except setting up some global variables, locking some memory, and installing allegro_exit() as an atexit() routine, but you must call it before doing anything else. Returns zero for success (at the moment it can't fail, so there is not much point checking the return value).

void allegro_exit();
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[];
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_WINNT      - Windows NT
      OSTYPE_OS2        - OS/2
      OSTYPE_WARP       - OS/2 Warp 3
      OSTYPE_DOSEMU     - Linux DOSEMU
      OSTYPE_OPENDOS    - Caldera OpenDOS
extern int windows_version, windows_sub_version;
These are set by allegro_init(), using int 0x2F, ax=0x1600 to detect the presence of Microsoft Windows. Under windows 3.1, windows_version will be set to 3, under win95 it will be 4, under NT it will be 0x100, and if windows isn't present it will be zero. Under Linux DOSEMU, they will both be set to -1.

void check_cpu();
Detects the CPU type, setting the following global variables:

extern char cpu_vendor[];
Set by check_cpu() to the CPU vendor name, if known.

extern int cpu_family;
Set by check_cpu() to the CPU type: 3=386, 4=486, 5=Pentium, 6=PPro, etc.

extern int cpu_model;
Set by check_cpu() to the CPU submodel. On a 386 (cpu_family=3), zero indicates a DX chip, 2 an SX, 4 an SL, and 15 is unknown. 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_fpu;
Set by check_cpu() to TRUE or FALSE, depending on whether a floating point processor is available.

extern int cpu_mmx;
Set by check_cpu() to TRUE or FALSE, depending on whether the MMX instruction set is available.

extern int cpu_3dnow;
Set by check_cpu() to TRUE or FALSE, depending on whether the 3DNow! instruction set is available.

extern int cpu_cpuid;
Set by check_cpu() to TRUE or FALSE, depending on whether the "cpuid" instruction was available (if this is set, the other CPU variables are 100% reliable, otherwise there may be some mistakes).



Back to Contents