Sets a graphic video mode.
Switches into graphics mode. The card parameter should usually be one of
the Allegro magic drivers (read introduction of chapter "Graphics modes")
or see the platform specific documentation for a list of the available
drivers. The w and h parameters specify what screen resolution you want.
The color depth of the graphic mode has to be specified before calling
this function with 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
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
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
Returns zero on success. On failure returns a negative number and stores a
description of the problem in allegro_error.
The following threads each have code containing this keyword:
Note: You can click on the numbers to jump directly to the posts that reference this page.
The following projects include source code containing this keyword: