diff options
| -rw-r--r-- | TODO | 1 | ||||
| -rw-r--r-- | libgamepad.h | 127 |
2 files changed, 107 insertions, 21 deletions
@@ -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 |