ControlsJoystick Class
This class handles joystick input. Unlike XBox 360 controllers, generic joysticks cannot be hot-plugged. Therefore, a joystick should be already plugged before you create an instance of this class.
The ControlsJoystick class provides access to the following controller input:
- Axes detect movement along X and Y axes (if a joystick is two-axis, which is the most typical case) and along Z axis (if it is three-axis one). Two-axis joysticks are configured in such a way that left-to-right movement of the stick is mapped to the movement along the X axis, while movement from backward to forward (down-up) indicates movement along the Y axis. In case of 3D joystick, twisting the stick to the left (counter-clockwise) or to the right (clockwise) corresponds to movement along the Z axis.
Axes are quired for their states via getAxis(). To provide smooth interpolation between frames and avoid jerks, axis values can be filtered via setFilter(). - Buttons correspond to the each button on the controller and can be either pressed or unpressed. Just in case with mouse/keyboard controls, they can be mapped to the specific controls states to bind input events and programmed actions.
You can either bind buttons in the code via setStateButton() or let the user assign the button for a control state via getStateEvent(). - POV (Point-Of-View) hat switches indicate the direction of view and support a number of positions such as left, right, up and down (similar to a D-pad).
A joystick should update the physical state of all its input controls (i.e. check whether the user has pressed the button, for example) each frame using updateEvents().
ControlsJoystick Class
Members
ControlsJoystick ()
ControlsJoystick (int num)
Constructor. Creates a new joystick.Arguments
- int num - Joystick number.
const char * getPovName (int pov)
Returns the name of a given POV hat switch.Arguments
- int pov - POV hat number.
Return value
POV hat name.int getButton (int button)
Returns a button state (pressed or not pressed).Arguments
- int button - Button number.
Return value
1 if the button is pressed; otherwise, 0.const char * getStateName (int state)
Returns the name of a given state, that was assigned to one of controls.Arguments
- int state - State (one of the CONTROLS_STATE_* variables).
Return value
State name.int restoreState (const Ptr<Stream> & stream)
Arguments
- const Ptr<Stream> & stream
Return value
int getNumButtons ()
Returns the number of buttons supported by the joystick.Return value
The number of buttons.int saveState (const Ptr<Stream> & stream)
Arguments
- const Ptr<Stream> & stream
Return value
int getNumber ()
Returns the joystick number.Return value
Joystick number.int getNumPovs ()
Returns the number of POV hat switches supported by the joystick.Return value
The number of POV hats.int getStateButton (int state)
Returns a game pad button that switches a given state on and off.Arguments
- int state - State (one of the CONTROLS_STATE_* variables).
Return value
Button that switches the given state.const char * getButtonName (int button)
Returns the name of a given button.Arguments
- int button - Button number.
Return value
Button name.int isAvailable ()
Checks if the joystick is available.Return value
1 if the joystick is available; otherwise, 0.float getFilter ()
Returns a filter value used to correct the current state of the joystick axis relative to the previous one:- Filter value of 0 means there is no interpolation and the current value is not corrected.
- Filter value of 1 means the previous state is used instead of the current one.
Return value
Filter value for interpolation between axis states.float getAxis (int axis)
Returns a state value of a given axis. It includes position of the joystick along the following axes: X, Y (two-axis joystick) and Z (three-axis joystick). When a joystick is in the center position, X and Y axes values are zero. Negative values indicate left or down; positive values indicate right or up.Arguments
- int axis - Axis number.
Return value
Value in range [-1; 1].int isStateEvent ()
Returns a value indicating if a joystick button is successfully assigned to a state.Return value
1 if a button is already assigned; otherwise, 0.int clearButton (int button)
Returns a button state and clears it to 0 (not pressed).Arguments
- int button - Button number.
Return value
1 if the button is pressed, and this function was not called previously in the current frame; otherwise, 0.void getStateEvent (int state)
Lets the user assign a joystick button to a given state.Arguments
- int state - State (one of the CONTROLS_STATE_* variables), to which a button is going to be assigned.
const char * getName ()
Returns the name of the joystick.Return value
Joystick name.int updateEvents ()
Scans the joystick controls (synchronizes joystick button states with the controller itself). Should be called each frame.Notice
On Windows, in case a joystick is not connected, this function can substantially increase per-frame update time. (This happens due to calling IDirectInput8::EnumDevices() method.)
Return value
0 if a joystick is not found or updateEvents() already has been called for the frame; otherwise 1.void setFilter (float filter)
Sets a filter value used to correct the current state of the joystick axis relative to the previous one.Arguments
- float filter - Filter value for interpolation between axis states. The provided value is clamped to a range [0;1].
- Filter value of 0 means there is no interpolation and the current value is not corrected.
- Filter value of 1 means the previous state is used instead of the current one.
int getPov (int pov)
Returns a POV hat switch state. POV hats support a the following positions: left, right, up and down.Arguments
- int pov - POV pad number.
Return value
One of the following:- -1 — not pressed
- 0 — pressed "up"
- 4500 — pressed "up" and "right"
- 9000 — pressed "right"
- 13500 — pressed "down" and "right"
- 18000 — pressed "down"
- 22500 — pressed "down" and "left"
- 27000 — pressed "left"
- 31500 — pressed "up" and "left"
void setStateButton (int state, int button)
Sets a joystick button that switches a given state on or off.Arguments
- int state - State (one of the CONTROLS_STATE_* variables).
- int button - Button number.
const char * getAxisName (int axis)
Returns the name of a given axis.Arguments
- int axis - Axis number.
Return value
Axis name.int getNumAxes ()
Returns the number of axes supported by the joystick.Return value
The number of axes.Last update: 2017-07-03
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)