The Be Book The Device Kit The Device Kit Index

BJoystick

Derived from: none
Declared in:  be/device/Joystick.h
Library: libdevice.so
Allocation: Constructor only
Summary:  more...


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

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

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:

Value Meaning
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

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

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

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

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. 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 Be Book The Device Kit The Device Kit Index

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

Copyright © 2000 Be, Inc. All rights reserved..