Using Allegro

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.

This function returns zero on success and non-zero on failure (e.g. no system driver could be used). Note: in previous versions of Allegro this function would abort on error.

See also: allegro_init, allegro_exit, set_uformat.
int allegro_init();

Macro which initialises the Allegro library. This is the same thing as calling install_allegro(SYSTEM_AUTODETECT, &errno, atexit).
See also: install_allegro, allegro_exit.
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.
See also: install_allegro, allegro_init.
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.
See also: set_gfx_mode, install_sound.
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_SUNOS      - SunOS/Solaris
      OSTYPE_FREEBSD    - FreeBSD
      OSTYPE_NETBSD     - NetBSD
      OSTYPE_IRIX       - IRIX
      OSTYPE_DARWIN     - Darwin
      OSTYPE_QNX        - QNX
      OSTYPE_UNIX       - Unknown Unix variant
      OSTYPE_BEOS       - BeOS
      OSTYPE_MACOS      - MacOS
See also: allegro_init, os_version, os_multitasking.
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.
See also: os_type, os_multitasking.
extern int os_multitasking;

Set by allegro_init() to either TRUE or FALSE depending on whether your Operating System is multitasking or not.
See also: os_type, os_version.
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 console (DOS and Unix) it will print the string to that console, attempting to work around codepage differences by reducing any accented characters to 7 bit ASCII approximations, and on platforms featuring a windowing system 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.
See also: set_close_button_callback.
int set_close_button_callback(void (*proc)(void));

On platforms that have a close button, this routine installs a callback function to handle the close event. In other words, when the user clicks the close button on your program's window or any equivalent device, the function you specify here will be called. Returns 0 on success and non-zero on failure (e.g. the feature is not supported by the platform).

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 as the 'proc' argument to this function to disable the close button functionality, which is the default state.

Note that Allegro cannot intercept the close button of a DOS box in Windows.

See also: set_window_title.
int desktop_color_depth();

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.
See also: get_desktop_resolution.
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.
See also: desktop_color_depth.
void yield_timeslice();

On systems that support this, gives up the rest of the current scheduler timeslice. Also known as the "play nice with multitasking" option.


void check_cpu();

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.
See also: cpu_vendor, cpu_family, cpu_model, cpu_capabilities.
extern char cpu_vendor[];

Contains the CPU vendor name, if known (empty string on non-Intel platforms).
See also: check_cpu, cpu_family, cpu_model, cpu_capabilities.
extern int cpu_family;

Contains the Intel CPU type, where applicable: 3=386, 4=486, 5=Pentium, 6=PPro, etc.
See also: check_cpu, cpu_vendor, cpu_model, cpu_capabilities.
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.
See also: check_cpu, cpu_vendor, cpu_family, cpu_capabilities.
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");
      }
See also: check_cpu, cpu_vendor, cpu_family, cpu_model, cpu_capabilities.
Back to contents