Graphics modes are the common denominator for most Allegro programs. While it is possible to write platform specific programs using Allegro which don't set a graphic mode through the routines provided in this chapter, these are not very common.
The first thing to note is that due to the wide range of supported platforms, a graphic mode is the only way to safely communicate with the user. When Allegro was a DOS only library (versions 3.x and previous), it was frequent for programmers to use functions from the C standard library to communicate with the user, like calling printf() before setting a graphic mode or maybe scanf() to read the user's input. However, what would happen for such a game running under Windows where there is no default console output or it may be hidden from the user? Even if the game compiled successfully, it would be unplayable, especially if there was vital information for the user in those text only messages.
Allegro provides the allegro_message() function to deal with this problem, but this is not a very user friendly method of communicating with the user and its main purpose is displaying small error like messages when no graphic mode is available. Therefore, the first thing your Allegro program should do is set a graphic mode, and from there on, use Allegro's text output routines to display messages to the user, just like `allegro/examples/exhello.c' does.
Setting a graphic mode involves deciding how to allocate the memory of the video card for your program. On some platforms this means creating a virtual screen bigger than the physical resolution to do hardware scrolling or page flipping. Virtual screens can cause a lot of confusion, but they are really quite simple. Warning: patronising explanation coming up, so you may wish to skip the rest of this paragraph. Think of video memory as a rectangular piece of paper which is being viewed through a small hole (your monitor) in a bit of cardboard. Since the paper is bigger than the hole you can only see part of it at any one time, but by sliding the cardboard around you can alter which portion of the image is visible. You could just leave the hole in one position and ignore the parts of video memory that aren't visible, but you can get all sorts of useful effects by sliding the screen window around, or by drawing images in a hidden part of video memory and then flipping across to display them.
For example, you could select a 640x480 mode in which the monitor acts as a window onto a 1024x1024 virtual screen, and then move the visible screen around in this larger area (hardware scrolling). Initially, with the visible screen positioned at the top left corner of video memory, this setup would look like:
(0,0)------------(640,0)----(1024,0)
| | |
| visible screen | |
| | |
(0,480)----------(640,480) |
| |
| the rest of video memory |
| |
(0,1024)--------------------(1024,1024)
The other reason you could use virtual screens for is page flipping. This means showing one portion of the virtual screen while your program draws to the hidden one. When you finish, you show the part you have been drawing to and repeat the process with the area now hidden. The result is a perfectly smooth screen update without flickering or other graphical artifacts.
Scrolling manually to one part of the video memory is one non portable way to accomplish this. The portable way is to use functions like create_system_bitmap(), create_video_bitmap(), show_video_bitmap(), etc. These functions divide the memory of the video card in areas and switch between them, a feature supported on all platforms and video cards (given that they have enough memory for the screen resolutions you asked for).
The last thing you need to know about setting a graphic mode are drivers. Each platform has a number of graphic drivers which support a different range of hardware or behave in different ways. To avoid cluttering your own code with #ifdefs and dealing with drivers added after you release your program, Allegro provides several so called magic drivers. These magic drivers don't really exists, they wrap around a specific kind of functionality.
The magic drivers you can use are:
set_color_depth(32);
if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0) {
abort_on_error("Couldn't set a 32 bit color resolution");
}
See also: get_color_depth, set_gfx_mode, set_color_conversion, makecol, getr, desktop_color_depth.
Examples using this: Available Allegro examples.
Note that the function returns whatever value you may have set previously with set_color_depth(), which can be different from the current color depth of the screen global variable. If you really need to know the color depth of the screen, use bitmap_color_depth().
See also: set_color_depth, bitmap_color_depth.
Examples using this: exrgbhsv.
request_refresh_rate(60);
if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0)
abort_on_error("Couldn't set graphic mode!");
if (get_refresh_rate() != 60)
abort_on_error("Couldn't set refresh rate to 60Hz!");See also: set_gfx_mode, get_refresh_rate.
See also: request_refresh_rate.
typedef struct GFX_MODE_LIST
{
int num_modes;
GFX_MODE *mode;
} GFX_MODE_LIST;
typedef struct GFX_MODE
{
int width, height, bpp;
} GFX_MODE;
Note that the card parameter must refer to a _real_ driver. This function fails if you pass GFX_SAFE, GFX_AUTODETECT, or any other "magic" driver.
Return value: Returns a pointer to a list structure of the type GFX_MODE_LIST or NULL if the request could not be satisfied.
See also: destroy_gfx_mode_list, set_gfx_mode, set_color_depth.
See also: get_gfx_mode_list, set_gfx_mode, set_color_depth.
The v_w and v_h parameters specify the minimum virtual screen size, in case you need a large virtual screen for hardware scrolling or page flipping. You should set them to zero if you don't care about the virtual screen size.
When you call set_gfx_mode(), the v_w and v_h parameters represent the minimum size of virtual screen that is acceptable for your program. The range of possible sizes is usually very restricted, and Allegro may end up creating a virtual screen much larger than the one you request. Allowed sizes are driver dependent and some drivers do not allow virtual screens that are larger than the visible screen at all: don't assume that whatever you pass will always work.
In mode-X the virtual width can be any multiple of eight greater than or equal to the physical screen width, and the virtual height will be set accordingly (the VGA has 256k of vram, so the virtual height will be 256*1024/virtual_width).
Currently, using a big virtual screen for page flipping is considered bad practice. There are platforms which don't support virtual screens bigger than the physical screen but can create different video pages to flip back and forth. This means that, if you want page flipping and aren't going to use hardware scrolling, you should call set_gfx_mode() with (0,0) as the virtual screen size and later create the different video pages with create_video_bitmap(). Otherwise your program will be limited to the platforms supporting hardware scrolling.
After you select a graphics mode, the physical and virtual screen sizes can be checked with the macros SCREEN_W, SCREEN_H, VIRTUAL_W, and VIRTUAL_H.
Return value: Returns zero on success. On failure returns a negative number and stores a description of the problem in allegro_error.
See also: set_color_depth, request_refresh_rate, screen, gfx_capabilities, allegro_error, Standard config variables, GFX_*/DOS, GFX_*/Windows, GFX_*/X, GFX_*/Linux, GFX_*/BeOS, GFX_*/MacOSX, create_video_bitmap, get_desktop_resolution, SCREEN_W, SCREEN_H, VIRTUAL_W, VIRTUAL_H.
Examples using this: Available Allegro examples.
Return value: Returns zero on success, invalidating at the same time all callbacks previously registered with set_display_switch_callback(). Returns -1 if the requested mode is not currently possible.
See also: set_display_switch_callback, get_display_switch_mode.
Examples using this: exmidi, exswitch.
Return value: Returns zero on success, decreasing the number of empty callback slots by one. Returns -1 if the request is impossible for the current platform or you have reached the maximum number of allowed callbacks.
See also: remove_display_switch_callback, set_display_switch_mode.
Examples using this: exswitch.
See also: set_display_switch_callback.
See also: set_display_switch_mode.
Examples using this: exswitch.
if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0)
abort_on_error("Couldn't set graphic mode!");
if (is_windowed_mode()) {
/* Windowed mode stuff. */
} else {
/* Fullscreen mode stuff. */
}Return value: Returns true if the current graphics mode is a windowed mode, or zero if it is a fullscreen mode. You should not call this function if you are not in graphics mode.
See also: set_gfx_mode.
GFX_CAN_SCROLL:
Indicates that the scroll_screen() function may be used with this
driver.
GFX_CAN_TRIPLE_BUFFER:
Indicates that the request_scroll() and poll_scroll() functions may be
used with this driver. If this flag is not set, it is possible that
the enable_triple_buffer() function may be able to activate it.
GFX_HW_CURSOR:
Indicates that a hardware mouse cursor is in use. When this flag is
set, it is safe to draw onto the screen without hiding the mouse
pointer first. Note that not every cursor graphic can be implemented
in hardware: in particular VBE/AF only supports 2-color images up to
32x32 in size, where the second color is an exact inverse of the
first. This means that Allegro may need to switch between hardware and
software cursors at any point during the execution of your program, so
you should not assume that this flag will remain constant for long
periods of time. It only tells you whether a hardware cursor is in use
at the current time, and may change whenever you hide/redisplay the
pointer.
GFX_SYSTEM_CURSOR
Indicates that the mouse cursor is the default system cursor, not
Allegro's custom cursor.
GFX_HW_HLINE:
Indicates that the normal opaque version of the hline() function is
implemented using a hardware accelerator. This will improve the
performance not only of hline() itself, but also of many other
functions that use it as a workhorse, for example circlefill(),
triangle(), and floodfill().
GFX_HW_HLINE_XOR:
Indicates that the XOR version of the hline() function, and any other
functions that use it as a workhorse, are implemented using a hardware
accelerator.
GFX_HW_HLINE_SOLID_PATTERN:
Indicates that the solid and masked pattern modes of the hline()
function, and any other functions that use it as a workhorse, are
implemented using a hardware accelerator (see note below).
GFX_HW_HLINE_COPY_PATTERN:
Indicates that the copy pattern mode of the hline() function, and any
other functions that use it as a workhorse, are implemented using a
hardware accelerator (see note below).
GFX_HW_FILL:
Indicates that the opaque version of the rectfill() function, the
clear_bitmap() routine, and clear_to_color(), are implemented using a
hardware accelerator.
GFX_HW_FILL_XOR:
Indicates that the XOR version of the rectfill() function is
implemented using a hardware accelerator.
GFX_HW_FILL_SOLID_PATTERN:
Indicates that the solid and masked pattern modes of the rectfill()
function are implemented using a hardware accelerator (see note below).
GFX_HW_FILL_COPY_PATTERN:
Indicates that the copy pattern mode of the rectfill() function is
implemented using a hardware accelerator (see note below).
GFX_HW_LINE:
Indicates that the opaque mode line() and vline() functions are
implemented using a hardware accelerator.
GFX_HW_LINE_XOR:
Indicates that the XOR version of the line() and vline() functions are
implemented using a hardware accelerator.
GFX_HW_TRIANGLE:
Indicates that the opaque mode triangle() function is implemented
using a hardware accelerator.
GFX_HW_TRIANGLE_XOR:
Indicates that the XOR version of the triangle() function is
implemented using a hardware accelerator.
GFX_HW_GLYPH:
Indicates that monochrome character expansion (for text drawing) is
implemented using a hardware accelerator.
GFX_HW_VRAM_BLIT:
Indicates that blitting from one part of the screen to another is
implemented using a hardware accelerator. If this flag is set,
blitting within the video memory will almost certainly be the fastest
possible way to display an image, so it may be worth storing some of
your more frequently used graphics in an offscreen portion of the
video memory.
GFX_HW_VRAM_BLIT_MASKED:
Indicates that the masked_blit() routine is capable of a hardware
accelerated copy from one part of video memory to another, and that
draw_sprite() will use a hardware copy when given a sub-bitmap of the
screen or a video memory bitmap as the source image. If this flag is
set, copying within the video memory will almost certainly be the
fastest possible way to display an image, so it may be worth storing
some of your more frequently used sprites in an offscreen portion of
the video memory.
Warning: if this flag is not set, masked_blit() and draw_sprite() will not work correctly when used with a video memory source image! You must only try to use these functions to copy within the video memory if they are supported in hardware.
GFX_HW_MEM_BLIT:
Indicates that blitting from a memory bitmap onto the screen is being
accelerated in hardware.
GFX_HW_MEM_BLIT_MASKED:
Indicates that the masked_blit() and draw_sprite() functions are being
accelerated in hardware when the source image is a memory bitmap and
the destination is the physical screen.
GFX_HW_SYS_TO_VRAM_BLIT:
Indicates that blitting from a system bitmap onto the screen is being
accelerated in hardware. Note that some acceleration may be present
even if this flag is not set, because system bitmaps can benefit from
normal memory to screen blitting as well. This flag will only be set
if system bitmaps have further acceleration above and beyond what is
provided by GFX_HW_MEM_BLIT.
GFX_HW_SYS_TO_VRAM_BLIT_MASKED:
Indicates that the masked_blit() and draw_sprite() functions are being
accelerated in hardware when the source image is a system bitmap and
the destination is the physical screen. Note that some acceleration
may be present even if this flag is not set, because system bitmaps
can benefit from normal memory to screen blitting as well. This flag
will only be set if system bitmaps have further acceleration above and
beyond what is provided by GFX_HW_MEM_BLIT_MASKED.
GFX_HW_VRAM_STRETCH_BLIT:
Indicates that stretched blitting of video bitmaps onto the screen is
implemented using hardware acceleration.
GFX_HW_SYS_STRETCH_BLIT:
Indicates that stretched blitting of system bitmaps onto the screen is
implemented using hardware acceleration.
GFX_HW_VRAM_STRETCH_BLIT_MASKED:
Indicates that masked stretched blitting (including stretch_sprite) of
video bitmaps onto the screen is implemented using hardware acceleration.
NOTE: some display drivers may show artifacts when this function is used.
If the image does not look correct try updating your video drivers.
GFX_HW_SYS_STRETCH_BLIT_MASKED:
Indicates that masked stretched blitting (including stretch_sprite) of
system bitmaps onto the screen is implemented using hardware acceleration.
NOTE: some display drivers may show artefact's when this function is used.
If the image does not look correct try updating your video drivers.
Note: even if the capabilities information says that patterned drawing is supported by the hardware, it will not be possible for every size of pattern. VBE/AF only supports patterns up to 8x8 in size, so Allegro will fall back on the original non-accelerated drawing routines whenever you use a pattern larger than this.
Note2: these hardware acceleration features will only take effect when you are drawing directly onto the screen bitmap, a video memory bitmap, or a sub-bitmap thereof. Accelerated hardware is most useful in a page flipping or triple buffering setup, and is unlikely to make any difference to the classic "draw onto a memory bitmap, then blit to the screen" system.
See also: screen, create_video_bitmap, scroll_screen, request_scroll, show_mouse, enable_triple_buffer.
Examples using this: ex3buf, exaccel, exsyscur, exupdate.
Return value: Returns zero if triple buffering is enabled, -1 otherwise.
See also: gfx_capabilities, request_scroll, request_video_bitmap.
Examples using this: ex3buf, exupdate.
Mode-X scrolling is reliable and will work on any card, other drivers may not work or not work reliably. See the platform-specific section of the docs for more information.
Allegro will handle any necessary vertical retrace synchronisation when scrolling the screen, so you don't need to call vsync() before it. This means that scroll_screen() has the same time delay effects as vsync().
Return value: Returns zero on success. Returns non-zero if the graphics driver can't handle hardware scrolling or the virtual screen is not large enough.
See also: set_gfx_mode, show_video_bitmap, request_scroll, request_video_bitmap.
Examples using this: exscroll.
Triple buffering is only possible with certain drivers: you can look at the GFX_CAN_TRIPLE_BUFFER bit in the gfx_capabilities flag to see if it will work with the current driver.
Return value: This function returns zero on success, non-zero otherwise.
See also: poll_scroll, request_video_bitmap, gfx_capabilities, scroll_screen.
Return value: Returns non-zero if it is still waiting to take place, and zero if the requested scroll has already happened.
See also: request_scroll, request_video_bitmap.
Examples using this: ex3buf, exupdate.
Allegro will handle any necessary vertical retrace synchronisation when page flipping, so you don't need to call vsync() before it. This means that show_video_bitmap() has the same time delay effects as vsync() by default. This can be adjusted with the "disable_vsync" config key in the [graphics] section of allegro.cfg. Example:
int current_page;
BITMAP *video_page[2];
...
/* Create pages for page flipping */
video_page[0] = create_video_bitmap(SCREEN_W, SCREEN_H);
video_page[1] = create_video_bitmap(SCREEN_W, SCREEN_H);
current_page = 0;
...
/* draw the screen and flip pages */
draw_screen(video_page[current_page]);
show_video_bitmap(video_page[current_page]);
current_page = (current_page+1)%2;
...Return value: Returns zero on success and non-zero on failure.
See also: scroll_screen, create_video_bitmap, Standard config variables.
Examples using this: exaccel, exflip, exupdate.
int current_page;
BITMAP *video_page[3];
...
/* Create pages for page flipping */
video_page[0] = create_video_bitmap(SCREEN_W, SCREEN_H);
video_page[1] = create_video_bitmap(SCREEN_W, SCREEN_H);
video_page[2] = create_video_bitmap(SCREEN_W, SCREEN_H);
current_page = 0;
...
/* draw the screen and flip pages */
draw_screen(video_page[current_page]);
do {
} while (poll_scroll());
request_video_bitmap(video_page[current_page]);
current_page = (current_page+1)%3;
...Return value: Returns zero on success and non-zero on failure.
See also: poll_scroll, request_scroll, gfx_capabilities, create_video_bitmap, scroll_screen.
Examples using this: ex3buf, exupdate.
See also: set_palette, scroll_screen.
Examples using this: Available Allegro examples.