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.

alUNIX

UNIX and Linux specific stuff.

alWin

Windows specific stuff.

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
  CloseButtonPressed := TRUE;
END;

    ...
  al_init;
  al_set_close_button_callback (@CloseButtonHandler);
    ...
  REPEAT DoStuff UNTIL CloseButtonPressed;
  

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.

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

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

Parameters

section

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.

name

Name of the variable to read.

def

Default value.

Returns

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

al_flush_config_file

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

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

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

  REPEAT
    AnimateLogo (al_screen)
  UNTIL al_keypressed;
   

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: LONGINT;
  ...
  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: LONGINT;
  ...
  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.

AL_JOY_TYPE_AUTODETECT

Attempts to autodetect your joystick hardware.

alWin

Windows specific stuff.

alUNIX

UNIX and Linux specific stuff.

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

False on success or True 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 aFrom and aTo (inclusive: pass 0 and 255 to set the entire palette).

Sets the palette entries between aFrom and aTo (inclusive: pass 0 and 255 to set the entire palette). If vsync is True 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.

See also

al_get_palette_range

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

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

See also

al_get_palette

Retrieves the entire palette of 256 colors.

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

image

The trucolor image to convert.

pal

The generated palette.

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, this function extracts the red component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

See also

al_getr_depth

Given a color in the format being used by the specified color depth, this functions extract the red component (ranging 0-255).

al_getg

Given a color in the format being used by the current video mode, this function extracts the green component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_getb

Given a color in the format being used by the current video mode, this function extracts the blue component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_geta

