m + add controller fingerprint + relay less on libevdev

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

1 files changed, 145 insertions, 16 deletions

diff --git a/libgamepad.h b/libgamepad.h
index b0efec4..e7abd6a 100644
--- a/libgamepad.h
+++ b/libgamepad.h
@@ -15,6 +15,13 @@
 #include <libevdev/libevdev.h>
 
 
+#if defined(__GNUC__)
+# define LIBGAMEPAD_PURE__ __attribute__((__pure__))
+#else
+# define LIBGAMEPAD_PURE__
+#endif
+
+
 /**
  * Opaque structure for monitoring device attachment changes
  */
@@ -265,7 +272,6 @@ enum libgamepad_game_controller {
 	 *     Digital button "R" at upper right index finger position
 	 *     Digital button "ZL" at lower left index finger position
 	 *     Digital button "ZR" at lower right index finger position
-	 *     Digital Stadia (icon: brand) button between analogue sticks
 	 *     2 digital buttons at inner left thumb position:
 	 *     - North = "−"
 	 *     - East  = Capture (icon: circle; shape: square)
@@ -491,7 +497,30 @@ enum libgamepad_game_controller {
 	 * 
 	 * Released 2012-11-18 for Wii U
 	 * 
-	 * TODO Document Wii U Pro Controller
+	 * Layout:
+	 *     Clickable analogue stick at upper left thumb position
+	 *     Clickable analogue stick at upper right thumb position
+	 *     Digital D-pad at lower left thumb position
+	 *     4 digital buttons at lower right thumb position:
+	 *     - North = "X"
+	 *     - West  = "Y"
+	 *     - South = "B"
+	 *     - East  = "A"
+	 *     Digital button "L" at upper left index finger position
+	 *     Digital button "R" at upper right index finger position
+	 *     Digital button "ZL" at lower left index finger position
+	 *     Digital button "ZR" at lower right index finger position
+	 *     3 digital buttons at centre thumb position:
+	 *     - West   = "SELECT" (icon: minus symbol)
+	 *     - Centre = "HOME" (icon: house)
+	 *     - East   = "START" (icon: plus symbol)
+	 *     Digital "POWER" (icon: power symbol with the 1 over top
+	 *       of the 0, colour: red) button at lower center thumb position
+	 * 
+	 * Other features:
+	 * - Wireless via Bluetooth
+	 * - 4 digital LEDs numbered 1 through 4 (??)
+	 * - 1 digital LEDs labelled "BATTERY" (??)
 	 */
 	LIBGAMEPAD_CONTROLLER_WII_U_PRO,
 
@@ -525,9 +554,25 @@ enum libgamepad_game_controller {
 	/**
 	 * Classic Controller Pro
 	 * 
-	 * Released 2009-??-?? for Wii
+	 * Released 2009-08-01 for Wii
 	 * 
-	 * TODO Document Classic Controller Pro
+	 * Layout:
+	 *     Digital D-pad at upper left thumb position
+	 *     Analogue stick at lower left thumb position
+	 *     Analogue stick at lower right thumb position
+	 *     4 digital buttons at upper right thumb position:
+	 *     - North = "x"
+	 *     - West  = "y"
+	 *     - South = "b"
+	 *     - East  = "a"
+	 *     Digital button "L" at upper left index finger position
+	 *     Digital button "R" at upper right index finger position
+	 *     Digital button "ZL" at lower left index finger position
+	 *     Digital button "ZR" at lower right index finger position
+	 *     3 digital buttons at centre thumb position:
+	 *     - West   = "SELECT" (icon: minus symbol)
+	 *     - Centre = "HOME" (icon: house, colour: blue)
+	 *     - East   = "START" (icon: plus symbol)
 	 */
 	LIBGAMEPAD_CONTROLLER_WII_CLASSIC_PRO,
 
@@ -546,7 +591,23 @@ enum libgamepad_game_controller {
 	 * 
 	 * Released 2006-11-19 for Wii
 	 * 
-	 * TODO Document Classic Controller
+	 * Layout:
+	 *     Digital D-pad at upper left thumb position
+	 *     Analogue stick at lower left thumb position
+	 *     Analogue stick at lower right thumb position
+	 *     4 digital buttons at upper right thumb position:
+	 *     - North = "x"
+	 *     - West  = "y"
+	 *     - South = "b"
+	 *     - East  = "a"
+	 *     Analogue button "L" at left index finger position
+	 *     Analogue button "R" at right index finger position
+	 *     Digital button "ZL" inward from left index finger position
+	 *     Digital button "ZR" inward from right index finger position
+	 *     3 digital buttons at centre thumb position:
+	 *     - West   = "SELECT" (icon: minus symbol)
+	 *     - Centre = "HOME" (icon: house, colour: blue)
+	 *     - East   = "START" (icon: plus symbol)
 	 */
 	LIBGAMEPAD_CONTROLLER_WII_CLASSIC,
 
@@ -555,7 +616,14 @@ enum libgamepad_game_controller {
 	 * 
 	 * Released 2006-11-19 for Wii
 	 * 
-	 * TODO Document Nunchuk
+	 * Layout:
+	 *     Designed to be held in the user's dominant hand
+	 *     Analogue stick at thumb position
+	 *     Digital button "C" at upper index finger position
+	 *     Digital button "Z" at lower index finger position
+	 * 
+	 * Other features:
+	 * - Accelerometer
 	 */
 	LIBGAMEPAD_CONTROLLER_NUNCHUK,
 
@@ -574,6 +642,9 @@ enum libgamepad_game_controller {
 	 * Released 2010-10-28 for Wii
 	 * 
 	 * Adds (3 axis?) gyroscope to `LIBGAMEPAD_CONTROLLER_WII_REMOTE`
+	 * 
+	 * Conforming controllers:
+	 * - Wii Remote with Wii MotionPlus adapter
 	 */
 	LIBGAMEPAD_CONTROLLER_WII_REMOTE_PLUS,
 
@@ -763,7 +834,8 @@ enum libgamepad_game_controller {
 	 * 
 	 * Released 1997-11-20 for PlayStation
 	 * 
-	 * TODO Document DualShock Analog Controller
+	 * Adds rubble support to `LIBGAMEPAD_CONTROLLER_DUAL_ANALOG`
+	 * (TODO What does digital mode on DualShock do?)
 	 */
 	LIBGAMEPAD_CONTROLLER_DUAL_SHOCK,
 
@@ -771,8 +843,32 @@ enum libgamepad_game_controller {
 	 * Dual Analog Controller
 	 * 
 	 * Released 1997-04-25 for PlayStation
+	 *
+	 * The first Japanese version of this controller
+	 * had rumble support and is therefore better
+	 * reported as `LIBGAMEPAD_CONTROLLER_DUAL_SHOCK`
+	 * 
+	 * Layout:
+	 *     Digital D-pad at upper left thumb position
+	 *     Clickable analogue stick at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 digital buttons at upper right thumb position
+	 *     - North = Triangle (colour: green)
+	 *     - West  = Square (colour: pink)
+	 *     - South = Cross (colour: blue)
+	 *     - East  = Circle (colour: red)
+	 *     Digital button "L1" at upper left index finger position
+	 *     Digital button "R1" at upper right index finger position
+	 *     Digital button "L2" at lower left index finger position
+	 *     Digital button "R2" at lower right index finger position
+	 *     2 digital buttons at centre position:
+	 *     - West = "SELECT" (shape: flat rectangle)
+	 *     - East = "START"  (shape: flat play icon)
 	 * 
-	 * TODO Document Dual Analog Controller
+	 * Other features:
+	 * - LED-indicated digital "ANALOG" button at south part of center position
+	 *   for toggling between analogue and digital mode
+	 *   (TODO What does digital mode on Dual Analog do?)
 	 */
 	LIBGAMEPAD_CONTROLLER_DUAL_ANALOG,
 
@@ -885,7 +981,7 @@ enum libgamepad_game_controller {
 	 *     Digital "MODE" button right index finger position
 	 *     Digital "START" (shape: horizontal line) button at centre position
 	 * 
-	 * Conforming platforms:
+	 * Conforming controllers:
 	 * - Sega Nomad (however "MODE" is east of "START" which is far south east of "A")
 	 */
 	LIBGAMEPAD_CONTROLLER_6_BUTTON_ARCADE_PAD,
@@ -973,7 +1069,7 @@ enum libgamepad_game_controller {
 	 *     - West = "SELECT"
 	 *     - East = "START"
 	 * 
-	 * Conforming platforms:
+	 * Conforming controllers:
 	 * - Nintendo Game Boy
 	 * - Supervision (however "START" is also labelled "PAUSE" and the "SELECT" and "START"
 	 *                buttons are horizontal and north (slightly east) for "A" and "B" which
@@ -1040,7 +1136,7 @@ enum libgamepad_game_controller {
 	 *     Digital "L" button at left index finger position
 	 *     Digital "R" button at right index finger position
 	 *
-	 * Conforming platforms:
+	 * Conforming controllers:
 	 * - Game King (however "SELECT" and "START" are north of D-pad,
 	 *              "SELECT" to east and "START to west)
 	 */
@@ -1100,7 +1196,10 @@ enum libgamepad_game_controller {
 	 * 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).
+	 * with this problem). In the event that a controller has only one
+	 * action button (and truly is a gamepad and not a joystick), it shall
+	 * be reported as BTN_SOUTH as this one is designated as mandatory
+	 * (BTN_GAMEPAD) is an alias of it.
 	 */
 	LIBGAMEPAD_CONTROLLER_LINUX_4_12,
 
@@ -1383,18 +1482,18 @@ struct libgamepad_device {
 	/**
 	 * Human-readable device (sub- or superdevice) name
 	 */
-	const char *name;
+	char *name;
 
 	/**
 	 * ID that is supposted to be unique to the device
 	 * (sub- or superdevice)
 	 */
-	const char *unique_id;
+	char *unique_id;
 
 	/**
 	 * The location if the device
 	 */
-	const char *physical_location;
+	char *physical_location;
 
 	/**
 	 * Number of (digital) buttons/keys present
@@ -1452,6 +1551,18 @@ struct libgamepad_device {
 	 * Bitmap of supported force feedback effects
 	 */
 	uint8_t force_feedback_support[(FF_CNT + 7) / 8];
+
+	/**
+	 * Device fingerprint that does not take `.unique_id`
+	 * into account
+	 */
+	char fingerprint[65];
+
+	/**
+	 * Device fingerprint that does take `.unique_id`
+	 * into account
+	 */
+	char fingerprint_unique[65];
 };
 
 
@@ -1697,6 +1808,15 @@ int16_t libgamepad_get_relative_axis_by_name(const char *);
 /**
  * Get whether a button/key is pressed down or not
  * 
+ * libgamepad caches the last read button/key state,
+ * and will return the cached .state The underlaying
+ * ioctl(3) will has the ability to read a state
+ * even when the device is grabbed, but even if the
+ * device is not grabbed, the state may be out of
+ * that. Because the state may be out of date,
+ * libgamepad reads the current state when a device
+ * is opened.
+ * 
  * @param   device  The device to retrieve the information for
  * @param   code    The button/key
  * @return          1 if the button/key is pressed down,
@@ -1707,11 +1827,20 @@ int libgamepad_get_button_is_pressed(struct libgamepad_device *, uint16_t);
 /**
  * Get information about an absolute axis
  * 
+ * libgamepad caches the last read axis value, and
+ * will return the cached value. The underlaying
+ * ioctl(3) will has the ability to read a value
+ * even when the device is grabbed, but even if the
+ * device is not grabbed, the value may be out of
+ * that. Because the value may be out of date,
+ * libgamepad reads the current state when a device
+ * is opened.
+ * 
  * @param   device  The device to retrieve the information for
  * @param   code    The axis
  * @return          Information about the axis
  */
-const struct input_absinfo *libgamepad_get_absolute_axis_info(struct libgamepad_device *, uint16_t);
+LIBGAMEPAD_PURE__ const struct input_absinfo *libgamepad_get_absolute_axis_info(struct libgamepad_device *, uint16_t);
 /* `struct input_absinfo` is defined in <linux/input.h> */