From 763e138903e42c939240fbcc302d3ec865f1343b Mon Sep 17 00:00:00 2001
From: Sam Lantinga <slouken@libsdl.org>
Date: Thu, 9 Mar 2017 16:09:16 -0800
Subject: [PATCH] Added an API to get the joystick instance ID before opening
 the device: SDL_JoystickGetDeviceInstanceID()

---
 include/SDL_joystick.h            | 14 ++++++++++++++
 src/dynapi/SDL_dynapi_overrides.h |  1 +
 src/dynapi/SDL_dynapi_procs.h     |  1 +
 src/joystick/SDL_joystick.c       | 20 ++++++++++++++------
 4 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h
index 1ee24803fc7af..698b09c1429c5 100644
--- a/include/SDL_joystick.h
+++ b/include/SDL_joystick.h
@@ -71,6 +71,13 @@ typedef struct {
     Uint8 data[16];
 } SDL_JoystickGUID;
 
+/**
+ * This is a unique ID for a joystick for the time it is connected to the system,
+ * and is never reused for the lifetime of the application. If the joystick is
+ * disconnected and reconnected, it will get a new ID.
+ *
+ * The ID value starts at 0 and increments from there. The value -1 is an invalid ID.
+ */
 typedef Sint32 SDL_JoystickID;
 
 typedef enum
@@ -144,6 +151,13 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_in
  */
 extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_index);
 
+/**
+ *  Get the instance ID of a joystick.
+ *  This can be called before any joysticks are opened.
+ *  If the index is out of range, this function will return -1.
+ */
+extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int device_index);
+
 /**
  *  Open a joystick for use.
  *  The index passed as an argument refers to the N'th joystick on the system.
diff --git a/src/dynapi/SDL_dynapi_overrides.h b/src/dynapi/SDL_dynapi_overrides.h
index 942737aa7135c..1817e7fde8a5e 100644
--- a/src/dynapi/SDL_dynapi_overrides.h
+++ b/src/dynapi/SDL_dynapi_overrides.h
@@ -623,3 +623,4 @@
 #define SDL_JoystickGetType SDL_JoystickGetType_REAL
 #define SDL_MemoryBarrierReleaseFunction SDL_MemoryBarrierReleaseFunction_REAL
 #define SDL_MemoryBarrierAcquireFunction SDL_MemoryBarrierAcquireFunction_REAL
+#define SDL_JoystickGetDeviceInstanceID SDL_JoystickGetDeviceInstanceID_REAL
diff --git a/src/dynapi/SDL_dynapi_procs.h b/src/dynapi/SDL_dynapi_procs.h
index b54cdfff46cbd..457001b699e2e 100644
--- a/src/dynapi/SDL_dynapi_procs.h
+++ b/src/dynapi/SDL_dynapi_procs.h
@@ -655,3 +655,4 @@ SDL_DYNAPI_PROC(SDL_JoystickType,SDL_JoystickGetDeviceType,(int a),(a),return)
 SDL_DYNAPI_PROC(SDL_JoystickType,SDL_JoystickGetType,(SDL_Joystick *a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_MemoryBarrierReleaseFunction,(void),(),)
 SDL_DYNAPI_PROC(void,SDL_MemoryBarrierAcquireFunction,(void),(),)
+SDL_DYNAPI_PROC(SDL_JoystickID,SDL_JoystickGetDeviceInstanceID,(int a),(a),return)
diff --git a/src/joystick/SDL_joystick.c b/src/joystick/SDL_joystick.c
index 12eccf26c761d..8ff9dde4709c5 100644
--- a/src/joystick/SDL_joystick.c
+++ b/src/joystick/SDL_joystick.c
@@ -108,7 +108,7 @@ SDL_NumJoysticks(void)
 const char *
 SDL_JoystickNameForIndex(int device_index)
 {
-    if ((device_index < 0) || (device_index >= SDL_NumJoysticks())) {
+    if (device_index < 0 || device_index >= SDL_NumJoysticks()) {
         SDL_SetError("There are %d joysticks available", SDL_NumJoysticks());
         return (NULL);
     }
@@ -170,10 +170,10 @@ SDL_JoystickOpen(int device_index)
 
     joysticklist = SDL_joysticks;
     /* If the joystick is already open, return it
-    * it is important that we have a single joystick * for each instance id
-    */
+     * it is important that we have a single joystick * for each instance id
+     */
     while (joysticklist) {
-        if (SDL_SYS_GetInstanceIdOfDeviceIndex(device_index) == joysticklist->instance_id) {
+        if (SDL_JoystickGetDeviceInstanceID(device_index) == joysticklist->instance_id) {
                 joystick = joysticklist;
                 ++joystick->ref_count;
                 SDL_UnlockJoystickList();
@@ -1078,7 +1078,7 @@ static SDL_JoystickType SDL_GetJoystickGUIDType(SDL_JoystickGUID guid)
 /* return the guid for this index */
 SDL_JoystickGUID SDL_JoystickGetDeviceGUID(int device_index)
 {
-    if ((device_index < 0) || (device_index >= SDL_NumJoysticks())) {
+    if (device_index < 0 || device_index >= SDL_NumJoysticks()) {
         SDL_JoystickGUID emptyGUID;
         SDL_SetError("There are %d joysticks available", SDL_NumJoysticks());
         SDL_zero(emptyGUID);
@@ -1128,7 +1128,15 @@ SDL_JoystickType SDL_JoystickGetDeviceType(int device_index)
     return type;
 }
 
-/* return the guid for this opened device */
+SDL_JoystickID SDL_JoystickGetDeviceInstanceID(int device_index)
+{
+    if (device_index < 0 || device_index >= SDL_NumJoysticks()) {
+        SDL_SetError("There are %d joysticks available", SDL_NumJoysticks());
+        return -1;
+    }
+    return SDL_SYS_GetInstanceIdOfDeviceIndex(device_index);
+}
+
 SDL_JoystickGUID SDL_JoystickGetGUID(SDL_Joystick * joystick)
 {
     if (!SDL_PrivateJoystickValid(joystick)) {