DOS specifics

DIGI_*/DOS — Supported DOS digital sound drivers.
GFX_*/DOS — Supported DOS graphic drivers.
i_love_bill — Tells if Allegro has to used fixed rate timers.
JOY_TYPE_*/DOS — Supported DOS joystick drivers.
MIDI_*/DOS — Supported DOS MIDI sound drivers.

There are four Allegro files which you should redistribute along your program. These are the files `keyboard.dat', `language.dat', `allegro.cfg' and `setup.exe'.

The first two contain internationalisation information for keyboard mappings and system messages to show up localised on the user's computer. The `setup.exe' program, which comes in Allegro's `setup' directory, is a standalone tool which you can graphically customise and even embed into your main binary. The user can generate a configuration file with this tool, to store special settings or avoid Allegro's autodetection failing on specific hardware. Even if you distribute `setup.exe', you are recommended to copy too the empty `allegro.cfg' file, in case the setup program itself is unable to run and the user has to edit manually the configuration with a text editor.

If you are using get_config_text() in your program to localise text strings, merge your xxtext.cfg files with the ones provided by Allegro in the `resource' directory before creating `language.dat', and redistribute this with your program. This file will contain then both Allegro's system messages and the strings of your program.

Drivers JOY_TYPE_*/DOS

The DOS library supports the following type parameters for the install_joystick() function:

JOY_TYPE_AUTODETECT
Attempts to autodetect your joystick hardware. It isn't possible to reliably distinguish between all the possible input setups, so this routine can only ever choose the standard joystick, Sidewider, GamePad Pro, or GrIP drivers, but it will use information from the configuration file if one is available (this can be created using the setup utility or by calling the save_joystick_data() function), so you can always use JOY_TYPE_AUTODETECT in your code and then select the exact hardware type from the setup program.
JOY_TYPE_NONE
Dummy driver for machines without any joystick.
JOY_TYPE_STANDARD
A normal two button stick.
JOY_TYPE_2PADS
Dual joystick mode (two sticks, each with two buttons).
JOY_TYPE_4BUTTON
Enable the extra buttons on a 4-button joystick.
JOY_TYPE_6BUTTON
Enable the extra buttons on a 6-button joystick.
JOY_TYPE_8BUTTON
Enable the extra buttons on an 8-button joystick.
JOY_TYPE_FSPRO
CH Flightstick Pro or compatible stick, which provides four buttons, an analogue throttle control, and a 4-direction coolie hat.
JOY_TYPE_WINGEX
A Logitech Wingman Extreme, which should also work with any Thrustmaster Mk.I compatible joystick. It provides support for four buttons and a coolie hat. This also works with the Wingman Warrior, if you plug in the 15 pin plug (remember to unplug the 9-pin plug!) and set the tiny switch in front to the "H" position (you will not be able to use the throttle or the spinner though).
JOY_TYPE_SIDEWINDER
The Microsoft Sidewinder digital pad (supports up to four controllers, each with ten buttons and a digital direction control).
JOY_TYPE_SIDEWINDER_AG
An alternative driver to JOY_TYPE_SIDEWINDER. Try this if your Sidewinder isn't recognized with JOY_TYPE_SIDEWINDER.
JOY_TYPE_SIDEWINDER_PP
The Microsoft Sidewinder 3D/Precision/Force Feedback Pro joysticks.
JOY_TYPE_GAMEPAD_PRO
The Gravis GamePad Pro (supports up to two controllers, each with ten buttons and a digital direction control).
JOY_TYPE_GRIP
Gravis GrIP driver, using the grip.gll driver file.
JOY_TYPE_GRIP4
Version of the Gravis GrIP driver that is constrained to only move along the four main axes.
JOY_TYPE_SNESPAD_LPT1
JOY_TYPE_SNESPAD_LPT2
JOY_TYPE_SNESPAD_LPT3
SNES joypads connected to LPT1, LPT2, and LPT3 respectively.
JOY_TYPE_PSXPAD_LPT1
JOY_TYPE_PSXPAD_LPT2
JOY_TYPE_PSXPAD_LPT3
PSX joypads connected to LPT1, LPT2, and LPT3 respectively. See http://www.ziplabel.com/dpadpro/index.html for information about the parallel cable required. The driver automagically detects which types of PSX pads are connected out of digital, analog (red or green mode), NegCon, multi taps, Namco light guns, Jogcons (force feedback steering wheel) and the mouse. If the controller isn't recognised it is treated as an analog controller, meaning the driver should work with just about anything. You can connect controllers in any way you see fit, but only the first 8 will be used. The Sony Dual Shock or Namco Jogcon will reset themselves (to digital mode) after not being polled for 5 seconds. This is normal, the same thing happens on a Playstation, it's designed to stop any vibration in case the host machine crashes. Other mode switching controllers may have similar quirks. However, if this happens to a Jogcon controller the mode button is disabled. To reenable the mode button on the Jogcon you need to hold down the Start and Select buttons at the same time. The G-con45 needs to be connected to (and pointed at) a TV type monitor connected to your computer. The composite video out on my video card works fine for this (a Hercules Stingray 128/3D 8Mb). The TV video modes in Mame should work too.
JOY_TYPE_N64PAD_LPT1
JOY_TYPE_N64PAD_LPT2
JOY_TYPE_N64PAD_LPT3
N64 joypads connected to LPT1, LPT2, and LPT3 respectively. See http://www.st-hans.de/N64.htm for information about the necessary hardware adapter. It supports up to four controllers on a single parallel port. There is no need to calibrate the analog stick, as this is done by the controller itself when powered up. This means that the stick has to be centred when the controller is initialised. One possible issue people may have with this driver is that it is physically impossible to move the analog stick fully diagonal, but I can't see this causing any major problems. This is because of the shape of the rim that the analog stick rests against. Like the Gravis Game Pad Pro, this driver briefly needs to disable hardware interrupts while polling. This causes a noticeable performance hit on my machine in both drivers, but there is no way around it. At a (very) rough guess I'd say it slows down Mame 5% - 10%.
JOY_TYPE_DB9_LPT1
JOY_TYPE_DB9_LPT2
JOY_TYPE_DB9_LPT3
A pair of two-button joysticks connected to LPT1, LPT2, and LPT3 respectively. Port 1 is compatible with Linux joy-db9 driver (multisystem 2-button), and port 2 is compatible with Atari interface for DirectPad Pro. See the source file (src/dos/multijoy.c) for pinout information.
JOY_TYPE_TURBOGRAFIX_LPT1
JOY_TYPE_TURBOGRAFIX_LPT2
JOY_TYPE_TURBOGRAFIX_LPT3
These drivers support up to 7 joysticks, each one with up to 5 buttons, connected to LPT1, LPT2, and LPT3 respectively. They use the TurboGraFX interface by Steffen Schwenke: see http://www.burg-halle.de/~schwenke/parport.html for details on how to build this.
JOY_TYPE_WINGWARRIOR
A Wingman Warrior joystick.
JOY_TYPE_IFSEGA_ISA
JOY_TYPE_IFSEGA_PCI
JOY_TYPE_IFSEGA_PCI_FAST
Drivers for the IF-SEGA joystick interface cards by the IO-DATA company (these come in PCI, PCI2, and ISA variants).

