Graphics modes

set_color_depth

set_gfx_mode

gfx_capabilities

scroll_screen

request_scroll

poll_scroll

show_video_bitmap

request_video_bitmap

request_modex_scroll

poll_modex_scroll

split_modex_screen

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.

int set_gfx_mode(int card, int w, int h, int v_w, int v_h);
Switches into graphics mode. The card parameter should be one of the values:

      GFX_TEXT          - return to text mode
      GFX_AUTODETECT    - let Allegro pick an appropriate graphics driver
      GFX_VGA           - normal VGA (320x200, 320x100, 160x120, or 80x80)
      GFX_MODEX         - select a planar, tweaked VGA mode
      GFX_VESA1         - use the VESA 1.x driver
      GFX_VESA2B        - use the VBE 2.0 banked mode driver
      GFX_VESA2L        - use the VBE 2.0 linear framebuffer driver
      GFX_VESA3         - use the VBE 3.0 driver
      GFX_VBEAF         - use the VBE/AF hardware accelerator API
      GFX_XTENDED       - use the unchained mode 640x400 driver

• The standard 256 color VGA mode 13h, using the GFX_VGA driver. This is normally sized 320x200, which will work on any VGA but doesn't support large virtual screens and hardware scrolling. Allegro also provides some tweaked variants of the mode which are able to scroll, sized 320x100 (with a 200 pixel high virtual screen), 160x120 (with a 409 pixel high virtual screen), and 80x80 (with a 819 pixel high virtual screen).

• Mode-X, using the GFX_MODEX driver. This will work on any VGA card, and provides a range of different 256 color tweaked resolutions.
  • Stable mode-X resolutions:
    • Square aspect ratio: 320x240

    • Skewed aspect ratio: 256x224, 256x240, 320x200, 320x400, 320x480, 320x600, 360x200, 360x240, 360x360, 360x400, 360x480

    These have worked on every card/monitor that I've tested.

  • Unstable mode-X resolutions:
    • Square aspect ratio: 360x270, 376x282, 400x300

    • Skewed aspect ratio: 256x200, 256x256, 320x350, 360x600, 376x308, 376x564, 400x150, 400x600

    These only work on some monitors. They were fine on my old machine, but don't get on very well with my new monitor. If you are worried about the possibility of damaging your monitor by using these modes, don't be. Of course I'm not providing any warranty with any of this, and if your hardware does blow up that is tough, but I don't think this sort of tweaking can do any damage. From the documentation of Robert Schmidt's TWEAK program:

    "Some time ago, putting illegal or unsupported values or combinations of such into the video card registers might prove hazardous to both your monitor and your health. I have *never* claimed that bad things can't happen if you use TWEAK, although I'm pretty sure it never will. I've never heard of any damage arising from trying out TWEAK, or from general VGA tweaking in any case."

  Most of the mode-X drawing functions are slower than in mode 13h, due to the complexity of the planar bitmap organisation, but solid area fills and plane-aligned blits from one part of video memory to another can be significantly faster, particularly on older hardware. Mode-X can address the full 256k of VGA RAM, so hardware scrolling and page flipping are possible, and it is possible to split the screen in order to scroll the top part of the display but have a static status indicator at the bottom.

• The standard SVGA modes, 640x480, 800x600, and 1024x768. These ought to work with any SVGA card: if they don't, get a copy of the SciTech Display Doctor and see if that fixes it. What color depths are available will depend on your hardware. Most cards support both 15 and 16 bit resolutions, but if at all possible I would advise you to support both (it's not hard...) in case one is not available. Some cards provide both 24 and 32 bit truecolor, in which case it is a choice between 24 (saves memory) or 32 (faster), but many older cards have no 32 bit mode and some newer ones don't support 24 bit resolutions. Use the vesainfo test program to see what modes your VESA driver provides.

• Many cards also support 640x400, 1280x1024, and 1600x1200, but these aren't available on everything, for example the S3 chipset has no 640x400 mode. Other weird resolution may be possible, eg. some Tseng boards can do 640x350, and the Avance Logic has a 512x512 mode.

