Improve documentation and add LIBGAMEPAD_CONTROLLER_LINUX_4_12_RECTIFIED_3BTN

Signed-off-by: Mattias Andrée <maandree@kth.se>

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