|
Typically you won't use these data members if you're using enhanced mode; they're provided primarily for backward compatibility.
|
| The Device Kit Table of Contents | The Device Kit Index |
Derived from: none
Declared in: be/device/Joystick.h
Library: libdevice.so
Allocation: Constructor only
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.
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.
|
|
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.
|
Closes the port, if it was not closed already.
ButtonValues() see CountButtons()
|
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);
|
RETURN CODES
B_OK. The name was returned successfully.
|
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 */
}
|
|
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.
|
RETURN CODES
B_OK. The name was returned successfully.
|
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:
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);
|
RETURN CODES
B_OK. The name was returned successfully.
|
Returns the number of joysticks connected to the opened game port.
|
|
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.
|
RETURN CODES
B_OK. The name was returned successfully.
GetButtonNameAt() see GetAxisNameAt()
|
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.
|
RETURN CODES
B_OK. The name was returned successfully.
GetHatNameAt() see GetAxisNameAt()
|
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() 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.
|
RETURN CODES
B_OK. The name was returned successfully.
|
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):
|
By attaching a Y cable to a machine port, you can make it support two joysticks. Cables, therefore, add two additional ports:
|
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.
|
To be able to obtain joystick data, a BJoystick object must have a port open.
|
Specifies the maximum latency to allow when accessing the joystick. Returns B_OK if the change is applied successfully, otherwise returns an error code.
|
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 |
Copyright © 2000 Be, Inc. All rights reserved..