• Xtended mode, as described by Mark Feldman in the PCGPE, sized 640x400 (256 colors) and using the GFX_XTENDED driver. This uses VESA to select an SVGA mode (so it will only work on cards supporting the VESA 640x400 resolution), and then unchains the VGA hardware as for mode-X. This allows the entire screen to be addressed without the need for bank switching, but hardware scrolling and page flipping are not possible. This driver will never be autodetected (the normal VESA 640x400 mode will be chosen instead), so if you want to use it you will have to explicitly pass GFX_XTENDED to set_gfx_mode().

• The SciTech Display Doctor provides several scrollable low resolution modes in a range of different color depths (320x200, 320x240, 320x400, 320x480, 360x200, 360x240, 360x400, and 360x480 all work on my ET4000 with 8, 15, or 16 bits per pixel). These are lovely, allowing scrolling and page flipping without the complexity of the mode-X planar setup, but unfortunately they aren't standard so you will need Display Doctor in order to use them.

• VBE/AF is a superset of the VBE 2.0 standard, which provides an API for accessing hardware accelerator features. VBE/AF drivers are currently only available from the FreeBE/AF project or as part of the SciTech Display Doctor package, but they can give dramatic speed improvements when used with suitable hardware. For a detailed discussion of hardware acceleration issues, refer to the documentation for the gfx_capabilities flag.

  You can use the afinfo test program to check whether you have a VBE/AF driver, and to see what resolutions it supports.

  The SciTech VBE/AF drivers require nearptr access to be enabled, so any stray pointers are likely to crash your machine while their drivers are in use. This means it may be a good idea to use VESA while debugging your program, and only switch to VBE/AF once the code is working correctly. The FreeBE/AF drivers do not have this problem.

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

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 is likely to end up creating a virtual screen much larger than the one you request. On an SVGA card with one megabyte of vram you can count on getting a 1024x1024 virtual screen (256 colors) or 1024x512 (15 or 16 bpp), and with 512k vram you can get 1024x512 (256 color). Other sizes may or may not be possible: don't assume that they will 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).

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.

If Allegro is unable to select an appropriate mode, set_gfx_mode() returns a negative number and stores a description of the problem in allegro_error. Otherwise it returns zero.

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. As a special case, the mode-X driver only supports triple buffering when the retrace simulator is installed, so you must call timer_simulate_retrace() before doing any triple buffering in a mode-X resolution.

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_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() 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_TEXTOUT_FIXED:
Indicates that monochrome character expansion (for the 8x8 and 8x16 fixed width font formats) 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.

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.

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). Returns zero on success: it may fail if the graphics driver can't handle hardware scrolling or the virtual screen isn't large enough. 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: see below.

Mode-X scrolling is reliable and will work on any card. Unfortunately most VESA implementations can only handle horizontal scrolling in four pixel increments, so smooth horizontal panning is impossible in SVGA modes. This is a shame, but I can't see any way round it. A significant number of VESA implementations seem to be very buggy when it comes to scrolling in truecolor video modes, so I suggest you don't depend on this routine working correctly in the truecolor resolutions unless you can be sure that SciTech Display Doctor is installed.

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().

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 (see examples/ex20.c). Triple buffering is only possible on certain hardware: it will work in any mode-X resolution if the timer retrace simulator is active (but this doesn't work correctly under win95), plus it is supported by the VBE 3.0 and VBE/AF drivers for a limited number of high-end graphics cards. 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.

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, returning non-zero if it is still waiting to take place, and zero if it has already happened.

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. Returns zero on success. This function will wait for a vertical retrace if the graphics card requires it, so you don't need to call vsync() yourself.

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().

int request_modex_scroll(int x, int y);
int poll_modex_scroll();
Obsolete versions of request_scroll() and poll_scroll(), preserved for backward compatibility.

void split_modex_screen(int line);
This function is only available in mode-X. It splits the VGA display into two parts at the specified line. The top half of the screen can be scrolled to any part of video memory with the scroll_screen() function, but the part below the specified line number will remain fixed and will display from position (0, 0) of the screen bitmap. After splitting the screen you will generally want to scroll so that the top part of the display starts lower down in video memory, and then create two sub-bitmaps to access the two sections (see examples/ex19.c for a demonstration of how this could be done). To disable the split, call split_modex_screen(0).

Back to Contents