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

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

Closes down the Allegro system. This includes returning the system to text mode and removing whatever mouse, keyboard, and timer routines have been installed. This procedure must be called before exit the program.

Note that after you call this function, other functions like al_destroy_bitmap will most likely crash.

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

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.

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.

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

Parameters

title

Title string.

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.

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

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

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.

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.

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

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.

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.

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.

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.

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.

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

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

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.

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.

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

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

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

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

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 LSH 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_key

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

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

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.

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.

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.

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.

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

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.

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.

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

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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

Retrieves the specified palette entry.

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

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

Returns

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

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.

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.

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.

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

Returns

True

Returns

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

Returns

True if bmp is a sub-bitmap.

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.

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.

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.

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 ('Couldn''t load image.pcx!

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.

al_load_lbm_pf

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

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 BMP 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_pcx which reads a BMP 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 BMP 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_pcx which reads a BMP 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).

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

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.

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.

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.

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.

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

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.

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

Sets the mouse wheel position variable to the specified value.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Returns the clipping rectangle for the specified bitmap.

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.

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.

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

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

Clears the bitmap to color 0.

See also

al_clear_to_color

Clears the bitmap to the specified color.

Clears the bitmap to the specified color.

See also

al_clear_bitmap

Clears the bitmap to color 0.

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 getr() / getg() / getb() / geta() family of functions

Faster inline version of al_getpixel. This is specific for 8 bits color depth and don't do any clipping, so you must make sure the point lies inside the bitmap.

Returns

the value of the pixel in 8bpp

Faster inline version of al_getpixel. This is specific for 15 bits color depth and don't do any clipping, so you must make sure the point lies inside the bitmap.

Returns

the value of the pixel in 15bpp

Faster inline version of al_getpixel. This is specific for 16 bits color depth and don't do any clipping, so you must make sure the point lies inside the bitmap.

Returns

the value of the pixel in 16bpp

Faster inline version of al_getpixel. This is specific for 24 bits color depth and don't do any clipping, so you must make sure the point lies inside the bitmap.

Returns

the value of the pixel in 24bpp

Faster inline version of al_getpixel. This is specific for 32 bits color depth and don't do any clipping, so you must make sure the point lies inside the bitmap.

Returns

the value of the pixel in 32bpp

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

Like the regular al_putpixel, but much faster because it's implemented as an inline functions for specific 8 bits color depth. It don't perform any clipping (they will crash if you try to draw outside the bitmap!), and ignore the drawing mode.

Like the regular al_putpixel, but much faster because it's implemented as an inline functions for specific 15 bits color depth. It don't perform any clipping (they will crash if you try to draw outside the bitmap!), and ignore the drawing mode.

Like the regular al_putpixel, but much faster because it's implemented as an inline functions for specific 16 bits color depth. It don't perform any clipping (they will crash if you try to draw outside the bitmap!), and ignore the drawing mode.

Like the regular al_putpixel, but much faster because it's implemented as an inline functions for specific 24 bits color depth. It don't perform any clipping (they will crash if you try to draw outside the bitmap!), and ignore the drawing mode.

Like the regular al_putpixel, but much faster because it's implemented as an inline functions for specific 32 bits color depth. It don't perform any clipping (they will crash if you try to draw outside the bitmap!), and ignore the drawing mode.

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

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

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.

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 an outline rectangle with the two points as its opposite corners.

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

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.

Draws a filled circle with the specified centre and radius.

See also

al_circle

Draws a circle with the specified centre and radius.

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.

Draws a filled ellipse with the specified centre and radius.

See also

al_ellipse

Draws an ellipse with the specified centre and radius.

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.

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

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.

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.

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_calc_spline

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

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, so it is suitable for use with al_putpixel. Example:

PROCEDURE DrawDustParticle (bmp: AL_BITMAPptr; x, y, d: LONGINT); 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, so it is suitable for use with al_putpixel. Example:

PROCEDURE DrawExplosionRing (bmp: AL_BITMAPptr; x, y, d: LONGINT); 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, so it is suitable for use with al_putpixel. Example:

