The Device Kit: BJoystick

The Device Kit Table of Contents | The Device Kit Index

# BJoystick

Derived from: none

Declared in: be/device/Joystick.h

Library: libdevice.so

Allocation: Constructor only

###### Summary

A BJoystick object provides an interface to a joystick (or other game controller) connected to the computer. The BeOS supports joysticks on the BeBox and Intel platforms.

The BeBox supports up to four analog joysticks, each of which can have up to two axes and two buttons; digital joysticks aren't supported by the built-in game ports. You can install a card that provides additional game ports (such as the Sound Blaster AWE64), and use digital joysticks on those ports.

BeOS for Intel systems supports joysticks through game ports on cards, as well as some built-in game ports.

Unlike the event and message-driven interface to the mouse and keyboard, the interface to a joystick is strictly demand-driven. An application must repeatedly poll the state of the joystick by calling the BJoystick object's `Update()` function. `Update()` queries the port and updates the object's data members to reflect the current state of the joystick.

There are two modes available. Standard mode supports only two axes per joystick, and two buttons per joystick. This mode has been available since the early days of the BeOS. You read the joystick in standard mode by looking at the BJoystick member variables `vertical` and `horizontal` to determine the joystick's axis values, and `button1` and `button2` to determine the state of the buttons.

Enhanced mode supports up to 32 buttons per joystick, and an indefinite number of axes and hats (thumb controls, usually located at the top of a stick). It also supports multiple joysticks chained to a single game port. Instead of reading variables to determine the state of the joystick, there are several functions provided to let you do this.

In addition, enhanced mode provides a mechanism for determining what joysticks are available and what types of (and how many) controls are available on the joysticks. There's also a preference application (cleverly named "Joysticks") that lets the user select and configure joysticks connected to their computer.

## Data Members

bigtime_t `timestamp` The time of the most recent update, as measured in microseconds from the beginning of 1970.

int16 `horizontal` The horizontal position of the joystick at the time of the last update. Values increase as the joystick moves from left to right.

int16 `vertical` The vertical position of the joystick at the time of the last update. Values decrease as the joystick moves forward and increase as it's pulled back.

bool `button1` `false` if the first button was pressed at the time of the last update, and `true` if not.

bool `button2` `false` if the second button was pressed at the time of the last update, and `true` if not.

The `horizontal` and `vertical` data members record values read directly from the ports, values that simply digitize the analog output of the joysticks. This class makes no effort to translate the values to a standard scale or range. Values can range from 0 through 4,095, but joysticks typically don't use the full range and some don't register all values within the range that is used. The scale is not linear—identical increments in different parts of the range can reflect differing amounts of horizontal and vertical movement. The exact variance from linearity and the extent of the usable range are partly characteristics of the individual joystick and partly functions of the computer's hardware.

|  | Typically you won't use these data members if you're using enhanced mode; they're provided primarily for backward compatibility.

## Constructor and Destructor

### BJoystick()

`BJoystick(`void`)`

Initializes the BJoystick object so that all values are set to 0. Before using the object, you must call `Open()` to open a particular joystick port. For the object to register any meaningful values, you must call `Update()` to query the open port.

See also: `Open()`, `Update()`

### ~BJoystick()

virtual `~BJoystick(`void`)`

Closes the port, if it was not closed already.

## Member Functions

### ButtonValues() see CountButtons()

### Close() see Open()

### CountAxes(), GetAxisValues()

int32 `CountAxes(`void`)`
status_t `GetAxisValues(`int16 *outValues, int32 forStick = 0`)`

CountAxes() returns the number of axes on the opened game port.

`GetAxisValues()` fills the array pointed to by outValues with the values of all the axes connected to the specified joystick. The forStick parameter lets you choose which joystick on the game port to read the values from (the default is to read from the first stick on the port).

The returned values range from -32,768 to 32,767.

The array outValues must be large enough to contain the values for all the axes. You can ensure that this is the case by using the following code:

       int16 *axes;

       axes = (int16 *) malloc(sizeof(int16) * stick->CountAxes());
       stick->GetAxisValues(axes);

|  | These functions can only be used in enhanced mode.

RETURN CODES

`B_OK`. The name was returned successfully.

`B_BAD_VALUE`. The joystick specified by forStick doesn't exist.

### CountButtons(), GetButtonValues()

int32 `CountButtons(`void`)`
uint32 `ButtonValues(`void`)`

CountButtons() returns the number of buttons on the opened game port.

`ButtonValues()` returns a 32-bit number in which each bit represents the state of one button. The forStick parameter lets you choose which joystick on the game port to read the values from (the default is to read from the first stick on the port). You can deterimine if a particular button is down by using the following code:

       uint32 buttonValues = stick->ButtonValues();

       if (buttonValues & (1 << whichButton)) {
          /* button number whichButton is pressed */
       }

|  | These functions can only be used in enhanced mode.

### CountDevices(), GetDeviceName()

int32 `CountDevices(`void`)`
status_t `GetDeviceName(`int32 index, char *outName, size_t bufSize = B_OS_NAME_LENGTH`)`

CountDevices() returns the number of game ports on the computer.

`GetDeviceName()` returns the name of the device specified by the given index. The buffer pointed to by outName is filled with the device name; bufSize indicates the size of the buffer.

The names returned by `GetDeviceName()` can be passed into the `Open()` function to open a device.

|  | The BJoystick doesn't need to have an open device before you use these functions; in fact, your application will typically use these to provide user interface allowing the user to choose the joystick device they'd like to use.

RETURN CODES

`B_OK`. The name was returned successfully.

B_BAD_INDEX. The specified index is invalid.

`B_NAME_TOO_LONG`. The device name is too long for the buffer.

### CountHats(), GetHatValues()

int32 `CountHats(`void`)`
status_t `GetHatValues(`int8 *outHats, int32 forStick = 0`)`

CountHats() returns the number of hats on the opened game port.

`GetHatValues()` fills the array pointed to by outHats with the values of all the hats connected to the specified joystick. The forStick parameter lets you choose which joystick on the game port to read the values from (the default is to read from the first stick on the port).

The return value means the following:

- 0: Centered

- 1: Up

- 2: Up and right

- 3: Right

- 4: Down and right

- 5: Down

- 6: Down and left

- 7: Left

- 8: Up and left

The array outHats must be large enough to contain the values for all the hats. You can ensure that this is the case by using the following code:

       int8 *hats;

       hats = (int8 *) malloc(sizeof(int8) * stick->CountAxes());
       stick->GetHatValues(hats);

|  | These functions can only be used in enhanced mode.

RETURN CODES

`B_OK`. The name was returned successfully.

`B_BAD_VALUE`. The joystick specified by forStick doesn't exist.

### CountSticks()

int32 `CountSticks(`void`)`

Returns the number of joysticks connected to the opened game port.

|  | This function can only be used in enhanced mode.

### GetAxisNameAt(), GetHatNameAt(), GetButtonNameAt()

status_t `GetAxisNameAt(`int32 index, BString *outName`)`
status_t `GetHatNameAt(`int32 index, BString *outName`)`
status_t `GetButtonNameAt(`int32 index, BString *outName`)`

Returns the name of the control specified by the given index. The BString object pointed to by outName is set to the control's name.

`GetAxisNameAt()` returns the specified axis' name, `GetHatNameAt()` returns the specified hat's name, and `GetButtonNameAt()` returns the specified button's name.

|  | These functions can only be used in enhanced mode.

RETURN CODES

`B_OK`. The name was returned successfully.

`B_BAD_INDEX`. The specified index is invalid.

### GetAxisValues() see CountAxes()

### GetButtonNameAt() see GetAxisNameAt()

### GetControllerModule(), GetControllerName()

status_t `GetControllerModule(` BString *outName`)`
status_t `GetControllerName(` BString *outName`)`

GetControllerModule() returns the name of the joystick module that represents the opened joystick device. If the device isn't in enhanced mode, this always returns "Legacy".

`GetControllerName()` returns the name of the joystick that's been configured for the opened device. This is the same string that appears in the Joysticks preference application. The returned string is always "2-axis" if the device isn't in enhanced mode.

