GFX_

Supported DOS graphic drivers.

Description

Drivers GFX_*/DOS
The DOS library supports the following card parameters for the set_gfx_mode() function:
  • GFX_TEXT
    Return to text mode.
  • GFX_AUTODETECT
    Let Allegro pick an appropriate graphics driver.
  • GFX_AUTODETECT_FULLSCREEN
    Autodetects a graphics driver, but will only use fullscreen drivers, failing if these are not available on current platform.
  • GFX_AUTODETECT_WINDOWED
    Same as above, but uses only windowed drivers. This will always fail under DOS.
  • GFX_SAFE
    Special driver for when you want to reliably set a graphics mode and don't really care what resolution or color depth you get. See the set_gfx_mode() documentation for details.
  • GFX_VGA
    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), 256x256 (no scrolling), and 80x80 (with a 819 pixel high virtual screen).
  • GFX_MODEX
    Mode-X 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.
  • 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. This is the only VESA driver that supports the request_refresh_rate() function.

    The standard VESA modes are 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.

    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.
  • GFX_VBEAF
    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.
  • GFX_XTENDED
    An unchained 640x400 mode, as described by Mark Feldman in the PCGPE. 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().
There are a few things you need to be aware of for scrolling: most VESA implementations can only handle horizontal scrolling in four pixel increments, so smooth horizontal panning is impossible in SVGA modes. A significant number of VESA implementations seem to be very buggy when it comes to scrolling in truecolor video modes, so you shouldn't depend on this routine working correctly in the truecolor resolutions unless you can be sure that SciTech Display Doctor is installed. Hardware scrolling may also not work at all under Windows.

Triple buffering is only possible with certain drivers: it will work in any DOS mode-X resolution if the timer retrace simulator is active (but this doesn't work correctly under Windows 95), plus it is supported by the VBE 3.0 and VBE/AF drivers for a limited number graphics cards.
See Also: