Display routines

Summary
Create a display, or window, with the specified dimensions.
Destroy a display.
Return a special bitmap representing the back-buffer of the current display.
Return a special bitmap representing the front-buffer of the current 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.
Update the the front buffer from the backbuffer in the specified region.
When the user receives a resize event 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.
Resize the current display.
Clear a complete display, but confined by the clipping rectangle.
Draws a line to the current target.
Draws a rectangle to the current target.
Draws a single pixel at x, y.
D3D and OpenGL allow sharing a texture in a way so it can be used for multiple windows.
Gets the width of the current display.
Gets the height of the current display.
Gets the pixel format of the current display.
Gets the refresh rate of the current display.
Gets the flags of the current display.
Get the number of available fullscreen display modes for the current set of display parameters.
Retrieves a display mode.
Wait for the beginning of a vertical retrace.
Set the region of the target bitmap or display that pixels get clipped to.
Gets the clipping rectangle of the target bitmap.
Changes the icon associated with the current display (window).

Functions

al_create_display

ALLEGRO_DISPLAY *al_create_display(int w,
int h)

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

Returns NULL on error.

See Also: al_set_new_display_format, al_set_new_display_refresh_rate, al_set_new_display_flags

al_destroy_display

void al_destroy_display(ALLEGRO_DISPLAY *display)

Destroy a display.

al_get_backbuffer

ALLEGRO_BITMAP *al_get_backbuffer(void)

Return a special bitmap representing the back-buffer of the current display.

al_get_frontbuffer

ALLEGRO_BITMAP *al_get_frontbuffer(void)

Return a special bitmap representing the front-buffer of the current display.  This may not be supported by the driver; returns NULL in that case.

al_flip_display

void al_flip_display(void)

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 and front buffer bitmaps remain valid and retain their semantics as back and front buffers respectively, although their contents may have changed.

al_update_display_region

bool al_update_display_region(int x,
int y,
int width,
int height)

Update the the front buffer from the backbuffer in the specified region.  This does not flip the whole buffer and preserves the contents of the front buffer outside of the given rectangle.  This may not be supported by all drivers, in which case it returns false.

al_acknowledge_resize

bool al_acknowledge_resize(ALLEGRO_DISPLAY *display)

When the user receives a resize event 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.  Returns true on success.

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

al_resize_display

bool al_resize_display(int width,
int height)

Resize the current display.  Returns true on success, or false on error.  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.

al_clear

void al_clear(ALLEGRO_COLOR color)

Clear a complete display, but confined by the clipping rectangle.

al_draw_line

void al_draw_line(float fx,
float fy,
float tx,
float ty,
ALLEGRO_COLOR color)

Draws a line to the current target.

fxfrom x
fyfrom y
txto x
tyto y
colorcan be obtained with al_map_*

al_draw_rectangle

void al_draw_rectangle(float tlx,
float tly,
float brx,
float bry,
ALLEGRO_COLOR color,
int flags)

Draws a rectangle to the current target.

tlxtop left x
tlytop left y
brxbottom right x
brybottom right y

flags can be

ALLEGRO_FILLEDfill the interior of the rectangle
ALLEGRO_OUTLINEDdraw only the rectangle borders

Outlined is the default.

al_draw_pixel

void al_draw_pixel(float x,
float y,
ALLEGRO_COLOR color)

Draws a single pixel at x, y.  This function, unlike al_put_pixel, does blending.

xdestination x
ydestination y
colorcolor of the pixel

al_is_compatible_bitmap

bool al_is_compatible_bitmap(ALLEGRO_BITMAP *bitmap)

D3D and OpenGL allow sharing a texture in a way so it can be used for multiple windows.  Each ALLEGRO_BITMAP created with al_create_bitmap however is usually tied to a single ALLEGRO_DISPLAY.  This function can be used to know if the bitmap is compatible with the current display, even if it is another display than the one it was created with.  It returns true if the bitmap is compatible (things like a cached texture version can be used) and false otherwise (blitting in the current display will be slow).  The only time this function is useful is if you are using multiple windows and need accelerated blitting of the same bitmaps to both.

al_get_display_width

int al_get_display_width(void)

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

al_get_display_height

int al_get_display_height(void)

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

al_get_display_format

int al_get_display_format(void)

Gets the pixel format of the current display.

al_get_display_refresh_rate

int al_get_display_refresh_rate(void)

Gets the refresh rate of the current display.

al_get_display_flags

int al_get_display_flags(void)

Gets the flags of the current display.

al_get_num_display_modes

int al_get_num_display_modes(void)

Get the number of available fullscreen display modes for the current set of display parameters.  This will use the values set with al_set_new_display_format, al_set_new_display_refresh_rate, and al_set_new_display_flags to find the number of modes that match.  Settings the new display parameters to zero will give a list of all modes for the default driver.

al_get_display_mode

ALLEGRO_DISPLAY_MODE *al_get_display_mode(int index,
ALLEGRO_DISPLAY_MODE *mode)

Retrieves a display mode.  Display parameters should not be changed between a call of al_get_num_display_modes and al_get_display_mode. index must be between 0 and the number returned from al_get_num_display_modes-1. mode must be an allocated ALLEGRO_DISPLAY_MODE structure.  This function will return NULL on failure, and the mode parameter that was passed in on success.

al_wait_for_vsync

bool al_wait_for_vsync(void)

Wait for the beginning of a vertical retrace.  Some driver/card/monitor combinations may not be capable of this.  Returns false if not possible, true if successful.

al_set_clipping_rectangle

void al_set_clipping_rectangle(int x,
int y,
int width,
int height)

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

al_get_clipping_rectangle

void al_get_clipping_rectangle(int *x,
int *y,
int *w,
int *h)

Gets the clipping rectangle of the target bitmap.

al_set_display_icon

void al_set_display_icon(ALLEGRO_BITMAP *icon)

Changes the icon associated with the current display (window).

Note: If the underlying OS can not use an icon with the size of the provided bitmap, it will be scaled.

TODO: Describe best practice for the size?  TODO: Allow providing multiple icons in differet sizes?

ALLEGRO_DISPLAY *al_create_display(int w,
int h)
Create a display, or window, with the specified dimensions.
void al_destroy_display(ALLEGRO_DISPLAY *display)
Destroy a display.
ALLEGRO_BITMAP *al_get_backbuffer(void)
Return a special bitmap representing the back-buffer of the current display.
ALLEGRO_BITMAP *al_get_frontbuffer(void)
Return a special bitmap representing the front-buffer of the current display.
void al_flip_display(void)
Copies or updates the front and back buffers so that what has been drawn previously on the currently selected display becomes visible on screen.
bool al_update_display_region(int x,
int y,
int width,
int height)
Update the the front buffer from the backbuffer in the specified region.
bool al_acknowledge_resize(ALLEGRO_DISPLAY *display)
When the user receives a resize event 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.
bool al_resize_display(int width,
int height)
Resize the current display.
void al_clear(ALLEGRO_COLOR color)
Clear a complete display, but confined by the clipping rectangle.
void al_draw_line(float fx,
float fy,
float tx,
float ty,
ALLEGRO_COLOR color)
Draws a line to the current target.
void al_draw_rectangle(float tlx,
float tly,
float brx,
float bry,
ALLEGRO_COLOR color,
int flags)
Draws a rectangle to the current target.
void al_draw_pixel(float x,
float y,
ALLEGRO_COLOR color)
Draws a single pixel at x, y.
bool al_is_compatible_bitmap(ALLEGRO_BITMAP *bitmap)
D3D and OpenGL allow sharing a texture in a way so it can be used for multiple windows.
int al_get_display_width(void)
Gets the width of the current display.
int al_get_display_height(void)
Gets the height of the current display.
int al_get_display_format(void)
Gets the pixel format of the current display.
int al_get_display_refresh_rate(void)
Gets the refresh rate of the current display.
int al_get_display_flags(void)
Gets the flags of the current display.
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.
bool al_wait_for_vsync(void)
Wait for the beginning of a vertical retrace.
void al_set_clipping_rectangle(int x,
int y,
int width,
int height)
Set the region of the target bitmap or display that pixels get clipped to.
void al_get_clipping_rectangle(int *x,
int *y,
int *w,
int *h)
Gets the clipping rectangle of the target bitmap.
void al_set_display_icon(ALLEGRO_BITMAP *icon)
Changes the icon associated with the current display (window).
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.
ALLEGRO_BITMAP *al_create_bitmap(int w,
int h)
Creates a new bitmap using the bitmap format and flags for the current thread.