Unit allegro

This function 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:

VAR
  OSTYPE_LINUX: LONGINT;
BEGIN
  OSTYPE_LINUX := AL_ID('TUX ');
END;
  

Initialises the Allegro library. You must call either this or al_init before doing anything other. The functions that can be called before this one will be marked explicitly in the documentation, like al_set_config_file.

The available system ID codes will vary from one platform to another, but you will almost always want to pass AL_SYSTEM_AUTODETECT. Alternatively, AL_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.

Parameters

system_id

Identification of the system.

Returns

True on success or False on failure (e.g. no system driver could be used).

See also

al_exit

Closes down the Allegro system.

al_set_uformat

Sets the current text encoding format.

al_set_config_file

Sets the configuration file to be used by all subsequent config functions.

Function which initialises the Allegro library. This is the same thing as calling al_install (AL_SYSTEM_AUTODETECT).

Returns

True on success or False on failure (e.g. no system driver could be used).

See also

al_exit

Closes down the Allegro system.

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 it will be called automatically when your program exits.

Note that after you call this function, other functions like al_destroy_bitmap will most likely crash. This might be a problem for some Object Pascal programs, depending where the destructors are called.

See also

al_install

Initialises the Allegro library.

al_init

Function which initialises the Allegro library.

Outputs a message. Usually you want to use this to report messages to the user in an OS independant 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 al_set_gfx_mode, or after a al_set_gfx_mode (AL_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 NOT al_init THEN
    EXIT (1);
  IF NOT init_my_data THEN
  BEGIN
    al_message ('Sorry, missing game data!\n');
    EXIT (2);
  END;
  

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 Nil as the `proc' argument to this function to disable the close button functionality, which is the default state.

Example:

VAR
  CloseButtonPressed: BOOLEAN = FALSE;

PROCEDURE CloseButtonHandler; CDECL;
BEGIN
  ClosePuttonPressed := TRUE;
END;

    ...
  al_init;
  al_set_close_button_callback (@CloseButtonHandler);
    ...
  WHILE NOT ClosePuttonPressed DO
    DoStuff;
  

Returns

True on success or False on failure (e.g. the feature is not supported by the platform).

See also

al_set_window_title

On platforms that are capable of it, this routine alters the window title for your Allegro program.

Detects the CPU type, setting the following global variables. You don't normally need to call this, because al_init will do it for you.

See also

al_cpu_vendor

On Intel PCs, contains the CPU vendor name if known.

al_cpu_family

Contains the CPU type, where applicable.

al_cpu_model

Contains the CPU submodel, where applicable.

al_cpu_capabilities

Contains CPU flags indicating what features are available on the current CPU.

On platforms that are capable of it, this routine alters the window title for your Allegro program.

Parameters

title

Title string.

See also

al_set_close_button_callback

On platforms that have a close button, this routine installs a callback function to handle the close event.

al_set_uformat

Sets the current text encoding format.

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.

Returns

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

See also

al_get_desktop_resolution

Finds out the currently selected desktop resolution.

al_set_color_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap.

al_set_gfx_mode

Switches into graphics mode.

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.

Parameters

w

Width desktop resolution.

h

Height desktop resolution.

Returns

True on success, or False 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

al_desktop_color_depth

Finds out the currently selected desktop color depth.

al_set_gfx_mode

Switches into graphics mode.

Sets the current text encoding format. This will affect all parts of Allegro, wherever you see a function that returns a string, or takes a string as a parameter.

Although you can change the text format on the fly, this is not a good idea. Many strings, for example the names of your hardware drivers and any language translations, are loaded when you call al_init, so if you change the encoding format after this, they will be in the wrong format, and things will not work properly. Generally you should only call al_set_uformat once, before al_init, and then leave it on the same setting for the duration of your program.

Parameters

type

Should be one of these values: AL_U_ASCII, AL_U_ASCII_CP, AL_U_UNICODE, AL_U_UTF8.

See also

al_get_uformat

Finds out what text encoding format is currently selected.

al_set_ucodepage

When you select the AL_U_ASCII_CP encoding mode, a set of tables are used to convert between 8-bit characters and their Unicode equivalents.

Finds out what text encoding format is currently selected. This function is probably useful only if you are writing an Allegro addon dealing with text strings and you use a different codepath for each possible format.

Returns

The currently selected text encoding format.

See also

al_set_uformat

Sets the current text encoding format.

When you select the AL_U_ASCII_CP encoding mode, a set of tables are used to convert between 8-bit characters and their Unicode equivalents. You can use this function to specify a custom set of mapping tables, which allows you to support different 8-bit codepages.

Allegro will use the table parameter when it needs to convert an ASCII string to an Unicode string. But when Allegro converts an Unicode string to ASCII, it will use both parameters. First, it will loop through the table parameter looking for an index position pointing at the Unicode value it is trying to convert (ie. the table parameter is also used for reverse matching). If that fails, the extras list is used. If that fails too, Allegro will put the character `ˆ', giving up the conversion.

Note that Allegro comes with a default parameters set internally. The default table will convert 8-bit characters to `ˆ'. The default extras list reduces Latin-1 and Extended-A characters to 7 bits in a sensible way (eg. an accented vowel will be reduced to the same vowel without the accent).

Parameters

table

Points to an array of 256 short integers, which contain the Unicode value for each character in your codepage.

extras

If not Nil, points to a list of mapping pairs, which will be used when reducing Unicode data to your codepage. Each pair consists of a Unicode value, followed by the way it should be represented in your codepage. The list is terminated by a zero Unicode value. This allows you to create a many->one mapping, where many different Unicode characters can be represented by a single codepage value (eg. for reducing accented vowels to 7-bit ASCII).

See also

al_set_uformat

Sets the current text encoding format.

Returns

The number of characters in the string. Note that this doesn't have to equal the string's size in bytes.

Converts the specified string s from _type to newtype, it checks before doing the conversion, and doesn't bother if the string formats are already the same (either both types are equal, or one is ASCII, the other is UTF-8, and the string contains only 7-bit ASCII characters).

See also

al_set_uformat

Sets the current text encoding format.

al_uconvert_ascii

Converts strings from ASCII into the current encoding format.

al_uconvert_toascii

Converts strings from the current encoding format into ASCII.

Converts strings from ASCII into the current encoding format.

See also

al_uconvert

Converts the specified string s from _type to newtype, it checks before doing the conversion, and doesn't bother if the string formats are already the same (either both types are equal, or one is ASCII, the other is UTF-8, and the string contains only 7-bit ASCII characters).

al_uconvert_toascii

Converts strings from the current encoding format into ASCII.

Converts strings from the current encoding format into ASCII.

See also

al_uconvert

Converts the specified string s from _type to newtype, it checks before doing the conversion, and doesn't bother if the string formats are already the same (either both types are equal, or one is ASCII, the other is UTF-8, and the string contains only 7-bit ASCII characters).

al_uconvert_ascii

Converts strings from ASCII into the current encoding format.

Sets the configuration file to be used by all subsequent config functions. (Allegro will not search for this file in other locations as it does with allegro.cfg at the time of initialization.)

All pointers returned by previous calls to al_get_config_string and other related functions are invalidated when you call this function! You can call this function before al_install to change the configuration file, but after al_set_uformat if you want to use a text encoding format other than the default.

See also

al_set_config_data

Specifies a block of data to be used by all subsequent config functions, which you have already loaded from disk (eg.

al_override_config_file

Specifies a file containing config overrides.

al_push_config_state

Pushes the current configuration state (filename, variable values, etc).

al_set_config_string

Writes a string variable to the current config file, replacing any existing value it may have, or removes the variable if val is empty.

Specifies a block of data to be used by all subsequent config functions, which you have already loaded from disk (eg. as part of some more complicated format of your own, or in a grabber datafile). This routine makes a copy of the information, so you can safely free the data after calling it.

See also

al_set_config_file

Sets the configuration file to be used by all subsequent config functions.

al_override_config_data

Version of al_override_config_file which uses a block of data that has already been read into memory.

al_push_config_state

Pushes the current configuration state (filename, variable values, etc).

al_set_config_string

Writes a string variable to the current config file, replacing any existing value it may have, or removes the variable if val is empty.

Specifies a file containing config overrides. These settings will be used in addition to the parameters in the main config file, and where a variable is present in both files this version will take priority. This can be used by application programmers to override some of the config settings from their code, while still leaving the main config file free for the end user to customise. For example, you could specify a particular sample frequency and IBK instrument file, but the user could still use an allegro.cfg file to specify the port settings and irq numbers.

The override config file will not only take precedence when reading, but will also be used for storing values. When you are done with using the override config file, you can call al_override_config_file with an empty string as parameter, so config data will be directly read from the current config file again.

Note: The override file is completely independent from the current configuration. You can e.g. call al_set_config_file, and the override file will still be active. Also the al_flush_config_file function will only affect the current config file (which can be changed with al_set_config_file), never the overriding one specified with this function. The modified override config is written back to disk whenever you call al_override_config_file.

Note that this function and al_override_config_data are mutually exclusive, i.e. calling one will cancel the effects of the other.

Version of al_override_config_file which uses a block of data that has already been read into memory. The length of the block has to be specified in bytes.

Note that this function and al_override_config_file are mutually exclusive, i.e. calling one will cancel the effects of the other.

Writes the current config file to disk if the contents have changed since it was loaded or since the latest call to the function.

See also

al_set_config_file

Sets the configuration file to be used by all subsequent config functions.

al_override_config_file

Specifies a file containing config overrides.

al_push_config_state

Pushes the current configuration state (filename, variable values, etc).

Pushes the current configuration state (filename, variable values, etc). onto an internal stack, allowing you to select some other config source and later restore the current settings by calling al_pop_config_state. This function is mostly intended for internal use by other library functions, for example when you specify a config filename to the al_save_joystick_data function, it pushes the config state before switching to the file you specified.

See also

al_set_config_file

Sets the configuration file to be used by all subsequent config functions.

Pops a configuration state previously stored by al_push_config_state, replacing the current config source with it.

Retrieves a string variable from the current config file. The section name may be set to an empty string to read variables from the root of the file, or used to control which set of parameters (eg. sound or joystick) you are interested in reading. Example:

VAR
  Lang: STRING;
  ...
  Lang := al_get_config_string ('system', 'language', 'EN');
  

Returns

the string to the constant string found in the configuration file. If the named variable cannot be found, or its entry in the config file is empty, the value of def is returned.

See also

al_set_config_file

Sets the configuration file to be used by all subsequent config functions.

al_set_config_string

Writes a string variable to the current config file, replacing any existing value it may have, or removes the variable if val is empty.

al_get_config_int

Reads an integer variable from the current config file.

al_get_config_hex

Reads an integer variable from the current config file, in hexadecimal.

al_get_config_float

Reads a floating point variable from the current config file.

Reads an integer variable from the current config file. See the comments about al_get_config_string.

Reads an integer variable from the current config file, in hexadecimal. See the comments about al_get_config_string.

Reads a floating point variable from the current config file. See the comments about al_get_config_string.

Reads a 4-letter driver ID variable from the current config file. See the comments about al_get_config_string.

Writes a string variable to the current config file, replacing any existing value it may have, or removes the variable if val is empty. The section name may be set to a empty string to write the variable to the root of the file, or used to control which section the variable is inserted into. The altered file will be cached in memory, and not actually written to disk until you call al_exit. Note that you can only write to files in this way, so the function will have no effect if the current config source was specified with al_set_config_data rather than al_set_config_file.

As a special case, variable or section names that begin with a '#' character are treated specially and will not be read from or written to the disk. Addon packages can use this to store version info or other status information into the config module, from where it can be read with the al_get_config_string function.

See also

al_set_config_file

Sets the configuration file to be used by all subsequent config functions.

al_get_config_string

Retrieves a string variable from the current config file.

al_set_config_int

Writes an integer variable to the current config file.

al_set_config_hex

Writes an integer variable to the current config file, in hexadecimal format.

al_set_config_float

Writes a floating point variable to the current config file.

Writes an integer variable to the current config file. See the comments about al_set_config_string.

Writes an integer variable to the current config file, in hexadecimal format. See the comments about al_set_config_string.

Writes a floating point variable to the current config file. See the comments about al_set_config_string.

Writes a 4-letter driver ID variable to the current config file. See the comments about al_set_config_string.

Installs the Allegro timer interrupt handler. You must do this before installing any user timer routines, and also before displaying a mouse pointer and playing FLI animations or MIDI music.

Returns

True on success, or False on failure (but you may decide not to check the return value as this function is very unlikely to fail).

See also

al_remove_timer

Removes the Allegro timer handler.

al_install_int

Installs a user timer handler, with the speed given as the number of milliseconds between ticks.

Removes the Allegro timer handler. You don't normally need to bother calling this, because al_exit will do it for you.

See also

al_install_timer

Installs the Allegro timer interrupt handler.

Adds a function to the list of user timer handlers or, if it is already installed, retroactively adjusts its speed (i.e makes as though the speed change occurred precisely at the last tick). The speed is given in hardware clock ticks, of which there are 1193181 a second. You can convert from other time formats to hardware clock ticks with the functions AL_SECS_TO_TIMER, AL_MSEC_TO_TIMER, AL_BPS_TO_TIMER and AL_BPM_TO_TIMER.

There can only be sixteen timers in use at a time, and some other parts of Allegro (the mouse pointer display routines, al_rest, the FLI player, and the MIDI player) need to install handlers of their own, so you should avoid using too many at the same time. If you call this routine without having first installed the timer module, al_install_timer will be called automatically.

Your function will be called by the Allegro interrupt handler and not directly by the processor, so it can be a normal CDECL function. You should be aware, however, that it will be called in an interrupt context, which imposes a lot of restrictions on what you can do in it. It should not use large amounts of stack, it must not make any calls to the operating system, use the run-time library functions, or contain any floating point code, and it must execute very quickly. Don't try to do lots of complicated code in a timer handler: as a general rule you should just set some flags and respond to these later in your main control loop.

Returns

True on success, or False if there is no room to add a new user timer.

See also

al_remove_int

Removes a function from the list of user interrupt routines.

al_install_int

Installs a user timer handler, with the speed given as the number of milliseconds between ticks.

al_install_param_int_ex

Like al_install_int_ex, but the callback routine will be passed a copy of the specified void pointer parameter.

Installs a user timer handler, with the speed given as the number of milliseconds between ticks. This is the same thing as al_install_int_ex (@proc, AL_MSEC_TO_TIMER (speed)). If you call this routine without having first installed the timer module, al_install_timer will be called automatically. Calling again this routine with the same timer handler as parameter allows you to adjust its speed.

Returns

True on success, or False if there is no room to add a new user timer.

See also

al_remove_int

Removes a function from the list of user interrupt routines.

al_install_int_ex

Adds a function to the list of user timer handlers or, if it is already installed, retroactively adjusts its speed (i.e makes as though the speed change occurred precisely at the last tick).

al_install_param_int

Like al_install_int, but the callback routine will be passed a copy of the specified void pointer parameter.

Removes a function from the list of user interrupt routines. al_exit does this automatically.

See also

al_install_int

Installs a user timer handler, with the speed given as the number of milliseconds between ticks.

al_remove_param_int

Like al_remove_int, but for use with timer callbacks that have parameter values.

Like al_install_int_ex, but the callback routine will be passed a copy of the specified void pointer parameter. To disable the handler, use al_remove_param_int instead of al_remove_int.

Like al_install_int, but the callback routine will be passed a copy of the specified void pointer parameter. To disable the handler, use al_remove_param_int instead of al_remove_int.

Like al_remove_int, but for use with timer callbacks that have parameter values. If there is more than one copy of the same callback active at a time, it identifies which one to remove by checking the parameter value (so you can't have more than one copy of a handler using an identical parameter).

See also

al_install_param_int

Like al_install_int, but the callback routine will be passed a copy of the specified void pointer parameter.

al_remove_int

Removes a function from the list of user interrupt routines.

Give the number of seconds between each tick to al_install_int_ex.

Give the number of milliseconds between each tick to al_install_int_ex.

Give the number of ticks each second to al_install_int_ex.

Give the number of ticks each minute to al_install_int_ex.

This function waits for the specified number of milliseconds.

Passing 0 as parameter will not wait, but just yield. This can be useful in order to "play nice" with other processes. Other values will cause CPU time to be dropped on most platforms. This will look better to users, and also does things like saving battery power and making fans less noisy.

Note that calling this inside your active game loop is a bad idea, as you never know when the OS will give you the CPU back, so you could end up missing the vertical retrace and skipping frames. On the other hand, on multitasking operating systems it is good form to give up the CPU for a while if you will not be using it.

Like al_rest, but for non-zero values continually calls the specified function while it is waiting for the required time to elapse. If the provided callback parameter is Nil, this function does exactly the same thing as calling al_rest.

Installs the Allegro keyboard interrupt handler. You must call this before using any of the keyboard input routines. Once you have set up the Allegro handler, you can no longer use operating system calls or the run-time library functions to access the keyboard.

Note that on some platforms the keyboard won't work unless you have set a graphics mode, even if this function returns a success value before calling al_set_gfx_mode. This can happen in environments with graphic windowed modes, since Allegro usually reads the keyboard through the graphical window (which appears after the al_set_gfx_mode call).

Returns

True on success, or False on failure (but you may decide not to check the return value as this function is very unlikely to fail).

See also

al_remove_keyboard

Removes the keyboard handler, returning control to the operating system.

al_poll_keyboard

Wherever possible, Allegro will read the keyboard input asynchronously (ie.

al_key

Array of flags indicating the state of each key, ordered by scancode.

al_keypressed

Returns True if there are keypresses waiting in the input buffer.

al_readkey

Returns the next character from the keyboard buffer, in ASCII format.

al_ureadkey

Returns the next character from the keyboard buffer, in Unicode format.

al_keyboard_lowlevel_callback

If set, this function is called by the keyboard handler in response to every keyboard event, both presses (including keyboard repeat rate) and releases.

al_three_finger_flag

The DJGPP keyboard handler provides an 'emergency exit' sequence which you can use to kill off your program.

al_key_led_flag

By default, the capslock, numlock, and scroll-lock keys toggle the keyboard LED indicators when they are pressed.

al_set_leds

Overrides the state of the keyboard LED indicators.

al_set_keyboard_rate

Sets the keyboard repeat rate.

Removes the keyboard handler, returning control to the operating system. You don't normally need to bother calling this, because al_exit will do it for you. However, you might want to call this during runtime if you want to change the keyboard mapping on those platforms were keyboard mappings are needed. You would first modify the configuration variable holding the keyboard mapping and then reinstall the keyboard handler.

Wherever possible, Allegro will read the keyboard input asynchronously (ie. from inside an interrupt handler), but on some platforms that may not be possible, in which case you must call this routine at regular intervals to update the keyboard state variables.

To help you test your keyboard polling code even if you are programming on a platform that doesn't require it, after the first time that you call this function Allegro will switch into polling mode, so from that point onwards you will have to call this routine in order to get any keyboard input at all, regardless of whether the current driver actually needs to be polled or not.

The al_keypressed, al_readkey, and al_ureadkey functions call al_poll_keyboard automatically, so you only need to use this function when accessing the al_key array and al_key_shifts variable.

Returns

zero on success or a negative on failure (ie. no keyboard driver installed).

Returns True if the current keyboard driver is operating in polling mode.

Returns True if there are keypresses waiting in the input buffer. You can use this to see if the next call to al_readkey is going to block or to simply wait for the user to press a key while you still update the screen possibly drawing some animation. Example:

  WHILE NOT al_keypressed DO
    AnimateLogo (al_screen);
   

See also

al_install_keyboard

Installs the Allegro keyboard interrupt handler.

al_readkey

Returns the next character from the keyboard buffer, in ASCII format.

al_simulate_keypress

Stuffs a key into the keyboard buffer, just as if the user had pressed it.

al_clear_keybuf

Empties the keyboard buffer.

Returns the next character from the keyboard buffer, in ASCII format. If the buffer is empty, it waits until a key is pressed. You can see if there are queued keypresses with al_keypressed.

The low byte of the return value contains the ASCII code of the key, and the high byte the scancode. The scancode remains the same whatever the state of the shift, ctrl and alt keys, while the ASCII code is affected by shift and ctrl in the normal way (shift changes case, ctrl+letter gives the position of that letter in the alphabet, eg. ctrl+A = 1, ctrl+B = 2, etc). Pressing alt+key returns only the scancode, with a zero ASCII code in the low byte. For example:

VAR
  val: INTEGER;
  ...
  val := al_readkey;

  IF (val AND $ff) = ORD ('d') THEN
    al_message ('You pressed "d"');

  IF (val SHR 8) = AL_KEY_SPACE THEN
    al_message ('You pressed Space');

  IF (val AND $ff) = 3 THEN
    al_message ('You pressed Control+C');

  IF val = (AL_KEY_X SHL 8) THEN
    al_message ('You pressed Alt+X');
   

This function cannot return character values greater than 255. If you need to read Unicode input, use al_ureadkey instead.

See also

al_install_keyboard

Installs the Allegro keyboard interrupt handler.

al_ureadkey

Returns the next character from the keyboard buffer, in Unicode format.

al_key

Array of flags indicating the state of each key, ordered by scancode.

al_clear_keybuf

Empties the keyboard buffer.

al_simulate_keypress

Stuffs a key into the keyboard buffer, just as if the user had pressed it.

Returns the next character from the keyboard buffer, in Unicode format. If the buffer is empty, it waits until a key is pressed. You can see if there are queued keypresses with al_keypressed. The return value contains the Unicode value of the key, and the argument will be set to the scancode. Unlike al_readkey, this function is able to return character values greater than 255. Example:

VAR
  val, scancode: INTEGER;
  ...
  val := al_ureadkey (scancode);
  IF val = $00F1 THEN
    al_message ('You pressed n with tilde');

  IF val = $00DF THEN
    al_message ('You pressed sharp s');
   

You should be able to find Unicode character maps at http://www.unicode.org/.

See also

al_readkey

Returns the next character from the keyboard buffer, in ASCII format.

Stuffs a key into the keyboard buffer, just as if the user had pressed it. The parameter is in the same format returned by al_readkey.

See also

al_simulate_ukeypress

Stuffs a key into the keyboard buffer, just as if the user had pressed it.

Stuffs a key into the keyboard buffer, just as if the user had pressed it. The parameter is in the same format returned by al_ureadkey.

See also

al_simulate_ukeypress

Stuffs a key into the keyboard buffer, just as if the user had pressed it.

Empties the keyboard buffer. Usually you want to use this in your program before reading keys to avoid previously buffered keys to be returned by calls to al_readkey or al_ureadkey.

See also

al_install_keyboard

Installs the Allegro keyboard interrupt handler.

Overrides the state of the keyboard LED indicators. The parameter is a bitmask containing any of the values AL_KB_SCROLOCK_FLAG, AL_KB_NUMLOCK_FLAG, and AL_KB_CAPSLOCK_FLAG, or -1 to restore the default behavior.

Note that the led behaviour cannot be guaranteed on some platforms, some leds might not react, or none at all. Therefore you shouldn't rely only on them to communicate information to the user, just in case it doesn't get through.

See also

al_install_keyboard

Installs the Allegro keyboard interrupt handler.

al_key_led_flag

By default, the capslock, numlock, and scroll-lock keys toggle the keyboard LED indicators when they are pressed.

Sets the keyboard repeat rate. Times are given in milliseconds. Passing zero times will disable the key repeat.

See also

al_install_keyboard

Installs the Allegro keyboard interrupt handler.

al_readkey

Returns the next character from the keyboard buffer, in ASCII format.

Converts the given scancode to an ASCII character for that key (mangling Unicode values), returning the unshifted uncapslocked result of pressing the key, or zero if the key isn't a character-generating key or the lookup can't be done. The lookup cannot be done for keys like the F1-F12 keys or the cursor keys, and some drivers will only return approximate values. Generally, if you want to display the name of a key to the user, you should use the al_scancode_to_name function.

This function returns a string pointer containing the name of they key with the given scancode. This is useful if you e.g. let the user choose a key for some action, and want to display something more meaningful than just the scancode.

See also

al_scancode_to_ascii

Converts the given scancode to an ASCII character for that key (mangling Unicode values), returning the unshifted uncapslocked result of pressing the key, or zero if the key isn't a character-generating key or the lookup can't be done.

Installs Allegro's joystick handler, and calibrates the centre position values. The type parameter should usually be AL_JOY_TYPE_AUTODETECT, or see the platform specific documentation for a list of the available drivers. You must call this routine before using any other joystick functions, and you should make sure that all joysticks are in the middle position at the time. Example:

  al_textout_centre_ex (al_screen, al_font,
			'Center the joystick and press a key.',
			AL_SCREEN_W DIV 2, SCREEN_H DIV 2, red_color, -1);
  al_readkey;
  IF NOT al_install_joystick (AL_JOY_TYPE_AUTODETECT) THEN
    abort_on_error ('Error initialising joystick!');
   

Returns

True on success. As soon as you have installed the joystick module, you will be able to read the button state and digital (on/off toggle) direction information, which may be enough for some games. If you want to get full analogue input, though, you need to use the al_calibrate_joystick functions to measure the exact range of the inputs.

See also

al_remove_joystick

Removes the joystick handler.

al_num_joysticks

Global variable containing the number of active joystick devices.

al_load_joystick_data

Restores calibration data previously stored by al_save_joystick_data or the setup utility.

al_poll_joystick

The joystick handler is not interrupt driven, so you need to call this function every now and again to update the global position values.

Removes the joystick handler. You don't normally need to bother calling this, because al_exit will do it for you.

See also

al_install_joystick

Installs Allegro's joystick handler, and calibrates the centre position values.

Pass the number of the joystick you want to calibrate as the parameter.

Returns

a text description for the next type of calibration that will be done on the specified joystick, or empty string if no more calibration is required.

See also

al_calibrate_joystick

Most joysticks need to be calibrated before they can provide full analogue input.

al_num_joysticks

Global variable containing the number of active joystick devices.

Most joysticks need to be calibrated before they can provide full analogue input. This function performs the next operation in the calibration series for the specified stick, assuming that the joystick has been positioned in the manner described by a previous call to al_calibrate_joystick_name, returning True on success. For example, a simple routine to fully calibrate all the joysticks might look like:

FUNCTION CalibrateJoysticks: BOOLEAN
VAR
  Cnt: INTEGER;
BEGIN
  FOR Cnt := 1 TO al_num_joysticks DO
  BEGIN
    WHILE (al_joy[Cnt - 1].flags AND AL_JOYFLAG_CALIBRATE) <> 0 DO
    BEGIN
      al_textout_ex (..., al_calibrate_joystick_name (Cnt - 1) + ', and press a key', ...);
      al_readkey;
      IF NOT al_calibrate_joystick (i - 1) THEN
      BEGIN
        al_textout_ex (..., 'oops!', ...);
	al_readkey;
	RESULT := FALSE;
	EXIT;
      END;
    END;
  END;
  RESULT := TRUE;
END;
   

Returns

True on success, False if the calibration could not be performed successfully.

See also

al_num_joysticks

Global variable containing the number of active joystick devices.

After all the headache of calibrating the joystick, you may not want to make your poor users repeat the process every time they run your program. Call this function to save the joystick calibration data into the specified configuration file, from which it can later be read by al_load_joystick_data. Pass a Nil filename to write the data to the currently selected configuration file.

Returns

True on success, False if the data could not be saved.

See also

al_calibrate_joystick

Most joysticks need to be calibrated before they can provide full analogue input.

Restores calibration data previously stored by al_save_joystick_data or the setup utility. This sets up all aspects of the joystick code: you don't even need to call al_install_joystick if you are using this function. Pass an empty filename to read the data from the currently selected configuration file.

Returns

True on success: if it fails the joystick state is undefined and you must reinitialise it from scratch.

See also

al_calibrate_joystick

Most joysticks need to be calibrated before they can provide full analogue input.

The joystick handler is not interrupt driven, so you need to call this function every now and again to update the global position values.

Returns

zero on success or a negative number on failure (usually because no joystick driver was installed).

See also

al_install_joystick

Installs Allegro's joystick handler, and calibrates the centre position values.

al_joy

Global array of joystick state information, which is updated by the al_poll_joystick function.

Sets the specified palette entry to the specified AL_RGB triplet. Unlike the other palette functions this doesn't do any retrace synchronisation, so you should call al_vsync before it to prevent snow problems.

See also

al_set_palette

Sets the entire palette of 256 colors.

al_get_color

Retrieves the specified palette entry.

Sets the entire palette of 256 colors. You should provide an array of 256 RGB structures. Unlike al_set_color, there is no need to call al_vsync before this function.

See also

al_get_palette

Retrieves the entire palette of 256 colors.

al_set_color

Sets the specified palette entry to the specified AL_RGB triplet.

al_set_palette_range

Sets the palette entries between from and ato (inclusive: pass 0 and 255 to set the entire palette).

Sets the palette entries between from and ato (inclusive: pass 0 and 255 to set the entire palette). If vsync is not zero it waits for the vertical retrace, otherwise it sets the colors immediately.

See also

al_set_color

Sets the specified palette entry to the specified AL_RGB triplet.

al_set_palette

Sets the entire palette of 256 colors.

Retrieves the specified palette entry.

See also

al_get_palette

Retrieves the entire palette of 256 colors.

al_set_color

Sets the specified palette entry to the specified AL_RGB triplet.

Retrieves the entire palette of 256 colors. You should provide a AL_PALETTE to store it in.

Retrieves the palette entries between from and ato (inclusive: pass 0 and 255 to set the entire palette).

Calculates a temporary palette part way between source and dest, returning it in the aoutput parameter. The position between the two extremes is specified by the pos value: 0 returns an exact copy of source, 64 returns dest, 32 returns a palette half way between the two, etc. This routine only affects colors between from and ato (inclusive: pass 0 and 255 to interpolate the entire palette).

See also

al_fade_in

Gradually fades from a black screen to the specified palette.

al_fade_out

Gradually fades from the current palette to a black screen.

al_fade_from

Gradually fades from the source palette to the dest palette.

Gradually fades a part of the palette from the source palette to the dest palette. The speed is from 1 (the slowest) up to 64 (instantaneous). This routine only affects colors between from and ato (inclusive: pass 0 and 255 to fade the entire palette).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also

al_fade_from

Gradually fades from the source palette to the dest palette.

Gradually fades a part of the palette from a black screen to the specified palette. The speed is from 1 (the slowest) up to 64 (instantaneous). This routine only affects colors between from and ato (inclusive: pass 0 and 255 to fade the entire palette).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also

al_fade_in

Gradually fades from a black screen to the specified palette.

Gradually fades a part of the current palette to the dest palette. The speed is from 1 (the slowest) up to 64 (instantaneous). This routine only affects colors between from and ato (inclusive: pass 0 and 255 to fade the entire palette).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also

al_fade_out

Gradually fades from the current palette to a black screen.

Gradually fades from the source palette to the dest palette. The speed is from 1 (the slowest) up to 64 (instantaneous).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also

al_fade_in

Gradually fades from a black screen to the specified palette.

al_fade_out

Gradually fades from the current palette to a black screen.

al_fade_interpolate

Calculates a temporary palette part way between source and dest, returning it in the aoutput parameter.

al_fade_from_range

Gradually fades a part of the palette from the source palette to the dest palette.

Gradually fades from a black screen to the specified palette. The speed is from 1 (the slowest) up to 64 (instantaneous).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also

al_fade_from

Gradually fades from the source palette to the dest palette.

al_fade_out

Gradually fades from the current palette to a black screen.

al_fade_interpolate

Calculates a temporary palette part way between source and dest, returning it in the aoutput parameter.

al_fade_in_range

Gradually fades a part of the palette from a black screen to the specified palette.

Gradually fades from the current palette to a black screen. The speed is from 1 (the slowest) up to 64 (instantaneous).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also

al_fade_from

Gradually fades from the source palette to the dest palette.

al_fade_in

Gradually fades from a black screen to the specified palette.

al_fade_interpolate

Calculates a temporary palette part way between source and dest, returning it in the aoutput parameter.

al_fade_out_range

Gradually fades a part of the current palette to the dest palette.

Ugly hack for use in various dodgy situations where you need to convert between paletted and truecolor image formats. Sets the internal palette table in the same way as the al_set_palette function, so the conversion will use the specified palette, but without affecting the display hardware in any way. The previous palette settings are stored in an internal buffer, and can be restored by calling al_unselect_palette. If you call al_select_palette again, however, the internal buffer will be overwritten.

Restores the palette tables that were in use before the last call to al_select_palette.

Constructs a fake truecolor palette, using three bits for red and green and two for the blue. The al_load_bitmap function fills the palette parameter with this if the file does not contain a palette itself (ie. you are reading a truecolor bitmap).

See also

al_generate_optimized_palette

Generates a 256-color palette suitable for making a reduced color version of the specified truecolor image.

al_set_color_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap.

Generates a 256-color palette suitable for making a reduced color version of the specified truecolor image.

Parameters

rsvdcols

points to a table indicating which colors it is allowed to modify: zero for free colors which may be set to whatever the optimiser likes, negative values for reserved colors which cannot be used, and positive values for fixed palette entries that must not be changed, but can be used in the optimisation.

Returns

the number of different colors recognised in the provided bitmap, zero if the bitmap is not a truecolor image or there wasn't enough memory to perform the operation, and negative if there was any internal error in the color reduction code.

See also

al_generate_332_palette

Constructs a fake truecolor palette, using three bits for red and green and two for the blue.

al_set_color_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap.

Fills the specified RGB mapping table with lookup data for the specified palette. If the callback function is not Nil, it will be called 256 times during the calculation, allowing you to display a progress indicator.

Convert color values between the HSV and RGB color spaces. The RGB values range from 0 to 255, hue is from 0 to 360, and saturation and value are from 0 to 1.

See also

al_rgb_to_hsv

Convert color values between the HSV and RGB color spaces.

Convert color values between the HSV and RGB color spaces. The RGB values range from 0 to 255, hue is from 0 to 360, and saturation and value are from 0 to 1.

See also

al_hsv_to_rgb

Convert color values between the HSV and RGB color spaces.

Searches the specified palette for the closest match to the requested color, which are specified in the VGA hardware 0-63 format. Normally you should call al_makecol_depth instead, but this lower level function may be useful if you need to use a palette other than the currently selected one, or specifically don't want to use the al_rgb_map lookup table.

Returns

the index of the palette for the closest match to the requested color.

See also

al_makecol8

Converts colors from a hardware independent form (red, green, and blue values ranging 0-255) into 8-bit color index.

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Returns

the requested RGB triplet in the current color depth.

See also

al_makeacol

Convert RGBA colors into display dependent pixel formats.

al_makecol8

Converts colors from a hardware independent form (red, green, and blue values ranging 0-255) into 8-bit color index.

al_makecol_depth

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the specified color depth.

AL_RGB_MAP

Stores an rgb map to accelerate conversions.

al_set_color_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap.

Converts colors from a hardware independent form (red, green, and blue values ranging 0-255) into 8-bit color index. Converting to an 8-bit color involves searching the palette to find the closest match, which is quite slow unless you have set up an RGB mapping table.

Returns

the requested RGB triplet in the specified color depth.

See also

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

al_makecol_depth

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the specified color depth.

AL_RGB_MAP

Stores an rgb map to accelerate conversions.

al_set_color_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap.

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the specified color depth.

Returns

the requested RGB triplet in the specified color depth.

See also

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

al_makecol_depth

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the specified color depth.

AL_RGB_MAP

Stores an rgb map to accelerate conversions.

al_set_color_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap.

Convert RGBA colors into display dependent pixel formats. In anything less than a 32-bit mode, these are the same as calling al_makecol or al_makecol_depth, but by using these routines it is possible to create 32-bit color values that contain a true 8 bit alpha channel along with the red, green, and blue components. You should only use RGBA format colors as the input to al_draw_trans_sprite or al_draw_trans_rle_sprite after calling al_set_alpha_blender, rather than drawing them directly to the screen.

Returns

the requested RGBA quadruplet.

Convert RGBA colors into display dependent pixel formats. In anything less than a 32-bit mode, these are the same as calling al_makecol or al_makecol_depth, but by using these routines it is possible to create 32-bit color values that contain a true 8 bit alpha channel along with the red, green, and blue components. You should only use RGBA format colors as the input to al_draw_trans_sprite or al_draw_trans_rle_sprite after calling al_set_alpha_blender, rather than drawing them directly to the screen.

Returns

the requested RGBA quadruplet.

Given a color in the format being used by the current video mode, these functions extract one of the red, green, blue, or alpha components (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate. The alpha part is only meaningful for 32-bit pixels.

See also

al_getr_depth

Given a color in the format being used by the specified color depth, these functions extract one of the red, green, blue, or alpha components (ranging 0-255).

al_getg

al_getb

al_geta

Given a color in the format being used by the specified color depth, these functions extract one of the red, green, blue, or alpha components (ranging 0-255). The alpha part is only meaningful for 32-bit pixels.

See also

al_getr

Given a color in the format being used by the current video mode, these functions extract one of the red, green, blue, or alpha components (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_getg_depth

al_getb_depth

al_geta_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap. Valid depths are 8 (the default), 15, 16, 24, and 32 bits.

Note that the screen color depth won't change until the next successful call to al_set_gfx_mode.

See also

al_get_color_depth

Returns the current pixel format.

al_set_color_conversion

Specifies how to convert images between the various color depths when reading graphics from external bitmap files or datafiles.

al_desktop_color_depth

Finds out the currently selected desktop color depth.

Returns the current pixel format. This can be very useful to know in order to write generic functions which select a different code path internally depending on the color depth being used.

Note that the function returns whatever value you may have set previously with al_set_color_depth, which can be different from the current color depth of the al_screen global variable. If you really need to know the color depth of the screen, use al_bitmap_color_depth.

Specifies how to convert images between the various color depths when reading graphics from external bitmap files or datafiles. The mode is a bitmask specifying which types of conversion are allowed. If the appropriate bit is set, data will be converted into the current pixel format (selected by calling the al_set_color_depth function), otherwise it will be left in the same format as the disk file, leaving you to convert it manually before the graphic can be displayed. The default mode is total conversion, so that all images will be loaded in the appropriate format for the current video mode. Valid bit flags are:

          AL_COLORCONV_NONE                // disable all format
                                           // conversions
          AL_COLORCONV_8_TO_15             // expand 8-bit to 15-bit
          AL_COLORCONV_8_TO_16             // expand 8-bit to 16-bit
          AL_COLORCONV_8_TO_24             // expand 8-bit to 24-bit
          AL_COLORCONV_8_TO_32             // expand 8-bit to 32-bit
          AL_COLORCONV_15_TO_8             // reduce 15-bit to 8-bit
          AL_COLORCONV_15_TO_16            // expand 15-bit to 16-bit
          AL_COLORCONV_15_TO_24            // expand 15-bit to 24-bit
          AL_COLORCONV_15_TO_32            // expand 15-bit to 32-bit
          AL_COLORCONV_16_TO_8             // reduce 16-bit to 8-bit
          AL_COLORCONV_16_TO_15            // reduce 16-bit to 15-bit
          AL_COLORCONV_16_TO_24            // expand 16-bit to 24-bit
          AL_COLORCONV_16_TO_32            // expand 16-bit to 32-bit
          AL_COLORCONV_24_TO_8             // reduce 24-bit to 8-bit
          AL_COLORCONV_24_TO_15            // reduce 24-bit to 15-bit
          AL_COLORCONV_24_TO_16            // reduce 24-bit to 16-bit
          AL_COLORCONV_24_TO_32            // expand 24-bit to 32-bit
          AL_COLORCONV_32_TO_8             // reduce 32-bit RGB to 8-bit
          AL_COLORCONV_32_TO_15            // reduce 32-bit RGB to 15-bit
          AL_COLORCONV_32_TO_16            // reduce 32-bit RGB to 16-bit
          AL_COLORCONV_32_TO_24            // reduce 32-bit RGB to 24-bit
          AL_COLORCONV_32A_TO_8            // reduce 32-bit RGBA to 8-bit
          AL_COLORCONV_32A_TO_15           // reduce 32-bit RGBA to 15-bit
          AL_COLORCONV_32A_TO_16           // reduce 32-bit RGBA to 16-bit
          AL_COLORCONV_32A_TO_24           // reduce 32-bit RGBA to 24-bit
          AL_COLORCONV_DITHER_PAL          // dither when reducing to 8-bit
          AL_COLORCONV_DITHER_HI           // dither when reducing to
                                           // hicolor
          AL_COLORCONV_KEEP_TRANS          // keep original transparency
   

For convenience, the following macros can be used to select common combinations of these flags:

          AL_COLORCONV_EXPAND_256          // expand 256-color to hi/truecolor
          AL_COLORCONV_REDUCE_TO_256       // reduce hi/truecolor to 256-color
          AL_COLORCONV_EXPAND_15_TO_16     // expand 15-bit hicolor to 16-bit
          AL_COLORCONV_REDUCE_16_TO_15     // reduce 16-bit hicolor to 15-bit
          AL_COLORCONV_EXPAND_HI_TO_TRUE   // expand 15/16-bit to 24/32-bit
          AL_COLORCONV_REDUCE_TRUE_TO_HI   // reduce 24/32-bit to 15/16-bit
          AL_COLORCONV_24_EQUALS_32        // convert between 24- and 32-bit
          AL_COLORCONV_TOTAL               // everything to current format
          AL_COLORCONV_PARTIAL             // convert 15 <-> 16-bit and
                                           // 24 <-> 32-bit
          AL_COLORCONV_MOST                // all but hi/truecolor <-> 256
          AL_COLORCONV_DITHER              // dither during all color reductions
          AL_COLORCONV_KEEP_ALPHA          // convert everything to current format
                                           // unless it would lose alpha information
   

If you enable the AL_COLORCONV_DITHER flag, dithering will be performed whenever truecolor graphics are converted into a hicolor or paletted format, including by the al_blit function, and any automatic conversions that take place while reading graphics from disk. This can produce much better looking results, but is obviously slower than a direct conversion.

If you intend using converted bitmaps with functions like al_masked_blit or al_draw_sprite, you should specify the AL_COLORCONV_KEEP_TRANS flag. It will ensure that the masked areas in the bitmap before and after the conversion stay exactly the same, by mapping transparent colors to each other and adjusting colors which would be converted to the transparent color otherwise. It affects every al_blit operation between distinct pixel formats and every automatic conversion.

See also

al_set_color_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap.

al_load_bitmap

Loads a bitmap from a file.

al_load_datafile

Loads a datafile into memory in one go.

al_get_color_conversion

Returns the current color conversion mode.

Returns the current color conversion mode.

See also

al_set_color_conversion

Specifies how to convert images between the various color depths when reading graphics from external bitmap files or datafiles.

Switches into graphics mode. The card parameter should usually be one of the Allegro magic drivers (read introduction of this unit) or see the platform specific documentation for a list of the available drivers. The w and h parameters specify what screen resolution you want. The color depth of the graphic mode has to be specified before calling this function with al_set_color_depth.

The v_w and v_h parameters specify the minimum virtual screen size, in case you need a large virtual screen for hardware scrolling or page flipping. You should set them to zero if you don't care about the virtual screen size.

When you call al_set_gfx_mode, the v_w and v_h parameters represent the minimum size of virtual screen that is acceptable for your program. The range of possible sizes is usually very restricted, and Allegro may end up creating a virtual screen much larger than the one you request. Allowed sizes are driver dependent and some drivers do not allow virtual screens that are larger than the visible screen at all: don't assume that whatever you pass will always work.

Currently, using a big virtual screen for page flipping is considered bad practice. There are platforms which don't support virtual screens bigger than the physical screen but can create different video pages to flip back and forth. This means that, if you want page flipping and aren't going to use hardware scrolling, you should call al_set_gfx_mode with (0,0) as the virtual screen size and later create the different video pages with al_create_video_bitmap. Otherwise your program will be limited to the platforms supporting hardware scrolling.

After you select a graphics mode, the physical and virtual screen sizes can be checked with the variables AL_SCREEN_W, AL_SCREEN_H, AL_VIRTUAL_W, and AL_VIRTUAL_H.

Returns

True on success. On failure returns False and stores a description of the problem in al_error.

See also

al_gfx_capabilities

Bitfield describing the capabilities of the current graphics driver and video hardware.

al_get_desktop_resolution

Finds out the currently selected desktop resolution.

Requests a hardware scroll request. Attempts to scroll the hardware screen to display a different part of the virtual screen (initially it will be positioned at 0, 0, which is the top left corner). You can use this to move the screen display around in a large virtual screen space, or to page flip back and forth between two non-overlapping areas of the virtual screen. Note that to draw outside the original position in the screen bitmap you will have to alter the clipping rectangle with al_set_clip_rect.

Mode-X scrolling is reliable and will work on any card, other drivers may not work or not work reliably. See the platform-specific section of the docs for more information.

Allegro will handle any necessary vertical retrace synchronisation when scrolling the screen, so you don't need to call al_vsync before it. This means that al_scroll_screen has the same time delay effects as al_vsync.

Returns

True on success, False if the graphics driver can't handle hardware scrolling or the virtual screen is not large enough.

See also

al_set_gfx_mode

Switches into graphics mode.

al_show_video_bitmap

Attempts to page flip the hardware screen to display the specified video bitmap object, which must be the same size as the physical screen, and should have been obtained by calling the al_create_video_bitmap function.

al_request_scroll

Queues a hardware scroll request with triple buffering.

al_request_video_bitmap

Requests a page flip to display the specified video bitmap object, but returns immediately rather than waiting for a retrace.

Queues a hardware scroll request with triple buffering. It requests a hardware scroll to the specified position, but returns immediately rather than waiting for a retrace. The scroll will then take place during the next vertical retrace, but you can carry on running other code in the meantime and use the al_poll_scroll routine to detect when the flip has actually taken place.

Triple buffering is only possible with certain drivers: you can look at the AL_GFX_CAN_TRIPLE_BUFFER bit in the al_gfx_capabilities flag to see if it will work with the current driver.

Returns

True on success, False Otherwise.

See also

al_request_video_bitmap

Requests a page flip to display the specified video bitmap object, but returns immediately rather than waiting for a retrace.

al_scroll_screen

Requests a hardware scroll request.

Checks the status of a scroll request with triple buffering.

Returns

True if it is still waiting to take place, or False if the requested scroll has already happened.

See also

al_request_scroll

Queues a hardware scroll request with triple buffering.

al_request_video_bitmap

Requests a page flip to display the specified video bitmap object, but returns immediately rather than waiting for a retrace.

Attempts to page flip the hardware screen to display the specified video bitmap object, which must be the same size as the physical screen, and should have been obtained by calling the al_create_video_bitmap function.

Allegro will handle any necessary vertical retrace synchronisation when page flipping, so you don't need to call al_vsync before it. This means that al_show_video_bitmap has the same time delay effects as al_vsync by default. This can be adjusted with the "disable_vsync" config key in the graphics section of allegro.cfg.

Returns

zero on success and non-zero on failure.

Requests a page flip to display the specified video bitmap object, but returns immediately rather than waiting for a retrace. The flip will then take place during the next vertical retrace, but you can carry on running other code in the meantime and use the al_poll_scroll routine to detect when the flip has actually taken place. Triple buffering is only possible on certain hardware: see the comments about al_request_scroll. Example:

VAR
  CurrentPage: INTEGER;
  VideoPage: ARRAY [0..2] OF AL_BITMAPptr;
BEGIN
  ...
// Create pages for page flipping
  FOR CurrentPage := Low (VideoPage) TO High (VideoPage) DO
    VideoPage[CurrentPage] := al_create_video_bitmap(SCREEN_W, SCREEN_H);
  CurrentPage := Low (VideoPage);
  ...
// draw the screen and flip pages
  DrawScreen (VideoPage[CurrentPage]);
  WHILE al_poll_scroll DO
    ;
  al_request_video_bitmap (VideoPage[CurrentPage]);
  CurrentPage := (CurrentPage + 1) MOD 3;
  ...
END.

Returns

True on success or False on failure.

See also

al_gfx_capabilities

Bitfield describing the capabilities of the current graphics driver and video hardware.

al_create_video_bitmap

Allocates a video memory bitmap of the specified size.

al_scroll_screen

Requests a hardware scroll request.

Enables triple buffering. If the AL_GFX_CAN_TRIPLE_BUFFER bit of the al_gfx_capabilities field is not set, you can attempt to enable it by calling this function. In particular if you are running in mode-X in a clean DOS environment, this routine will enable the timer retrace simulator, which will activate the triple buffering functions.

Returns

True if triple buffering is enabled, False otherwise.

See also

al_request_scroll

Queues a hardware scroll request with triple buffering.

al_request_video_bitmap

Requests a page flip to display the specified video bitmap object, but returns immediately rather than waiting for a retrace.

Creates a memory bitmap sized w by h. The bitmap will have clipping turned on, and the clipping rectangle set to the full size of the bitmap. The image memory will not be cleared, so it will probably contain garbage: you should clear the bitmap before using it. This routine always uses the global pixel format, as specified by calling al_set_color_depth. The minimum height of the bitmap must be 1 and width can't be negative.

Returns

a pointer to the created bitmap, or Nil if the bitmap could not be created . Remember to free this bitmap later to avoid memory leaks.

See also

al_create_bitmap_ex

Creates a bitmap in a specific color depth (8, 15, 16, 24 or 32 bits per pixel).

al_create_sub_bitmap

Creates a sub-bitmap, ie.

al_create_video_bitmap

Allocates a video memory bitmap of the specified size.

al_create_system_bitmap

Allocates a system memory bitmap of the specified size.

al_destroy_bitmap

Destroys a memory bitmap, sub-bitmap, video memory bitmap, or system bitmap when you are finished with it.

al_set_color_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap.

al_is_memory_bitmap

al_clear_bitmap

Clears the bitmap to color 0.

Creates a bitmap in a specific color depth (8, 15, 16, 24 or 32 bits per pixel).

Returns

a pointer to the created bitmap, or Nil if the bitmap could not be created . Remember to free this bitmap later to avoid memory leaks.

See also

al_create_bitmap

Creates a memory bitmap sized w by h.

Creates a sub-bitmap, ie. a bitmap sharing drawing memory with a pre-existing bitmap, but possibly with a different size and clipping settings. When creating a sub-bitmap of the mode-X screen, the x position must be a multiple of four. The sub-bitmap width and height can extend beyond the right and bottom edges of the parent (they will be clipped), but the origin point must lie within the parent region.

Remember to free the sub bitmap before freeing the parent bitmap to avoid memory leaks and potential crashes accessing memory which has been freed.

Returns

a pointer to the created sub bitmap, or Nil if the sub bitmap could not be created.

See also

al_create_bitmap

Creates a memory bitmap sized w by h.

Allocates a video memory bitmap of the specified size. This can be used to allocate offscreen video memory for storing source graphics ready for a hardware accelerated blitting operation, or to create multiple video memory pages which can then be displayed by calling al_show_video_bitmap. Read the introduction of this chapter for a comparison with other types of bitmaps and other specific details.

Warning: video memory bitmaps are usually allocated from the same space as the screen bitmap, so they may overlap with it; it is therefore not a good idea to use the global screen at the same time as any surfaces returned by this function.

Remember to destroy this bitmap before any subsequent call to al_set_gfx_mode.

Returns

a pointer to the bitmap on success, or Nil if you have run out of video ram.

See also

al_create_bitmap

Creates a memory bitmap sized w by h.

al_screen

Screen bitmap

al_show_video_bitmap

Attempts to page flip the hardware screen to display the specified video bitmap object, which must be the same size as the physical screen, and should have been obtained by calling the al_create_video_bitmap function.

al_gfx_capabilities

Bitfield describing the capabilities of the current graphics driver and video hardware.

al_is_video_bitmap

if bmp is the screen bitmap, a video memory bitmap, or a sub-bitmap of either.)

Allocates a system memory bitmap of the specified size. Read the introduction of this chapter for a comparison with other types of bitmaps and other specific details.

Remember to destroy this bitmap before any subsequent call to al_set_gfx_mode.

Returns

a pointer to the bitmap on success, Nil otherwise.

See also

al_create_bitmap

Creates a memory bitmap sized w by h.

al_is_system_bitmap

Destroys a memory bitmap, sub-bitmap, video memory bitmap, or system bitmap when you are finished with it. If you pass a Nil pointer this function won't do anything.

The bitmap must not have a mouse cursor shown on it at the time it is destroyed.

See also

al_create_bitmap

Creates a memory bitmap sized w by h.

al_load_bitmap

Loads a bitmap from a file.

al_show_mouse

Tells Allegro to display a mouse pointer on the screen.

Each bitmap has an associated clipping rectangle, which is the area of the image that it is OK to draw onto. Nothing will be drawn to positions outside this space. This function sets the clipping rectangle for the specified bitmap. Pass the coordinates of the top-left and bottom-right corners of the clipping rectangle in this order; these are both inclusive, i.e. al_set_clip_rect (bitmap, 16, 16, 32, 32) will allow drawing to (16, 16) and (32, 32), but not to (15, 15) and (33, 33).

Drawing operations will be performed (at least partially) on the bitmap as long as the first coordinates of its clipping rectangle are not greater than the second coordinates and its intersection with the actual image is non-empty. If either condition is not fulfilled, drawing will be turned off for the bitmap, e.g.: al_set_clip_rect (bmp, 0, 0, -1, -1) will disable drawing on bmp.

Note that passing "out-of-bitmap" coordinates is allowed, but they are likely to be altered (and so the coordinates returned by al_get_clip_rect will be different). However, such modifications are guaranteed to preserve the external effect of the clipping rectangle, that is not to modify the actual area of the image that it is OK to draw onto.

See also

al_add_clip_rect

Sets the clipping rectangle of the specified bitmap as the intersection of its current clipping rectangle and the rectangle described by the four coordinates.

al_set_clip_state

Turns on (if state is True) or off (if state is False) clipping for the specified bitmap.

al_get_clip_state

Returns the clipping state.

Sets the clipping rectangle of the specified bitmap as the intersection of its current clipping rectangle and the rectangle described by the four coordinates.

Clears the bitmap to color 0.

See also

al_clear_to_color

Clears the bitmap to the specified color.

Waits for a vertical retrace to begin. The retrace happens when the electron beam in your monitor has reached the bottom of the screen and is moving back to the top ready for another scan. During this short period the graphics card isn't sending any data to the monitor, so you can do things to it that aren't possible at other times, such as altering the palette without causing flickering (snow). Allegro will automatically wait for a retrace before altering the palette or doing any hardware scrolling, though, so you don't normally need to bother with this function.

See also

al_gfx_capabilities

Bitfield describing the capabilities of the current graphics driver and video hardware.

al_create_video_bitmap

Allocates a video memory bitmap of the specified size.

Clears the bitmap to the specified color.

See also

al_clear_bitmap

Clears the bitmap to color 0.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Returns

the color depth of the specified bitmap (8, 15, 16, 24, or 32).

See also

al_set_color_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap.

al_bitmap_mask_color

Returns

the mask color for the specified bitmap (the value which is skipped when drawing sprites). For 256-color bitmaps this is zero, and for truecolor bitmaps it is bright pink (maximum red and blue, zero green). A frequent use of this function is to clear a bitmap with the mask color so you can later use this bitmap with al_draw_sprite after drawing other stuff on it.

See also

al_set_color_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap.

al_bitmap_color_depth

Returns

True if the two bitmaps describe the same drawing surface, ie. the pointers are equal, one is a sub-bitmap of the other, or they are both sub-bitmaps of a common parent.

See also

al_create_sub_bitmap

Creates a sub-bitmap, ie.

Returns

True if bmp is a memory bitmap, ie. it was created by calling al_create_bitmap or loaded from a grabber datafile or image file.

Returns

True if bmp is the screen bitmap, or a sub-bitmap of the screen.

See also

al_screen

Screen bitmap

al_create_sub_bitmap

Creates a sub-bitmap, ie.

if bmp is the screen bitmap, a video memory bitmap, or a sub-bitmap of either.)

Returns

True

See also

al_screen

Screen bitmap

al_create_video_bitmap

Allocates a video memory bitmap of the specified size.

al_create_sub_bitmap

Creates a sub-bitmap, ie.

Returns

True if bmp is a system bitmap object, or a sub-bitmap of one.

See also

al_create_system_bitmap

Allocates a system memory bitmap of the specified size.

al_create_sub_bitmap

Creates a sub-bitmap, ie.

Returns

True if bmp is a sub-bitmap.

See also

al_create_sub_bitmap

Creates a sub-bitmap, ie.

Acquires the specified video bitmap prior to drawing onto it. You never need to call the function explicitly as it is low level, and will only give you a speed up if you know what you are doing. Using it wrongly may cause slowdown, or even lock up your program.

Note: You do never need to use al_acquire_bitmap on a memory bitmap, i.e. a normal bitmap created with al_create_bitmap. It will simply do nothing in that case.

It still can be useful, because e.g. under the current DirectDraw driver of Allegro, most drawing functions need to lock a video bitmap before drawing to it. But doing this is very slow, so you will get much better performance if you acquire the screen just once at the start of your main redraw function, then call multiple drawing operations which need the bitmap locked, and only release it when done.

Multiple acquire calls may be nested, but you must make sure to match up the acquire_bitmap and al_release_bitmap calls. Be warned that DirectX and X11 programs activate a mutex lock whenever a surface is locked, which prevents them from getting any input messages, so you must be sure to release all your bitmaps before using any timer, keyboard, or other non-graphics routines!

Note that if you are using hardware accelerated VRAM->VRAM functions, you should not call al_acquire_bitmap. Such functions need an unlocked target bitmap under DirectX, so there is now just the opposite case from before - if the bitmap is already locked with al_acquire_bitmap, the drawing operation has to unlock it.

Note: For backwards compatibility, the unlocking behavior of such functions is permanent. That is, if you call al_acquire_bitmap first, then call e.g. an accelerated blit, the DirectX bitmap will be unlocked internally (it won't affect the nesting counter of acquire/release calls).

There is no clear cross-platform way in this Allegro version to know which drawing operations need a locked/unlocked state. For example a normal rectfill most probably is accelerated under DirectX, and therefore needs the screen unlocked, but an XOR rectfill, or one with blending activated, most probably is not, and therefore locks the screen. And while the DirectX driver will do automatic unlocking, there is no such thing under X11, where the function is used to synchronize X11 calls from different threads. Your best bet is to never use al_acquire_bitmap - changes are you are doing something in the wrong way if you think you need it.

Warning: This function can be very dangerous to use, since the whole program may get locked while the bitmap is locked. So the lock should only be held for a short time, and you should not call anything but drawing operations onto the locked video bitmap while a lock is in place. Especially don't call things like al_show_mouse (or al_scare_mouse which calls that) or al_readkey, since it will most likely deadlock your entire program.

See also

al_acquire_screen

Shortcut version of al_acquire_bitmap (screen);

al_release_screen

Shortcut version of al_release_bitmap (screen);

Releases a bitmap that was previously locked by calling al_acquire_bitmap. If the bitmap was locked multiple times, you must release it the same number of times before it will truly be unlocked.

See also

al_acquire_screen

Shortcut version of al_acquire_bitmap (screen);

al_release_screen

Shortcut version of al_release_bitmap (screen);

Shortcut version of al_acquire_bitmap (screen);

See also

al_acquire_bitmap

Acquires the specified video bitmap prior to drawing onto it.

Shortcut version of al_release_bitmap (screen);

See also

al_release_bitmap

Releases a bitmap that was previously locked by calling al_acquire_bitmap.

Returns the clipping rectangle for the specified bitmap.

See also

al_set_clip_rect

Each bitmap has an associated clipping rectangle, which is the area of the image that it is OK to draw onto.

al_add_clip_rect

Sets the clipping rectangle of the specified bitmap as the intersection of its current clipping rectangle and the rectangle described by the four coordinates.

al_get_clip_state

Returns the clipping state.

Turns on (if state is True) or off (if state is False) clipping for the specified bitmap. Turning clipping off may slightly speed up some drawing operations (usually a negligible difference, although every little helps) but will result in your program dying a horrible death if you try to draw beyond the edges of the bitmap.

See also

al_set_clip_rect

Each bitmap has an associated clipping rectangle, which is the area of the image that it is OK to draw onto.

al_get_clip_rect

Returns the clipping rectangle for the specified bitmap.

al_add_clip_rect

Sets the clipping rectangle of the specified bitmap as the intersection of its current clipping rectangle and the rectangle described by the four coordinates.

al_get_clip_state

Returns the clipping state.

Returns the clipping state.

See also

al_get_clip_rect

Returns the clipping rectangle for the specified bitmap.

al_add_clip_rect

Sets the clipping rectangle of the specified bitmap as the intersection of its current clipping rectangle and the rectangle described by the four coordinates.

al_set_clip_state

Turns on (if state is True) or off (if state is False) clipping for the specified bitmap.

Loads a bitmap from a file. The palette data will be stored in the second parameter, which should be an AL_PALETTE structure. At present this function supports BMP, LBM, PCX, and TGA files, determining the type from the file extension.

If the file contains a truecolor image, you must set the video mode or call al_set_color_conversion before loading it. In this case, if the destination color depth is 8-bit, the palette will be generated by calling al_generate_optimized_palette on the bitmap; otherwise, the returned palette will be generated by calling al_generate_332_palette

The pal argument may be Nil. In this case, the palette data are simply not returned. Additionally, if the file is a truecolor image and the destination color depth is 8-bit, the color conversion process will use the current palette instead of generating an optimized one.

Example:

VAR
  bmp: AL_BITMAPptr;
  palette: AL_PALETTE;
          ...
  bmp := al_load_bitmap ('image.pcx', @palette);
  IF bmp = NIL THEN
    abort_on_error ('Could not load image.pcx!');
          ...
   al_destroy_bitmap (bmp);

See also

al_load_bmp

Loads an 8-bit, 16-bit, 24-bit or 32-bit Windows or OS/2 BMP file.

al_load_pcx

Loads a 256-color or 24-bit truecolor PCX file.

al_load_tga

Loads a 256-color, 15-bit hicolor, 24-bit truecolor, or 32-bit truecolor+alpha TGA file.

al_load_lbm

Loads a 256-color IFF ILBM/PBM file.

al_save_bitmap

Writes a bitmap into a file, using the specified palette, which should be an AL_PALETTE structure.

Loads an 8-bit, 16-bit, 24-bit or 32-bit Windows or OS/2 BMP file. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

Returns

a pointer to the bitmap or Nil on error.

See also

al_load_bitmap

Loads a bitmap from a file.

al_load_bmp_pf

A version of al_load_bmp which reads a BMP file from a packfile.

Loads a 256-color IFF ILBM/PBM file. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

Returns

a pointer to the bitmap or Nil on error.

See also

al_load_bitmap

Loads a bitmap from a file.

Loads a 256-color or 24-bit truecolor PCX file. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

Returns

a pointer to the bitmap or Nil on error.

See also

al_load_bitmap

Loads a bitmap from a file.

al_load_pcx_pf

A version of al_load_pcx which reads a PCX file from a packfile.

Loads a 256-color, 15-bit hicolor, 24-bit truecolor, or 32-bit truecolor+alpha TGA file. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

Returns

a pointer to the bitmap or Nil on error.

See also

al_load_bitmap

Loads a bitmap from a file.

al_load_tga_pf

A version of al_load_tga which reads a TGA file from a packfile.

Writes a bitmap into a file, using the specified palette, which should be an AL_PALETTE structure. The output format is determined from the filename extension: at present this function supports BMP, PCX and TGA formats.

Two things to watch out for: on some video cards it may be faster to copy the screen to a memory bitmap and save the latter, and if you use this to dump the screen into a file you may end up with an image much larger than you were expecting, because Allegro often creates virtual screens larger than the visible screen. You can get around this by using a sub-bitmap to specify which part of the screen to save, eg:

VAR
  bmp: AL_BITMAPptr;
  palette: AL_PALETTE;
          ...
  al_get_palette (palette);
  bmp := al_create_sub_bitmap (al_screen, 0, 0, AL_SCREEN_W, AL_SCREEN_H);
  al_save_bitmap ('dump.pcx', bmp, @palette);
  al_destroy_bitmap (bmp);

Writes a bitmap into a 256-color or 24-bit truecolor BMP file.

Returns

non-zero on error.

See also

al_save_bitmap

Writes a bitmap into a file, using the specified palette, which should be an AL_PALETTE structure.

al_save_bmp_pf

A version of al_save_bmp which reads a BMP file from a packfile.

Writes a bitmap into a 256-color or 24-bit truecolor PCX file.

Returns

non-zero on error.

See also

al_save_bitmap

Writes a bitmap into a file, using the specified palette, which should be an AL_PALETTE structure.

al_save_pcx_pf

A version of al_save_pcx which reads a PCX file from a packfile.

Writes a bitmap into a 256-color, 15-bit hicolor, 24-bit truecolor, or 32-bit truecolor+alpha TGA file.

Returns

non-zero on error.

See also

al_save_bitmap

Writes a bitmap into a file, using the specified palette, which should be an AL_PALETTE structure.

al_save_tga_pf

A version of al_save_tga which reads a TGA file from a packfile.

Installs the Allegro mouse handler. You must do this before using any other mouse functions.

Returns

-1 on failure, zero if the mouse handler is already installed (in which case this function does nothing) or the number of buttons on the mouse if the mouse handler has successfully been installed (ie. this is the first time a handler is installed or you have removed the previous one).

Note that the number of mouse buttons returned by this function is more an indication than a physical reality. With most devices there is no way of telling how many buttons there are, and any user can override the number of mouse buttons returned by this function with a custom configuration file and the variable num_buttons. Even if this value is overridden by the user, the global mouse variables will still report whatever the hardware is sending.

Removes the mouse handler. You don't normally need to bother calling this, because al_exit will do it for you.

Wherever possible, Allegro will read the mouse input asynchronously (ie. from inside an interrupt handler), but on some platforms that may not be possible, in which case you must call this routine at regular intervals to update the mouse state variables. To help you test your mouse polling code even if you are programming on a platform that doesn't require it, after the first time that you call this function Allegro will switch into polling mode, so from that point onwards you will have to call this routine in order to get any mouse input at all, regardless of whether the current driver actually needs to be polled or not.

Returns

zero on success, or a negative number on failure (ie. no mouse driver installed).

See also

al_mouse_needs_poll

Returns True if the current mouse driver is operating in polling mode.

al_install_mouse

Installs the Allegro mouse handler.

Returns True if the current mouse driver is operating in polling mode.

See also

al_poll_mouse

Wherever possible, Allegro will read the mouse input asynchronously (ie.

al_install_mouse

Installs the Allegro mouse handler.

After calling this function, Allegro will let the operating system draw the mouse cursor instead of doing it itself. This is not possible with all graphics drivers though: you'll need to check the al_gfx_capabilities flags after calling al_show_mouse to see if this works. On some platforms, enabling the hardware cursor causes al_get_mouse_mickeys to return only a limited range of values, so you should not call this function if you need mouse mickeys.

See also

al_set_mouse_sprite

You don't like Allegro's mouse pointer? No problem.

al_disable_hardware_cursor

After calling this function, Allegro will be responsible for drawing the mouse cursor rather than the operating system.

al_show_mouse

Tells Allegro to display a mouse pointer on the screen.

After calling this function, Allegro will be responsible for drawing the mouse cursor rather than the operating system. On some platforms calling al_enable_hardware_cursor makes the return values of al_get_mouse_mickeys unreliable. After calling this function, al_get_mouse_mickeys returns reliable results again.

Tells Allegro to display a mouse pointer on the screen. This will only work if the timer module has been installed. The mouse pointer will be drawn onto the specified bitmap, which should normally be al_screen (see later for information about bitmaps). To hide the mouse pointer, call al_show_mouse (Nil).

Warning: if you draw anything onto the screen while the pointer is visible, a mouse movement interrupt could occur in the middle of your drawing operation. If this happens the mouse buffering and graphics drawing code will get confused and will leave 'mouse droppings' all over the screen. To prevent this, you must make sure you turn off the mouse pointer whenever you draw onto the screen. This is not needed if you are using a hardware cursor.

Note: you must not be showing a mouse pointer on a bitmap at the time that the bitmap is destroyed with al_destroy_bitmap, e.g. call al_show_mouse (Nil); before destroying the bitmap. This does not apply to al_screen since you never destroy al_screen with al_destroy_bitmap.

See also

al_scare_mouse

Helper for hiding the mouse pointer prior to a drawing operation.

Helper for hiding the mouse pointer prior to a drawing operation. This will temporarily get rid of the pointer, but only if that is really required (ie. the mouse is visible, and is displayed on the physical screen rather than some other memory surface, and it is not a hardware or OS cursor). The previous mouse state is stored for subsequent calls to al_unscare_mouse.

See also

al_show_mouse

Tells Allegro to display a mouse pointer on the screen.

al_scare_mouse_area

Like al_scare_mouse, but will only hide the cursor if it is inside the specified rectangle.

Like al_scare_mouse, but will only hide the cursor if it is inside the specified rectangle. Otherwise the cursor will simply be frozen in place until you call al_unscare_mouse, so it cannot interfere with your drawing.

Undoes the effect of a previous call to al_scare_mouse or al_scare_mouse_area, restoring the original pointer state.

See also

al_show_mouse

Tells Allegro to display a mouse pointer on the screen.

Moves the mouse to the specified screen position. It is safe to call even when a mouse pointer is being displayed.

See also

al_position_mouse_z

Sets the mouse wheel position variable to the specified value.

al_position_mouse_w

Sets the horizontal mouse wheel position variable to the specified value.

Sets the mouse wheel position variable to the specified value.

See also

al_position_mouse

Moves the mouse to the specified screen position.

Sets the horizontal mouse wheel position variable to the specified value.

See also

al_position_mouse

Moves the mouse to the specified screen position.

This function allows you to use the operating system's native mouse cursors rather than some custom cursor. You will need to enable this functionality by calling al_enable_hardware_cursor beforehand. If the operating system does not support this functionality, or if it has not been enabled, then Allegro will substitute its own cursor images. You can change these substitute images using al_set_mouse_cursor_bitmap.

Note that the effects of this function are not apparent until al_show_mouse is called.

To know whether the operating system's native cursor is being used, or if Allegro has made a substitution, you can check the AL_GFX_SYSTEM_CURSOR flag in al_gfx_capabilities after calling al_show_mouse.

The cursor argument selects the type of cursor to be displayed: AL_MOUSE_CURSOR_NONE, AL_MOUSE_CURSOR_ALLEGRO, AL_MOUSE_CURSOR_ARROW, AL_MOUSE_CURSOR_BUSY, AL_MOUSE_CURSOR_QUESTION, AL_MOUSE_CURSOR_EDIT

This function changes the cursor image Allegro uses if al_select_mouse_cursor is called but no native operating system cursor can be used, e.g. because you did not call al_enable_hardware_cursor.

The effect of this function will not be apparent until al_show_mouse is called.

Parameters

cursor

one of: AL_MOUSE_CURSOR_ALLEGRO, AL_MOUSE_CURSOR_ARROW, AL_MOUSE_CURSOR_BUSY, AL_MOUSE_CURSOR_QUESTION, AL_MOUSE_CURSOR_EDIT but not AL_MOUSE_CURSOR_NONE.

bmp

can either point to a valid bitmap or it can be Nil. Passing a bitmap makes Allegro use that image in place of its own default substitution (should the operating system's native cursor be unavailable). The bitmap must remain available for the duration in which it could be used. Passing Nil lets Allegro revert to its default substitutions.

The mouse focus is the bit of the pointer that represents the actual mouse position, ie. the (al_mouse_x, al_mouse_y) position. By default this is the top left corner of the arrow, but if you are using a different mouse pointer you might need to alter it.

See also

al_set_mouse_sprite

You don't like Allegro's mouse pointer? No problem.

Measures how far the mouse has moved since the last call to this function. The values of mickeyx and mickeyy will become negative if the mouse is moved left or up, respectively. The mouse will continue to generate movement mickeys even when it reaches the edge of the screen, so this form of input can be useful for games that require an infinite range of mouse movement.

Note that the infinite movement may not work in windowed mode, since under some platforms the mouse would leave the window, and may not work at all if the hardware cursor is in use.

You don't like Allegro's mouse pointer? No problem. Use this function to supply an alternative of your own. If you change the pointer and then want to get Allegro's lovely arrow back again, call al_set_mouse_sprite (Nil).

As a bonus, al_set_mouse_sprite (Nil) uses the current palette in choosing colors for the arrow. So if your arrow mouse sprite looks ugly after changing the palette, call al_set_mouse_sprite (Nil).

See also

al_show_mouse

Tells Allegro to display a mouse pointer on the screen.

al_set_mouse_sprite_focus

The mouse focus is the bit of the pointer that represents the actual mouse position, ie.

In case you do not need Allegro's mouse cursor API, which automatically emulates a cursor in software if no other cursor is available, you can use this low level function to try to display or hide the system cursor directly. The cursor parameter takes the same values as al_select_mouse_cursor. This function is very similar to calling al_enable_hardware_cursor, al_select_mouse_cursor and al_show_mouse, but will not try to do anything if no system cursor is available.

The most common use for this function is to just call it once at the beginning of the program to tell it to display the system cursor inside the Allegro window. The return value can be used to see if this succeeded or not. On some systems (e.g. DirectX fullscreen) this is not supported and the function will always fail, and in other cases only some of the cursors will work, or in the case of AL_MOUSE_CURSOR_ALLEGRO, only certain bitmap sizes may be supported.

You never should use al_show_os_cursor together with the function al_show_mouse and other functions affecting it (al_select_mouse_cursor, al_enable_hardware_cursor, al_disable_hardware_cursor, al_scare_mouse, al_unscare_mouse). They implement the standard high level mouse API, and don't work together with this low level function.

Returns

True if a system cursor is being displayed after the function returns, or False otherwise.

Tells you whether the mouse pointer is currently on screen.

This function can be useful to prevent having two mouse pointers on the screen at the same time when running your program in windowed mode and drawing the mouse pointer yourself. Other possible uses include the ability to pause your game when the mouse goes off of the window, or only scrolling the view when the pointer is near the edge of the window, but not while off of the window.

Sets the graphics drawing mode. This only affects the geometric routines like al_putpixel, lines, rectangles, circles, polygons, floodfill, etc, not the text output, blitting, or sprite drawing functions. The mode should be one of the following constants:

• AL_DRAW_MODE_SOLID

• AL_DRAW_MODE_XOR

• AL_DRAW_MODE_COPY_PATTERN

• AL_DRAW_MODE_SOLID_PATTERN

• AL_DRAW_MODE_MASKED_PATTERN

• AL_DRAW_MODE_TRANS

With the patterned modes, you provide a pattern bitmap which is tiled across the surface of the shape. Allegro stores a pointer to this bitmap rather than copying it, so you must not destroy the bitmap while it is still selected as the pattern. The width and height of the pattern must be powers of two, but they can be different, eg. a 64x16 pattern is fine, but a 17x3 one is not. The pattern is tiled in a grid starting at point (x_anchor, y_anchor). Normally you should just pass zero for these values, which lets you draw several adjacent shapes and have the patterns meet up exactly along the shared edges. Zero alignment may look peculiar if you are moving a patterned shape around the screen, however, because the shape will move but the pattern alignment will not, so in some situations you may wish to alter the anchor position.

See also

al_xor_mode

This is a shortcut for toggling xor drawing mode on and off.

al_solid_mode

This is a shortcut for selecting solid drawing mode.

al_set_trans_blender

Enables a linear interpolator blender mode for combining translucent or lit truecolor pixels.

al_color_table

Pointer to the color mapping table.

This is a shortcut for toggling xor drawing mode on and off. Calling al_xor_mode (True) is equivalent to al_drawing_mode (AL_DRAW_MODE_XOR, Nil, 0, 0). Calling al_xor_mode (False) is equivalent to al_drawing_mode (A_DRAW_MODE_SOLID, Nil, 0, 0).

See also

al_drawing_mode

Sets the graphics drawing mode.

This is a shortcut for selecting solid drawing mode. It is equivalent to calling al_drawing_mode (AL_DRAW_MODE_XOR, NIL, 0, 0).

See also

al_drawing_mode

Sets the graphics drawing mode.

Calculates all the points along a line from point (x1, y1) to (x2, y2), calling the supplied function for each one. This will be passed a copy of the bmp parameter, the x and y position, and a copy of the d parameter. Example:

PROCEDURE DrawDustParticle (bmp: AL_BITMAPptr; x, y, d: AL_INT); CDECL;
BEGIN
   ...
END;

  al_do_line (al_screen, 0, 0, AL_SCREEN_W-1, AL_SCREEN_H-2,
              DustStrength, @DrawDustParticle);

See also

al_do_circle

Calculates all the points in a circle around point (x, y) with radius r, calling the supplied function for each one.

al_do_ellipse

Calculates all the points in an ellipse around point (x, y) with radius rx and ry, calling the supplied function for each one.

al_do_arc

Calculates all the points in a circular arc around point (x, y) with radius r, calling the supplied function for each one.

Calculates all the points in a circle around point (x, y) with radius r, calling the supplied function for each one. This will be passed a copy of the bmp parameter, the x and y position, and a copy of the d parameter. Example:

PROCEDURE DrawExplosionRing (bmp: AL_BITMAPptr; x, y, d: AL_INT); CDECL;
BEGIN
   ...
END;

  al_do_circle (al_screen, AL_SCREEN_W DIV 2, AL_SCREEN_H DIV 2,
                AL_SCREEN_H DIV 16, FlameColor, @DrawExplosionRing);

See also

al_do_line

Calculates all the points along a line from point (x1, y1) to (x2, y2), calling the supplied function for each one.

al_do_ellipse

Calculates all the points in an ellipse around point (x, y) with radius rx and ry, calling the supplied function for each one.

al_do_arc

Calculates all the points in a circular arc around point (x, y) with radius r, calling the supplied function for each one.

Calculates all the points in an ellipse around point (x, y) with radius rx and ry, calling the supplied function for each one. This will be passed a copy of the bmp parameter, the x and y position, and a copy of the d parameter. Example:

PROCEDURE DrawExplosionRing (bmp: AL_BITMAPptr; x, y, d: AL_INT); CDECL;
BEGIN
   ...
END;

  al_do_ellipse (al_screen, AL_SCREEN_W DIV 2, AL_SCREEN_H DIV 2,
                AL_SCREEN_H DIV 16, FlameColor, @DrawExplosionRing);

See also

al_do_line

Calculates all the points along a line from point (x1, y1) to (x2, y2), calling the supplied function for each one.

al_do_circle

Calculates all the points in a circle around point (x, y) with radius r, calling the supplied function for each one.

al_do_arc

Calculates all the points in a circular arc around point (x, y) with radius r, calling the supplied function for each one.

Calculates all the points in a circular arc around point (x, y) with radius r, calling the supplied function for each one. This will be passed a copy of the bmp parameter, the x and y position, and a copy of the d parameter. The arc will be plotted in an anticlockwise direction starting from the angle a1 and ending when it reaches a2. These values are specified in 16.16 fixed point format, with 256 equal to a full circle, 64 a right angle, etc. Zero is to the right of the centre point, and larger values rotate anticlockwise from there. Example:

PROCEDURE DrawExplosionRing (bmp: AL_BITMAPptr; x, y, d: AL_INT); CDECL;
BEGIN
   ...
END;

  al_do_arc (al_screen, AL_SCREEN_W DIV 2, AL_SCREEN_H DIV 2,
                AL_SCREEN_H DIV 16, FlameColor, @DrawExplosionRing);

See also

al_do_line

Calculates all the points along a line from point (x1, y1) to (x2, y2), calling the supplied function for each one.

al_do_circle

Calculates all the points in a circle around point (x, y) with radius r, calling the supplied function for each one.

al_do_ellipse

Calculates all the points in an ellipse around point (x, y) with radius rx and ry, calling the supplied function for each one.

Calculates a series of npts values along a Bezier spline, storing them in the output x and y arrays.

The Bezier curve is specified by the four x/y control points in the points array: points[0] and points[1] contain the coordinates of the first control point, points[2] and points[3] are the second point, etc. Control points 0 and 3 are the ends of the spline, and points 1 and 2 are guides. The curve probably won't pass through points 1 and 2, but they affect the shape of the curve between points 0 and 3 (the lines p0-p1 and p2-p3 are tangents to the spline). The easiest way to think of it is that the curve starts at p0, heading in the direction of p1, but curves round so that it arrives at p3 from the direction of p2.

In addition to their role as graphics primitives, spline curves can be useful for constructing smooth paths around a series of control points, as in exspline.pp.

See also

al_spline

Draws a Bezier spline using the four control points specified in the points array.

Copies a rectangular area of the source bitmap to the destination bitmap. The source_x and source_y parameters are the top left corner of the area to copy from the source bitmap, and dest_x and dest_y are the corresponding position in the destination bitmap. This routine respects the destination clipping rectangle, and it will also clip if you try to blit from areas outside the source bitmap.

You can blit between any parts of any two bitmaps, even if the two memory areas overlap (ie. source and dest are the same, or one is sub-bitmap of the other). You should be aware, however, that a lot of SVGA cards don't provide separate read and write banks, which means that blitting from one part of the screen to another requires the use of a temporary bitmap in memory, and is therefore extremely slow. As a general rule you should avoid blitting from the screen onto itself in SVGA modes.

If the AL_GFX_HW_VRAM_BLIT bit in the al_gfx_capabilities flag is set, the current driver supports hardware accelerated blits from one part of the screen onto another. This is extremely fast, so when this flag is set it may be worth storing some of your more frequently used graphics in an offscreen portion of the video memory.

Unlike most of the graphics routines, al_blit allows the source and destination bitmaps to be of different color depths, so it can be used to convert images from one pixel format to another. In this case, the behavior is affected by the AL_COLORCONV_KEEP_TRANS and AL_COLORCONV_DITHER* flags of the current color conversion mode.

See also

al_masked_blit

Like al_blit, but skips transparent pixels, which are marked by a zero in 256-color modes or bright pink for truecolor data (maximum red and blue, zero green), and requires the source and destination bitmaps to be of the same color depth.

al_stretch_blit

Like al_blit, except it can scale images (so the source and destination rectangles don't need to be the same size) and requires the source and destination bitmaps to be of the same color depth.

al_set_color_conversion

Specifies how to convert images between the various color depths when reading graphics from external bitmap files or datafiles.

Like al_blit, but skips transparent pixels, which are marked by a zero in 256-color modes or bright pink for truecolor data (maximum red and blue, zero green), and requires the source and destination bitmaps to be of the same color depth. The source and destination regions must not overlap.

If the AL_GFX_HW_VRAM_BLIT_MASKED bit in the al_gfx_capabilities flag is set, the current driver supports hardware accelerated masked blits from one part of the screen onto another. This is extremely fast, so when this flag is set it may be worth storing some of your more frequently used sprites in an offscreen portion of the video memory.

Warning: if the hardware acceleration flag is not set, al_masked_blit will not work correctly when used with a source image in system or video memory so the latter must be a memory bitmap.

See also

al_masked_stretch_blit

Like al_masked_blit, except it can scale images (so the source and destination rectangles don't need to be the same size).

al_draw_sprite

Draws a copy of the sprite bitmap onto the destination bitmap at the specified position.

al_bitmap_mask_color

Like al_blit, except it can scale images (so the source and destination rectangles don't need to be the same size) and requires the source and destination bitmaps to be of the same color depth. This routine doesn't do as much safety checking as the regular al_blit: in particular you must take care not to copy from areas outside the source bitmap, and you cannot blit between overlapping regions, ie. you must use different bitmaps for the source and the destination. Moreover, the source must be a memory bitmap.

See also

al_masked_stretch_blit

Like al_masked_blit, except it can scale images (so the source and destination rectangles don't need to be the same size).

al_stretch_sprite

Like al_draw_sprite, except it can stretch the sprite image to the specified width and height and requires the sprite image and destination bitmap to be of the same color depth.

Like al_masked_blit, except it can scale images (so the source and destination rectangles don't need to be the same size). This routine doesn't do as much safety checking as the regular al_masked_blit: in particular you must take care not to copy from areas outside the source bitmap. Moreover, the source must be a memory bitmap.

See also

al_blit

Copies a rectangular area of the source bitmap to the destination bitmap.

al_stretch_sprite

Like al_draw_sprite, except it can stretch the sprite image to the specified width and height and requires the sprite image and destination bitmap to be of the same color depth.

Like al_draw_sprite, except it can stretch the sprite image to the specified width and height and requires the sprite image and destination bitmap to be of the same color depth. Moreover, the sprite image must be a memory bitmap.

See also

al_stretch_blit

Like al_blit, except it can scale images (so the source and destination rectangles don't need to be the same size) and requires the source and destination bitmaps to be of the same color depth.

al_bitmap_mask_color

Rotates a sprite.

Draws the sprite image onto the bitmap. It is placed with its top left corner at the specified position, then rotated by the specified angle around its centre. The angle is a fixed point 16.16 number in the same format used by the fixed point trig routines, with 256 equal to a full circle, 64 a right angle, etc. All rotation functions can draw between any two bitmaps, even screen bitmaps or bitmaps of different color depth.

Positive increments of the angle will make the sprite rotate clockwise on the screen, as demonstrated by the Allegro example.

See also

al_draw_trans_sprite

Uses the global al_color_table table or truecolor blender functions to overlay the sprite on top of the existing image.

al_rotate_scaled_sprite_trans

Rotates and stretches a sprite.

al_rotate_sprite_v_flip_trans

Rotates and flips a sprite.

al_rotate_scaled_sprite_v_flip_trans

Rotates and stretches a sprite.

Rotates and flips a sprite.

Like al_rotate_sprite_trans, but flips the image vertically before rotating it. To flip horizontally, use this routine but add al_itofix (128) to the angle. To flip in both directions, use and add al_itofix (128) to its angle.

See also

al_rotate_sprite

Draws the sprite image onto the bitmap.

Rotates and stretches a sprite.

Like al_rotate_sprite_trans, but stretches or shrinks the image at the same time as rotating it.

Rotates and stretches a sprite.

Like al_rotate_scaled_sprite_trans, except that it flips the sprite vertically first.

Rotates a sprite around a specified point.

Like al_rotate_sprite_trans, but aligns the point in the sprite given by cx, cy to x, y in the bitmap, then rotates around this point.

Rotates and flips a sprite around a specified point.

Like al_rotate_sprite_trans, but aligns the point in the sprite given by cx, cy to x, y in the bitmap, then rotates around this point.

Rotates and stretches a sprite.

Like al_rotate_scaled_sprite_trans, but aligns the point in the sprite given by cx, cy to x, y in the bitmap, then rotates and scales around this point.

Rotates and stretches a sprite.

Like al_rotate_scaled_sprite_v_flip_trans, but aligns the point in the sprite given by (cx, cy) to (x, y) in the bitmap, then rotates and scales around this point.

Rotates a sprite.

Draws the sprite image onto the bitmap. It is placed with its top left corner at the specified position, then rotated by the specified angle around its centre. The angle is a fixed point 16.16 number in the same format used by the fixed point trig routines, with 256 equal to a full circle, 64 a right angle, etc. All rotation functions can draw between any two bitmaps, even screen bitmaps or bitmaps of different color depth.

Rotates a sprite.

Like , but flips the image vertically before rotating it. To flip horizontally, use this routine but add al_itofix(128) to the angle. To flip in both directions, use al_rotate_sprite_lit and add al_itofix(128) to its angle.

See also

al_rotate_sprite_lit

Rotates a sprite.

Rotates and stretches a sprite.

Like al_rotate_sprite_lit, but stretches or shrinks the image at the same time as rotating it.

Rotates and stretches a sprite.

Draws the sprite, similar to al_rotate_scaled_sprite_lit except that it flips the sprite vertically first.

Rotates a sprite.

Like al_rotate_sprite_lit, but aligns the point in the sprite given by (cx, cy) to (x, y) in the bitmap, then rotates around this point.

Rotates a sprite.

Like al_rotate_sprite_v_flip_lit, but aligns the point in the sprite given by (cx, cy) to (x, y) in the bitmap, then rotates around this point.

Rotates and stretches a sprite.

Like al_rotate_scaled_sprite_lit, but aligns the point in the sprite given by (cx, cy) to (x, y) in the bitmap, then rotates and scales around this point.

Rotates and stretches a sprite.

Like al_rotate_scaled_sprite_v_flip_lit, but aligns the point in the sprite given by (cx, cy) to (x, y) in the bitmap, then rotates and scales around this point.

Reads a pixel from point (x, y) in the bitmap.

Returns

-1 if the point lies outside the bitmap (ignoring the clipping rectangle), otherwise the value of the pixel in the color format of the bitmap.

Warning: -1 is also a valid value for pixels contained in 32-bit bitmaps with alpha channel (when R,G,B,A are all equal to 255) so you can't use the test against -1 as a predicate for such bitmaps. In this cases, the only reliable predicate is check if it is inside the bitmap.

To extract the individual color components, use the al_getr / al_getg / al_getb / al_geta family of functions

See also

al_putpixel

Writes a pixel to the specified position in the bitmap, using the current drawing mode and the bitmap's clipping rectangle.

_al_getpixel

Faster inline version of al_getpixel.

Writes a pixel to the specified position in the bitmap, using the current drawing mode and the bitmap's clipping rectangle.

See also

al_getpixel

Reads a pixel from point (x, y) in the bitmap.

_al_putpixel

Like the regular al_putpixel, but much faster because it's implemented as an inline functions for specific 8 bits color depth.

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws a vertical line onto the bitmap, from point (x, y1) to (x, y2).

See also

al_hline

Draws a horizontal line onto the bitmap, from point (x1, y) to (x2, y).

al_line

Draws a line onto the bitmap, from point (x1, y1) to (x2, y2).

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws a horizontal line onto the bitmap, from point (x1, y) to (x2, y).

See also

al_vline

Draws a vertical line onto the bitmap, from point (x, y1) to (x, y2).

al_line

Draws a line onto the bitmap, from point (x1, y1) to (x2, y2).

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws a line onto the bitmap, from point (x1, y1) to (x2, y2). .

See also

al_fastline

Faster version of the previous function.

al_polygon

Draws a filled polygon with an arbitrary number of corners.

al_do_line

Calculates all the points along a line from point (x1, y1) to (x2, y2), calling the supplied function for each one.

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Faster version of the previous function. Note that pixel correctness is not guaranteed for this function.

See also

al_line

Draws a line onto the bitmap, from point (x1, y1) to (x2, y2).

Draws a solid, filled rectangle with the two points as its opposite corners.

See also

al_triangle

Draws a filled triangle between the three points.

al_polygon

Draws a filled polygon with an arbitrary number of corners.

al_quad3d

Draw 3D quads, using fixed point vertex structures.

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws a filled triangle between the three points.

See also

al_polygon

Draws a filled polygon with an arbitrary number of corners.

al_triangle3d

Draw 3D triangles, using fixed point vertex structures.

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws a filled polygon with an arbitrary number of corners. Pass the number of vertices and an array containing a series of x, y points (a total of vertices*2 values).

See also

al_triangle

Draws a filled triangle between the three points.

al_polygon3d

Draw 3d polygons onto the specified bitmap, using the specified rendering mode.

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws an outline rectangle with the two points as its opposite corners.

See also

al_rectfill

Draws a solid, filled rectangle with the two points as its opposite corners.

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws a circle with the specified centre and radius.

See also

al_ellipse

Draws an ellipse with the specified centre and radius.

al_circlefill

Draws a filled circle with the specified centre and radius.

al_do_circle

Calculates all the points in a circle around point (x, y) with radius r, calling the supplied function for each one.

al_arc

Draws a circular arc.

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws a filled circle with the specified centre and radius.

See also

al_circle

Draws a circle with the specified centre and radius.

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws an ellipse with the specified centre and radius.

See also

al_circle

Draws a circle with the specified centre and radius.

al_ellipsefill

Draws a filled ellipse with the specified centre and radius.

al_arc

Draws a circular arc.

al_do_ellipse

Calculates all the points in an ellipse around point (x, y) with radius rx and ry, calling the supplied function for each one.

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws a filled ellipse with the specified centre and radius.

See also

al_ellipse

Draws an ellipse with the specified centre and radius.

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws a circular arc.

Draws a circular arc with centre x, y and radius r, in an anticlockwise direction starting from the angle a1 and ending when it reaches a2. These values are specified in 16.16 fixed point format, with 256 equal to a full circle, 64 a right angle, etc. Zero is to the right of the centre point, and larger values rotate anticlockwise from there.

See also

al_circle

Draws a circle with the specified centre and radius.

al_do_arc

Calculates all the points in a circular arc around point (x, y) with radius r, calling the supplied function for each one.

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws a Bezier spline using the four control points specified in the points array. Read the description of al_calc_spline for information on how to build the points array.

See also

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Floodfills an enclosed area, starting at point (x, y), with the specified color.

See also

al_drawing_mode

Sets the graphics drawing mode.

al_makecol

Converts colors from a hardware independent format (red, green, and blue values ranging 0-255) to the pixel format required by the current video mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as appropriate.

Draws a copy of the sprite bitmap onto the destination bitmap at the specified position. This is almost the same as al_blit (sprite, bmp, 0, 0, x, y, spriteˆ.w, spriteˆ.h), but it uses a masked drawing mode where transparent pixels are skipped, so the background image will show through the masked parts of the sprite. Transparent pixels are marked by a zero in 256-color modes or bright pink for truecolor data (maximum red and blue, zero green). Example:

VAR
  SpaceShip: AL_BITMAPptr;

          ...
  al_draw_sprite (al_screen, SpaceShip, x, y);
  

If the AL_GFX_HW_VRAM_BLIT_MASKED bit in the al_gfx_capabilities flag is set, the current driver supports hardware accelerated sprite drawing when the source image is a video memory bitmap or a sub-bitmap of the screen. This is extremely fast, so when this flag is set it may be worth storing some of your more frequently used sprites in an offscreen portion of the video memory.

Warning: if the hardware acceleration flag is not set, al_draw_sprite will not work correctly when used with a sprite image in system or video memory so the latter must be a memory bitmap.

Although generally not supporting graphics of mixed color depths, as a special case this function can be used to draw 256-color source images onto truecolor destination bitmaps, so you can use palette effects on specific sprites within a truecolor program.

See also

al_draw_sprite_v_flip

This is like al_draw_sprite, but it additionally flip the image vertically.

al_draw_trans_sprite

Uses the global al_color_table table or truecolor blender functions to overlay the sprite on top of the existing image.

al_draw_lit_sprite

In 256-color modes, uses the global al_color_table table to tint the sprite image to the specified color or to light it to the level specified by 'color', depending on the function which was used to build the table (al_create_trans_table or al_create_light_table), and draws the resulting image to the destination bitmap.

al_draw_gouraud_sprite

More sophisticated version of al_draw_lit_sprite: the color parameter is not constant across the sprite image anymore but interpolated between the four specified corner colors.

al_rotate_sprite

Draws the sprite image onto the bitmap.

al_draw_rle_sprite

Draws an RLE sprite onto a bitmap at the specified position.

Draws the sprite image onto the destination bitmap using the specified mode argument, optionally flipping the sprite in the orientation specified by flip argument.

Parameters

mode

defines how is sprite going to be drawn on the destination bitmap:

• AL_DRAW_SPRITE_NORMAL draws a masked sprite, like al_draw_sprite.

• (AL_DRAW_SPRITE_LIT) draws a tinted sprite, like al_draw_lit_sprite.

• (AL_DRAW_SPRITE_TRANS) draws a blended sprite, like al_draw_trans_sprite.

flip

defines the flipping orientation:

• AL_DRAW_SPRITE_NO_FLIP do not perform flipping.

• AL_DRAW_SPRITE_H_FLIP flip horizontally.

• AL_DRAW_SPRITE_V_FLIP flip vertically.

• AL_DRAW_SPRITE_VH_FLIP flip both vertically and horizontally-

This is like al_draw_sprite, but it additionally flip the image vertically. Flipping vertically means that the y-axis is reversed, between the source and the destination. This produces exact mirror images, which is not the same as rotating the sprite (and it is a lot faster than the rotation routine). The sprite must be a memory bitmap.