The BeOS provides two ways to describe a joystick to the system:  The simple way is to use the Joysticks preference app, which is fine if you're a simple user, but it doesn't go far enough for many gamers.  If you want more control over the definition and calibration of your joystick, you can use the joystick text description file format that Be supplies.  A number of joystick descriptions files are provided in the /boot/beos/etc/joystick directory.  The following sections tell you how to use these files, and explains their format.

Copying a Joystick Description

Open the /boot/beos/etc/joystick directory.  If you see a file that names your joystick, you should copy the file into your into your /boot/home/config/settings/joystick/ directory so the system will see it when it's setting up the joystick port.  However, you can't simply copy the file; it has to be properly named and cataloged:

1. Create a subdirectory of /boot/home/config/settings/joystick/ that names the port that you're using. 

   $ mkdir -p ~/config/settings/joystick/gameport

2. Now copy the file and rename it to the port number.  For example:

   $ cd /boot/beos/etc/joystick $ cp Logitech_CyberMan_2 ~/config/settings/joystick/gameport/201

   You can also create a symbolic link to the original, rather than copy the file.  The rules for naming the link are the same as for copying the file.

The Joystick Text Description Format

Joystick descriptions are plain text files; except for the "module" line, which you mustn't touch, all fields in the file can be tweaked.  The first part of the file is the basic description:

module = moduleName

This is a name identifier for the system code that supports this joystick.  DO NOT CHANGE THE MODULE NAME.  Bad things could happen if you do. 

gadget = gadgetName

This is the commercial name of the joystick.

num_axes = n

The number of axes your joystick can pivot around.

num_hats = n

The number of "hats," or wand-topping buttons your joystick has.

num_buttons = n

The number of regular buttons your joystick has.

axis i = name

For each axis, you can provide a name.  Note that i is zero-based.

hat i = name

Same for the hats.

button i = name

And the buttons

Next comes the "advanced" section.  These lines let you fine-tune the joystick:

calibrate i = low, low-dead, high-dead, high, low-scale, high-scale

Calibrates the input for axis i (zero-based).  All values must be integers.  The arguments are:

low	The minimum value returned from your joystick (the perfect joystick gives you -32767).
low-dead, high-dead	The beginning and end of the "dead zone" (which is considered centered).
high	The maximum value returned by your joystick (perfect joysticks return 32767).
low-scale, high-scale	The factors used to scale values below and above the dead zone.  The factor you pass in is further scaled by 128.

For example, if your joystick returns values from -18000 to 12000, with the center being around -2500, the left-right axis calibrate line would look like this:



calibrate 0 = -18000, -3500, -1500, 12000, 289, 310



This line would give you the maximum negative response at -18000, the maximum positive response at +12000, and have a "dead zone" from -3200 to -1500.  Note that you can reverse an axis by making the two last numbers negative.

autofire i = bool

This is a toggle that sets the autofire characteristc for button i (zero-based).  If bool is 1, the button will strobe, returning 0 and 1 alternately while the button is down.  This mode is preferrable to the built-in autofire on some joysticks, since it knows when applications are asking for the value and returns them perfectly alternating, whereas a hardware auto-fire might not match the rate at which your program reads the joystick.

latch i = bool

Sets the latch characteristic for button i (zero-based).  If bool is 1, the button becomes an on/off switch.  The first time you press the button, it turns on and remains on until after you press it again.  This is sometimes very useful, especially when combined with the "run" feature of some games -- or with autofire in unlimited-ammo situations!






---



BeOS Release 4

---



Copyright © 1998 Be, Inc.  All rights reserved.