<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: DOS specifics
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<h1><a name="DOS specifics">DOS specifics</a></h1>
<ul>
<li><a href="#DIGI_*/DOS">DIGI_*/DOS</a> — Supported DOS digital sound drivers.
<li><a href="#GFX_*/DOS">GFX_*/DOS</a> — Supported DOS graphic drivers.
<li><a href="#i_love_bill">i_love_bill</a> — Tells if Allegro has to used fixed rate timers.
<li><a href="#JOY_TYPE_*/DOS">JOY_TYPE_*/DOS</a> — Supported DOS joystick drivers.
<li><a href="#MIDI_*/DOS">MIDI_*/DOS</a> — Supported DOS MIDI sound drivers.
</ul>
<p>
There are four Allegro files which you should redistribute along your program.
These are the files <tt>`keyboard.dat'</tt>, <tt>`language.dat'</tt>, <tt>`allegro.cfg'</tt> and
<tt>`setup.exe'</tt>.
<p>
The first two contain internationalisation information for keyboard mappings
and system messages to show up localised on the user's computer. The
<tt>`setup.exe'</tt> program, which comes in Allegro's <tt>`setup'</tt> 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 <tt>`setup.exe'</tt>, you are recommended to copy too
the empty <tt>`allegro.cfg'</tt> file, in case the setup program itself is unable to
run and the user has to edit manually the configuration with a text editor.
<p>
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
<tt>`resource'</tt> directory before creating <tt>`language.dat'</tt>, and redistribute this
with your program. This file will contain then both Allegro's system
messages and the strings of your program.
<p><br>
<div class="al-api"><b>Drivers <a name="JOY_TYPE_*/DOS">JOY_TYPE_*/DOS</a></b></div><br>
The DOS library supports the following type parameters for the
install_joystick() function:
<ul><li>
JOY_TYPE_AUTODETECT<br>
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.
<li>
JOY_TYPE_NONE<br>
Dummy driver for machines without any joystick.
<li>
JOY_TYPE_STANDARD<br>
A normal two button stick.
<li>
JOY_TYPE_2PADS<br>
Dual joystick mode (two sticks, each with two buttons).
<li>
JOY_TYPE_4BUTTON<br>
Enable the extra buttons on a 4-button joystick.
<li>
JOY_TYPE_6BUTTON<br>
Enable the extra buttons on a 6-button joystick.
<li>
JOY_TYPE_8BUTTON<br>
Enable the extra buttons on an 8-button joystick.
<li>
JOY_TYPE_FSPRO<br>
CH Flightstick Pro or compatible stick, which provides four buttons,
an analogue throttle control, and a 4-direction coolie hat.
<li>
JOY_TYPE_WINGEX<br>
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).
<li>
JOY_TYPE_SIDEWINDER<br>
The Microsoft Sidewinder digital pad (supports up to four controllers,
each with ten buttons and a digital direction control).
<li>
JOY_TYPE_SIDEWINDER_AG<br>
An alternative driver to JOY_TYPE_SIDEWINDER.
Try this if your Sidewinder isn't recognized with JOY_TYPE_SIDEWINDER.
<li>
JOY_TYPE_SIDEWINDER_PP<br>
The Microsoft Sidewinder 3D/Precision/Force Feedback Pro joysticks.
<li>
JOY_TYPE_GAMEPAD_PRO<br>
The Gravis GamePad Pro (supports up to two controllers, each with ten
buttons and a digital direction control).
<li>
JOY_TYPE_GRIP<br>
Gravis GrIP driver, using the grip.gll driver file.
<li>
JOY_TYPE_GRIP4<br>
Version of the Gravis GrIP driver that is constrained to only move
along the four main axes.
<li>
JOY_TYPE_SNESPAD_LPT1<br>
JOY_TYPE_SNESPAD_LPT2<br>
JOY_TYPE_SNESPAD_LPT3<br>
SNES joypads connected to LPT1, LPT2, and LPT3 respectively.
<li>
JOY_TYPE_PSXPAD_LPT1<br>
JOY_TYPE_PSXPAD_LPT2<br>
JOY_TYPE_PSXPAD_LPT3<br>
PSX joypads connected to LPT1, LPT2, and LPT3 respectively. See
<a href="http://www.ziplabel.com/dpadpro/index.html">http://www.ziplabel.com/dpadpro/index.html</a> 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.
<li>
JOY_TYPE_N64PAD_LPT1<br>
JOY_TYPE_N64PAD_LPT2<br>
JOY_TYPE_N64PAD_LPT3<br>
N64 joypads connected to LPT1, LPT2, and LPT3 respectively. See
<a href="http://www.st-hans.de/N64.htm">http://www.st-hans.de/N64.htm</a> 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%.
<li>
JOY_TYPE_DB9_LPT1<br>
JOY_TYPE_DB9_LPT2<br>
JOY_TYPE_DB9_LPT3<br>
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.
<li>
JOY_TYPE_TURBOGRAFIX_LPT1<br>
JOY_TYPE_TURBOGRAFIX_LPT2<br>
JOY_TYPE_TURBOGRAFIX_LPT3<br>
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
<a href="http://www.burg-halle.de/~schwenke/parport.html">http://www.burg-halle.de/~schwenke/parport.html</a> for details
on how to build this.
<li>
JOY_TYPE_WINGWARRIOR<br>
A Wingman Warrior joystick.
<li>
JOY_TYPE_IFSEGA_ISA<br>
JOY_TYPE_IFSEGA_PCI<br>
JOY_TYPE_IFSEGA_PCI_FAST<br>
Drivers for the IF-SEGA joystick interface cards by the IO-DATA
company (these come in PCI, PCI2, and ISA variants).
</ul>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg007.html#install_joystick" title="Initialises the joystick.">install_joystick</a>.</blockquote>
<div class="al-api"><b>Drivers <a name="GFX_*/DOS">GFX_*/DOS</a></b></div><br>
The DOS library supports the following card parameters for the
set_gfx_mode() function:
<ul><li>
GFX_TEXT<br>
Return to text mode.
<li>
GFX_AUTODETECT<br>
Let Allegro pick an appropriate graphics driver.
<li>
GFX_AUTODETECT_FULLSCREEN<br>
Autodetects a graphics driver, but will only use fullscreen drivers,
failing if these are not available on current platform.
<li>
GFX_AUTODETECT_WINDOWED<br>
Same as above, but uses only windowed drivers. This will always fail
under DOS.
<li>
GFX_SAFE<br>
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.
<li>
GFX_VGA<br>
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).
<li>
GFX_MODEX<br>
Mode-X will work on any VGA card, and provides a range of different
256-color tweaked resolutions.
<ul><li>
Stable mode-X resolutions:
<ul><li>
Square aspect ratio: 320x240
<li>
Skewed aspect ratio: 256x224, 256x240, 320x200, 320x400,
320x480, 320x600, 360x200, 360x240,
360x360, 360x400, 360x480
</ul>
These have worked on every card/monitor that I've tested.
<li>
Unstable mode-X resolutions:
<ul><li>
Square aspect ratio: 360x270, 376x282, 400x300
<li>
Skewed aspect ratio: 256x200, 256x256, 320x350, 360x600,
376x308, 376x564, 400x150, 400x600
</ul>
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."
</ul>
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.
<li>
GFX_VESA1<br>
Use the VESA 1.x driver.
<li>
GFX_VESA2B<br>
Use the VBE 2.0 banked mode driver.
<li>
GFX_VESA2L<br>
Use the VBE 2.0 linear framebuffer driver.
<li>
GFX_VESA3<br>
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.
<li>
GFX_VBEAF<br>
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.
<li>
GFX_XTENDED<br>
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().
</ul>
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.
<p>
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.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg008.html#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>.</blockquote>
<div class="al-api"><b>Drivers <a name="DIGI_*/DOS">DIGI_*/DOS</a></b></div><br>
The DOS sound functions support the following digital sound cards:
<blockquote class="text"><pre>
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</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg024.html#detect_digi_driver" title="Detects whether the specified digital sound device is available.">detect_digi_driver</a>,
<a class="xref" href="alleg024.html#install_sound" title="Initialises the sound module.">install_sound</a>,
<a class="xref" href="alleg029.html#install_sound_input" title="Initialises the sound recorder module.">install_sound_input</a>.</blockquote>
<div class="al-api"><b>Drivers <a name="MIDI_*/DOS">MIDI_*/DOS</a></b></div><br>
The DOS sound functions support the following MIDI sound cards:
<blockquote class="text"><pre>
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)</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg024.html#detect_midi_driver" title="Detects whether the specified MIDI sound device is available.">detect_midi_driver</a>,
<a class="xref" href="alleg024.html#install_sound" title="Initialises the sound module.">install_sound</a>,
<a class="xref" href="alleg029.html#install_sound_input" title="Initialises the sound recorder module.">install_sound_input</a>.</blockquote>
<br><center><h2><a name="DOS integration routines">DOS integration routines</a></h2></center><p>
<p><br>
<div class="al-api"><b>extern int <a name="i_love_bill">i_love_bill</a>;</b></div><br>
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.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg005.html#install_timer" title="Installs the Allegro timer interrupt handler.">install_timer</a>,
<a class="xref" href="alleg000.html#allegro_init" title="Macro to initialise the Allegro library.">allegro_init</a>,
<a class="xref" href="alleg000.html#os_type" title="Stores the detected type of the OS.">os_type</a>.</blockquote>
<hr><div class="al-back-to-contents"><a href="allegro.html">Back to contents</a></div>
</body>
</html>