PROCEDURE DrawExplosionRing (bmp: AL_BITMAPptr; x, y, d: LONGINT); 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, so it is suitable for use with al_putpixel. 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: LONGINT); 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.

Loads a font from a file. At present, this supports loading fonts from a GRX format .fnt file, a 8x8 or 8x16 BIOS format .fnt file, a datafile or any bitmap format that can be loaded by al_load_bitmap.

If the font contains palette information, then the palette is returned in the second parameter, which should be an array of 256 AL_RGB structures (a AL_PALETTE). The pal argument may be Nil. In this case, the palette data, if present, is simply not returned.

Note that another way of loading fonts is embedding them into a datafile and using the datafile related functions.

Returns

a pointer to the font or Nil on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

Tries to grab a font from a bitmap. The bitmap can be in any format that al_load_bitmap understands.

The size of each character is determined by the layout of the image, which should be a rectangular grid containing all the ASCII characters from space (32) up to the tilde (126). The way the characters are separated depends on the color depth of the image file:

• paletted (8 bit) image file Use color 0 for the transparent portions of the characters and fill the spaces between each letter with color 255.

• High (15/16 bit) and true (24/32 bit) color image file use bright pink (maximum red and blue, zero green) for the transparent portions of the characters and fill the spaces between each letter with bright yellow (maximum red and green, zero blue).

Note that in each horizontal row the bounding boxes around the characters should align and have the same height.

