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

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, set_config_file.
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, some flavours of UNIX 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(), install_sound() and other functions 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. Example: 
      void abort_on_error(const char *message)
      {
         if (screen != NULL)
            set_gfx_mode(GFX_TEXT, 0, 0, 0, 0);

         allegro_message("%s.\nLast Allegro error `%s'\n",
                         message, allegro_error);
         exit(-1);
      }
      ...
         if (some_allegro_function() == ERROR_CODE)
            abort_on_error("Error calling some function!");
See also: set_gfx_mode, install_sound.
Examples using this: Available Allegro examples.
#define ALLEGRO_VERSION

Defined to the major version of Allegro. From a version number like 4.1.16, this would be defined to the integer 4.


#define ALLEGRO_SUB_VERSION

Defined to the middle version of Allegro. From a version number like 4.1.16, this would be defined to the integer 1.


#define ALLEGRO_WIP_VERSION

Defined to the minor version of Allegro. From a version number like 4.1.16, this would be defined to the integer 16.


#define ALLEGRO_VERSION_STR

Defined to a text string containing all version numbers and maybe some additional text. This could be `4.2.1 (SVN)' for an Allegro version obtained straight from the SVN repository.


#define ALLEGRO_DATE_STR

Defined to a text string containing the year this version of Allegro was released, like `2004'.


#define ALLEGRO_DATE

Defined to an integer containing the release date of Allegro in the packed format `yyyymmdd'. Example: 
      const int year = ALLEGRO_DATE / 10000;
      const int month = (ALLEGRO_DATE / 100) % 100;
      const int day = ALLEGRO_DATE % 100;

      allegro_message("Year %d, month %d, day %d\n",
         year, month, day);


Macro AL_ID(a,b,c,d)

This macro can be used to create a packed 32 bit integer from 8 bit characters, on both 32 and 64 bit machines. These can be used for various things, like custom datafile objects or system IDs. Example: 
      #define OSTYPE_LINUX       AL_ID('T','U','X',' ')
See also: DAT_ID.
Macro MAKE_VERSION(a, b, c)

This macro can be used to check if some Allegro version is (binary) compatible with the current version. It is safe to use > and < to check if one version is more recent than another. The third number is ignored if the second number is even, so MAKE_VERSION(4, 2, 0) is equivalent to MAKE_VERSION(4, 2, 1). This is because of our version numbering policy since 4.0.0: the second number is even for stable releases, which must be ABI-compatible with earlier versions of the same series. This macro is mainly useful for addon packages and libraries. See the `ABI compatibility information' section of the manual for more detailed information. Example: 
      /* Check if the current version is compatible with Allegro 4.2.0 */
      #if (MAKE_VERSION(4, 2, 0) <= MAKE_VERSION(ALLEGRO_VERSION, \
                         ALLEGRO_SUB_VERSION, ALLEGRO_WIP_VERSION))
         /* Allegro 4.2.0 compatibility */
      #else
         /* Work-around */
      #endif
See also: ALLEGRO_VERSION, ALLEGRO_SUB_VERSION, ALLEGRO_WIP_VERSION.
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_WIN2003    - Windows 2003
      OSTYPE_WINVISTA   - Windows Vista
      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.
void allegro_message(const char *text_format, ...);

Outputs a message, using a printf() format string. Usually you want to use this to report messages to the user in an OS independent way when some Allegro subsystem cannot be initialised. But you must not use this function if you are in a graphic mode, only before calling set_gfx_mode(), or after a set_gfx_mode(GFX_TEXT). Also, this function depends on a system driver being installed, which means that it won't display the message at all on some platforms if Allegro has not been initialised correctly.

On platforms featuring a windowing system, it will bring up a blocking GUI message box. If there is no windowing system, it will try to print the string to a text console, attempting to work around codepage differences by reducing any accented characters to 7-bit ASCII approximations. Example: 

      if (allegro_init() != 0)
         exit(1);

      if (init_my_data() != 0) {
         allegro_message("Sorry, missing game data!\n");
         exit(2);
      }
See also: allegro_init, install_allegro, 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. Example: 
      set_window_title("Allegro rules!");
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.

Also note that the supplied callback is also called under MacOS X when the user hits Command-Q or selects "Quit" from the application menu. Example: 

      volatile int close_button_pressed = FALSE;

      void close_button_handler(void)
      {
         close_button_pressed = TRUE;
      }
      END_OF_FUNCTION(close_button_handler)
      ...
      
      allegro_init();
      LOCK_FUNCTION(close_button_handler);
      set_close_button_callback(close_button_handler);
      ...
         
      while (!close_button_pressed)
         do_stuff();

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 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[];

On Intel PCs, contains the CPU vendor name if known. On Mac OSX systems this contains the PPC subtype name. On other platforms, this may be an empty string. 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 type, where applicable. Allegro defines the following CPU family types: 
      CPU_FAMILY_UNKNOWN  - The type of processor is unknown
      CPU_FAMILY_I386     - The processor is an Intel-compatible 386
      CPU_FAMILY_I486     - The processor is an Intel-compatible 486
      CPU_FAMILY_I586     - The processor is a Pentium or equivalent
      CPU_FAMILY_I686     - The processor is a Pentium Pro, II, III
                            or equivalent
      CPU_FAMILY_ITANIUM  - The processor is an Itanium processor
      CPU_FAMILY_POWERPC  - The processor is a PowerPC processor
      CPU_FAMILY_EXTENDED - The processor type needs to be read
                            from the cpu_model
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 CPU submodel, where applicable. Allegro defines at least the following CPU family types (see include/allegro/system.h for a more complete list): 
      CPU_FAMILY_I586:
         CPU_MODEL_PENTIUM, CPU_MODEL_K5, CPU_MODEL_K6

      CPU_FAMILY_I686:
         CPU_MODEL_PENTIUMPRO, CPU_MODEL_PENTIUMII,
         CPU_MODEL_PENTIUMIIIKATMAI, CPU_MODEL_PENTIUMIIICOPPERMINE,
         CPU_MODEL_ATHLON, CPU_MODEL_DURON

      CPU_FAMILY_EXTENDED:
         CPU_MODEL_PENTIUMIV, CPU_MODEL_XEON,
         CPU_MODEL_ATHLON64, CPU_MODEL_OPTERON

      CPU_FAMILY_POWERPC:
         CPU_MODEL_POWERPC_x, for x=601-604, 620, 750, 7400, 7450
You can read this variable after you have called check_cpu() (which is automatically called by allegro_init()). Make sure you check the cpu_family and cpu_vendor so you know which models make sense to check.
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 FPU is available.
      CPU_IA64     - Running on Intel 64 bit CPU
      CPU_AMD64    - Running on AMD 64 bit CPU
      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_SSE3     - Intel SSE3 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