Graphics modes

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)
With a virtual screen bigger than the visible screen you can perform smooth CPU inexpensive scrolling: you draw your graphics once, and then only tell the video card to show a different portion of the screen. However, virtual screens are not supported on all platforms, and on some they might be emulated through software, losing any performance. On top of that, many video cards only allow horizontal scrolling in steps of 32 bytes. This is not a problem if your game runs in 24 or 32 bit, but it tends to mean jerky scrolling for other color depths.

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:


void set_color_depth(int depth);

Sets the pixel format to be used by subsequent calls to set_gfx_mode() and create_bitmap(). Valid depths are 8 (the default), 15, 16, 24, and 32 bits. Example:
      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");
      }
Note that the screen color depth won't change until the next successful call to set_gfx_mode().
See also: get_color_depth, set_gfx_mode, set_color_conversion, makecol, getr, desktop_color_depth.
Examples using this: Available Allegro examples.
int get_color_depth(void);

Returns the current pixel format. This can be very useful to know in order to write generic functions which select a different code path internally depending on the color depth being used.

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.
void request_refresh_rate(int rate);

Requests that the next call to set_gfx_mode() try to use the specified refresh rate, if possible. Not all drivers are able to control this at all, and even when they can, not all rates will be possible on all hardware, so the actual settings may differ from what you requested. After you call set_gfx_mode(), you can use get_refresh_rate() to find out what was actually selected. At the moment only the DOS VESA 3.0, X DGA 2.0 and some Windows DirectX drivers support this function. The speed is specified in Hz, eg. 60, 70. To return to the normal default selection, pass a rate value of zero. Example:
      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.
int get_refresh_rate(void);

Returns the current refresh rate, if known (not all drivers are able to report this information). Returns zero if the actual rate is unknown.
See also: request_refresh_rate.
GFX_MODE_LIST *get_gfx_mode_list(int card);

Attempts to create a list of all the supported video modes for a certain graphics driver, made up from the GFX_MODE_LIST structure, which has the following definition:
      typedef struct GFX_MODE_LIST
      {
         int num_modes;
         GFX_MODE *mode;
      } GFX_MODE_LIST;
The mode entry points to the actual list of video modes.
      typedef struct GFX_MODE
      {
         int width, height, bpp;
      } GFX_MODE;
This list of video modes is terminated with an { 0, 0, 0 } entry.

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.
void destroy_gfx_mode_list(GFX_MODE_LIST *mode_list);

Removes the mode list created by get_gfx_mode_list() from memory. Use this once you are done with the generated mode list to avoid memory leaks in your program.
See also: get_gfx_mode_list, set_gfx_mode, set_color_depth.
int set_gfx_mode(int card, int w, int h, int v_w, int v_h);

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 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.
int set_display_switch_mode(int mode);

Sets how the program should handle being switched into the background, if the user tabs away from it. Not all of the possible modes will be supported by every graphics driver on every platform. The available modes are: Note that you should be very careful when you are using graphics routines in the switching context: you must always call acquire_screen() before the start of any drawing code onto the screen and not release it until you are completely finished, because the automatic locking mechanism may not be good enough to work when the program runs in the background or has just been raised in the foreground.

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, exsample, exstream, exswitch.
int set_display_switch_callback(int dir, void (*cb)());

Installs a notification callback for the switching mode that was previously selected by calling set_display_switch_mode(). The direction parameter can either be SWITCH_IN or SWITCH_OUT, depending whether you want to be notified about switches away from your program or back to your program. You can sometimes install callbacks for both directions at the same time, but not every platform supports this. You can install several switch callbacks, but no more than eight on any platform.

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.
void remove_display_switch_callback(void (*cb)());

Removes a notification callback that was previously installed by calling set_display_switch_callback(). All the callbacks will automatically be removed when you call set_display_switch_mode(). You can safely call this function even if the callback you want to remove is not installed.
See also: set_display_switch_callback.
int get_display_switch_mode();

Returns the current display switching mode, in the same format passed to set_display_switch_mode().
See also: set_display_switch_mode.
Examples using this: exswitch.
int is_windowed_mode(void);

This function can be used to detect whether or not set_gfx_mode() selected a windowed mode. Example:
      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.
int get_gfx_mode_type(int graphics_card);

