Screen Update API for Allegro

Screen Update API for Allegro
by Chris "23yrold3yrold" Barry

The accompanying code was written in an attempt to make screen updating using Allegro as easy as possible by writing a small library of functions that could automate the most commonly used screen update methods. This includes initialization, shutdown, the actual drawing and a few minor options. The update methods include standard double buffering methods, drawing directly to video memory for hardware acceleration and "page flipping", and even a combination of the two for things like blending, when reading from the drawing buffer is desirable (this is obviously very slow for video bitmaps). You can even switch update methods on the fly, so the player can select the method that best suits their computer as the program runs.

The API caught the eye of someone relating to work on the core Allegro library, and the API is (AFAIK) planned to be integrated into Allegro itself. Which is very nice; it's the first major contribution I've made to the library, however inadvertantly. However, it's going through some significant changes to fit with where the graphics API is going (Allegro is currently going through an overhaul) and it may be a while until this shows up in a public version. So, here it is for you now in a form very friendly with the current version of Allegro.

The following is a copy of the documentation found in readme.txt. The source files al_screen.h and al_screen.c are all you need to use the API; main.cpp is an example program demonstrating the API's functionality. As a slight bonus, the example program also shows how to use the configuration file routines to store the update method and remember it for the next time the program is run.

int initialize_screen_updating(int i);
Initializes the screen update system. This function must be called after set_gfx_mode() and can be called with the following values:

UPDATE_TRIPLE_BUFFER	standard triple buffering setup
UPDATE_PAGE_FLIP	standard page flipping setup
UPDATE_SYSTEM_BUFFER	double buffering system using a system bitmap
UPDATE_DOUBLE_BUFFER	double buffering system using a memory bitmap
UPDATE_TRIPLE_WMB	triple buffering, but with a memory bitmap buffer instead of a video bitmap
UPDATE_PAGEFLIP_WMB	page flipping, but with a memory bitmap buffer instead of a video bitmap

UPDATE_TRIPLE_WMB and UPDATE_PAGEFLIP_WMB are for times you're using a lot of blending or whatnot, and don't want your program slowed down due to reading from video memory. UPDATE_SYSTEM_BUFFER and UPDATE_DOUBLE_BUFFER don't synchronize to the vertical retrace of the screen unless vsync is enabled (by calling enable_vsync()). Note that these two mode alone are affected by the vsync functions; the triple buffering and page flipping modes automatically handle vertical retrace synchronisation.

You can call this function multiple times in one program. So if you want the user to be able to switch between update methods to find one best suited to their system, it's as easy as calling initialize_screen_updating() again.

void shutdown_screen_updating();

Does what it says. Call this at the end of your program to prevent memory leaks.

BITMAP* get_buffer();
This function returns the drawing surface. Do all your drawing to this bitmap during your drawing code. It doesn't affect the screen until you call update_screen().

void update_screen();
Blits the buffer to the screen.

int get_update_method();
Returns the update method in the form of one of the six values listed under initialize_screen_updating().

void enable_vsync();
Makes update_screen() wait for a vertical retrace to end before updating the screen. Note this only affects UPDATE_SYSTEM_BUFFER and UPDATE_DOUBLE_BUFFER.

void disable_vsync();
Disables vertical retrace synchronisation for UPDATE_SYSTEM_BUFFER and UPDATE_DOUBLE_BUFFER modes.

void toggle_vsync();
Toggles vertical retrace synchronisation for UPDATE_SYSTEM_BUFFER and UPDATE_DOUBLE_BUFFER modes.

int vsync_is_enabled();
Returns whether vertical retrace synchronisation is enabled.

Discussion on development of this API can be found here, if you're interested. Hope this was helpful to you.

Chris "23yrold3yrold" Barry

Discuss this article in the forums

Date this article was posted to GameDev.net: 9/30/2004
(Note that this date does not necessarily correspond to the date the article was written)

See Also:
General
Sweet Snippets