aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMattias Andrée <maandree@kth.se>2022-07-27 01:49:10 +0200
committerMattias Andrée <maandree@kth.se>2022-07-27 02:00:07 +0200
commit237d742ccac8c5b0690b09f3fb05ed9820bc8120 (patch)
treef385bd273c3c71cf1ff532eaf22f6f225416c7c1
parentCorrect info about Sixaxis and add the Linux standard and a 6-button extension of it (diff)
downloadlibgamepad-237d742ccac8c5b0690b09f3fb05ed9820bc8120.tar.gz
libgamepad-237d742ccac8c5b0690b09f3fb05ed9820bc8120.tar.bz2
libgamepad-237d742ccac8c5b0690b09f3fb05ed9820bc8120.tar.xz
Improve documentation and add LIBGAMEPAD_CONTROLLER_LINUX_4_12_RECTIFIED_3BTN
Signed-off-by: Mattias Andrée <maandree@kth.se>
-rw-r--r--TODO1
-rw-r--r--libgamepad.h127
2 files changed, 107 insertions, 21 deletions
diff --git a/TODO b/TODO
index 8cd3c2a..f58da4e 100644
--- a/TODO
+++ b/TODO
@@ -7,3 +7,4 @@ Add support for creating instance from a file descriptor
Add man pages
Add readme file
Add force feedback tests
+Generic ABS and REL names shall be in "0x%02X" format
diff --git a/libgamepad.h b/libgamepad.h
index 3e884cc..b0efec4 100644
--- a/libgamepad.h
+++ b/libgamepad.h
@@ -1066,52 +1066,110 @@ enum libgamepad_game_controller {
*
* Version documented since Linux 4.12 in Documentation/input/gamepad
*
- * There are multiple substandard, this one includes all features
- *
* Layout:
- * Analogue BTN_DPAD_{LEFT,RIGHT,UP,DOWN}/ABS_HAT0X/ABS_HAT0Y D-pad at upper left thumb position
+ * Analogue ABS_HAT0X/ABS_HAT0Y/BTN_DPAD_* D-pad at upper left thumb position
* Clickable analogue BTN_THUMBL/ABS_X/ABS_Y stick at lower left thumb position
* Clickable analogue BTN_THUMBR/ABS_RX/ABS_RY stick at lower right thumb position
* 4 digital buttons at upper right thumb position:
- * - North = BTN_NORTH (= BTN_X)
- * - West = BTN_WEST (= BTN_Y)
- * - South = BTN_SOUTH (= BTN_A)
- * - East = BTN_EAST (= BTN_B)
+ * - North or upper left = BTN_NORTH (= BTN_X)
+ * - West or lower left = BTN_WEST (= BTN_Y)
+ * - South or lower right = BTN_SOUTH (= BTN_A)
+ * - East or upper right = BTN_EAST (= BTN_B)
* Analogue button BTN_TL/ABS_HAT1Y at upper left index finger position
* Analogue button BTN_TR/ABS_HAT1X at upper right index finger position
- * Analogue button BTN_TL2/ABS_HAT1Y at lower left index finger position
- * Analogue button BTN_TR2/ABS_HAT1X at lower right index finger position
+ * Analogue button BTN_TL2/ABS_HAT2Y at lower left index finger position
+ * Analogue button BTN_TR2/ABS_HAT2X at lower right index finger position
* 3 digital button north of the centre
* - West = BTN_SELECT
* - East = BTN_START
* - South = BTN_MODE
+ *
+ * Applications shall be aware that kernel drivers, even written for
+ * specific controllers, do not always use the correct codes. For example
+ * the Sony drivers currently (Linux 5.18) use ABS_Z and ABS_RZ instead
+ * of ABS_HAT2Y and ABS_HAT2X respectively.
+ *
+ * There are multiple substandard, this one includes all features,
+ * however notably, there cannot be a BTN_SELECT without a BTN_START,
+ * and all gamepads must have at least 2 action buttons: BTN_SOUTH
+ * and BTN_EAST, and if there is a third action button, it is mapped
+ * to BTN_WEST. The action buttons, in the case that there is either
+ * 2 or 3 of them, ordered from left to right: BTN_WEST (if present),
+ * BTN_SOUTH, BTN_EAST, with the caveat that if they buttons are
+ * perfectly vertically aligned the order, is from bottom up, BTN_SOUTH,
+ * BTN_EAST if there are 2 action buttons but reversed if there are 3
+ * action buttons: (from bottom up) BTN_EAST, BTN_SOUTH, BTN_WEST
+ * (`LIBGAMEPAD_CONTROLLER_LINUX_4_12_RECTIFIED_3BTN` is added to deal
+ * with this problem).
*/
LIBGAMEPAD_CONTROLLER_LINUX_4_12,
/**
- * 6-button extension of `LIBGAMEPAD_CONTROLLER_LINUX_4_12`
+ * libgamepad defined amended version of the 3-button subversion
+ * of `LIBGAMEPAD_CONTROLLER_LINUX_4_12`
*
* There are multiple substandard, this one includes all features
*
+ * The amended version flips the order of BTN_WEST, BTN_SOUTH, BTN_EAST
+ * (the action buttons) when they are perfectly vertically aligned. A
+ * layout that conforms to either `LIBGAMEPAD_CONTROLLER_LINUX_4_12` or
+ * `LIBGAMEPAD_CONTROLLER_LINUX_4_12_RECTIFIED_3BTN`, and has
+ * exactly 3 actions button that are not perfectly vertically aligned,
+ * conforms to both.
+ *
* Layout:
- * Analogue BTN_DPAD_{LEFT,RIGHT,UP,DOWN}/ABS_HAT0X/ABS_HAT0Y D-pad at upper left thumb position
+ * Analogue ABS_HAT0X/ABS_HAT0Y/BTN_DPAD_* D-pad at upper left thumb position
* Clickable analogue BTN_THUMBL/ABS_X/ABS_Y stick at lower left thumb position
* Clickable analogue BTN_THUMBR/ABS_RX/ABS_RY stick at lower right thumb position
- * 4 digital buttons at upper right thumb position:
- * - NE of N = BTN_X (= BTN_NORTH)
- * - North = BTN_Y (= BTN_WEST)
- * - West = BTN_Z
- * - South = BTN_A (= BTN_SOUTH)
- * - East = BTN_B (= BTN_EAST)
- * - NE of E = BTN_C
+ * 3 digital buttons at upper right thumb position:
+ * - Left/lower = BTN_WEST (= BTN_Y)
+ * - Middle = BTN_SOUTH (= BTN_A)
+ * - Right/upper = BTN_EAST (= BTN_B)
* Analogue button BTN_TL/ABS_HAT1Y at upper left index finger position
* Analogue button BTN_TR/ABS_HAT1X at upper right index finger position
- * Analogue button BTN_TL2/ABS_HAT1Y at lower left index finger position
- * Analogue button BTN_TR2/ABS_HAT1X at lower right index finger position
+ * Analogue button BTN_TL2/ABS_HAT2Y at lower left index finger position
+ * Analogue button BTN_TR2/ABS_HAT2X at lower right index finger position
* 3 digital button north of the centre
* - West = BTN_SELECT
* - East = BTN_START
* - South = BTN_MODE
+ *
+ * Applications shall be aware that kernel drivers, even written for
+ * specific controllers, do not always use the correct codes. For example
+ * the Sony drivers currently (Linux 5.18) use ABS_Z and ABS_RZ instead
+ * of ABS_HAT2Y and ABS_HAT2X respectively.
+ */
+ LIBGAMEPAD_CONTROLLER_LINUX_4_12_RECTIFIED_3BTN,
+
+ /**
+ * libgamepad defined 6-button extension of `LIBGAMEPAD_CONTROLLER_LINUX_4_12`
+ *
+ * There are multiple substandard, this one includes all features
+ *
+ * Layout:
+ * Analogue ABS_HAT0X/ABS_HAT0Y/BTN_DPAD_* D-pad at upper left thumb position
+ * Clickable analogue BTN_THUMBL/ABS_X/ABS_Y stick at lower left thumb position
+ * Clickable analogue BTN_THUMBR/ABS_RX/ABS_RY stick at lower right thumb position
+ * 6 digital buttons at upper right thumb position:
+ * - Upper right = BTN_X (= BTN_NORTH)
+ * - Upper middle = BTN_Y (= BTN_WEST)
+ * - Upper left = BTN_Z
+ * - Lower left = BTN_A (= BTN_SOUTH)
+ * - Lower middle = BTN_B (= BTN_EAST)
+ * - Lower right = BTN_C
+ * Analogue button BTN_TL/ABS_HAT1Y at upper left index finger position
+ * Analogue button BTN_TR/ABS_HAT1X at upper right index finger position
+ * Analogue button BTN_TL2/ABS_HAT2Y at lower left index finger position
+ * Analogue button BTN_TR2/ABS_HAT2X at lower right index finger position
+ * 3 digital button north of the centre
+ * - West = BTN_SELECT
+ * - East = BTN_START
+ * - South = BTN_MODE
+ *
+ * Applications shall be aware that kernel drivers, even written for
+ * specific controllers, do not always use the correct codes. For example
+ * the Sony drivers currently (Linux 5.18) use ABS_Z and ABS_RZ instead
+ * of ABS_HAT2Y and ABS_HAT2X respectively.
*/
LIBGAMEPAD_CONTROLLER_LINUX_4_12_6BTN_EXT
};
@@ -1548,6 +1606,15 @@ int libgamepad_next_event(struct libgamepad_device *, struct libgamepad_input_ev
/**
* Get the name of a button/key
*
+ * If `device` is `NULL`, the returned name will
+ * have a prefix , that does not include an underscore
+ * except (mandatorily) as the very last character
+ * in the prefix, however if the key/button is valid
+ * but does not have a name a numerical representation
+ * is given (currently "0x" prefixed upper case
+ * hexadecimal); there are currently two prefixes:
+ * "KEY_" and "BTN_"
+ *
* @param device If `NULL`, a generic name will be returned,
* otherwise the canonical name for the button/key
* on the specific device will be returned
@@ -1560,6 +1627,15 @@ const char *libgamepad_get_button_name(const struct libgamepad_device *, uint16_
/**
* Get the name of an absolute axis
*
+ * If `device` is `NULL`, the returned name will
+ * have a prefix , that does not include an underscore
+ * except (mandatorily) as the very last character
+ * in the prefix, however if the axis is valid but
+ * does not have a name a numerical representation
+ * is given (currently "0x" prefixed upper case
+ * hexadecimal); there is currently only one prefix:
+ * "ABS_"
+ *
* @param device If `NULL`, a generic name will be returned,
* otherwise the canonical name for the axis
* on the specific device will be returned
@@ -1572,6 +1648,15 @@ const char *libgamepad_get_absolute_axis_name(const struct libgamepad_device *,
/**
* Get the name of a relative axis
*
+ * If `device` is `NULL`, the returned name will
+ * have a prefix , that does not include an underscore
+ * except (mandatorily) as the very last character
+ * in the prefix, however if the axis is valid but
+ * does not have a name a numerical representation
+ * is given (currently "0x" prefixed upper case
+ * hexadecimal); there is currently only one prefix:
+ * "REL_"
+ *
* @param device If `NULL`, a generic name will be returned,
* otherwise the canonical name for the axis
* on the specific device will be returned
@@ -1591,7 +1676,7 @@ const char *libgamepad_get_relative_axis_name(const struct libgamepad_device *,
int16_t libgamepad_get_button_by_name(const char *);
/**
- * Get a absolute axis code from it's name
+ * Get an absolute axis code from it's name
*
* @param name The absolute axis' name or textual
* representation of its code number