Unit allegro5

Returns the compiled version of the Allegro library (i.e. the dll/so/dylib file), packed into a single integer as groups of 8 bits.

You can use code like this to extract the version number:

VAR
  Version: LONGINT;
  Major, Minor, Revision, Release: INTEGER;
  VersionStr: STRING;
BEGIN
  Version := al_get_allegro_version;
  Major    :=  Version SHR 24;
  Minor    := (Version SHR 16) AND 255;
  Revision := (Version SHR  8) AND 255;
  Release  :=  Version         AND 255;
  VersionStr := Format ('%d.%d.%d[%d]', [Major, Minor, Revision, Release])
END;

The release number is 0 for an unofficial version and 1 or greater for an official release. For example "5.0.2[1]" would be the (first) official 5.0.2 release while "5.0.2[0]" would be a compile of a version from the "5.0.2" branch before the official release.

Remember this version number isn't for Allegro.pas but for Allegro. In most cases will not be the same than ALLEGRO_VERSION_INT.

See also

ALLEGRO_VERSION_INT

Packs Allegro's version number in a simple AL_INT number.

This function is useful in cases where you don't have a main function but want to run Allegro (mostly useful in a wrapper library). Under Windows and Linux this is no problem because you simply can call al_install_system. But some other system (like OSX) don't allow calling al_install_system in the main thread. al_run_main will know what to do in that case.

The passed argc and argv will simply be passed on to user_main and the return value of user_main will be returned.

Note

This is used because the way the C language works. I didn't test if Pascal do need this kind of stuff. Future versions of Allegro.pas would not include this function, so don't use it unless your really need to (and tell me if you really need it to remove this warning from documentation).

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;

Returns the number of seconds since the Allegro library was initialised. The return value is undefined if Allegro is uninitialised. The resolution depends on the used driver, but typically can be in the order of microseconds.

See also

al_rest

Waits for the specified number of seconds.

Waits for the specified number of seconds. This tells the system to pause the current thread for the given amount of time. With some operating systems, the accuracy can be in the order of 10ms. That is, even al_rest (0.000001) might pause for something like 10ms. Also see the other timer rutines (i.e. al_create_timer) for easier ways to time your program without using up all CPU.

See also

al_get_time

Returns the number of seconds since the Allegro library was initialised.

al_init_timeout

Sets timeout value of some number of seconds after the function call.

Sets timeout value of some number of seconds after the function call.

For compatibility with all platforms, seconds must be 2,147,483.647 seconds or less.

See also

ALLEGRO_TIMEOUT

Represents a timeout value.

al_wait_for_event_until

Waits until the event queue specified is non-empty.

Converts r, g, b (ranging from 0-255) into an ALLEGRO_COLOR, using 255 for alpha.

See also

al_map_rgba

Convert r, g, b, a (ranging from 0-255) into an ALLEGRO_COLOR.

al_map_rgba_f

Convert r, g, b, a (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR.

al_map_rgb_f

Convert r, g, b (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR, using 1.0f for alpha.

Convert r, g, b, a (ranging from 0-255) into an ALLEGRO_COLOR.

See also

al_map_rgb

Converts r, g, b (ranging from 0-255) into an ALLEGRO_COLOR, using 255 for alpha.

al_map_rgba_f

Convert r, g, b, a (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR.

al_map_rgb_f

Convert r, g, b (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR, using 1.0f for alpha.

Convert r, g, b (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR, using 1.0f for alpha.

See also

al_map_rgba

Convert r, g, b, a (ranging from 0-255) into an ALLEGRO_COLOR.

al_map_rgba_f

Convert r, g, b, a (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR.

al_map_rgb

Converts r, g, b (ranging from 0-255) into an ALLEGRO_COLOR, using 255 for alpha.

Convert r, g, b, a (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR. seealso(al_map_rgba)

See also

al_map_rgba_f

Convert r, g, b, a (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR.

al_map_rgb

Converts r, g, b (ranging from 0-255) into an ALLEGRO_COLOR, using 255 for alpha.

This is a shortcut for al_map_rgba (r * a / 255, g * a / 255, b * a / 255, a).

By default Allegro uses pre-multiplied alpha for transparent blending of bitmaps and primitives (see al_load_bitmap_flags for a discussion of that feature). This means that if you want to tint a bitmap or primitive to be transparent you need to multiply the color components by the alpha components when you pass them to this function. For example:

VAR
  c: ALLEGRO_COLOR;
  bmp: ALLEGRO_BITMAPptr;
BEGIN
  c := al_premul_rgba (255, 0, 0, 127);
{ Draw the bitmap tinted red and half-transparent. }
  al_draw_tinted_bitmap (bmp, c, 0, 0, 0);
END;

See also

al_map_rgba

Convert r, g, b, a (ranging from 0-255) into an ALLEGRO_COLOR.

al_premul_rgba_f

This is a shortcut for al_map_rgba (r * a, g * a, b * a, a).

This is a shortcut for al_map_rgba (r * a, g * a, b * a, a).

By default Allegro uses pre-multiplied alpha for transparent blending of bitmaps and primitives (see al_load_bitmap_flags for a discussion of that feature). This means that if you want to tint a bitmap or primitive to be transparent you need to multiply the color components by the alpha components when you pass them to this function. For example:

VAR
  c: ALLEGRO_COLOR;
  bmp: ALLEGRO_BITMAPptr;
BEGIN
  c := al_premul_rgba_f (1, 0, 0, 0.5);
{ Draw the bitmap tinted red and half-transparent. }
  al_draw_tinted_bitmap (bmp, c, 0, 0, 0);
END;

See also

al_map_rgba_f

Convert r, g, b, a (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR.

al_premul_rgba

This is a shortcut for al_map_rgba (r * a / 255, g * a / 255, b * a / 255, a).

Retrieves components of an ALLEGRO_COLOR, ignoring alpha. Components will range from 0-255.

See also

al_unmap_rgba

Retrieves components of an ALLEGRO_COLOR.

al_unmap_rgb_f

Retrieves components of an ALLEGRO_COLOR, ignoring alpha.

Retrieves components of an ALLEGRO_COLOR. Components will range from 0-255.

See also

al_unmap_rgb

Retrieves components of an ALLEGRO_COLOR, ignoring alpha.

al_unmap_rgba_f

Retrieves components of an ALLEGRO_COLOR.

Retrieves components of an ALLEGRO_COLOR, ignoring alpha. Components will range from 0.0f-1.0f.

See also

al_unmap_rgb

Retrieves components of an ALLEGRO_COLOR, ignoring alpha.

al_unmap_rgba_f

Retrieves components of an ALLEGRO_COLOR.

Retrieves components of an ALLEGRO_COLOR. Components will range from 0.0f-1.0f.

See also

al_unmap_rgba

Retrieves components of an ALLEGRO_COLOR.

al_unmap_rgb_f

Retrieves components of an ALLEGRO_COLOR, ignoring alpha.

Returns the number of bytes that a pixel of the given format occupies. For blocked pixel formats (e.g. compressed formats), this returns 0.

See also

ALLEGRO_PIXEL_FORMAT

Pixel formats.

al_get_pixel_format_bits

Returns the number of bits that a pixel of the given format occupies.

Returns the number of bits that a pixel of the given format occupies. For blocked pixel formats (e.g. compressed formats), this returns 0.

See also

ALLEGRO_PIXEL_FORMAT

Pixel formats.

al_get_pixel_size

Returns the number of bytes that a pixel of the given format occupies.

Returns the number of bytes that a block of pixels with this format occupies.

See also

ALLEGRO_PIXEL_FORMAT

Pixel formats.

al_get_pixel_block_width

Returns the width of the pixel block of this format.

al_get_pixel_block_height

Returns the height of the pixel block of this format.

Returns the width of the pixel block of this format.

See also

ALLEGRO_PIXEL_FORMAT

Pixel formats.

al_get_pixel_block_size

Returns the number of bytes that a block of pixels with this format occupies.

al_get_pixel_block_height

Returns the height of the pixel block of this format.

Returns the height of the pixel block of this format.

See also

ALLEGRO_PIXEL_FORMAT

Pixel formats.

al_get_pixel_block_width

Returns the width of the pixel block of this format.

al_get_pixel_block_size

Returns the number of bytes that a block of pixels with this format occupies.

Sets the pixel format for newly created bitmaps. The default format is ALLEGRO_PIXEL_FORMAT_ANY and means the display driver will choose the best format.

See also

al_create_bitmap

Creates a new bitmap using the bitmap format and flags for the current thread.

ALLEGRO_PIXEL_FORMAT

Pixel formats.

al_get_new_bitmap_format

Returns the format used for newly created bitmaps.

Sets the flags to use for newly created bitmaps. Valid flags are:

ALLEGRO_MEMORY_BITMAP

Creates a bitmap residing in system memory. Operations on, and with, memory bitmaps will not be hardware accelerated. However, direct pixel access can be relatively quick compared to video bitmaps, which depend on the display driver in use.

Note: Allegro's software rendering routines are currently somewhat unoptimised.

Note: Combining ALLEGRO_VIDEO_BITMAP with ALLEGRO_MEMORY_BITMAP flags is invalid.

ALLEGRO_VIDEO_BITMAP

Creates a bitmap that resides in the video card memory. These types of bitmaps receive the greatest benefit from hardware acceleration.

Note: Creating a video bitmap will fail if there is no current display or the current display driver cannot create the bitmap. The latter will happen if for example the format or dimensions are not supported.

Note: Bitmaps created with this flag will be converted to memory bitmaps when the last display is destroyed. In most cases it is therefore easier to use the ALLEGRO_CONVERT_BITMAP flag instead.

Note: Combining ALLEGRO_VIDEO_BITMAP with ALLEGRO_MEMORY_BITMAP flags is invalid.

ALLEGRO_CONVERT_BITMAP

This is the default. It will try to create a video bitmap and if that fails create a memory bitmap. Bitmaps created with this flag when there is no active display will be converted to video bitmaps next time a display is created. They also will remain video bitmaps if the last display is destroyed and then another is created again.

Note: You can combine this flag with ALLEGRO_MEMORY_BITMAP or ALLEGRO_VIDEO_BITMAP to force the initial type (and fail in the latter case if no video bitmap can be created) - but usually neither of those combinations is very useful.

You can use the display option ALLEGRO_AUTO_CONVERT_BITMAPS to control which displays will try to auto-convert bitmaps.

ALLEGRO_NO_PRESERVE_TEXTURE

Normally, every effort is taken to preserve the contents of bitmaps, since some platforms may forget them. This can take extra processing time. If you know it doesn't matter if a bitmap keeps its pixel data, for example when it's a temporary buffer, use this flag to tell Allegro not to attempt to preserve its contents.

ALLEGRO_ALPHA_TEST

This is a driver hint only. It tells the graphics driver to do alpha testing instead of alpha blending on bitmaps created with this flag. Alpha testing is usually faster and preferred if your bitmaps have only one level of alpha (0). This flag is currently not widely implemented (i.e., only for memory bitmaps).

ALLEGRO_MIN_LINEAR

When drawing a scaled down version of the bitmap, use linear filtering. This usually looks better. You can also combine it with the ALLEGRO_MIPMAP flag for even better quality.

ALLEGRO_MAG_LINEAR

When drawing a magnified version of a bitmap, use linear filtering. This will cause the picture to get blurry instead of creating a big rectangle for each pixel. It depends on how you want things to look like whether you want to use this or not.

ALLEGRO_MIPMAP

This can only be used for bitmaps whose width and height is a power of two. In that case, it will generate mipmaps and use them when drawing scaled down versions. For example if the bitmap is 64x64, then extra bitmaps of sizes 32x32, 16x16, 8x8, 4x4, 2x2 and 1x1 will be created always containing a scaled down version of the original.

See also

al_create_bitmap

Creates a new bitmap using the bitmap format and flags for the current thread.

al_add_new_bitmap_flag

A convenience function which does the same as

al_set_new_bitmap_flags (al_get_new_bitmap_flags OR flag);

al_get_new_bitmap_flags

Returns the format used for newly created bitmaps.

al_get_bitmap_flags

Returns the flags user to create the bitmap.

Returns the format used for newly created bitmaps.

See also

ALLEGRO_PIXEL_FORMAT

Pixel formats.

al_set_new_bitmap_format

Sets the pixel format for newly created bitmaps.

Returns the format used for newly created bitmaps.

See also

ALLEGRO_PIXEL_FORMAT

Pixel formats.

al_set_new_bitmap_flags

Sets the flags to use for newly created bitmaps.

A convenience function which does the same as

al_set_new_bitmap_flags (al_get_new_bitmap_flags OR flag);

See also

al_set_new_bitmap_flags

Sets the flags to use for newly created bitmaps.

al_get_new_bitmap_flags

Returns the format used for newly created bitmaps.

al_get_bitmap_flags

Returns the flags user to create the bitmap.

Returns the width of a bitmap in pixels.

Returns the height of a bitmap in pixels.

Returns the pixel format of a bitmap.

See also

ALLEGRO_PIXEL_FORMAT

Pixel formats.

al_set_new_bitmap_format

Sets the pixel format for newly created bitmaps.

Returns the flags user to create the bitmap.

See also

al_set_new_bitmap_flags

Sets the flags to use for newly created bitmaps.

Creates a new bitmap using the bitmap format and flags for the current thread. Blitting between bitmaps of differing formats, or blitting between memory bitmaps and display bitmaps may be slow.

Unless you set the ALLEGRO_MEMORY_BITMAP flag, the bitmap is created for the current display. Blitting to another display may be slow.

If a display bitmap is created, there may be limitations on the allowed dimensions. For example a DirectX or OpenGL backend usually has a maximum allowed texture size - so if bitmap creation fails for very large dimensions, you may want to re-try with a smaller bitmap. Some platforms also dictate a minimum texture size, which is relevant if you plan to use this bitmap with the primitives addon. If you try to create a bitmap smaller than this, this call will not fail but the returned bitmap will be a section of a larger bitmap with the minimum size. The minimun size that will work on all platforms is 32 by 32.

Some platforms do not directly support display bitmaps whose dimensions are not powers of two. Allegro handles this by creating a larger bitmap that has dimensions that are powers of two and then returning a section of that bitmap with the dimensions you requested. This can be relevant if you plan to use this bitmap with the primitives addon but shouldn't be an issue otherwise.

If you create a bitmap without ALLEGRO_MEMORY_BITMAP set but there is no current display, a temporary memory bitmap will be created instead. You can later convert all such bitmap to video bitmap and assign to a display by calling al_convert_memory_bitmaps.

On some platforms the contents of video bitmaps may be lost when your application loses focus. Allegro has an internal mechanism to restore the contents of these video bitmaps, but it is not foolproof (sometimes bitmap contents can get lost permanently) and has performance implications. If you are using a bitmap as an intermediate buffer this mechanism may be wasteful. In this case, if you do not want Allegro to manage the bitmap contents for you, you can disable this mechanism by creating the bitmap with the ALLEGRO_NO_PRESERVE_TEXTURE flag. The bitmap contents are lost when you get the ALLEGRO_EVENT_DISPLAY_LOST and ALLEGRO_EVENT_DISPLAY_HALT_DRAWING and a should be restored when you get the ALLEGRO_EVENT_DISPLAY_FOUND and when you call al_acknowledge_drawing_resume (after ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING event). You can use those events to implement your own bitmap content restoration mechanism if Allegro's does not work well enough for you (for example, you can reload them all from disk).

Note: The contents of a newly created bitmap are undefined - you need to clear the bitmap or make sure all pixels get overwritten before drawing it.

When you are done with using the bitmap you must call al_destroy_bitmap on it to free any resources allocated for it.

See also

al_set_new_bitmap_format

Sets the pixel format for newly created bitmaps.

al_set_new_bitmap_flags

Sets the flags to use for newly created bitmaps.

al_clone_bitmap

Creates a new bitmap with al_create_bitmap, and copyes the pixel data from the old bitmap across.

al_create_sub_bitmap

Creates a sub-bitmap of the parent, at the specified coordinates and of the specified size.

al_convert_memory_bitmaps

If you create a bitmap when there is no current display (for example because you have not called al_create_display in the current thread) and are using the ALLEGRO_CONVERT_BITMAP bitmap flag (which is set by default) then the bitmap will be created successfully, but as a memory bitmap.

al_destroy_bitmap

Destroys the given bitmap, freeing all resources used by it.

Destroys the given bitmap, freeing all resources used by it. This function does nothing if the bitmap argument is Nil.

As a convenience, if the calling thread is currently targeting the bitmap then the bitmap will be untargeted first. The new target bitmap is unspecified.

Otherwise, it is an error to destroy a bitmap while it (or a sub-bitmap) is the target bitmap of any thread.

See also

al_create_bitmap

Creates a new bitmap using the bitmap format and flags for the current thread.

Draws a single pixel on the target bitmap. This operation is slow on non-memory bitmaps. Consider locking the bitmap if you are going to use this function multiple times on the same bitmap. This function is not affected by the transformations or the color blenders.

See also

ALLEGRO_COLOR

An ALLEGRO_COLOR structure describes a color in a device independent way.

al_get_pixel

Gets a pixel's color value from the specified bitmap.

al_put_blended_pixel

Like al_put_pixel, but the pixel color is blended using the current blenders before being drawn.

al_lock_bitmap

Locks an entire bitmap for reading or writing.

Like al_put_pixel, but the pixel color is blended using the current blenders before being drawn.

Gets a pixel's color value from the specified bitmap. This operation is slow on non-memory bitmaps. Consider locking the bitmap if you are going to use this function multiple times on the same bitmap.

See also

ALLEGRO_COLOR

An ALLEGRO_COLOR structure describes a color in a device independent way.

al_put_pixel

Draws a single pixel on the target bitmap.

al_lock_bitmap

Locks an entire bitmap for reading or writing.

Converts the given mask color to an alpha channel in the bitmap. Can be used to convert older 4.2-style bitmaps with magic pink to alpha-ready bitmaps.

See also

ALLEGRO_COLOR

An ALLEGRO_COLOR structure describes a color in a device independent way.

Sets the region of the target bitmap or display that pixels get clipped to. The default is to clip pixels to the entire bitmap.

See also

al_get_clipping_rectangle

Gets the clipping rectangle of the target bitmap.

al_reset_clipping_rectangle

Equivalent to calling al_set_clipping_rectangle (0, 0, w, h) where w and h are the width and height of the target bitmap respectively.

Equivalent to calling al_set_clipping_rectangle (0, 0, w, h) where w and h are the width and height of the target bitmap respectively.

Does nothing if there is no target bitmap.

See also

al_set_clipping_rectangle

Sets the region of the target bitmap or display that pixels get clipped to.

Gets the clipping rectangle of the target bitmap.

See also

al_set_clipping_rectangle

Sets the region of the target bitmap or display that pixels get clipped to.

Creates a sub-bitmap of the parent, at the specified coordinates and of the specified size. A sub-bitmap is a bitmap that shares drawing memory with a pre-existing (parent) bitmap, but possibly with a different size and clipping settings.

The sub-bitmap may originate off or extend past the parent bitmap.

See the discussion in al_get_backbuffer about using sub-bitmaps of the backbuffer.

The parent bitmap's clipping rectangles are ignored.

If a sub-bitmap was not or cannot be created then Nil is returned.

When you are done with using the sub-bitmap you must call al_destroy_bitmap on it to free any resources allocated for it.

Note that destroying parents of sub-bitmaps will not destroy the sub-bitmaps; instead the sub-bitmaps become invalid and should no longer be used for drawing - they still must be destroyed with al_destroy_bitmap however. It does not matter whether you destroy a sub-bitmap before or after its parent otherwise.

See also

al_create_bitmap

Creates a new bitmap using the bitmap format and flags for the current thread.

al_is_sub_bitmap

Returns true if the specified bitmap is a sub-bitmap, false otherwise.

al_get_parent_bitmap

Returns the bitmap this bitmap is a sub-bitmap of.

Returns true if the specified bitmap is a sub-bitmap, false otherwise.

See also

al_create_sub_bitmap

Creates a sub-bitmap of the parent, at the specified coordinates and of the specified size.

al_get_parent_bitmap

Returns the bitmap this bitmap is a sub-bitmap of.

Returns the bitmap this bitmap is a sub-bitmap of. Returns Nil if this bitmap is not a sub-bitmap. This function always returns the real bitmap, and never a sub-bitmap. This might NOT match what was passed to al_create_sub_bitmap. Consider this code, for instance:

VAR
  a, b, c: ALLEGRO_BITMAPptr;
BEGIN
  a := al_create_bitmap (512, 512);
  b := al_create_sub_bitmap (a, 128, 128, 256, 256);
  c := al_create_sub_bitmap (b, 64, 64, 128, 128);
  IF (al_get_parent_bitmap (b) = a) AND (al_get_parent_bitmap (c) = a) THEN
    WriteLn ('b & c are sub-bitmaps of a')
END;

The message will be printed because only a is a real bitmap, and both b and c are its sub-bitmaps.

See also

al_create_sub_bitmap

Creates a sub-bitmap of the parent, at the specified coordinates and of the specified size.

al_is_sub_bitmap

Returns true if the specified bitmap is a sub-bitmap, false otherwise.

For a sub-bitmap, returns it's x position within the parent.

See also

al_create_sub_bitmap

Creates a sub-bitmap of the parent, at the specified coordinates and of the specified size.

al_get_parent_bitmap

Returns the bitmap this bitmap is a sub-bitmap of.

al_get_bitmap_y

For a sub-bitmap, returns it's y position within the parent.

For a sub-bitmap, returns it's y position within the parent.

See also

al_create_sub_bitmap

Creates a sub-bitmap of the parent, at the specified coordinates and of the specified size.

al_get_parent_bitmap

Returns the bitmap this bitmap is a sub-bitmap of.

al_get_bitmap_x

For a sub-bitmap, returns it's x position within the parent.

For a sub-bitmap, changes the parent, position and size. This is the same as destroying the bitmap and re-creating it with al_create_sub_bitmap - except the bitmap pointer stays the same. This has many uses, for example an animation player could return a single bitmap which can just be re-parented to different animation frames without having to re-draw the contents. Or a sprite atlas could re-arrange its sprites without having to invalidate all existing bitmaps.

See also

al_create_sub_bitmap

Creates a sub-bitmap of the parent, at the specified coordinates and of the specified size.

al_get_parent_bitmap

Returns the bitmap this bitmap is a sub-bitmap of.

Creates a new bitmap with al_create_bitmap, and copyes the pixel data from the old bitmap across. The newly created bitmap will be created with the current new bitmap flags, and not the ones that were used to create the original bitmap. If the new bitmap is a memory bitmap, its projection bitmap is reset to be orthographic.

See also

al_create_bitmap

Creates a new bitmap using the bitmap format and flags for the current thread.

al_set_new_bitmap_format

Sets the pixel format for newly created bitmaps.

al_set_new_bitmap_flags

Sets the flags to use for newly created bitmaps.

al_convert_bitmap

Converts the bitmap to the current bitmap flags and format.

Converts the bitmap to the current bitmap flags and format. The bitmap will be as if it was created new with al_create_bitmap but retain its contents. All of this bitmap's sub-bitmaps are also converted. If the new bitmap type is memory, then the bitmap's projection bitmap is reset to be orthographic.

If this bitmap is a sub-bitmap, then it, its parent and all the sibling sub-bitmaps are also converted.

See also

al_create_bitmap

Creates a new bitmap using the bitmap format and flags for the current thread.

al_set_new_bitmap_format

Sets the pixel format for newly created bitmaps.

al_set_new_bitmap_flags

Sets the flags to use for newly created bitmaps.

al_clone_bitmap

Creates a new bitmap with al_create_bitmap, and copyes the pixel data from the old bitmap across.

If you create a bitmap when there is no current display (for example because you have not called al_create_display in the current thread) and are using the ALLEGRO_CONVERT_BITMAP bitmap flag (which is set by default) then the bitmap will be created successfully, but as a memory bitmap. This function converts all such bitmaps to proper video bitmaps belonging to the current display.

Note that video bitmaps get automatically converted back to memory bitmaps when the last display is destroyed.

This operation will preserve all bitmap flags except ALLEGRO_VIDEO_BITMAP and ALLEGRO_MEMORY_BITMAP.

See also

al_convert_bitmap

Converts the bitmap to the current bitmap flags and format.

al_create_bitmap

Creates a new bitmap using the bitmap format and flags for the current thread.

Draws an unscaled, unrotated bitmap at the given position to the current target bitmap. flags can be a combination of:

• ALLEGRO_FLIP_HORIZONTAL - flip the bitmap about the y-axis

• ALLEGRO_FLIP_VERTICAL - flip the bitmap about the x-axis

Note

The current target bitmap must be a different bitmap. Drawing a bitmap to itself (or to a sub-bitmap of itself) or drawing a sub-bitmap to its parent (or another sub-bitmap of its parent) are not currently supported. To copy part of a bitmap into the same bitmap simply use a temporary bitmap instead.

Note

The backbuffer (or a sub-bitmap thereof) can not be transformed, blended or tinted. If you need to draw the backbuffer draw it to a temporary bitmap first with no active transformation (except translation). Blending and tinting settings/parameters will be ignored. This does not apply when drawing into a memory bitmap.

Parameters

bitmap

Origin bitmap.

dx

Destination x.

dy

Destination y.

flags

Read description above.

See also

al_set_target_bitmap

This function selects the bitmap to which all subsequent drawing operations in the calling thread will draw to.

al_draw_bitmap_region

Draws a region of the given bitmap to the target bitmap.

al_draw_scaled_bitmap

Draws a scaled version of the given bitmap to the target bitmap.

al_draw_rotated_bitmap

Draws a rotated version of the given bitmap to the target bitmap.

al_draw_scaled_rotated_bitmap

Like al_draw_rotated_bitmap, but can also scale the bitmap.

Draws a region of the given bitmap to the target bitmap.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

Parameters

bitmap

Origin bitmap.

sx

source x

sy

source y

sw

source width (width of region to blit)

sh

source height (height of region to blit)

dx

destination x

dy

destination y

flags

same as for al_draw_bitmap

See also

al_draw_bitmap

Draws an unscaled, unrotated bitmap at the given position to the current target bitmap.

al_draw_scaled_bitmap

Draws a scaled version of the given bitmap to the target bitmap.

al_draw_rotated_bitmap

Draws a rotated version of the given bitmap to the target bitmap.

al_draw_scaled_rotated_bitmap

Like al_draw_rotated_bitmap, but can also scale the bitmap.

Draws a scaled version of the given bitmap to the target bitmap.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

Parameters

bitmap

Origin bitmap.

sx

source x

sy

source y

sw

source width

sh

source height

dx

destination x

dy

destination y

dw

destination width

dh

destination height

flags

same as for al_draw_bitmap

See also

al_draw_bitmap

Draws an unscaled, unrotated bitmap at the given position to the current target bitmap.

al_draw_bitmap_region

Draws a region of the given bitmap to the target bitmap.

al_draw_rotated_bitmap

Draws a rotated version of the given bitmap to the target bitmap.

al_draw_scaled_rotated_bitmap

Like al_draw_rotated_bitmap, but can also scale the bitmap.

Draws a rotated version of the given bitmap to the target bitmap.

The point at cx/cy relative to the upper left corner of the bitmap will be drawn at dx/dy and the bitmap is rotated around this point. If cx,cy is 0,0 the bitmap will rotate around its upper left corner.

Example:

VAR
  w, h: SINGLE;
BEGIN
  w := al_get_bitmap_width (bitmap);
  h := al_get_bitmap_height (bitmap);
  al_draw_rotated_bitmap (bitmap, w / 2, h / 2, x, y, ALLEGRO_PI / 2, 0)
END;

The above code draws the bitmap centered on x/y and rotates it 90° clockwise.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

Parameters

bitmap

Origin bitmap.

cx

center x (relative to the left of bitmap)

cy

center y (relative to the top or bitmap)

dx

destination x

dy

destination y

angle

angle in radians by which to rotate clockwise

flags

same as for al_draw_bitmap

See also

al_draw_bitmap

Draws an unscaled, unrotated bitmap at the given position to the current target bitmap.

al_draw_bitmap_region

Draws a region of the given bitmap to the target bitmap.

al_draw_scaled_bitmap

Draws a scaled version of the given bitmap to the target bitmap.

al_draw_scaled_rotated_bitmap

Like al_draw_rotated_bitmap, but can also scale the bitmap.

Like al_draw_rotated_bitmap, but can also scale the bitmap.

The point at cx/cy in the bitmap will be drawn at dx/dy and the bitmap is rotated and scaled around this point.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

Parameters

bitmap

Origin bitmap.

cx

center x (relative to the left of bitmap)

cy

center y (relative to the top or bitmap)

dx

destination x

dy

destination y

xscale

how much to scale on the x-axis (e.g. 2 for twice the size)

yscale

how much to scale on the y-axis

angle

angle in radians by which to rotate clockwise

flags

same as for al_draw_bitmap

See also

al_draw_bitmap

Draws an unscaled, unrotated bitmap at the given position to the current target bitmap.

al_draw_bitmap_region

Draws a region of the given bitmap to the target bitmap.

al_draw_scaled_bitmap

Draws a scaled version of the given bitmap to the target bitmap.

Like al_draw_bitmap but multiplies all colors in the bitmap with the given color. For example:

al_draw_tinted_bitmap (bitmap, al_map_rgba_f (0.5, 0.5, 0.5, 0.5), x, y, 0);

The above will draw the bitmap 50% transparently (r/g/b values need to be pre-multiplied with the alpha component with the default blend mode).

al_draw_tinted_bitmap(bitmap, al_map_rgba_f(1, 0, 0, 1), x, y, 0);

The above will only draw the red component of the bitmap.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also

al_draw_bitmap

Draws an unscaled, unrotated bitmap at the given position to the current target bitmap.

al_draw_tinted_bitmap_region

Like al_draw_bitmap_region but multiplies all colors in the bitmap with the given color.

al_draw_tinted_scaled_bitmap

Like al_draw_scaled_bitmap but multiplies all colors in the bitmap with the given color.

al_draw_tinted_rotated_bitmap

Like al_draw_rotated_bitmap but multiplies all colors in the bitmap with the given color.

al_draw_tinted_scaled_rotated_bitmap

Like al_draw_scaled_rotated_bitmap but multiplies all colors in the bitmap with the given color.

al_draw_tinted_scaled_rotated_bitmap_region

Like al_draw_tinted_scaled_rotated_bitmap but you specify an area within the bitmap to be drawn.

Like al_draw_bitmap_region but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be

See also

al_draw_tinted_bitmap

Like al_draw_bitmap but multiplies all colors in the bitmap with the given color.

Like al_draw_scaled_bitmap but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be

See also

al_draw_tinted_bitmap

Like al_draw_bitmap but multiplies all colors in the bitmap with the given color.

Like al_draw_rotated_bitmap but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be

See also

al_draw_tinted_bitmap

Like al_draw_bitmap but multiplies all colors in the bitmap with the given color.

Like al_draw_scaled_rotated_bitmap but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also

al_draw_tinted_bitmap

Like al_draw_bitmap but multiplies all colors in the bitmap with the given color.

Like al_draw_tinted_scaled_rotated_bitmap but you specify an area within the bitmap to be drawn.

You can get the same effect with a sub bitmap:

  al_draw_tinted_scaled_rotated_bitmap_region (
    bitmap, sx, sy, sw, sh, tint,
    cx, cy, dx, dy, xscale, yscale, angle, flags
  );

{ Next code draws the same: }
  sub_bitmap := al_create_sub_bitmap (bitmap, sx, sy, sw, sh);
  al_draw_tinted_scaled_rotated_bitmap (
    sub_bitmap, tint, cx, cy,
    dx, dy, xscale, yscale, angle, flags
  );

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also

al_draw_tinted_bitmap

Like al_draw_bitmap but multiplies all colors in the bitmap with the given color.

Creates and opens a file (real or virtual) given the path and mode. The current file interface is used to open the file.

Depending on the stream type and the mode string, files may be opened in "text" mode. The handling of newlines is particularly important. For example, using the default stdio-based streams on DOS and Windows platforms, where the native end-of-line terminators are CR+LF sequences, a call to al_fgetc may return just one character ('\n') where there were two bytes (CR+LF) in the file. When writing out '\n', two bytes would be written instead. (As an aside, '\n' is not defined to be equal to LF either.)

Newline translations can be useful for text files but is disastrous for binary files. To avoid this behaviour you need to open file streams in binary mode by using a mode argument containing a "b", e.g. 'rb', 'wb.

Parameters

path

Path to the file to open.

mode

Access mode to open the file in ('r', 'w', etc.).

Returns

a file handle on success, or Nil on error.

See also

al_fclose

Closes the given file, writing any buffered output data (if any).

al_set_new_file_interface

Sets the ALLEGRO_FILE_INTERFACE table for the calling thread.

al_fopen_interface

Opens a file using the specified interface, instead of the interface set with al_set_new_file_interface.

al_fread

Reads size bytes into the buffer pointed to by ptr, from the given file.

al_fwrite

Write size bytes from the buffer pointed to by ptr into the given file.

Opens a file using the specified interface, instead of the interface set with al_set_new_file_interface.

See also

al_fopen

Creates and opens a file (real or virtual) given the path and mode.

Creates an empty, opened file handle with some abstract user data. This allows custom interfaces to extend the ALLEGRO_FILEptr struct with their own data. You should close the handle with the standard al_fclose function when you are finished with it.

See also

al_fopen

Creates and opens a file (real or virtual) given the path and mode.

al_fclose

Closes the given file, writing any buffered output data (if any).

al_set_new_file_interface

Sets the ALLEGRO_FILE_INTERFACE table for the calling thread.

Closes the given file, writing any buffered output data (if any).

Returns

True on success, False on failure.

See also

al_fopen

Creates and opens a file (real or virtual) given the path and mode.

Reads size bytes into the buffer pointed to by ptr, from the given file.

Returns

The number of bytes actually read. If an error occurs, or the end-of-file is reached, the return value is a short byte count (or zero).

al_fread does not distinguish between AL_EOF and other errors. Use al_feof and al_ferror to determine which occurred.

See also

AL_EOF

End of file.

al_fgetc

Reads and returns next byte in the given file.

al_fwrite

Write size bytes from the buffer pointed to by ptr into the given file.

al_fread16be

Reads a 16-bit word in big-endian format (MSB first).

al_fread16le

Reads a 16-bit word in little-endian format (LSB first).

al_fread32be

Reads a 32-bit word in big-endian format (MSB first).

al_fread32le

Reads a 32-bit word in little-endian format (LSB first).

Write size bytes from the buffer pointed to by ptr into the given file.

Returns

The number of bytes actually written. If an error occurs, the return value is a short byte count (or zero).

See also

al_fputc

Writes a single byte to the given file.

al_fputs

Writes a string to file.

al_fread

Reads size bytes into the buffer pointed to by ptr, from the given file.

al_fwrite16be

Writes a 16-bit word in big-endian format (MSB first).

al_fwrite16le

Writes a 16-bit word in little-endian format (LSB first).

al_fwrite32be

Writes a 32-bit word in big-endian format (MSB first).

al_fwrite32le

Writes a 32-bit word in little-endian format (LSB first).

Flushes any pending writes to the given file.

Returns

True on success, False otherwise.

See also

al_get_errno

Some Allegro functions will set an error number as well as returning an error code.

Returns the current position in the given file, or -1 on error.

On some platforms this function may not support large files.

See also

al_fseek

Sets the current position of the given file to a position relative to that specified by whence, plus offset number of bytes.

al_get_errno

Some Allegro functions will set an error number as well as returning an error code.

Sets the current position of the given file to a position relative to that specified by whence, plus offset number of bytes.

whence can be:

• ALLEGRO_SEEK_SET - seek relative to beginning of file

• ALLEGRO_SEEK_CUR - seek relative to current file position

• ALLEGRO_SEEK_END - seek relative to end of file

After a successful seek, the end-of-file indicator is cleared and all pushback bytes are forgotten.

On some platforms this function may not support large files.

Returns

True on success, False on failure.

See also

al_ftell

Returns the current position in the given file, or -1 on error.

al_get_errno

Some Allegro functions will set an error number as well as returning an error code.

Returns True if the end-of-file indicator has been set on the file, i.e. we have attempted to read past the end of the file.

This does not return True if we simply are at the end of the file. The following code correctly reads two bytes, even when the file contains exactly two bytes:

b1 := al_fgetc (f);
b2 := al_fgetc (f);
IF al_feof (f) THEN
{ At least one byte was unsuccessfully read. }
  ReportError ();

See also

AL_EOF

End of file.

al_ferror

Returns non-zero if the error indicator is set on the given file, i.e.

al_fclearerr

Clears the error indicator for the given file.

Returns non-zero if the error indicator is set on the given file, i.e. there was some sort of previous error. The error code may be system or file interface specific.

See also

al_feof

Returns True if the end-of-file indicator has been set on the file, i.e.

al_fclearerr

Clears the error indicator for the given file.

al_ferrmsg

Returns a message string with details about the last error that occurred on the given file handle.

Returns a message string with details about the last error that occurred on the given file handle. The returned string is empty if there was no error, or if the file interface does not provide more information.

See also

al_fclearerr

Clears the error indicator for the given file.

al_ferror

Returns non-zero if the error indicator is set on the given file, i.e.

Clears the error indicator for the given file.

The standard I/O backend also clears the end-of-file indicator, and other backends should try to do this. However, they may not if it would require too much effort (e.g. PhysicsFS backend), so your code should not rely on it if you need your code to be portable to other backends.

See also

al_ferror

Returns non-zero if the error indicator is set on the given file, i.e.

al_feof

Returns True if the end-of-file indicator has been set on the file, i.e.

Ungets a single byte from a file. Pushed-back bytes are not written to the file, only made available for subsequent reads, in reverse order.

The number of pushbacks depends on the backend. The standard I/O backend only guarantees a single pushback; this depends on the libc implementation.

For backends that follow the standard behavior, the pushback buffer will be cleared after any seeking or writing; also calls to al_fseek and al_ftell are relative to the number of pushbacks. If a pushback causes the position to become negative, the behavior of al_fseek and al_ftell are undefined.

See also

al_fgetc

Reads and returns next byte in the given file.

al_get_errno

Some Allegro functions will set an error number as well as returning an error code.

Returns the size of the file, if it can be determined, or -1 otherwise.

Reads and returns next byte in the given file. Returns a negative number on end of file or if an error occurred.

See also

al_fputc

Writes a single byte to the given file.

al_fungetc

Ungets a single byte from a file.

Writes a single byte to the given file. The byte written is the value of c cast to an unsigned char.

Parameters

c

byte value to write.

f

file to write to.

Returns

the written byte (cast back to an AL_INT) on success, or negative number on error.

Reads a 16-bit word in little-endian format (LSB first).

Returns

On success, the 16-bit word. On failure, returns EOF (-1). Since -1 is also a valid return value, use al_feof to check if the end of the file was reached prematurely, or al_ferror to check if an error occurred.

See also

al_fread16be

Reads a 16-bit word in big-endian format (MSB first).

Reads a 16-bit word in big-endian format (MSB first).

Returns

On success, the 16-bit word. On failure, returns EOF (-1). Since -1 is also a valid return value, use al_feof to check if the end of the file was reached prematurely, or al_ferror to check if an error occurred.

See also

al_fread16le

Reads a 16-bit word in little-endian format (LSB first).

Writes a 16-bit word in little-endian format (LSB first).

Returns

The number of bytes written: 2 on success, less than 2 on an error.

See also

al_fwrite16be

Writes a 16-bit word in big-endian format (MSB first).

Writes a 16-bit word in big-endian format (MSB first).

Returns

The number of bytes written: 2 on success, less than 2 on an error.

See also

al_fwrite16le

Writes a 16-bit word in little-endian format (LSB first).

Reads a 32-bit word in little-endian format (LSB first).

Returns

On success, the 32-bit word. On failure, returns EOF (-1). Since -1 is also a valid return value, use al_feof to check if the end of the file was reached prematurely, or al_ferror to check if an error occurred.

See also

al_fread32be

Reads a 32-bit word in big-endian format (MSB first).

Reads a 32-bit word in big-endian format (MSB first).

Returns

On success, the 32-bit word. On failure, returns EOF (-1). Since -1 is also a valid return value, use al_feof to check if the end of the file was reached prematurely, or al_ferror to check if an error occurred.

See also

al_fread32le

Reads a 32-bit word in little-endian format (LSB first).

Writes a 32-bit word in little-endian format (LSB first).

Returns

The number of bytes written: 2 on success, less than 2 on an error.

See also

al_fwrite32be

Writes a 32-bit word in big-endian format (MSB first).

Writes a 32-bit word in big-endian format (MSB first).

Returns

The number of bytes written: 2 on success, less than 2 on an error.

See also

al_fwrite32le

Writes a 32-bit word in little-endian format (LSB first).

Reads a string of bytes terminated with a newline or end-of-file into the buffer given. The line terminator(s), if any, are included in the returned string. A maximum of max-1 bytes are read, with one byte being reserved for a NUL terminator.

See al_fopen about translations of end-of-line characters.

Parameters

f

File to read from.

buf

Buffer to fill.

max

Maximum size of buffer.

Returns

The pointer to buf on success. Returns Nil if an error occurred or if the end of file was reached without reading any bytes.

See also

al_fget_ustr

Read a string of bytes terminated with a newline or end-of-file.

Read a string of bytes terminated with a newline or end-of-file. The line terminator(s), if any, are included in the returned string.

See al_fopen about translations of end-of-line characters.

Returns

On success a pointer to a new ALLEGRO_USTR structure. This must be freed eventually with al_ustr_free. Returns Nil if an error occurred or if the end of file was reached without reading any bytes.

See also

al_fgetc

Reads and returns next byte in the given file.

al_fgets

Reads a string of bytes terminated with a newline or end-of-file into the buffer given.

Writes a string to file. Apart from the return value, this is equivalent to al_fwrite (f, p, Length (p));

Note

depending on the stream type and the mode passed to al_fopen, newline characters in the string may or may not be automatically translated to native end-of-line sequences, e.g. CR/LF instead of LF.

Parameters

f

File handle to write to.

p

String to write.

Returns

A non-negative integer on success, EOF (-1) on error.

See also

al_fwrite

Write size bytes from the buffer pointed to by ptr into the given file.

Opens a slice (subset) of an already open random access file as if it were a stand alone file. While the slice is open, the parent file handle must not be used in any way.

The slice is opened at the current location of the parent file, up through initial_size bytes. The initial_size may be any non-negative integer that will not exceed the bounds of the parent file.

Seeking with ALLEGRO_SEEK_SET will be relative to this starting location. ALLEGRO_SEEK_END will be relative to the starting location plus the size of the slice.

The mode can be any combination of:

• r: read access

• w: write access

• e: expandable

For example, a mode of 'rw' indicates the file can be read and written. (Note that this is slightly different from the stdio modes.) Keep in mind that the parent file must support random access and be open in normal write mode (not append) for the slice to work in a well defined way.

If the slice is marked as expandable, then reads and writes can happen after the initial end point, and the slice will grow accordingly. Otherwise, all activity is restricted to the initial size of the slice.

A slice must be closed with al_fclose. The parent file will then be positioned immediately after the end of the slice.

See also

al_fopen

Creates and opens a file (real or virtual) given the path and mode.

Returns a pointer to the ALLEGRO_FILE_INTERFACE table in effect for the calling thread.

See also

al_store_state

Stores part of the state of the current thread in the given ALLEGRO_STATE object.

al_restore_state

Restores part of the state of the current thread from the given ALLEGRO_STATE object.

al_set_new_file_interface

Sets the ALLEGRO_FILE_INTERFACE table for the calling thread.

Sets the ALLEGRO_FILE_INTERFACE table for the calling thread. This will change the handler for later calls to al_fopen.

See also

al_set_standard_file_interface

Sets the ALLEGRO_FILE_INTERFACE table to the default, for the calling thread.

al_store_state

Stores part of the state of the current thread in the given ALLEGRO_STATE object.

al_restore_state

Restores part of the state of the current thread from the given ALLEGRO_STATE object.

Sets the ALLEGRO_FILE_INTERFACE table to the default, for the calling thread. This will change the handler for later calls to al_fopen.

See also

al_set_new_file_interface

Sets the ALLEGRO_FILE_INTERFACE table for the calling thread.

Returns a pointer to the custom userdata that is attached to the file handle. This is intended to be used by functions that extend ALLEGRO_FILE_INTERFACE.

Registers a handler for al_load_bitmap.

Parameters

ext

File extension. It should include the leading dot ('.') character. It will be matched case-insensitively.

loader

The given function used to handle the loading of bitmaps files with the given extension. It may be Nil to unregister an entry.

Returns

True on success, False on error. Returns False if unregistering an entry that doesn't exist.

See also

al_register_bitmap_saver

Registers a handler for al_save_bitmap.

al_register_bitmap_loader_f

Registers a handler for al_load_bitmap_f.

Registers a handler for al_save_bitmap.

Parameters

ext

File extension. It should include the leading dot ('.') character. It will be matched case-insensitively.

saver

The given function used to handle the savint of bitmaps files with the given extension. It may be Nil to unregister an entry.

Returns

True on success, False on error. Returns False if unregistering an entry that doesn't exist.

See also

al_register_bitmap_loader

Registers a handler for al_load_bitmap.

al_register_bitmap_saver_f

Registers a handler for al_save_bitmap_f.

Registers a handler for al_load_bitmap_f.

Parameters

ext

File extension. It should include the leading dot ('.') character. It will be matched case-insensitively.

fs_loader

The given function used to handle the loading of bitmaps files with the given extension. It may be Nil to unregister an entry.

Returns

True on success, False on error. Returns False if unregistering an entry that doesn't exist.

See also

al_register_bitmap_loader

Registers a handler for al_load_bitmap.

Registers a handler for al_save_bitmap_f.

Parameters

ext

File extension. It should include the leading dot ('.') character. It will be matched case-insensitively.

fs_saver

The given function used to handle the savint of bitmaps files with the given extension. It may be Nil to unregister an entry.

Returns

True on success, False on error. Returns False if unregistering an entry that doesn't exist.

See also

al_register_bitmap_saver

Registers a handler for al_save_bitmap.

Registers an identify handler for al_identify_bitmap. The given function will be used to detect files for the given extension. It will be called with a single argument of type ALLEGRO_FILEptr which is a file handle opened for reading and located at the first byte of the file. The handler should try to read as few bytes as possible to safely determine if the given file contents correspond to the type with the extension and return True in that case, False otherwise. The file handle must not be closed but there is no need to reset it to the beginning.

Parameters

ext

The extension. It should include the leading dot ('.') character. It will be matched case-insensitively.

identifier

The identifier handler. It may be Nil to unregister an entry.

Returns

True on success, False on error. Returns False if unregistering an entry that doesn't exist.

See also

al_identify_bitmap

This works exactly as al_identify_bitmap_f but you specify the filename of the file for which to detect the type and not a file handle.

Loads an image file into a new ALLEGRO_BITMAPptr. The file type is determined by the extension, except if the file has no extension in which case al_identify_bitmap is used instead.

This is the same as calling al_load_bitmap_flags with a flags parameter of 0.

Note

the core Allegro library does not support any image file formats by default. You must use the al5image addon, or register your own format handler.

Returns

A pointer to the loaded bitmap or Nil on error.

See also

al_load_bitmap_f

Loads an image from an ALLEGRO_FILEptr stream into a new ALLEGRO_BITMAPptr.

al_register_bitmap_loader

Registers a handler for al_load_bitmap.

al_load_bitmap_flags

Loads an image file into a new ALLEGRO_BITMAPptr.

al_set_new_bitmap_format

Sets the pixel format for newly created bitmaps.

al_set_new_bitmap_flags

Sets the flags to use for newly created bitmaps.

al_init_image_addon

Initializes the image addon.

Loads an image file into a new ALLEGRO_BITMAPptr. The file type is determined by the extension, except if the file has no extension in which case al_identify_bitmap is used instead.

Note: the core Allegro library does not support any image file formats by default. You must use the al5image addon, or register your own format handler.

Parameters

filename

The file to load.

flags

It may be a combination of the following constants:

• ALLEGRO_NO_PREMULTIPLIED_ALPHA By default, Allegro pre-multiplies the alpha channel of an image with the images color data when it loads it. Typically that would look something like this:

  r := get_float_byte;
  g := get_float_byte;
  b := get_float_byte;
  a := get_float_byte;
  
  r := r * a;
  g := g * a;
  b := b * a;
  
  set_image_pixel (x, y, r, g, b, a);

  The reason for this can be seen in the Allegro example ex_premulalpha, ie, using pre-multiplied alpha gives more accurate color results in some cases. To use alpha blending with images loaded with pre-multiplied alpha, you would use the default blending mode, which is set with al_set_blender (ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_INVERSE_ALPHA).

  The ALLEGRO_NO_PREMULTIPLIED_ALPHA flag being set will ensure that images are not loaded with alpha pre-multiplied, but are loaded with color values direct from the image. That looks like this:

  r := get_float_byte;
  g := get_float_byte;
  b := get_float_byte;
  a := get_float_byte;
  
  set_image_pixel (x, y, r, g, b, a);

  To draw such an image using regular alpha blending, you would use al_set_blender (ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA) to set the correct blender. This has some caveats. First, as mentioned above, drawing such an image can result in less accurate color blending (when drawing an image with linear filtering on, the edges will be darker than they should be). Second, the behaviour is somewhat confusing, which is explained in the example below.

  { Load and create bitmaps with an alpha channel. }
    al_set_new_bitmap_format (ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA);
  { Load some bitmap with alpha in it. }
    bmp := al_load_bitmap ('some_alpha_bitmap.png');
  { We will draw to this buffer and then draw this buffer to the screen. }
    tmp_buffer := al_create_bitmap (SCREEN_W, SCREEN_H);
  { Set the buffer as the target and clear it. }
    al_set_target_bitmap (tmp_buffer);
    al_clear_to_color (al_map_rgba_f (0, 0, 0, 1));
  { Draw the bitmap to the temporary buffer. }
    al_draw_bitmap (bmp, 0, 0, 0);
  { Finally, draw the buffer to the screen.
    The output will look incorrect (may take close inspection
    depending on the bitmap -- it may also be very obvious). }
    al_set_target_bitmap (al_get_backbuffer (display));
    al_draw_bitmap (tmp_buffer, 0, 0, 0);

  To explain further, if you have a pixel with 0.5 alpha, and you're using (ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA) for blending, the formula is:

  a := da * dst + sa * src

  Expands to:

  result_a := dst_a * (1-0.5) + 0.5 * 

  So if you draw the image to the temporary buffer, it is blended once resulting in 0.75 alpha, then drawn again to the screen, blended in the same way, resulting in a pixel has 0.1875 as an alpha value.

• ALLEGRO_KEEP_INDEX

  Load the palette indices of 8-bit .bmp and .pcx files instead of the rgb colors.

• ALLEGRO_KEEP_BITMAP_FORMAT

  Force the resulting ALLEGRO_BITMAP to use the same format as the file.

  This is not yet honoured.

Returns

A pointer to the loaded bitmap or Nil on error.

See also

al_load_bitmap

Loads an image file into a new ALLEGRO_BITMAPptr.

Loads an image from an ALLEGRO_FILEptr stream into a new ALLEGRO_BITMAPptr. The file type is determined by the passed ident parameter, which is a file name extension including the leading dot. If (and only if) ident is an empty string, the file type is determined with al_identify_bitmap_f instead.

This is the same as calling al_load_bitmap_flags_f with 0 for the flags parameter.

Note

the core Allegro library does not support any image file formats by default. You must use the al5image addon, or register your own format handler.

Returns

A pointer to the loaded bitmap or Nil on error. The file remains open afterwards.

See also

al_load_bitmap_flags_f

Loads an image from an ALLEGRO_FILEptr stream into a new ALLEGRO_BITMAPptr.

al_load_bitmap

Loads an image file into a new ALLEGRO_BITMAPptr.

al_register_bitmap_loader_f

Registers a handler for al_load_bitmap_f.

al_init_image_addon

Initializes the image addon.

Loads an image from an ALLEGRO_FILEptr stream into a new ALLEGRO_BITMAPptr. The file type is determined by the passed ident parameter, which is a file name extension including the leading dot. If (and only if) ident is an empty string, the file type is determined with al_identify_bitmap_f instead.

The flags parameter is the same as for al_load_bitmap_flags.

Note

the core Allegro library does not support any image file formats by default. You must use the al5image addon, or register your own format handler.

Returns

A pointer to the loaded bitmap or Nil on error. The file remains open afterwards.

See also

al_load_bitmap_f

Loads an image from an ALLEGRO_FILEptr stream into a new ALLEGRO_BITMAPptr.

al_load_bitmap_flags

Loads an image file into a new ALLEGRO_BITMAPptr.

Saves an ALLEGRO_BITMAP to an image file. The file type is determined by the extension.

Note

the core Allegro library does not support any image file formats by default. You must use the al5image addon, or register your own format handler.

Returns

True on success, False on error.

See also

al_save_bitmap_f

Saves an ALLEGRO_BITMAP to an ALLEGRO_FILE stream.

al_register_bitmap_saver

Registers a handler for al_save_bitmap.

al_init_image_addon

Initializes the image addon.

Saves an ALLEGRO_BITMAP to an ALLEGRO_FILE stream. The file type is determined by the passed ident parameter, which is a file name extension including the leading dot.

Note

the core Allegro library does not support any image file formats by default. You must use the al5image addon, or register your own format handler.

Returns

True on success, False on error. The file remains open afterwards.

See also

al_save_bitmap

Saves an ALLEGRO_BITMAP to an image file.

al_register_bitmap_saver_f

Registers a handler for al_save_bitmap_f.

al_init_image_addon

Initializes the image addon.

Tries to guess the bitmap file type of the given file by reading the first few bytes. The extension, if any, of the passed filename is not taken into account - only the file contents. By default Allegro cannot recognize any file types, but calling al_init_image_addon will add detection of (some of) the types it can read. You can also use al_register_bitmap_identifier to add identification of custom file types.

Returns

a pointer to a static string with a file extension for the type, including the leading dot. For example ".png" or ".jpg". Returns Nil if the bitmap type cannot be determined.

See also

al_init_image_addon

Initializes the image addon.

al_identify_bitmap

This works exactly as al_identify_bitmap_f but you specify the filename of the file for which to detect the type and not a file handle.

al_register_bitmap_identifier

Registers an identify handler for al_identify_bitmap.

This works exactly as al_identify_bitmap_f but you specify the filename of the file for which to detect the type and not a file handle. The extension, if any, of the passed filename is not taken into account - only the file contents.

See also

al_init_image_addon

Initializes the image addon.

al_identify_bitmap_f

Tries to guess the bitmap file type of the given file by reading the first few bytes.

al_register_bitmap_identifier

Registers an identify handler for al_identify_bitmap.

Locks an entire bitmap for reading or writing. If the bitmap is a display bitmap it will be updated from system memory after the bitmap is unlocked (unless locked read only).

Note: For some reason, this function seems not to work properly on Windows, neither using Delphi nor Free Pascal.

On some platforms, Allegro automatically backs up the contents of video bitmaps because they may be occasionally lost (see discussion in al_create_bitmap's documentation). If you're completely recreating the bitmap contents often (e.g. every frame) then you will get much better performance by creating the target bitmap with ALLEGRO_NO_PRESERVE_TEXTURE flag.

Note

While a bitmap is locked, you can not use any drawing operations on it (with the sole exception of al_put_pixel and al_put_blended_pixel).

Parameters

flags

• ALLEGRO_LOCK_READONLY The locked region will not be written to. This can be faster if the bitmap is a video texture, as it can be discarded after the lock instead of uploaded back to the card.

• ALLEGRO_LOCK_WRITEONLY The locked region will not be read from. This can be faster if the bitmap is a video texture, as no data need to be read from the video card. You are required to fill in all pixels before unlocking the bitmap again, so be careful when using this flag.

• ALLEGRO_LOCK_READWRITE The locked region can be written to and read from. Use this flag if a partial number of pixels need to be written to, even if reading is not needed.

format

Indicates the pixel format that the returned buffer will be in. To lock in the same format as the bitmap stores its data internally, call with al_get_bitmap_format (bitmap) as the format or use ALLEGRO_PIXEL_FORMAT_ANY. Locking in the native format will usually be faster. If the bitmap format is compressed, using ALLEGRO_PIXEL_FORMAT_ANY will choose an implementation defined non-compressed format.

Returns

Nil if the bitmap cannot be locked, e.g. the bitmap was locked previously and not unlocked. It also returns Nil if the format is a compressed format.

See also

ALLEGRO_LOCKED_REGION

Users who wish to manually edit or read from a bitmap are required to lock it first.

ALLEGRO_PIXEL_FORMAT

Pixel formats.

al_unlock_bitmap

Unlocks a previously locked bitmap or bitmap region.

al_lock_bitmap_region

Like al_lock_bitmap, but only locks a specific area of the bitmap.

al_lock_bitmap_blocked

Like al_lock_bitmap, but allows locking bitmaps with a blocked pixel format (i.e.

al_lock_bitmap_region_blocked

Like al_lock_bitmap_blocked, but allows locking a sub-region, for performance.

Like al_lock_bitmap, but only locks a specific area of the bitmap. If the bitmap is a video bitmap, only that area of the texture will be updated when it is unlocked. Locking only the region you indend to modify will be faster than locking the whole bitmap.

Note

Using the ALLEGRO_LOCK_WRITEONLY with a blocked pixel format (i.e. formats for which al_get_pixel_block_width or al_get_pixel_block_height do not return 1) requires you to have the region be aligned to the block width for optimal performance. If it is not, then the function will have to lock the region with the ALLEGRO_LOCK_READWRITE instead in order to pad this region with valid data.

See also

ALLEGRO_LOCKED_REGION

Users who wish to manually edit or read from a bitmap are required to lock it first.

ALLEGRO_PIXEL_FORMAT

Pixel formats.

al_unlock_bitmap

Unlocks a previously locked bitmap or bitmap region.

Like al_lock_bitmap, but allows locking bitmaps with a blocked pixel format (i.e. a format for which al_get_pixel_block_width or al_get_pixel_block_height do not return 1) in that format. To that end, this function also does not allow format conversion. For bitmap formats with a block size of 1, this function is identical to calling al_lock_bitmap (bmp, al_get_bitmap_format (bmp), flags).

Note

Currently there are no drawing functions that work when the bitmap is locked with a compressed format. al_get_pixel will also not work.

See also

al_lock_bitmap

Locks an entire bitmap for reading or writing.

al_lock_bitmap_region_blocked

Like al_lock_bitmap_blocked, but allows locking a sub-region, for performance.

Like al_lock_bitmap_blocked, but allows locking a sub-region, for performance. Unlike al_lock_bitmap_region the region specified in terms of blocks and not pixels.

See also

al_lock_bitmap_region

Like al_lock_bitmap, but only locks a specific area of the bitmap.

al_lock_bitmap_blocked

Like al_lock_bitmap, but allows locking bitmaps with a blocked pixel format (i.e.

Unlocks a previously locked bitmap or bitmap region. If the bitmap is a video bitmap, the texture will be updated to match the system memory copy (unless it was locked read only).

See also

al_lock_bitmap

Locks an entire bitmap for reading or writing.

al_lock_bitmap_region

Like al_lock_bitmap, but only locks a specific area of the bitmap.

al_lock_bitmap_blocked

Like al_lock_bitmap, but allows locking bitmaps with a blocked pixel format (i.e.

al_lock_bitmap_region_blocked

Like al_lock_bitmap_blocked, but allows locking a sub-region, for performance.

Returns whether or not a bitmap is already locked.

See also

al_lock_bitmap

Locks an entire bitmap for reading or writing.

al_lock_bitmap_region

Like al_lock_bitmap, but only locks a specific area of the bitmap.

al_unlock_bitmap

Unlocks a previously locked bitmap or bitmap region.

Sets the function to use for blending for the current thread.

Blending means, the source and destination colors are combined in drawing operations.

Assume the source color (e.g. color of a rectangle to draw, or pixel of a bitmap to draw) is given as its red/green/blue/alpha components (if the bitmap has no alpha it always is assumed to be fully opaque, so 255 for 8-bit or 1.0 for floating point): s = s.r, s.g, s.b, s.a. And this color is drawn to a destination, which already has a color: d = d.r, d.g, d.b, d.a.

The conceptional formula used by Allegro to draw any pixel then depends on the op parameter:

• ALLEGRO_ADD

  r = d.r * df.r + s.r * sf.r
  g = d.g * df.g + s.g * sf.g
  b = d.b * df.b + s.b * sf.b
  a = d.a * df.a + s.a * sf.a

• ALLEGRO_DEST_MINUS_SRC

  r = d.r * df.r - s.r * sf.r
  g = d.g * df.g - s.g * sf.g
  b = d.b * df.b - s.b * sf.b
  a = d.a * df.a - s.a * sf.a

• ALLEGRO_SRC_MINUS_DEST

  r = s.r * sf.r - d.r * df.r
  g = s.g * sf.g - d.g * df.g
  b = s.b * sf.b - d.b * df.b
  a = s.a * sf.a - d.a * df.a

Valid values for the factors sf and df passed to this function are as follows, where s is the source color, d the destination color and cc the color set with al_set_blend_color (white by default)

• ALLEGRO_ZERO f = 0, 0, 0, 0

• ALLEGRO_ONE f = 1, 1, 1, 1

• ALLEGRO_ALPHA f = s.a, s.a, s.a, s.a

• ALLEGRO_INVERSE_ALPHA f = 1 - s.a, 1 - s.a, 1 - s.a, 1 - s.a

• ALLEGRO_SRC_COLOR f = s.r, s.g, s.b, s.a

• ALLEGRO_DEST_COLOR f = d.r, d.g, d.b, d.a

• ALLEGRO_INVERSE_SRC_COLOR f = 1 - s.r, 1 - s.g, 1 - s.b, 1 - s.a

• ALLEGRO_INVERSE_DEST_COLOR f = 1 - d.r, 1 - d.g, 1 - d.b, 1 - d.a

• ALLEGRO_CONST_COLOR f = cc.r, cc.g, cc.b, cc.a

• ALLEGRO_INVERSE_CONST_COLOR f = 1 - cc.r, 1 - cc.g, 1 - cc.b, 1 - cc.a

So for example, to restore the default of using premultiplied alpha blending, you would use:

al_set_blender (ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_INVERSE_ALPHA);

As formula:

r = d.r * (1 - s.a) + s.r * 1
g = d.g * (1 - s.a) + s.g * 1
b = d.b * (1 - s.a) + s.b * 1
a = d.a * (1 - s.a) + s.a * 1

If you are using non-pre-multiplied alpha, you could use

al_set_blender(ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA);

Additive blending would be achieved with

al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ONE);

Copying the source to the destination (including alpha) unmodified

al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ZERO);

Multiplying source and destination components

al_set_blender(ALLEGRO_ADD, ALLEGRO_DEST_COLOR, ALLEGRO_ZERO)

Tinting the source (like al_draw_tinted_bitmap)

al_set_blender(ALLEGRO_ADD, ALLEGRO_CONST_COLOR, ALLEGRO_ONE);
al_set_blend_color(al_map_rgb(0, 96, 255)); { nice Chrysler blue }

Averaging source and destination pixels

al_set_blender(ALLEGRO_ADD, ALLEGRO_CONST_COLOR, ALLEGRO_CONST_COLOR);
al_set_blend_color(al_map_rgba_f(0.5, 0.5, 0.5, 0.5));

As formula:

r = d.r * 0 + s.r * d.r
g = d.g * 0 + s.g * d.g
b = d.b * 0 + s.b * d.b
a = d.a * 0 + s.a * d.a

See also

al_set_separate_blender

Like al_set_blender, but allows specifying a separate blending operation for the alpha channel.

al_set_blend_color

Sets the color to use for blending when using the ALLEGRO_CONST_COLOR or ALLEGRO_INVERSE_CONST_COLOR blend functions.

al_get_blender

Returns the active blender for the current thread.

Sets the color to use for blending when using the ALLEGRO_CONST_COLOR or ALLEGRO_INVERSE_CONST_COLOR blend functions. See al_set_blender for more information.

See also

al_set_blender

Sets the function to use for blending for the current thread.

al_get_blend_color

Returns the color currently used for constant color blending (white by default).

Returns the active blender for the current thread.

See also

al_set_blender

Sets the function to use for blending for the current thread.

al_get_separate_blender

Returns the active blender for the current thread.

Returns the color currently used for constant color blending (white by default).

See also

al_set_blend_color

Sets the color to use for blending when using the ALLEGRO_CONST_COLOR or ALLEGRO_INVERSE_CONST_COLOR blend functions.

al_set_blender

Sets the function to use for blending for the current thread.

Like al_set_blender, but allows specifying a separate blending operation for the alpha channel. This is useful if your target bitmap also has an alpha channel and the two alpha channels need to be combined in a different way than the color components.

See also

al_set_blender

Sets the function to use for blending for the current thread.

al_get_blender

Returns the active blender for the current thread.

al_get_separate_blender

Returns the active blender for the current thread.

Returns the active blender for the current thread.

See also

al_set_separate_blender

Like al_set_blender, but allows specifying a separate blending operation for the alpha channel.

al_get_blender

Returns the active blender for the current thread.

Returns True if the event type is not a builtin event type, i.e. one of those described in ALLEGRO_EVENT_TYPE.

See also

ALLEGRO_GET_EVENT_TYPE

Makes an event type identifier, which is a 32-bit integer.

Makes an event type identifier, which is a 32-bit integer. Usually, but not necessarily, this will be made from four 8-bit character codes, for example:

MY_EVENT_TYPE := ALLEGRO_GET_EVENT_TYPE ('MINE');

IDs less than 1024 are reserved for Allegro or its addons. Don't use anything lower than ALLEGRO_GET_EVENT_TYPE (#0#0#4#0).

You should try to make your IDs unique so they don't clash with any 3rd party code you may be using. Be creative. Numbering from 1024 is not creative.

If you need multiple identifiers, you could define them like this:

BASE_EVENT := ALLEGRO_GET_EVENT_TYPE ('MINE');
BARK_EVENT := BASE_EVENT + 1;
MEOW_EVENT := BASE_EVENT + 2;
SQUAWK_EVENT := BASE_EVENT + 3;

See also

ALLEGRO_EVENT

An ALLEGRO_EVENT is an union of all builtin event structures, i.e.

ALLEGRO_USER_EVENT

An event structure that can be emitted by user event sources.

ALLEGRO_EVENT_TYPE_IS_USER

Returns True if the event type is not a builtin event type, i.e.

Initialices an event source for emitting user events. The space for the event source must already have been allocated.

One possible way of creating custom event sources is to derive other structures with ALLEGRO_EVENT_SOURCE at the head, e.g.

TYPE
  THINGptr = ˆTHING;
  THING = RECORD
    event_source: ALLEGRO_EVENT_SOURCE;
    field1, field2: INTEGER;
    { etc. }
  END;

FUNCTION CreateThing: THINGptr;
BEGIN
  RESULT := getmem (sizeof (THING));
  IF RESULT <> NIL THEN
  BEGIN
    al_init_user_event_source (@(RESULTˆ.event_source));
    RESULTˆ.field1 := 0;
    RESULTˆ.field2 := 0
  END
END;

The advantage here is that the THING pointer will be the same as the ALLEGRO_EVENT_SOURCE pointer. Events emitted by the event source will have the event source pointer as the source field, from which you can get a pointer to a THING by a simple cast (after ensuring checking the event is of the correct type).

However, it is only one technique and you are not obliged to use it.

The user event source will never be destroyed automatically. You must destroy it manually with al_destroy_user_event_source.

Parameters

source

Pointer to the variable that will store the source information.

See also

ALLEGRO_EVENT_SOURCE

An event source is any object which can generate events.

al_destroy_user_event_source

Destroys an event source initialised with al_init_user_event_source.

al_emit_user_event

Emits an event from a user event source.

ALLEGRO_USER_EVENT

An event structure that can be emitted by user event sources.

Destroys an event source initialised with al_init_user_event_source.

This does not free the memory, as that was user allocated to begin with.

Parameters

source

Pointer to the variable that stored the source information.

See also

ALLEGRO_EVENT_SOURCE

An event source is any object which can generate events.

Emits an event from a user event source. The event source must have been initialised with al_init_user_event_source.

Events are copied in and out of event queues, so after this function returns the memory pointed to by event may be freed or reused. Some fields of the event being passed in may be modified by the function.

Reference counting will be performed if dtor is not Nil. Whenever a copy of the event is made, the reference count increases. You need to call al_unref_user_event to decrease the reference count once you are done with a user event that you have received from al_get_next_event, al_peek_next_event, al_wait_for_event, etc.

Once the reference count drops to zero dtor will be called with a copy of the event as an argument. It should free the resources associated with the event, but not the event itself (since it is just a copy).

If dtor is Nil then reference counting will not be performed. It is safe, but unnecessary, to call al_unref_user_event on non-reference counted user events.

You can use al_emit_user_event to emit both user and non-user events from your user event source. Note that emitting input events will not update the corresponding input device states. For example, you may emit an event of type ALLEGRO_EVENT_KEY_DOWN, but it will not update the ALLEGRO_KEYBOARD_STATE returned by al_get_keyboard_state.

Returns

False if the event source isn't registered with any queues, hence the event wouldn't have been delivered into any queues.

See also

ALLEGRO_USER_EVENT

An event structure that can be emitted by user event sources.

al_unref_user_event

Decreases the reference count of a user-defined event.

ALLEGRO_EVENT_DTOR_PROC

User event destructor.

Decreases the reference count of a user-defined event. This must be called on any user event that you get from al_get_next_event, al_peek_next_event, al_wait_for_event, etc. which is reference counted. This function does nothing if the event is not reference counted.

See also

al_emit_user_event

Emits an event from a user event source.

ALLEGRO_USER_EVENT

An event structure that can be emitted by user event sources.

Assigns the abstract user data to the event source. Allegro does not use the data internally for anything; it is simply meant as a convenient way to associate your own data or objects with events.

See also

al_get_event_source_data

Returns the abstract user data associated with the event source.

Returns the abstract user data associated with the event source. If no data was previously set, returns Nil.

See also

al_set_event_source_data

Assigns the abstract user data to the event source.

Creates a new, empty event queue.

Returns

A pointer to the newly created object if successful, Nil on error.

See also

al_register_event_source

Register the event source with the event queue specified.

al_destroy_event_queue

Destroys the event queue specified.

ALLEGRO_EVENT_QUEUEptr

An event queue holds events that have been generated by event sources that are registered with the queue.

Destroys the event queue specified. All event sources currently registered with the queue will be automatically unregistered before the queue is destroyed.

See also

al_create_event_queue

Creates a new, empty event queue.

ALLEGRO_EVENT_QUEUEptr

An event queue holds events that have been generated by event sources that are registered with the queue.

Returns True if the event source is registered.

See also

al_register_event_source

Register the event source with the event queue specified.

Register the event source with the event queue specified. An event source may be registered with any number of event queues simultaneously, or none. Trying to register an event source with the same event queue more than once does nothing.

See also

al_unregister_event_source

Unregister an event source with an event queue.

ALLEGRO_EVENT_SOURCE

An event source is any object which can generate events.

Unregister an event source with an event queue. If the event source is not actually registered with the event queue, nothing happens.

If the queue had any events in it which originated from the event source, they will no longer be in the queue after this call.

See also

al_register_event_source

Register the event source with the event queue specified.

Pauses or resumes accepting new events into the event queue (to resume, pass False for pause). Events already in the queue are unaffected.

While a queue is paused, any events which would be entered into the queue are simply ignored. This is an alternative to unregistering then re-registering all event sources from the event queue, if you just need to prevent events piling up in the queue for a while.

See also

al_is_event_queue_paused

Returns True if the event queue is paused.

Returns True if the event queue is paused.

See also

al_pause_event_queue

Pauses or resumes accepting new events into the event queue (to resume, pass False for pause).

Returns True if the event queue specified is currently empty.

See also

al_get_next_event

Takes the next event out of the event queue specified, and copy the contents into ret_event, returning True.

al_peek_next_event

Copies the contents of the next event in the event queue specified into ret_event and returns True.

Takes the next event out of the event queue specified, and copy the contents into ret_event, returning True. The original event will be removed from the queue. If the event queue is empty, returns False and the contents of ret_event are unspecified.

See also

ALLEGRO_EVENT

An ALLEGRO_EVENT is an union of all builtin event structures, i.e.

al_peek_next_event

Copies the contents of the next event in the event queue specified into ret_event and returns True.

al_wait_for_event

Waits until the event queue specified is non-empty.

Copies the contents of the next event in the event queue specified into ret_event and returns True. The original event packet will remain at the head of the queue. If the event queue is actually empty, this function returns False and the contents of ret_event are unspecified.

See also

ALLEGRO_EVENT

An ALLEGRO_EVENT is an union of all builtin event structures, i.e.

al_get_next_event

Takes the next event out of the event queue specified, and copy the contents into ret_event, returning True.

al_drop_next_event

Drops (removes) the next event from the queue.

Drops (removes) the next event from the queue. If the queue is empty, nothing happens.

Parameters

queue

Pointer to the queue.

Returns

(True) if an event was dropped.

See also

al_flush_event_queue

Drops all events, if any, from the queue.

al_is_event_queue_empty

Returns True if the event queue specified is currently empty.

Drops all events, if any, from the queue.

See also

al_drop_next_event

Drops (removes) the next event from the queue.

al_is_event_queue_empty

Returns True if the event queue specified is currently empty.

Waits until the event queue specified is non-empty. If ret_event is not Nil, the first event in the queue will be copied into ret_event and removed from the queue. If ret_event is Nil the first event is left at the head of the queue.

See also

ALLEGRO_EVENT

An ALLEGRO_EVENT is an union of all builtin event structures, i.e.

al_wait_for_event_timed

Waits until the event queue specified is non-empty.

al_wait_for_event_until

Waits until the event queue specified is non-empty.

al_get_next_event

Takes the next event out of the event queue specified, and copy the contents into ret_event, returning True.

Waits until the event queue specified is non-empty.

Parameters

queue

Pointer to the queue.

ret_event

If it is not Nil, the first event in the queue will be copied into ret_event and removed from the queue. If it is Nil the first event is left at the head of the queue.

secs

Determines approximately how many seconds to wait. If the call times out, False is returned. Otherwise, if an event ocurred, True is returned. For compatibility with all platforms, secs must be 2,147,483.647 seconds or less.

See also

ALLEGRO_EVENT

An ALLEGRO_EVENT is an union of all builtin event structures, i.e.

al_wait_for_event

Waits until the event queue specified is non-empty.

al_wait_for_event_until

Waits until the event queue specified is non-empty.

Waits until the event queue specified is non-empty.

Parameters

queue

Pointer to the queue.

ret_event

If it is not Nil, the first event in the queue will be copied into ret_event and removed from the queue. If it is Nil the first event is left at the head of the queue.

timeout

Determines how long to wait. If the call times out, False is returned. Otherwise, if an event ocurred, True is returned. For compatibility with all platforms, timeout must be 2,147,483.647 seconds or less.

See also

ALLEGRO_EVENT

An ALLEGRO_EVENT is an union of all builtin event structures, i.e.

al_init_timeout

Sets timeout value of some number of seconds after the function call.

al_wait_for_event

Waits until the event queue specified is non-empty.

al_wait_for_event_timed

Waits until the event queue specified is non-empty.

Sets the refresh rate to use when creating new displays on the calling thread. If the refresh rate is not available, al_create_display will fail. A list of modes with refresh rates can be found with al_get_num_display_modes and al_get_display_mode.

The default setting is zero (don't care).

See also

al_get_new_display_refresh_rate

Gets the requested refresh rate to be used when creating new displays on the calling thread.

Sets various flags to be used when creating new displays on the calling thread. flags is a bitfield containing any reasonable combination of the following:

• ALLEGRO_WINDOWED Prefer a windowed mode.

  Under multi-head X (not XRandR/TwinView), the use of more than one adapter is impossible due to bugs in X and GLX. al_create_display will fail if more than one adapter is attempted to be used.

• ALLEGRO_FULLSCREEN_WINDOW Make the window span the entire screen. Unlike ALLEGRO_FULLSCREEN this will never attempt to modify the screen resolution. Instead the pixel dimensions of the created display will be the same as the desktop.

  The passed width and height are only used if the window is switched out of fullscreen mode later but will be ignored initially.

  Under Windows and X11 a fullscreen display created with this flag will behave differently from one created with the ALLEGRO_FULLSCREEN flag - even if the ALLEGRO_FULLSCREEN display is passed the desktop dimensions. The exact difference is platform dependent, but some things which may be different is how alt-tab works, how fast you can toggle between fullscreen/windowed mode or how additional monitors behave while your display is in fullscreen mode.

  Additionally under X, the use of more than one adapter in multi-head mode or with true Xinerama enabled is impossible due to bugs in X/GLX, creation will fail if more than one adapter is attempted to be used.

• ALLEGRO_FULLSCREEN Prefer a fullscreen mode.

  Under X the use of more than one FULLSCREEN display when using multi-head X, or true Xinerama is not possible due to bugs in X and GLX, display creation will fail if more than one adapter is attempted to be used.

  Note: Prefer using ALLEGRO_FULLSCREEN_WINDOW as it typically provides a better user experience as the monitor doesn't change resolution and switching away from your game via Alt-Tab works smoothly. ALLEGRO_FULLSCREEN is typically less well supported compared to ALLEGRO_FULLSCREEN_WINDOW.

• ALLEGRO_RESIZABLE The display is resizable (only applicable if combined with ALLEGRO_WINDOWED).

• ALLEGRO_MAXIMIZED The display window will be maximized (only applicable if combined with ALLEGRO_RESIZABLE).

• ALLEGRO_OPENGL Require the driver to provide an initialized OpenGL context after returning successfully.

• ALLEGRO_OPENGL_3_0 Require the driver to provide an initialized OpenGL context compatible with OpenGL version 3.0.

• ALLEGRO_OPENGL_FORWARD_COMPATIBLE If this flag is set, the OpenGL context created with ALLEGRO_OPENGL_3_0 will be forward compatible only, meaning that all of the OpenGL API declared deprecated in OpenGL 3.0 will not be supported. Currently, a display created with this flag will not be compatible with Allegro drawing routines; the display option ALLEGRO_COMPATIBLE_DISPLAY will be set to false.

• ALLEGRO_OPENGL_ES_PROFILE Used together with ALLEGRO_OPENGL, requests that the OpenGL context uses the OpenGL ES profile. A specific version can be requested with al_set_new_display_option. Note: Currently this is only supported by the X11/GLX driver.

• ALLEGRO_DIRECT3D Require the driver to do rendering with Direct3D and provide a Direct3D device.

• ALLEGRO_PROGRAMMABLE_PIPELINE Require a programmable graphics pipeline. This flag is required to use ALLEGRO_SHADERptr objects.

• ALLEGRO_FRAMELESS Try to create a window without a frame (i.e. no border or titlebar). This usually does nothing for fullscreen modes, and even in windowed modes it depends on the underlying platform whether it is supported or not.

• ALLEGRO_GENERATE_EXPOSE_EVENTS Let the display generate expose events.

0 can be used for default values.

See also

al_set_new_display_option

Sets an extra display option, to be used when creating new displays on the calling thread.

al_get_display_option

Returns an extra display setting of the display.

al_set_display_option

Changes an option that was previously set for a display.

Gets the requested refresh rate to be used when creating new displays on the calling thread.

See also

al_set_new_display_refresh_rate

Sets the refresh rate to use when creating new displays on the calling thread.

Gets the display flags to be used when creating new displays on the calling thread.

See also

al_set_new_display_flags

Sets various flags to be used when creating new displays on the calling thread.

al_set_display_flag

Enables or disables one of the display flags.

Sets the title that will be used when a new display is created. Allegro uses a static buffer of ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE to store this, so the length of the titme you set must be less than this.

See also

al_set_window_title

Sets the title on a display.

al_get_new_window_title

Returns the title that will be used when a new display is created.

al_create_display

Creates a display, or window, with the specified dimensions.

ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE

Max size of window titles.

Returns the title that will be used when a new display is created. This returns the value that al_set_window_title was called with. The current implementation returns a pointer to a static buffer of which you should make a copy if you want to modify it.

See also

al_set_window_title

Sets the title on a display.

al_set_new_window_title

Sets the title that will be used when a new display is created.

al_create_display

Creates a display, or window, with the specified dimensions.

Gets the width of the display. This is like SCREEN_W in Allegro 4.x.

See also

al_get_display_height

Gets the height of the display.

Gets the height of the display. This is like SCREEN_H in Allegro 4.x.

See also

al_get_display_width

Gets the width of the display.

Gets pixel format of the display.

See also

ALLEGRO_PIXEL_FORMAT

Pixel formats.

Gets the refresh rate of the display.

See also

al_set_new_display_refresh_rate

Sets the refresh rate to use when creating new displays on the calling thread.

Gets the flags of the display.

In addition to the flags set for the display at creation time with al_set_new_display_flags it can also have the ALLEGRO_MINIMIZED flag set, indicating that the window is currently minimized. This flag is very platform-dependent as even a minimized application may still render a preview version so normally you should not care whether it is minimized or not.

See also

al_set_new_display_flags

Sets various flags to be used when creating new displays on the calling thread.

al_set_display_flag

Enables or disables one of the display flags.

Return the display orientation, which can be one of the following:

• ALLEGRO_DISPLAY_ORIENTATION_UNKNOWN

• ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES

• ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES

• ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES

• ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES

• ALLEGRO_DISPLAY_ORIENTATION_FACE_UP

• ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN

Enables or disables one of the display flags. The flags are the same as for al_set_new_display_flags. The only flags that can be changed after creation are:

• ALLEGRO_FULLSCREEN_WINDOW

• ALLEGRO_FRAMELESS

• ALLEGRO_MAXIMIZED

You can use al_get_display_flags to query whether the given display property actually changed.

Returns

True if the driver supports toggling the specified flag else False.

See also

al_set_new_display_flags

Sets various flags to be used when creating new displays on the calling thread.

al_get_display_flags

Gets the flags of the display.

Creates a display, or window, with the specified dimensions. The parameters of the display are determined by the last calls to al_set_new_display_* . Default parameters are used if none are set explicitly. Creating a new display will automatically make it the active one, with the backbuffer selected for drawing.

Each display that uses OpenGL as a backend has a distinct OpenGL rendering context associated with it. See al_set_target_bitmap for the discussion about rendering contexts.

Returns

Nil on error.

See also

al_set_new_display_flags

Sets various flags to be used when creating new displays on the calling thread.

al_set_new_display_option

Sets an extra display option, to be used when creating new displays on the calling thread.

al_set_new_display_refresh_rate

Sets the refresh rate to use when creating new displays on the calling thread.

al_set_new_display_adapter

Sets the adapter to use for new displays created by the calling thread.

al_set_new_window_title

Sets the title that will be used when a new display is created.

al_destroy_display

Destroys a display.

Destroys a display.

If the target bitmap of the calling thread is tied to the display, then it implies a call to al_set_target_bitmap (Nil); before the display is destroyed.

That special case notwithstanding, you should make sure no threads are currently targeting a bitmap which is tied to the display before you destroy it.

See also

al_set_target_bitmap

This function selects the bitmap to which all subsequent drawing operations in the calling thread will draw to.

Returns the display that is "current" for the calling thread, or Nil if there is none.

See also

al_set_target_bitmap

This function selects the bitmap to which all subsequent drawing operations in the calling thread will draw to.

This function selects the bitmap to which all subsequent drawing operations in the calling thread will draw to. To return to drawing to a display, set the backbuffer of the display as the target bitmap, using al_get_backbuffer. As a convenience, you may also use al_set_target_backbuffer.

Each video bitmap is tied to a display. When a video bitmap is set to as the target bitmap, the display that the bitmap belongs to is automatically made "current" for the calling thread (if it is not current already). Then drawing other bitmaps which are tied to the same display can be hardware accelerated.

A single display cannot be current for multiple threads simultaneously. If you need to release a display, so it is not current for the calling thread, call al_set_target_bitmap (Nil);

Setting a memory bitmap as the target bitmap will not change which display is current for the calling thread.

On some platforms, Allegro automatically backs up the contents of video bitmaps because they may be occasionally lost (see discussion in al_create_bitmap's documentation). If you're completely recreating the bitmap contents often (e.g. every frame) then you will get much better performance by creating the target bitmap with ALLEGRO_NO_PRESERVE_TEXTURE flag.

OpenGL note:

Framebuffer objects (FBOs) allow OpenGL to directly draw to a bitmap, which is very fast. When using an OpenGL display, if all of the following conditions are met an FBO will be created for use with the bitmap:

• The GL_EXT_framebuffer_object OpenGL extension is available.

• The bitmap is not a memory bitmap.

• The bitmap is not currently locked.

In Allegro 5.0.0, you had to be careful as an FBO would be kept around until the bitmap is destroyed or you explicitly called al_remove_opengl_fbo on the bitmap, wasting resources. In newer versions, FBOs will be freed automatically when the bitmap is no longer the target bitmap, unless you have called al_get_opengl_fbo to retrieve the FBO id.

In the following example, no FBO will be created:

lock := al_lock_bitmap (bitmap);
al_set_target_bitmap (bitmap);
al_put_pixel (x, y, color);
al_unlock_bitmap (bitmap);

The above allows using al_put_pixel on a locked bitmap without creating an FBO.

In this example an FBO is created however:

al_set_target_bitmap (bitmap);
al_draw_line (x1, y1, x2, y2, color, 0);

An OpenGL command will be used to directly draw the line into the bitmap's associated texture.

See also

al_get_target_bitmap

Returns the target bitmap of the calling thread.

al_set_target_backbuffer

Same as al_set_target_bitmap(al_get_backbuffer(display));.

Same as al_set_target_bitmap(al_get_backbuffer(display));.

See also

al_set_target_bitmap

This function selects the bitmap to which all subsequent drawing operations in the calling thread will draw to.

al_get_backbuffer

Returns a special bitmap representing the back-buffer of the display.

Returns a special bitmap representing the back-buffer of the display.

Care should be taken when using the backbuffer bitmap (and its sub-bitmaps) as the source bitmap (e.g as the bitmap argument to al_draw_bitmap). Only untransformed operations are hardware accelerated. These consist of al_draw_bitmap and al_draw_bitmap_region when the current transformation is the identity. If the tranformation is not the identity, or some other drawing operation is used, the call will be routed through the memory bitmap routines, which are slow. If you need those operations to be accelerated, then first copy a region of the backbuffer into a temporary bitmap (via the al_draw_bitmap and al_draw_bitmap_region), and then use that temporary bitmap as the source bitmap.

Returns the target bitmap of the calling thread.

See also

al_set_target_bitmap

This function selects the bitmap to which all subsequent drawing operations in the calling thread will draw to.

When the user receives a resize event (ALLEGRO_EVENT_DISPLAY_RESIZE from a resizable display, if they wish the display to be resized they must call this function to let the graphics driver know that it can now resize the display.

Adjusts the clipping rectangle to the full size of the backbuffer. This also resets the backbuffers projection transform to default orthographic transform (see al_use_projection_transform).

Note that a resize event may be outdated by the time you acknowledge it; there could be further resize events generated in the meantime.

Returns

True on success.

See also

al_resize_display

Resizes the display.

ALLEGRO_EVENT

An ALLEGRO_EVENT is an union of all builtin event structures, i.e.

Resizes the display. This works on both fullscreen and windowed displays, regardless of the ALLEGRO_RESIZABLE flag.

Adjusts the clipping rectangle to the full size of the backbuffer.

Returns

True on success, or False on error.

See also

al_acknowledge_resize

When the user receives a resize event (ALLEGRO_EVENT_DISPLAY_RESIZE from a resizable display, if they wish the display to be resized they must call this function to let the graphics driver know that it can now resize the display.

Copies or updates the front and back buffers so that what has been drawn previously on the currently selected display becomes visible on screen. Pointers to the special back buffer bitmap remain valid and retain their semantics as the back buffer, although the contents may have changed.

Several display options change how this function behaves:

• With ALLEGRO_SINGLE_BUFFER, no flipping is done. You still have to call this function to display graphics, depending on how the used graphics system works.

• The ALLEGRO_SWAP_METHOD option may have additional information about what kind of operation is used internally to flip the front and back buffers.

• If ALLEGRO_VSYNC is 1, this function will force waiting for vsync. If ALLEGRO_VSYNC is 2, this function will not wait for vsync. With many drivers the vsync behavior is controlled by the user and not the application, and ALLEGRO_VSYNC will not be set; in this case al_flip_display will wait for vsync depending on the settings set in the system's graphics preferences.