Thread local storage

Some of Allegro’s “global” state is thread-specific.  For example, each thread in the program will have it’s own target bitmap, and calling al_set_target_bitmap will only change the target bitmap of the calling thread.  This reduces the problems with global state in multithreaded programs.

Summary
Some of Allegro’s “global” state is thread-specific.
Set the pixel format for al displays created after this call.
Sets the refresh rate to use for newly created displays.
Sets various flags for display creation.
Gets the current pixel format used for newly created displays.
Gets the current refresh rate used for newly created displays.
Gets the current flags used for newly created displays.
Change the current display for the calling thread.
Query for the current display in the calling thread.
Select the bitmap to which all subsequent drawing operations in the calling thread will draw.
Return the target bitmap of the current display.
Sets the pixel format for newly created bitmaps.
Sets the flags to use for newly created bitmaps.
Returns the format used for newly created bitmaps.
Returns the flags used for newly created bitmaps.
Sets the function to use for blending for the current thread.
Returns the active blender for the current thread.

Functions

al_set_new_display_format

void al_set_new_display_format(int format)

Set the pixel format for al displays created after this call.

al_set_new_display_refresh_rate

void al_set_new_display_refresh_rate(int refresh_rate)

Sets the refresh rate to use for newly created displays.  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, documented above.

See Also

al_get_display_mode

al_set_new_display_flags

void al_set_new_display_flags(int flags)

Sets various flags for display creation. flags is a bitfield containing any reasonable combination of the following:

ALLEGRO_WINDOWEDprefer a windowed mode
ALLEGRO_FULLSCREENprefer a fullscreen mode
ALLEGRO_RESIZABLEthe display is resizable (only applicable if combined with ALLEGRO_WINDOWED)
ALLEGRO_OPENGLrequire the driver to provide an initialized opengl context after returning successfully
ALLEGRO_DIRECT3Drequire the driver to do rendering with Direct3D and provide a Direct3D device
ALLEGRO_DOUBLEBUFFERuse double buffering
ALLEGRO_PAGEFLIPuse page flipping
ALLEGRO_SINGLEBUFFERuse only one buffer (front and back buffer are the same)

0 can be used for default values.

al_get_new_display_format

int al_get_new_display_format(void)

Gets the current pixel format used for newly created displays.

al_get_new_display_refresh_rate

int al_get_new_display_refresh_rate(void)

Gets the current refresh rate used for newly created displays.

al_get_new_display_flags

int al_get_new_display_flags(void)

Gets the current flags used for newly created displays.

al_set_current_display

void al_set_current_display(ALLEGRO_DISPLAY *display)

Change the current display for the calling thread.  Also sets the target bitmap to the display’s backbuffer.

al_get_current_display

ALLEGRO_DISPLAY *al_get_current_display(void)

Query for the current display in the calling thread.

al_set_target_bitmap

void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)

Select the bitmap to which all subsequent drawing operations in the calling thread will draw.

al_get_target_bitmap

ALLEGRO_BITMAP *al_get_target_bitmap(void)

Return the target bitmap of the current display.

al_set_new_bitmap_format

void al_set_new_bitmap_format(int format)

Sets the pixel format for newly created bitmaps. format is one of the same values as used for al_set_new_display_format.  The default format is 0 and means the display driver will choose the best format.

al_set_new_bitmap_flags

void al_set_new_bitmap_flags(int flags)

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

ALLEGRO_MEMORY_BITMAPThe bitmap will use a format most closely resembling the format used in the bitmap file and al_create_memory_bitmap will be used to create it.  If this flag is not specified, al_create_bitmap will be used instead and the display driver will determine the format.
ALLEGRO_KEEP_BITMAP_FORMATOnly used when loading bitmaps from disk files, forces the resulting ALLEGRO_BITMAP to use the same format as the file.
ALLEGRO_FORCE_LOCKINGWhen drawing to a bitmap with this flag set, always use pixel locking and draw to it using Allegro’s software drawing primitives.  This should never be used as it may cause severe performance penalties, but can be useful for debugging.

al_get_new_bitmap_format

int al_get_new_bitmap_format(void)

Returns the format used for newly created bitmaps.

al_get_new_bitmap_flags

int al_get_new_bitmap_flags(void)

Returns the flags used for newly created bitmaps.

al_set_blender

void al_set_blender(int src,
int dst,
ALLEGRO_COLOR color)

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: sr, sg, sb, sa And this color is drawn to a destination, which already has a color: dr, dg, db, da

The conceptional formula used by Allegro to draw any pixel then is

r = dr * dst + sr * src * color.r
g = dg * dst + sg * src * color.g
b = db * dst + sb * src * color.b
a = da * dst + sa * src * color.a

The src, dst and color values are specified by this function.  Valid values for src and dst are:

ALLEGRO_ZEROsrc = 0 / dst = 0
ALLEGRO_ONEsrc = 1 / dst = 1
ALLEGRO_ALPHAsrc = sa / dst = sa
ALLEGRO_INVERSE_ALPHAsrc = (1 - sa) / dst = (1 - sa)

So for example, to restore the default of using alpha blending, you would use (pseudo code):

al_set_blender(ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA, {1, 1, 1, 1})

This means, the color is not modified, all source components are multipled with the alpha component and combined with the destination according to this same alpha value.

If you want to tint the result to some specific color, you can also change the color from white to some other color.

Additive blending would be achieved with

al_set_blender(ALLEGRO_ONE, ALLEGRO_ONE, {1, 1, 1, 1})

Copying the source to the destination (including alpha) unmodified

al_set_blender(ALLEGRO_ONE, ALLEGRO_ZERO, {1, 1, 1, 1})

al_get_blender

void al_get_blender(int *src,
int *dst,
ALLEGRO_COLOR *color)

Returns the active blender for the current thread.

void al_set_new_display_format(int format)
Set the pixel format for al displays created after this call.
void al_set_new_display_refresh_rate(int refresh_rate)
Sets the refresh rate to use for newly created displays.
void al_set_new_display_flags(int flags)
Sets various flags for display creation.
int al_get_new_display_format(void)
Gets the current pixel format used for newly created displays.
int al_get_new_display_refresh_rate(void)
Gets the current refresh rate used for newly created displays.
int al_get_new_display_flags(void)
Gets the current flags used for newly created displays.
void al_set_current_display(ALLEGRO_DISPLAY *display)
Change the current display for the calling thread.
ALLEGRO_DISPLAY *al_get_current_display(void)
Query for the current display in the calling thread.
void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)
Select the bitmap to which all subsequent drawing operations in the calling thread will draw.
ALLEGRO_BITMAP *al_get_target_bitmap(void)
Return the target bitmap of the current display.
void al_set_new_bitmap_format(int format)
Sets the pixel format for newly created bitmaps.
void al_set_new_bitmap_flags(int flags)
Sets the flags to use for newly created bitmaps.
int al_get_new_bitmap_format(void)
Returns the format used for newly created bitmaps.
int al_get_new_bitmap_flags(void)
Returns the flags used for newly created bitmaps.
void al_set_blender(int src,
int dst,
ALLEGRO_COLOR color)
Sets the function to use for blending for the current thread.
void al_get_blender(int *src,
int *dst,
ALLEGRO_COLOR *color)
Returns the active blender for the current thread.
int al_get_num_display_modes(void)
Get the number of available fullscreen display modes for the current set of display parameters.
ALLEGRO_DISPLAY_MODE *al_get_display_mode(int index,
ALLEGRO_DISPLAY_MODE *mode)
Retrieves a display mode.