This function lets you determine the types of operating modes that a specific graphics card driver operates in. It will tell you whether it is a windowed, fullscreen, definitely windowed or fullscreen, and/or a magic driver.

The value returned is a bitfield consisting of these fields:
GFX_TYPE_UNKNOWN
GFX_TYPE_WINDOWED
GFX_TYPE_FULLSCREEN
GFX_TYPE_DEFINITE
GFX_TYPE_MAGIC

The return value will only be equivalent to GFX_TYPE_UNKNOWN when it is a driver unrecognized on that platform, or it is a bogus value. Test for the other types by using a bitwise AND. If the driver is windowed or fullscreen, it will also have the definite flag set. For example,

   int gfx_type = get_gfx_mode_type(GFX_AUTODETECT_WINDOWED);
gfx_type would have the GFX_TYPE_WINDOWED, GFX_TYPE_DEFINITE, and GFX_TYPE_MAGIC flags set.

Allegro needs to be initialized first.

Example:

   /* Accept the use of only windowed drivers in our selection dialog */
   int accept_windowed(int card , int w , int h , int color_depth)
   {
      if (get_gfx_mode_type(card) & GFX_TYPE_WINDOWED)
         return 0;
      return 1;
   }

   /* In main: */
   gfx_mode_select_filter(&card, &w, &h, &color_depth, accept_windowed);

Return value: Returns a bitfield describing the graphics mode type.

See also: gfx_mode_select_filter, get_gfx_mode, set_gfx_mode, is_windowed_mode.
int get_gfx_mode();

This function will let you determine which graphics driver is currently set by allegro. If no graphics driver is set, it will return GFX_NONE.

Return value:

Returns the id of the current graphics driver if there is one, or GFX_NONE if none is set.

See also: set_gfx_mode, is_windowed_mode.
extern int gfx_capabilities;

Bitfield describing the capabilities of the current graphics driver and video hardware. This may contain combination any of the flags:

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.
int enable_triple_buffer();

If the GFX_CAN_TRIPLE_BUFFER bit of the gfx_capabilities field is not set, you can attempt to enable it by calling this function. In particular if you are running in mode-X in a clean DOS environment, this routine will enable the timer retrace simulator, which will activate the triple buffering functions.

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.
int scroll_screen(int x, int y);

Attempts to scroll the hardware screen to display a different part of the virtual screen (initially it will be positioned at 0, 0, which is the top left corner). You can use this to move the screen display around in a large virtual screen space, or to page flip back and forth between two non-overlapping areas of the virtual screen. Note that to draw outside the original position in the screen bitmap you will have to alter the clipping rectangle with set_clip_rect().

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.
int request_scroll(int x, int y);

This function is used for triple buffering. It requests a hardware scroll to the specified position, but returns immediately rather than waiting for a retrace. The scroll will then take place during the next vertical retrace, but you can carry on running other code in the meantime and use the poll_scroll() routine to detect when the flip has actually taken place.

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.
int poll_scroll();

This function is used for triple buffering. It checks the status of a hardware scroll previously initiated by the request_scroll() routine.

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.
int show_video_bitmap(BITMAP *bitmap);

Attempts to page flip the hardware screen to display the specified video bitmap object, which must be the same size as the physical screen, and should have been obtained by calling the create_video_bitmap() function.

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 request_video_bitmap(BITMAP *bitmap);

This function is used for triple buffering. It requests a page flip to display the specified video bitmap object, but returns immediately rather than waiting for a retrace. The flip will then take place during the next vertical retrace, but you can carry on running other code in the meantime and use the poll_scroll() routine to detect when the flip has actually taken place. Triple buffering is only possible on certain hardware: see the comments about request_scroll(). Example:
      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.
void vsync();

Waits for a vertical retrace to begin. The retrace happens when the electron beam in your monitor has reached the bottom of the screen and is moving back to the top ready for another scan. During this short period the graphics card isn't sending any data to the monitor, so you can do things to it that aren't possible at other times, such as altering the palette without causing flickering (snow). Allegro will automatically wait for a retrace before altering the palette or doing any hardware scrolling, though, so you don't normally need to bother with this function.
See also: set_palette, scroll_screen.
Examples using this: Available Allegro examples.

Back to contents