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. Currently this function always returns zero. If no system driver can be used, the program will abort.

int allegro_init();
Macro which initialises the Allegro library. This is the same thing as calling install_allegro(SYSTEM_AUTODETECT, &errno, atexit).

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[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_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 disable it.

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

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.

Proceed anyway?

[Yes] [No]

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 Windows.

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.

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.

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.

extern char cpu_vendor[];
Contains the CPU vendor name, if known (empty string on non-Intel platforms).

extern int cpu_family;
Contains the Intel CPU type, where applicable: 3=386, 4=486, 5=Pentium, 6=PPro, etc.

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");