Joystick Library for Dos

Given the great success of arcade game emulation on PC, I decided to release to the public my Joystick Library for Dos (which is also used in my emulator JoyEmu). The package includes full C source code (Borland C and DJGPP, but should be ported to other dialects without great efforts) and a test program. If you are an emulator author, or are just planning to add joystick support to your programs, take a look at it!

Type

C library; freeware/GNU General Public License 2.0.

Version

1.2 / english

Fixes in version 1.2:

• fixed the lock up that happened when joysticks were disconnected during port reading;
• fixed a problem with automatic recalibration;
• added support for 8-button joysticks.

Description

This small package is aimed at those programmers who would like to add joystick support to some of their programs, but don't want to waste too much time over this feature. With just two functions, you can test the status of both joysticks, including fire buttons; joysticks with 2, 4, 6 and 8 fire buttons are supported.
If you are not a programmer, you could take a look at JoyEmu by the same author; this keyboard emulator has a full featured control panel, let you add joystick support to existing programs without modifying the code and is Dos and Windows 95 compatible.

The code for these routines is taken from JoyEmu's source code; it compiles without errors under:

• Borland C (version 3.1 tested)
• DJGPP (version 2.7.2.1 tested)

but should be fairly portable to other Dos C compilers.

Requirements

• Dos/Windows C compiler (Borland C or DJGPP raccomended).

Features

The usage is very simple:

• include "joystick.h" at the beginning of your program and compile and link the module "joystick.c";
• at program startup, use:

unsigned char j, mode, skipjoy;

// Set mode to the kind of joystick requested:
// JOY_2BUTTONS    standard 2-button joysticks
// JOY_4BUTTONS    4-button joysticks (fire 3 and 4 are other joystick's
//                 fire buttons)
// JOY_6BUTTONS    6-button joystick (fire 3 & 4 as above, fire 5 and 6
//                 connected to left and up directions of joystick #2)
// JOY_8BUTTONS    8-button joystick (fire 1..6 as above, fire 7 and 8
//                 connected to right and down directions of joystick #2)
//
// Set skipjoy to:
// JOY_NONE    if all joysticks connected should be detected and calibrated;
// JOY_SECOND  if only first joystick is used and thus should be calibrated.
//
// Set calibfile to the name of a file to be used for saving/reloading
// calibration (NULL to force re-calibration at each run).

j = InstallJoystick(mode, skipjoy, calibfile);

• use the value j to determine number of joysticks connected:

j & JOY_FIRST    first joystick is present
j & JOY_SECOND   second joystick is present
j & JOY_BOTH     both joysticks present (or one 6/8-button joystick)

• when you want to read the joystick(s), use:

unsigned int fj, sj;

ReadJoystick(&fj, &sj);

• then, you can determine if a direction is activated by:

fj & JOY_xx // direction is active?

where "xx" can be: UP, DN (down), LT (left), RT (right)

• you can test the fire buttons in a similar way:

fj & JOY_AF // 1st button is pressed?
fj & JOY_BF // 2nd button is pressed?
fj & JOY_CF // 3rd button (only when mode >= JOY_4BUTTONS)
fj & JOY_DF // 4th button (only when mode >= JOY_4BUTTONS)
fj & JOY_EF // 5th button (only joystick 1, when mode >= JOY_6BUTTONS)
fj & JOY_FF // 6th button (only joystick 1, when mode >= JOY_6BUTTONS)
fj & JOY_GF // 7th button (only joystick 1, when mode = JOY_8BUTTONS)
fj & JOY_HF // 8th button (only joystick 1, when mode = JOY_8BUTTONS)

Of course, replace "fj" above with "sj" to test second joystick.

• if you want to poll joystick at regular intervals, you can chain the system timer (int 8).

The calibration configuration is saved and reloaded automatically when you specify 'calibfile' in InstallJoystick; user is not warned, however, when configuration cannot be saved successfully. Joystick mode is saved in the configuration; if specified mode or the mode saved is JOY_6BUTTONS/JOY_8BUTTONS and the two modes don't match, the routine re-calibrate the joystick; the same happens if a new joystick is found, or if incorrect calibration is detected (this is tricky: it is possible that different joysticks have similar but not identical calibration, that is not detected by this routine).
If you want to re-calibrate the joystick(s), just delete the configuration file.
If your program needs more than two fire buttons, be sure to leave an option for those with 2-button joysticks, so that they can use the keyboard for the missing buttons.
If your program uses just one joystick, use JOY_SECOND as the value for parameter skipjoy.
The routine automatically de-activates joysticks as soon as they are desconnected; you must call InstallJoystick again after you have reconnected the device.

Download

Download Joystick Library for Dos (version 1.2)

Back to top