mirror of
https://github.com/FEX-Emu/linux.git
synced 2024-12-28 12:25:31 +00:00
Input: convert gamepad specification into ReST format
This file require minimum adjustments to be a valid ReST file. Do it, in order to be able to parse it with Sphinx. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
This commit is contained in:
parent
3057d50980
commit
5c631b7130
@ -1,15 +1,19 @@
|
||||
Linux Gamepad API
|
||||
----------------------------------------------------------------------------
|
||||
-----------------
|
||||
Linux Gamepad API
|
||||
-----------------
|
||||
|
||||
1. Intro
|
||||
~~~~~~~~
|
||||
:Author: 2013 by David Herrmann <dh.herrmann@gmail.com>
|
||||
|
||||
|
||||
Intro
|
||||
~~~~~
|
||||
Linux provides many different input drivers for gamepad hardware. To avoid
|
||||
having user-space deal with different button-mappings for each gamepad, this
|
||||
document defines how gamepads are supposed to report their data.
|
||||
|
||||
2. Geometry
|
||||
~~~~~~~~~~~
|
||||
As "gamepad" we define devices which roughly look like this:
|
||||
Geometry
|
||||
~~~~~~~~
|
||||
As "gamepad" we define devices which roughly look like this::
|
||||
|
||||
____________________________ __
|
||||
/ [__ZL__] [__ZR__] \ |
|
||||
@ -35,6 +39,7 @@ As "gamepad" we define devices which roughly look like this:
|
||||
Menu Pad
|
||||
|
||||
Most gamepads have the following features:
|
||||
|
||||
- Action-Pad
|
||||
4 buttons in diamonds-shape (on the right side). The buttons are
|
||||
differently labeled on most devices so we define them as NORTH,
|
||||
@ -58,8 +63,9 @@ Most gamepads have the following features:
|
||||
Many devices provide force-feedback features. But are mostly just
|
||||
simple rumble motors.
|
||||
|
||||
3. Detection
|
||||
~~~~~~~~~~~~
|
||||
Detection
|
||||
~~~~~~~~~
|
||||
|
||||
All gamepads that follow the protocol described here map BTN_GAMEPAD. This is
|
||||
an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such.
|
||||
However, not all gamepads provide all features, so you need to test for all
|
||||
@ -85,75 +91,101 @@ devices that report a small subset of the events.
|
||||
No other devices, that do not look/feel like a gamepad, shall report these
|
||||
events.
|
||||
|
||||
4. Events
|
||||
~~~~~~~~~
|
||||
Events
|
||||
~~~~~~
|
||||
|
||||
Gamepads report the following events:
|
||||
|
||||
Action-Pad:
|
||||
- Action-Pad:
|
||||
|
||||
Every gamepad device has at least 2 action buttons. This means, that every
|
||||
device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless
|
||||
of the labels on the buttons, the codes are sent according to the
|
||||
physical position of the buttons.
|
||||
|
||||
Please note that 2- and 3-button pads are fairly rare and old. You might
|
||||
want to filter gamepads that do not report all four.
|
||||
2-Button Pad:
|
||||
|
||||
- 2-Button Pad:
|
||||
|
||||
If only 2 action-buttons are present, they are reported as BTN_SOUTH and
|
||||
BTN_EAST. For vertical layouts, the upper button is BTN_EAST. For
|
||||
horizontal layouts, the button more on the right is BTN_EAST.
|
||||
3-Button Pad:
|
||||
|
||||
- 3-Button Pad:
|
||||
|
||||
If only 3 action-buttons are present, they are reported as (from left
|
||||
to right): BTN_WEST, BTN_SOUTH, BTN_EAST
|
||||
If the buttons are aligned perfectly vertically, they are reported as
|
||||
(from top down): BTN_WEST, BTN_SOUTH, BTN_EAST
|
||||
4-Button Pad:
|
||||
|
||||
- 4-Button Pad:
|
||||
|
||||
If all 4 action-buttons are present, they can be aligned in two
|
||||
different formations. If diamond-shaped, they are reported as BTN_NORTH,
|
||||
BTN_WEST, BTN_SOUTH, BTN_EAST according to their physical location.
|
||||
If rectangular-shaped, the upper-left button is BTN_NORTH, lower-left
|
||||
is BTN_WEST, lower-right is BTN_SOUTH and upper-right is BTN_EAST.
|
||||
|
||||
D-Pad:
|
||||
- D-Pad:
|
||||
|
||||
Every gamepad provides a D-Pad with four directions: Up, Down, Left, Right
|
||||
Some of these are available as digital buttons, some as analog buttons. Some
|
||||
may even report both. The kernel does not convert between these so
|
||||
applications should support both and choose what is more appropriate if
|
||||
both are reported.
|
||||
Digital buttons are reported as:
|
||||
BTN_DPAD_*
|
||||
Analog buttons are reported as:
|
||||
ABS_HAT0X and ABS_HAT0Y
|
||||
(for ABS values negative is left/up, positive is right/down)
|
||||
|
||||
Analog-Sticks:
|
||||
- Digital buttons are reported as:
|
||||
|
||||
BTN_DPAD_*
|
||||
|
||||
- Analog buttons are reported as:
|
||||
|
||||
ABS_HAT0X and ABS_HAT0Y
|
||||
|
||||
(for ABS values negative is left/up, positive is right/down)
|
||||
|
||||
- Analog-Sticks:
|
||||
|
||||
The left analog-stick is reported as ABS_X, ABS_Y. The right analog stick is
|
||||
reported as ABS_RX, ABS_RY. Zero, one or two sticks may be present.
|
||||
If analog-sticks provide digital buttons, they are mapped accordingly as
|
||||
BTN_THUMBL (first/left) and BTN_THUMBR (second/right).
|
||||
(for ABS values negative is left/up, positive is right/down)
|
||||
|
||||
Triggers:
|
||||
(for ABS values negative is left/up, positive is right/down)
|
||||
|
||||
- Triggers:
|
||||
|
||||
Trigger buttons can be available as digital or analog buttons or both. User-
|
||||
space must correctly deal with any situation and choose the most appropriate
|
||||
mode.
|
||||
|
||||
Upper trigger buttons are reported as BTN_TR or ABS_HAT1X (right) and BTN_TL
|
||||
or ABS_HAT1Y (left). Lower trigger buttons are reported as BTN_TR2 or
|
||||
ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2Y (left/ZL).
|
||||
|
||||
If only one trigger-button combination is present (upper+lower), they are
|
||||
reported as "right" triggers (BTN_TR/ABS_HAT1X).
|
||||
(ABS trigger values start at 0, pressure is reported as positive values)
|
||||
|
||||
Menu-Pad:
|
||||
(ABS trigger values start at 0, pressure is reported as positive values)
|
||||
|
||||
- Menu-Pad:
|
||||
|
||||
Menu buttons are always digital and are mapped according to their location
|
||||
instead of their labels. That is:
|
||||
1-button Pad: Mapped as BTN_START
|
||||
2-button Pad: Left button mapped as BTN_SELECT, right button mapped as
|
||||
BTN_START
|
||||
|
||||
- 1-button Pad:
|
||||
|
||||
Mapped as BTN_START
|
||||
|
||||
- 2-button Pad:
|
||||
|
||||
Left button mapped as BTN_SELECT, right button mapped as BTN_START
|
||||
|
||||
Many pads also have a third button which is branded or has a special symbol
|
||||
and meaning. Such buttons are mapped as BTN_MODE. Examples are the Nintendo
|
||||
"HOME" button, the XBox "X"-button or Sony "PS" button.
|
||||
|
||||
Rumble:
|
||||
Rumble is advertised as FF_RUMBLE.
|
||||
- Rumble:
|
||||
|
||||
----------------------------------------------------------------------------
|
||||
Written 2013 by David Herrmann <dh.herrmann@gmail.com>
|
||||
Rumble is advertised as FF_RUMBLE.
|
||||
|
Loading…
Reference in New Issue
Block a user