# Using Allegro

- allegro_error
- allegro_exit
- allegro_id
- allegro_init
- allegro_message
- check_cpu
- cpu_capabilities
- cpu_family
- cpu_model
- cpu_vendor
- desktop_color_depth
- END_OF_MAIN
- get_desktop_resolution
- install_allegro
- os_multitasking
- os_revision
- os_type
- os_version
- set_close_button_callback
- set_window_title
- yield_timeslice

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 other functions that can be called before this one will be marked explicitly in the documentation.

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. Example:

>           install_allegro(SYSTEM_AUTODETECT, &errno, atexit);

Return value: 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.

> Examples using this: Available Allegro examples.

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.

Note that after you call this function, other functions like destroy_bitmap() will most likely crash. This is a problem for C++ global destructors, which usually get called after atexit(), so don't put Allegro calls in them. You can write the destructor code in another method which you can manually call before your program exits, avoiding this problem.

> See also: install_allegro, allegro_init, destroy_bitmap.

> Examples using this: ex3d, exscn3d, exswitch, exxfade, exzbuf.

Macro END_OF_MAIN()
In order to maintain cross-platform compatibility, you have to put this macro at the very end of your main function. This macro uses some ``magic'` to mangle your main procedure on platforms that need it like Windows, Linux or MacOS X. On the other platforms this macro compiles to nothing, so you don't have to #ifdef around it. Example:

>           int main(void)
>           {
>              allegro_init();
>              /* more stuff goes here */
>              ...
>              return 0;
>           }
>           END_OF_MAIN()

> See also: Windows specifics, Unix specifics, MacOS X specifics, Differences between platforms.

> Examples using this: Available Allegro examples.

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.

> Examples using this: Available Allegro examples.

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
>           OSTYPE_MACOSX     - MacOS X

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

> Examples using this: exdodgy.

void allegro_message(const char *text_format, ...);
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. Example:

>           ret = allegro_init();
>           if (ret != 0) {
>              allegro_message("Sorry, couldn't init Allegro (%d).\n", ret);
>              exit(ret);
>           }

> See also: set_uformat.

> Examples using this: Available Allegro examples.

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, set_uformat.

> Examples using this: exunicod.

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.

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.

Return value: Returns zero on success and non-zero on failure (e.g. the feature is not supported by the platform).

> See also: set_window_title.

int desktop_color_depth();
Finds out the currently selected desktop color depth. You can use this information to make your program use the same color depth as the desktop, which will likely make it run faster because the graphic driver won't be doing unnecessary color conversions behind your back.

Under some OSes, switching to a full screen graphics mode may automatically change the desktop color depth. You have, therefore, to call this function before setting any graphics mode in order to retrieve the real desktop color depth. Example:

>           allegro_init();
>           ...
>           if ((depth = desktop_color_depth()) != 0) {
>              set_color_depth(depth);
>           }

Return value: Returns the color depth or zero on platforms where this information is not available or does not apply.

> See also: get_desktop_resolution, set_color_depth, set_gfx_mode.

int get_desktop_resolution(int *width, int *height);
Finds out the currently selected desktop resolution. You can use this information to avoid creating windows bigger than the current resolution. This is especially important for some windowed drivers which are unable to create windows bigger than the desktop. Each parameter is a pointer to an integer where one dimension of the screen will be stored.

Under some OSes, switching to a full screen graphics mode may automatically change the desktop resolution. You have, therefore, to call this function before setting any graphics mode in order to retrieve the real desktop resolution. Example:

>           int width, height;

>           allegro_init();
>           ...
>           if (get_desktop_resolution(&width, &height) == 0) {
>              /* Got the resolution correctly */
>           }

Return value: 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 the variables you provided for ``width'` and ``height'` are undefined.

> See also: desktop_color_depth, set_gfx_mode.

void yield_timeslice();
To "play nice" with other processes you can call this function. On systems that support it, it will give up the rest of the current scheduler timeslice and offer it to some other process. Your CPU consumption rate will drop *only* if there is another process ready to use the freed timeslice.

Note that calling this inside your active game loop is a very bad idea, you never know when the OS will give you the CPU back, so you could end up missing the vertical retrace and skipping frames.

> See also: vsync.

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, allegro_init.

extern char cpu_vendor[];
Contains the CPU vendor name, if known (empty string on non-Intel platforms). You can read this variable after you have called check_cpu() (which is automatically called by allegro_init()).

> See also: check_cpu, cpu_family, cpu_model, cpu_capabilities, allegro_init.

extern int cpu_family;
Contains the Intel CPU type, where applicable: 3=386, 4=486, 5=Pentium, 6=PPro, etc. You can read this variable after you have called check_cpu() (which is automatically called by allegro_init()).

> See also: check_cpu, cpu_vendor, cpu_model, cpu_capabilities, allegro_init.

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. You can read this variable after you have called check_cpu() (which is automatically called by allegro_init()).

> See also: check_cpu, cpu_vendor, cpu_family, cpu_capabilities, allegro_init.

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

You can read this variable after you have called check_cpu() (which is automatically called by allegro_init()).

> See also: check_cpu, cpu_vendor, cpu_family, cpu_model, cpu_capabilities, allegro_init.

Back to contents