Given a color in the format being used by the current video mode, this function extracts the alpha chanel value (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

Given a color in the format being used by the current video mode, this function extracts the green component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

See also

al_getg_depth

Given a color in the format being used by the specified color depth, this functions extract the green component (ranging 0-255).

al_getr

Given a color in the format being used by the current video mode, this function extracts the red component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_getb

Given a color in the format being used by the current video mode, this function extracts the blue component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_geta

Given a color in the format being used by the current video mode, this function extracts the alpha chanel value (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

Given a color in the format being used by the current video mode, this function extracts the blue component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

See also

al_getb_depth

Given a color in the format being used by the specified color depth, this functions extract the blue component (ranging 0-255).

al_getr

Given a color in the format being used by the current video mode, this function extracts the red component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_getg

Given a color in the format being used by the current video mode, this function extracts the green component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_geta

Given a color in the format being used by the current video mode, this function extracts the alpha chanel value (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

Given a color in the format being used by the current video mode, this function extracts the alpha chanel value (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_geta_depth

Given a color in the format being used by the specified color depth, this functions extract the alpha channel value (ranging 0-255).

al_getr

Given a color in the format being used by the current video mode, this function extracts the red component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_getg

Given a color in the format being used by the current video mode, this function extracts the green component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_getb

Given a color in the format being used by the current video mode, this function extracts the blue component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

Given a color in the format being used by the specified color depth, this functions extract the red component (ranging 0-255).

See also

al_getr

Given a color in the format being used by the current video mode, this function extracts the red component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_getg_depth

Given a color in the format being used by the specified color depth, this functions extract the green component (ranging 0-255).

al_getb_depth

Given a color in the format being used by the specified color depth, this functions extract the blue component (ranging 0-255).

al_geta_depth

Given a color in the format being used by the specified color depth, this functions extract the alpha channel value (ranging 0-255).

Given a color in the format being used by the specified color depth, this functions extract the green component (ranging 0-255).

See also

al_getg

Given a color in the format being used by the current video mode, this function extracts the green component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_getr_depth

Given a color in the format being used by the specified color depth, this functions extract the red component (ranging 0-255).

al_getb_depth

Given a color in the format being used by the specified color depth, this functions extract the blue component (ranging 0-255).

al_geta_depth

Given a color in the format being used by the specified color depth, this functions extract the alpha channel value (ranging 0-255).

Given a color in the format being used by the specified color depth, this functions extract the blue component (ranging 0-255).

See also

al_getb

Given a color in the format being used by the current video mode, this function extracts the blue component (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_getr_depth

Given a color in the format being used by the specified color depth, this functions extract the red component (ranging 0-255).

al_getg_depth

Given a color in the format being used by the specified color depth, this functions extract the green component (ranging 0-255).

al_geta_depth

Given a color in the format being used by the specified color depth, this functions extract the alpha channel value (ranging 0-255).

Given a color in the format being used by the specified color depth, this functions extract the alpha channel value (ranging 0-255). The alpha part is only meaningful for 32-bit pixels.

See also

al_geta

Given a color in the format being used by the current video mode, this function extracts the alpha chanel value (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get functions as appropriate.

al_getr_depth

Given a color in the format being used by the specified color depth, this functions extract the red component (ranging 0-255).

al_getg_depth

Given a color in the format being used by the specified color depth, this functions extract the green component (ranging 0-255).

al_getb_depth

Given a color in the format being used by the specified color depth, this functions extract the blue component (ranging 0-255).

Attempts to create a list of all the supported video modes for a certain graphics driver, made up from the AL_GFX_MODE_LIST structure. This list of video modes is terminated with an [ 0, 0, 0 ] entry. Note that the card parameter must refer to a real driver. This function fails if you pass AL_GFX_SAFE, AL_GFX_AUTODETECT, or any other "magic" driver.

Returns

A pointer to a list structure of the type AL_GFX_MODE_LIST or Nil if the request could not be satisfied.

See also

al_destroy_gfx_mode_list

Removes the mode list created by al_get_gfx_mode_list from memory.

al_set_gfx_mode

Switches into graphics mode.

al_set_color_depth

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

Removes the mode list created by al_get_gfx_mode_list from memory. Use this once you are done with the generated mode list to avoid memory leaks in your program.

See also

al_get_gfx_mode_list

Attempts to create a list of all the supported video modes for a certain graphics driver, made up from the AL_GFX_MODE_LIST structure.

al_set_gfx_mode

Switches into graphics mode.

al_set_color_depth

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

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.

Requests that the next call to al_set_gfx_mode try to use the specified refresh rate, if possible. Not all drivers are able to control this at all, and even when they can, not all rates will be possible on all hardware, so the actual settings may differ from what you requested. After you call al_set_gfx_mode, you can use al_get_refresh_rate to find out what was actually selected. At the moment only some Windows DirectX drivers support this function. The speed is specified in Hz, eg. 60, 70. To return to the normal default selection, pass a rate value of zero.

Example:

     al_request_refresh_rate(60);
     IF  NOT al_set_gfx_mode (AL_GFX_AUTODETECT, 640, 480, 0, 0) THEN
       abort_on_error ('Couldn''t set graphic mode!');
     IF al_get_refresh_rate <> 60 THEN
       abort_on_error ('Couldn''t set refresh rate to 60Hz!

See also

al_set_gfx_mode

Switches into graphics mode.

al_get_refresh_rate

Returns the current refresh rate, if known (not all drivers are able to report this information).

Returns the current refresh rate, if known (not all drivers are able to report this information). Returns zero if the actual rate is unknown.

See also

al_request_refresh_rate

Requests that the next call to al_set_gfx_mode try to use the specified refresh rate, if possible.

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_AUTODETECT

Allegro will try to set the specified resolution with the current color depth in fullscreen mode.

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.

alUNIX

UNIX and Linux specific stuff.

alWin

Windows specific stuff.

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

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

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

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

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

Returns True if bmp is a memory bitmap, ie.

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

Returns True 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

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

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.

Lets you determine the types of operating modes that a specific graphics card driver operates in. It will tell you whether it is a windowed, fullscreen, definitely windowed or fullscreen, and/or a magic driver.

The value returned is a bitfield consisting of these fields:

• AL_GFX_TYPE_UNKNOWN

• AL_GFX_TYPE_WINDOWED

• AL_GFX_TYPE_FULLSCREEN

• AL_GFX_TYPE_DEFINITE

• AL_GFX_TYPE_MAGIC

The return value will only be equivalent to AL_GFX_TYPE_UNKNOWN when it is a driver unrecognized on that platform, or it is a bogus value. Test for the other types by using a bitwise AND. If the driver is windowed or fullscreen, it will also have the definite flag set. For example,

  aGfxType := al_get_gfx_mode_type (AL_GFX_AUTODETECT_WINDOWED);

aGfxType would have the AL_GFX_TYPE_WINDOWED, AL_GFX_TYPE_DEFINITE, and AL_GFX_TYPE_MAGIC flags set.

Allegro needs to be initialized first. Example:

// Accept the use of only windowed drivers in our selection dialog.
  FUNCTION AcceptWindowed (CardId, w, h, ColorDepth: AL_INT): AL_INT;
  BEGIN
    IF (al_get_gfx_mode_type (CardId) AND AL_GFX_TYPE_WINDOWED) <> 0 THEN
      EXIT (0);
    RESULT := -1;
  END;

// In program:
  al_gfx_mode_select_filter (Card, w, h, ColorDepth, @AcceptWindowed);

Parameters

graphics_card

Identifier of the graphics card to check.

Returns

a bitfield describing the graphics mode type.

See also

al_gfx_mode_select_filter

Even more extended version of the graphics mode selection dialog, which allows the programmer to customize the contents of the dialog and the user to select the color depth as well as the resolution and hardware driver.

al_get_gfx_mode

Lets you determine which graphics driver is currently set by allegro.

al_set_gfx_mode

Switches into graphics mode.

al_is_windowed_mode

Tells if you are running in windowed mode.

Lets you determine which graphics driver is currently set by allegro. If no graphics driver is set, it will return AL_GFX_NONE.

Returns

the id of the current graphics driver if there is one, or AL_GFX_NONE if none is set.

See also

al_set_gfx_mode

Switches into graphics mode.

al_is_windowed_mode

Tells if you are running in windowed mode.

Sets how the program should handle being switched into the background, if the user tabs away from it. Not all of the possible modes will be supported by every graphics driver on every platform. The available modes are:

• AL_SWITCH_NONE Disables switching. This is the default in single-tasking systems like DOS. It may be supported on other platforms, but you should use it with caution, because your users won't be impressed if they want to switch away from your program, but you don't let them!

• AL_SWITCH_PAUSE Pauses the program whenever it is in the background. Execution will be resumed as soon as the user switches back to it. This is the default in most fullscreen multitasking environments, for example the Linux console, but not under Windows.

• AL_SWITCH_AMNESIA Like AL_SWITCH_PAUSE, but this mode doesn't bother to remember the contents of video memory, so the screen, and any video bitmaps that you have created, will be erased after the user switches away and then back to your program. This is not a terribly useful mode to have, but it is the default for the fullscreen drivers under Windows because DirectDraw is too dumb to implement anything better.

• AL_SWITCH_BACKGROUND The program will carry on running in the background, with the screen bitmap temporarily being pointed at a memory buffer for the fullscreen drivers. You must take special care when using this mode, because bad things will happen if the screen bitmap gets changed around when your program isn't expecting it (see below).

• AL_SWITCH_BACKAMNESIA Like SWITCH_BACKGROUND, but this mode doesn't bother to remember the contents of video memory (see AL_SWITCH_AMNESIA). It is again the only mode supported by the fullscreen drivers under Windows that lets the program keep running in the background.

Note that you should be very careful when you are using graphics routines in the switching context: you must always call al_acquire_screen before the start of any drawing code onto the screen and not release it until you are completely finished, because the automatic locking mechanism may not be good enough to work when the program runs in the background or has just been raised in the foreground.

Parameters

mode

The switching mode.

Returns

True on success, invalidating at the same time all callbacks previously registered with al_set_display_switch_callback. False if the requested mode is not currently possible.

See also

al_set_display_switch_callback

Installs a notification callback for the switching mode that was previously selected by calling al_set_display_switch_mode.

al_get_display_switch_mode

Returns the current display switching mode, in the same format passed to al_set_display_switch_mode.

Returns the current display switching mode, in the same format passed to al_set_display_switch_mode.

See also

al_set_display_switch_mode

Sets how the program should handle being switched into the background, if the user tabs away from it.

Installs a notification callback for the switching mode that was previously selected by calling al_set_display_switch_mode. The direction parameter can either be AL_SWITCH_IN or AL_SWITCH_OUT, depending whether you want to be notified about switches away from your program or back to your program. You can sometimes install callbacks for both directions at the same time, but not every platform supports this. You can install several switch callbacks, but no more than eight on any platform.

Parameters

dir

Direction of the notification.

cb

Callback procedure.

Returns

True on success, decreasing the number of empty callback slots by one. False if the request is impossible for the current platform or you have reached the maximum number of allowed callbacks.

See also

al_remove_display_switch_callback

Removes a notification callback that was previously installed by calling al_set_display_switch_callback.

al_set_display_switch_mode

Sets how the program should handle being switched into the background, if the user tabs away from it.

Removes a notification callback that was previously installed by calling al_set_display_switch_callback. All the callbacks will automatically be removed when you call al_set_display_switch_mode. You can safely call this function even if the callback you want to remove is not installed.

Parameters

cb

Callback procedure to remove.

See also

al_set_display_switch_callback

Installs a notification callback for the switching mode that was previously selected by calling al_set_display_switch_mode.

Tells if you are running in windowed mode. You should not call this function if you are not in graphics mode.

Example:

  IF NOT al_set_gfx_mode (AL_GFX_AUTODETECT, 640, 480, 0, 0) THEN
    abort_on_error ('Couldn''t set graphic mode!

Returns

True if the current graphics mode is a windowed mode, or False if it is a fullscreen mode.

See also

al_set_gfx_mode

Switches into graphics mode.

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