The Allegro Wiki is migrating to github at

Allegro usage

From Allegro Wiki
Jump to: navigation, search
This article is incomplete and needs some revision or has some pending TODOs. Please help Allegro by editing and finishing it. When the article becomes complete, you may remove this tag.

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.


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


  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.


  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
  or Linux. On the other platforms this macro compiles to nothing, so you
  don't have to #ifdef around it. Example:

<highlightSyntax language="C"> int main(void)

        /* more stuff goes here */
        return 0;


  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 =] =;==</b>
  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.