Probably the easiest way to get to grips with how this works is to load up the `demo.dat' file and export the TITLE_FONT into a PCX file. Have a look at the resulting picture in your paint program: that is the format a font should be in.

Take care with high and true color fonts: Allegro will convert these to the current color depth when you load the font. If you try to use a font on a bitmap with a different color depth Allegro will do color conversions on the fly, which will be rather slow. For optimal performance you should set the color depth to the color depth you want to use before loading any fonts.

Returns

a pointer to the font or Nil on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

See also

al_load_bmp_pf

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

This function is the work-horse of al_load_bitmap_font, and can be used to grab a font from a bitmap in memory. You can use this if you want to generate or modify a font at runtime. The bitmap should follow the layout described for al_load_bitmap_font.

Returns

a pointer to the font or Nil on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

This function checks if the given font is a color font, as opposed to a monochrome font.

Returns

True if the font is a color font, False if it is not.

This function checks if the given font is a mono font, as opposed to a color font.

Returns

True if the font is a monochrome font, False if it is not.

This function compares the two fonts, which you can use to find out if Allegro is capable of merging them.

Returns

True if the two fonts are of the same general type (both are color fonts or both are monochrome fonts, for instance).

Frees the memory being used by a font structure. Don't use this on the default global Allegro font or any text routines using it could crash. You should use this only on fonts you have loaded manually after you are done with them, to prevent memory leaks in your program.

Writes the string onto the bitmap at given position, using the specified font, foreground color and background color. If the background color is -1, then the text is written transparently. If the foreground color is -1 and a color font is in use, it will be drawn using the colors from the original font bitmap (the one you imported into the grabber program), which allows multicolored text output. For high and true color fonts, the foreground color is ignored and always treated as -1.

Parameters

bmp

The output bitmap.

f

The font to render.

x

Horizontal position.

y

Vertical position.

color

Foreground color. Set to -1 to use multicolor fonts.

bg

Background color. Set to -1 to use transparent background.

See also

al_textout_centre_ex

Like al_textout_ex, but interprets the x coordinate as the centre rather than the left edge of the string.

al_textout_right_ex

Like al_textout_ex, but interprets the x coordinate as the right rather than the left edge of the string.

al_textout_justify_ex

Draws justified text within the region x1-x2.

Like al_textout_ex, but interprets the x coordinate as the centre rather than the left edge of the string.

See also

al_textout_ex

Writes the string onto the bitmap at given position, using the specified font, foreground color and background color.

al_textout_right_ex

Like al_textout_ex, but interprets the x coordinate as the right rather than the left edge of the string.

al_textout_justify_ex

Draws justified text within the region x1-x2.

Like al_textout_ex, but interprets the x coordinate as the right rather than the left edge of the string.

See also

al_textout_ex

Writes the string onto the bitmap at given position, using the specified font, foreground color and background color.

al_textout_centre_ex

Like al_textout_ex, but interprets the x coordinate as the centre rather than the left edge of the string.

al_textout_justify_ex

Draws justified text within the region x1-x2.

Draws justified text within the region x1-x2. If the amount of spare space is greater than the diff value, it will give up and draw regular left justified text instead.

See also

al_textout_ex

Writes the string onto the bitmap at given position, using the specified font, foreground color and background color.

al_textout_centre_ex

Like al_textout_ex, but interprets the x coordinate as the centre rather than the left edge of the string.

al_textout_right_ex

Like al_textout_ex, but interprets the x coordinate as the right rather than the left edge of the string.

Returns the length (in pixels) of a string in the specified font.

Returns the height (in pixels) of the specified font.

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_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, 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.

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

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.

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.

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.

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 horizontally. Flipping horizontally means that the x-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.

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.

This is like al_draw_sprite, but it additionally flip the image vertically and horizontally. Flipping vertically means that the y-axis is reversed, while flipping horizontally means that de x-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.

Uses the global al_color_table table or truecolor blender functions to overlay the sprite on top of the existing image. This must only be used after you have set up the color mapping table (for 256-color modes) or blender functions (for truecolor modes). Because it involves reading as well as writing the bitmap memory, translucent drawing is very slow if you draw directly to video RAM, so wherever possible you should use a memory bitmap instead. Example:

VAR
  global_trans_table: AL_COLOR_MAP;

          ...
   al_create_trans_table (@global_trans_table, my_palette,
                             128, 128, 128, NIL);
          ...
   IF al_get_color_depth = 8
     al_color_table := @global_trans_table
   ELSE
     al_set_trans_blender (128, 128, 128, 128);
   al_draw_trans_sprite (buffer, ghost_sprite, x, y);

The bitmap and sprite must normally be in the same color depth, but as a special case you can draw 32 bit RGBA format sprites onto any hicolor or truecolor bitmap, as long as you call al_set_alpha_blender first, and you can draw 8-bit alpha images onto a 32-bit RGBA destination, as long as you call al_set_write_alpha_blender first. As al_draw_sprite this function skips transparent pixels, except if the source sprite is an 8-bit image; if this is the case, you should pay attention to properly set up your color map table for index 0.

See also

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_color_table

Pointer to the color mapping table.

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. In truecolor modes, uses the blender functions to light the sprite image using the alpha level specified by 'color' (the alpha level which was passed to the blender functions is ignored) and draws the resulting image to the destination bitmap.

Parameters

c

must be in the range [0..255] whatever its actual meaning is. This must only be used after you have set up the color mapping table (for 256-color modes) or blender functions (for truecolor modes).

See also

al_draw_sprite

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

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_color_table

Pointer to the color mapping table.

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. The corner values passed to this function indicate the strength of the color applied on them, ranging from 0 (no strength) to 255 (full strength).

See also

al_draw_sprite

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

al_color_table

Pointer to the color mapping table.

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.

Like al_rotate_sprite, 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 and add al_itofix (128) to its angle.

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

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

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

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

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

Like al_rotate_scaled_sprite_v_flip, 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.

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 all_itofix (128) to the angle. To flip in both directions, use al_rotate_sprite and add al_itofix (128) to its angle.

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 al_rotate_sprite_lit, but flips the image vertically before rotating it. To flip horizontally, use this routine but add itofix(128) to the angle. To flip in both directions, use al_rotate_sprite and add itofix(128) to its angle.

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.

Creates an RLE sprite based on the specified bitmap (which must be a memory bitmap). Remember to free this RLE sprite later to avoid memory leaks.

Parameters

bitmap

Pointer to the bitmap used to create the sprite.

Returns

A pointer to the created RLE sprite, or Nil if it could not be created. Remember to free this RLE sprite later to avoid memory leaks.

See also

al_destroy_rle_sprite

Destroys an RLE sprite structure previously returned by al_get_rle_sprite.

al_draw_rle_sprite

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

Destroys an RLE sprite structure previously returned by al_get_rle_sprite. If you pass a Nil pointer this function won't do anything. Use this once you are done with an RLE sprite to avoid memory leaks in your program.

Parameters

sprite

The RLE sprite to destroy.

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

Parameters

bmp

Bitmap where the sprite will be draw.

spr

Sprite to draw.

x

Horizontal coordinate.

y

Vertical coordinate.

See also

al_draw_sprite

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

Translucent version of al_draw_rle_sprite. This must only be used after you have set up the color mapping table (for 256-color modes) or blender functions (for truecolor modes). The bitmap and sprite must normally be in the same color depth, but as a special case you can draw 32-bit RGBA format sprites onto any hicolor or truecolor bitmap, as long as you call al_set_alpha_blender first.

Parameters

bmp

Bitmap where the sprite will be draw.

spr

Sprite to draw.

x

Horizontal coordinate.

y

Vertical coordinate.

See also

al_draw_rle_sprite

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

al_color_table

Pointer to the color mapping table.

al_set_trans_blender

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

Tinted version of al_draw_rle_sprite. This must only be used after you have set up the color mapping table (for 256-color modes) or blender functions (for truecolor modes).

Parameters

bmp

Bitmap where the sprite will be draw.

spr

Sprite to draw.

x

Horizontal coordinate.

y

Vertical coordinate.

color

Tint color.

See also

al_draw_rle_sprite

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

al_color_table

Pointer to the color mapping table.

Call this function to specify the number of voices that are to be used by the digital and MIDI sound drivers respectively. This must be done before calling al_install_sound. If you reserve too many voices, subsequent calls to al_install_sound will fail. How many voices are available depends on the driver, and in some cases you will actually get more than you reserve (eg. the FM synth drivers will always provide 9 voices on an OPL2 and 18 on an OPL3, and the SB digital driver will round the number of voices up to the nearest power of two). Pass negative values to restore the default settings. You should be aware that the sound quality is usually inversely related to how many voices you use, so don't reserve any more than you really need.

By default, Allegro will play a centered sample at half volume on both the left and right channel. A sample panned to the far right or left will be played at maximum volume on that channel only. This is done so you can play a single panned sample without distortion. If you play multiple samples at full volume, the mixing process can result in clipping, a noticeable form of distortion. The more samples, the more likely clipping is to occur, and the more clipping, the worse the output will sound.

If clipping is a problem - or if the output is too quiet - this function can be used to adjust the volume of each voice. You should first check that your speakers are at a reasonable volume, Allegro's global volume is at maximum (see al_set_volume), and any other mixers such as the Volume Control are set reasonably. Once you are sure that Allegro's output level is unsuitable for your application, use this function to adjust it.

Each time you increase the parameter by one, the volume of each voice will halve. For example, if you pass 4, you can play up to 16 centred samples at maximum volume without distortion.

If you pass 0 to this function, each centred sample will play at the maximum volume possible without distortion, as will all samples played through a mono driver. Samples at the extreme left and right will distort if played at full volume. If you wish to play panned samples at full volume without distortion, you should pass 1 to this function.

Of course this function does not override the volume you specify with al_play_sample or al_set_volume. It simply alters the overall output of the program. If you play samples at lower volumes, or if they are not normalised, then you can play more of them without distortion.

It is recommended that you hard-code the parameter into your program, rather than offering it to the user. The user can alter the volume with the configuration file instead, or you can provide for this with al_set_volume.

Initialises the sound module. You should normally pass AL_DIGI_AUTODETECT and AL_MIDI_AUTODETECT as the driver parameters to this function, in which case Allegro will read hardware settings from the current configuration file. This allows the user to select different values with the setup utility: see the configuration section for details.

failure. If it fails it will store a description of the problem in al_error.)

Returns

(True if the sound is successfully installed, and False on

Cleans up after you are finished with the sound routines. You don't normally need to call this, because al_exit will do it for you.

Alters the global sound output volume. Specify volumes for both digital samples and MIDI playback, as integers from 0 to 255, or pass a negative value to leave one of the settings unchanged. Values bigger than 255 will be reduced to 255. This routine will not alter the volume of the hardware mixer if it exists (i.e. only your application will be affected).

Alters the hardware sound output volume. Specify volumes for both digital samples and MIDI playback, as integers from 0 to 255, or pass a negative value to leave one of the settings unchanged. Values bigger than 255 will be reduced to 255. This routine will use the hardware mixer to control the volume if it exists (i.e. the volume of all the applications on your machine will be affected), otherwise do nothing.

Retrieves the global sound output volume, both for digital samples and MIDI playback, as integers from 0 to 255.

Retrieves the hardware sound output volume, both for digital samples and MIDI playback, as integers from 0 to 255, or -1 if the information is not available.

Sets the resampling quality of the mixer. Valid values are the same as the quality config variable. Please read chapter "Standard config variables" for details. You can call this function at any point in your program, even before al_init.

Returns the current mixing quality, as specified by the quality config variable, or a previous call to al_set_mixer_quality.

Returns the mixer frequency, in Hz.

Returns the mixer bit depth (8 or 16).

Returns the number of output channels. 2 for stereo, 1 for mono, 0 if the mixer isn't active.

Returns the number of voices allocated to the mixer.

Returns the number of samples per channel in the mixer buffer.

Loads a MIDI file (handles both format 0 and format 1).

Returns

a pointer to a AL_MIDI structure, or Nil on error. Remember to free this MIDI file later to avoid memory leaks.

Destroys a AL_MIDI structure when you are done with it. It is safe to call this even when the MIDI file might be playing, because it checks and will kill it off if it is active. Use this to avoid memory leaks in your program.

Starts playing the specified AL_MIDI file, first stopping whatever music was previously playing. If the loop flag is set to True, the data will be repeated until replaced with something else, otherwise it will stop at the end of the file. Passing a Nil pointer will stop whatever music is currently playing.

Returns

False if an error occurs (this may happen if a patch-caching wavetable driver is unable to load the required samples, or at least it might in the future when somebody writes some patch-caching wavetable drivers :-)

Starts playing a MIDI file with a user-defined loop position. When the player reaches the loop_end position or the end of the file (loop_end may be -1 to only loop at EOF), it will wind back to the loop_start point. Both positions are specified in the same beat number format as the al_midi_pos variable.

Returns

False if an error occurs, True otherwise.

Stops whatever music is currently playing. This is the same thing as calling al_play_midi (Nil, False).

See also

al_play_midi

Starts playing the specified AL_MIDI file, first stopping whatever music was previously playing.

Pauses the MIDI player.

See also

al_midi_resume

Resumes playback of a paused MIDI file.

al_play_midi

Starts playing the specified AL_MIDI file, first stopping whatever music was previously playing.

Resumes playback of a paused MIDI file.

See also

al_midi_pause

Pauses the MIDI player.

Seeks to the given al_midi_pos in the current MIDI file. If the target is earlier in the file than the current al_midi_pos it seeks from the beginning; otherwise it seeks from the current position.

Returns

zero if it could successfully seek to the requested position. Otherwise, a return value of 1 means it stopped playing, and al_midi_pos is set to the negative length of the MIDI file (so you can use this function to determine the length of a MIDI file). A return value of 2 means the MIDI file looped back to the start.

This function will simulate playing the given MIDI, from start to end, to determine how long it takes to play. After calling this function, al_midi_pos will contain the negative number of beats, and al_midi_time the length of the midi, in seconds.

Note that any currently playing midi is stopped when you call this function. Usually you would call it before al_play_midi, to get the length of the midi to be played.

Returns

the value of al_midi_time, the length of the midi.

See also

al_load_midi

Loads a MIDI file (handles both format 0 and format 1).

al_midi_time

Contains the position in seconds in the currently playing midi.

al_midi_pos

Stores the current position (beat number) in the MIDI file, or contains a negative number if no music is currently playing.

Streams a block of MIDI commands into the player in real-time, allowing you to trigger notes, jingles, etc, over the top of whatever MIDI file is currently playing.

Forces the MIDI driver to load the entire set of patches ready for use. You will not normally need to call this, because Allegro automatically loads whatever data is required for the current MIDI file, but you must call it before sending any program change messages via the al_midi_out command.

Returns

False if an error occurred.