|  | These functions can only be used in enhanced mode.

RETURN CODES

`B_OK`. The name was returned successfully.

`B_BAD_INDEX`. The specified index is invalid.

### GetDeviceName() see CountDevices()

### GetHatNameAt() see GetAxisNameAt()

### GetHatValues() see CountHats()

### EnableCalibration() see IsCalibrationEnabled()

### EnterEnhancedMode()

bool `EnterEnhancedMode(`const entry_ref *ref = NULL`)`

Switches the device into enhanced mode. If ref isn't `NULL`, it's treated as a reference to a joystick description file (such as those in /boot/beos/etc/joysticks). If ref is `NULL`, the currently-configured joystick settings (as per the Joysticks preference application) are used.

If enhanced mode is entered successfully (or the device is already in enhanced mode), `true` is returned. Otherwise, `EnterEnhancedMode()` returns `false`.

### IsCalibrationEnabled(), EnableCalibration()

bool `IsCalibrationEnabled(`void`)`
status_t `EnableCalibration(`bool calibrates = true`)`

IsCalibrationEnabled() returns `true` if axis values returned by the joystick will be calibrated automatically into the range -32,768 to 32,767, or `false` if the raw values will be returned.

`EnableCalibration()` enables or disables automatic calibration for the joystick's axes. Specify a value of `true` for calibrates to enable calibration; otherwise, specify `false`.

The names returned by `GetDeviceName()` can be passed into the `Open()` function to open a device.

|  | The Joysticks preference application lets the user calibrate the joystick. Calibration is enabled by default. These functions may only be used in enhanced mode.

RETURN CODES

`B_OK`. The name was returned successfully.

B_NO_INIT. The device isn't in enhanced mode.

### Open(), Close()

status_t `Open(`const char *devName`)`
status_t `Open(`const char *devName, bool enterEnhanced`)`
void `Close(`void`)`

These functions open the joystick port specified by devName and close it again.

On the BeBox, there are two ports on the back of the computer, and they have names that correspond to their labels on the machine (and in The BeOS User's Guide diagram):

|  | "joystick1" (on the top) "joystick2" (on the bottom)

By attaching a Y cable to a machine port, you can make it support two joysticks. Cables, therefore, add two additional ports:

|  | "joystick3" (on the top) "joystick4" (on the bottom)

The cable maps the bottom row of pins on a machine port to the top row on a cable port. Therefore, the first two names listed above correspond to the top row of pins on a machine port; the last two names correspond to the bottom row of pins.

On other systems, the devName should be the name of a game port device. The easiest way to determine valid device names is by using the `CountDevices()` and `GetDeviceName()` functions.

If it's able to open the port, `Open()` returns a positive integer. If unable or if the name isn't valid, it returns `B_ERROR`. If the name port is already open, `Open()` tries to close it first, then open it again.

By default, `Open()` opens the device in enhanced mode. If you want to use the old, unenhanced mode, you can use the second form of `Open()` to specify whether or not you want to use enhanced mode; set enterEnhanced to `true` to use enhanced mode; specify `false` if you don't want enhanced mode.

|  | Even in enhanced mode, the classic BJoystick data members are valid (for compatibility with older applications). However, they only give you access to the first two axes and buttons of the joystick.

To be able to obtain joystick data, a BJoystick object must have a port open.

### SetMaxLatency()

status_t `SetMaxLatency(`bigtime_t maxLatency`)`

Specifies the maximum latency to allow when accessing the joystick. Returns `B_OK` if the change is applied successfully, otherwise returns an error code.

### Update()

status_t `Update(`void`)`

Updates the data members of the object so that they reflect the current state of the joystick. An application would typically call `Update()` periodically to poll the condition of the device, then read the values of the data members, or—if in enhanced mode—call the various functions for obtaining joystick state information.

This function returns `B_ERROR` if the BJoystick object doesn't have a port open, and `B_OK` if it does.

The Device Kit Table of Contents | The Device Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 4.5.

Copyright © 1999 Be, Inc. All rights reserved.

Text last modified June 6, 1999.