Allegro-Manual-4.2.1.En.Pdf
Total Page:16
File Type:pdf, Size:1020Kb
______ ___ ___ /\ _ \ /\_ \ /\_ \ \ \ \L\ \\//\ \ \//\ \ __ __ _ __ ___ \ \ __ \ \ \ \ \ \ \ /’__‘\ /’_ ‘\/\‘’__\/ __‘\ \ \ \/\ \ \_\ \_ \_\ \_/\ __//\ \L\ \ \ \//\ \L\ \ \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/ \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/ /\____/ \_/__/ Version 4.2.1 A game programming library. By Shawn Hargreaves, Nov 26, 2006. See the AUTHORS file for a complete list of contributors. #include <std disclaimer.h> "I do not accept responsibility for any effects, adverse or otherwise, that this code may have on you, your computer, your sanity, your dog, and anything else that you can think of. Use it at your own risk." Chapter 1: API 1 1 API 1.1 Using Allegro See readme.txt for a general introduction, copyright details, and information about how to install Allegro and link your program with it. 1.1.1 install allegro 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() man- ually. Example: install_allegro(SYSTEM_AUTODETECT, &errno, atexit); 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: See Section 1.1.2 [allegro init], page 1. See Section 1.1.3 [allegro exit], page 2. See Section 1.3.1 [set uformat], page 26. See Section 1.4.1 [set config file], page 51. 1.1.2 allegro init int allegro_init(); Macro which initialises the Allegro library. This is the same thing as calling install allegro(SYSTEM AUTODETECT, &errno, atexit). See also: See Section 1.1.1 [install allegro], page 1. 2 Allegro Manual See Section 1.1.3 [allegro exit], page 2. See Section 3.4 [Available], page 397. 1.1.3 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. 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: See Section 1.1.1 [install allegro], page 1. See Section 1.1.2 [allegro init], page 1. See Section 1.10.9 [destroy bitmap], page 127. See Section 3.4.34 [ex3d], page 430. See Section 3.4.38 [exscn3d], page 435. See Section 3.4.47 [exswitch], page 447. See Section 3.4.31 [exxfade], page 426. See Section 3.4.39 [exzbuf], page 437. 1.1.4 END OF MAIN 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() Chapter 1: API 3 See also: See Section 2.2 [Windows], page 365. See Section 2.3 [Unix], page 374. See Section 2.6 [MacOS], page 382. See Section 2.7 [Differences], page 384. See Section 3.4 [Available], page 397. 1.1.5 allegro id extern char allegro_id[]; Text string containing a date and version number for the library, in case you want to display these somewhere. 1.1.6 allegro error extern char allegro_error[ALLEGRO_ERROR_SIZE]; Text string used by set gfx mode(), install sound() and other functions to re- port 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: See Section 1.9.7 [set gfx mode], page 110. See Section 1.25.5 [install sound], page 245. See Section 3.4 [Available], page 397. 1.1.7 ALLEGRO VERSION #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. 4 Allegro Manual 1.1.8 ALLEGRO SUB VERSION #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. 1.1.9 ALLEGRO WIP VERSION #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. 1.1.10 ALLEGRO VERSION STR #define ALLEGRO_VERSION_STR Defined to a text string containing all version numbers and maybe some ad- ditional text. This could be ‘4.1.16 (CVS)’ for an Allegro version obtained straight from the CVS repository. 1.1.11 ALLEGRO DATE STR #define ALLEGRO_DATE_STR Defined to a text string containing the year this version of Allegro was released, like ‘2004’. 1.1.12 ALLEGRO DATE #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); 1.1.13 AL ID 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: See Section 1.32.13 [DAT ID], page 304. Chapter 1: API 5 1.1.14 MAKE VERSION 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: See Section 1.1.7 [ALLEGRO VERSION], page 3. See Section 1.1.8 [ALLEGRO SUB VERSION], page 4. See Section 1.1.9 [ALLEGRO WIP VERSION], page 4. 1.1.15 os type 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 6 Allegro Manual 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: See Section 1.1.2 [allegro init], page 1. See Section 1.1.16 [os version], page 6. See Section 1.1.17 [os multitasking], page 6. 1.1.16 os version 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: See Section 1.1.15 [os type], page 5.