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@xxxxxxxxxxxxxxxx>
---
Documentation/input/gamepad.txt | 43 +++++++++++++++++++++++++++++------------
1 file changed, 31 insertions(+), 12 deletions(-)
diff --git a/Documentation/input/gamepad.txt b/Documentation/input/gamepad.txt
index 3f6d8a5e9cdc..8bc7fdea3705 100644
--- a/Documentation/input/gamepad.txt
+++ b/Documentation/input/gamepad.txt
@@ -1,5 +1,9 @@
- Linux Gamepad API
-----------------------------------------------------------------------------
+-----------------
+Linux Gamepad API
+-----------------
+
+:Author: 2013 by David Herrmann <dh.herrmann@xxxxxxxxx>
+
1. Intro
~~~~~~~~
@@ -9,7 +13,7 @@ document defines how gamepads are supposed to report their data.
2. Geometry
~~~~~~~~~~~
-As "gamepad" we define devices which roughly look like this:
+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,
@@ -60,6 +65,7 @@ Most gamepads have the following features:
3. 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
@@ -87,6 +93,7 @@ events.
4. Events
~~~~~~~~~
+
Gamepads report the following events:
Action-Pad:
@@ -94,8 +101,10 @@ Action-Pad:
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:
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
@@ -118,42 +127,52 @@ D-Pad:
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)
+
+ (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)
+
+ (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)
+
+ (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.
-
-----------------------------------------------------------------------------
- Written 2013 by David Herrmann <dh.herrmann@xxxxxxxxx>
--
2.9.3
--
To unsubscribe from this list: send the line "unsubscribe linux-input" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