See also: install_joystick.

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: set_gfx_mode.

Drivers DIGI_*/DOS

The DOS sound functions support the following digital sound cards:

      DIGI_AUTODETECT      - let Allegro pick a digital sound driver
      DIGI_NONE            - no digital sound
      DIGI_SB              - Sound Blaster (autodetect type)
      DIGI_SB10            - SB 1.0 (8-bit mono single shot DMA)
      DIGI_SB15            - SB 1.5 (8-bit mono single shot DMA)
      DIGI_SB20            - SB 2.0 (8-bit mono auto-initialised
                             DMA)
      DIGI_SBPRO           - SB Pro (8-bit stereo)
      DIGI_SB16            - SB16 (16-bit stereo)
      DIGI_AUDIODRIVE      - ESS AudioDrive
      DIGI_SOUNDSCAPE      - Ensoniq Soundscape
      DIGI_WINSOUNDSYS     - Windows Sound System

See also: detect_digi_driver, install_sound, install_sound_input.

Drivers MIDI_*/DOS

The DOS sound functions support the following MIDI sound cards:

      MIDI_AUTODETECT      - let Allegro pick a MIDI sound driver
      MIDI_NONE            - no MIDI sound
      MIDI_ADLIB           - Adlib or SB FM synth (autodetect type)
      MIDI_OPL2            - OPL2 synth (mono, used in Adlib and SB)
      MIDI_2XOPL2          - dual OPL2 synths (stereo, used in
                             SB Pro-I)
      MIDI_OPL3            - OPL3 synth (stereo, SB Pro-II
                             and above)
      MIDI_SB_OUT          - SB MIDI interface
      MIDI_MPU             - MPU-401 MIDI interface
      MIDI_DIGMID          - sample-based software wavetable player
      MIDI_AWE32           - AWE32 (EMU8000 chip)

See also: detect_midi_driver, install_sound, install_sound_input.

DOS integration routines

extern int i_love_bill;

When running in clean DOS mode, the timer handler dynamically reprograms the clock chip to generate interrupts at exactly the right times, which gives an extremely high accuracy. Unfortunately, this constant speed adjustment doesn't work under most multitasking systems (notably Windows), so there is an alternative mode that just locks the hardware timer interrupt to a speed of 200 ticks per second. This reduces the accuracy of the timer (for instance, rest() will round the delay time to the nearest 5 milliseconds), and prevents the vertical retrace simulator from working, but on the plus side, it makes Allegro programs work under Windows. This flag is set by allegro_init() if it detects the presence of a multitasking OS, and enables the fixed rate timer mode.

See also: install_timer, allegro_init, os_type.

Back to contents