Updated gamepad, joystick, sensor APIs, removing device indices

Instead of indexing into an internal list of devices which requires locking, we return a list of device IDs which can then be queried individually.

Reference: https://github.com/libsdl-org/SDL/issues/6889

include/SDL3/SDL_events.h

@@ -397,7 +397,7 @@ typedef struct SDL_JoyDeviceEvent
 {
     Uint32 type;        /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */
     Uint64 timestamp;   /**< In nanoseconds, populated using SDL_GetTicksNS() */
-    SDL_JoystickID which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
+    SDL_JoystickID which;       /**< The joystick instance id */
 } SDL_JoyDeviceEvent;
 
 /**
@@ -450,7 +450,7 @@ typedef struct SDL_GamepadDeviceEvent
 {
     Uint32 type;        /**< ::SDL_GAMEPADADDED, ::SDL_GAMEPADREMOVED, or ::SDL_GAMEPADDEVICEREMAPPED */
     Uint64 timestamp;   /**< In nanoseconds, populated using SDL_GetTicksNS() */
-    SDL_JoystickID which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
+    SDL_JoystickID which;       /**< The joystick instance id */
 } SDL_GamepadDeviceEvent;
 
 /**

include/SDL3/SDL_gamepad.h

@@ -181,7 +181,7 @@ typedef struct SDL_GamepadBinding
  * \sa SDL_GetGamepadMapping
  * \sa SDL_GetGamepadMappingForGUID
  */
-extern DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char* mappingString);
+extern DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mappingString);
 
 /**
  * Load a set of Game Controller mappings from a seekable SDL data stream.
@@ -211,7 +211,7 @@ extern DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char* mappingString);
  * \sa SDL_AddGamepadMappingsFromFile
  * \sa SDL_GetGamepadMappingForGUID
  */
-extern DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromRW(SDL_RWops * rw, int freerw);
+extern DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromRW(SDL_RWops *rw, int freerw);
 
 /**
  *  Load a set of mappings from a file, filtered by the current SDL_GetPlatform()
@@ -250,7 +250,7 @@ extern DECLSPEC char * SDLCALL SDL_GetGamepadMappingForIndex(int mapping_index);
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetJoystickDeviceGUID
+ * \sa SDL_GetJoystickInstanceGUID
  * \sa SDL_GetJoystickGUID
  */
 extern DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_JoystickGUID guid);
@@ -274,14 +274,33 @@ extern DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_JoystickGUID gui
  */
 extern DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad);
 
+/**
+ * Return whether there are gamepads connected
+ *
+ * \returns SDL_TRUE if there are gamepads connected, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetGamepads
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasGamepads(void);
+
+/**
+ * Get a list of currently connected gamepads.
+ *
+ * \param count a pointer filled in with the number of gamepads returned
+ * \returns a 0 terminated array of joystick instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_OpenGamepad
+ */
+extern DECLSPEC SDL_JoystickID *SDLCALL SDL_GetGamepads(int *count);
+
 /**
  * Check if the given joystick is supported by the gamepad interface.
  *
- * `joystick_index` is the same as the `device_index` passed to
- * SDL_OpenJoystick().
- *
- * \param joystick_index the device_index of a device, up to
- *                       SDL_GetNumJoysticks()
+ * \param instance_id the joystick instance ID
  * \returns SDL_TRUE if the given joystick is supported by the gamepad
  *          interface, SDL_FALSE if it isn't or it's an invalid index.
  *
@@ -290,88 +309,142 @@ extern DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad);
  * \sa SDL_GetGamepadNameForIndex
  * \sa SDL_OpenGamepad
  */
-extern DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(int joystick_index);
+extern DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id);
 
 /**
- * Get the implementation dependent name for the gamepad.
+ * Get the implementation dependent name of a gamepad.
  *
- * This function can be called before any gamepads are opened.
+ * This can be called before any gamepads are opened.
  *
- * `joystick_index` is the same as the `device_index` passed to
- * SDL_OpenJoystick().
- *
- * \param joystick_index the device_index of a device, from zero to
- *                       SDL_GetNumJoysticks()-1
- * \returns the implementation-dependent name for the gamepad, or NULL
- *          if there is no name or the index is invalid.
+ * \param instance_id the joystick instance ID
+ * \returns the name of the selected gamepad. If no name can be found, this
+ *          function returns NULL; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetGamepadName
  * \sa SDL_OpenGamepad
- * \sa SDL_IsGamepad
  */
-extern DECLSPEC const char *SDLCALL SDL_GetGamepadNameForIndex(int joystick_index);
+extern DECLSPEC const char *SDLCALL SDL_GetGamepadInstanceName(SDL_JoystickID instance_id);
 
 /**
- * Get the implementation dependent path for the gamepad.
+ * Get the implementation dependent path of a gamepad.
  *
- * This function can be called before any gamepads are opened.
+ * This can be called before any gamepads are opened.
  *
- * `joystick_index` is the same as the `device_index` passed to
- * SDL_OpenJoystick().
- *
- * \param joystick_index the device_index of a device, from zero to
- *                       SDL_GetNumJoysticks()-1
- * \returns the implementation-dependent path for the gamepad, or NULL
- *          if there is no path or the index is invalid.
+ * \param instance_id the joystick instance ID
+ * \returns the path of the selected gamepad. If no path can be found, this
+ *          function returns NULL; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetGamepadPath
+ * \sa SDL_OpenGamepad
  */
-extern DECLSPEC const char *SDLCALL SDL_GetGamepadPathForIndex(int joystick_index);
+extern DECLSPEC const char *SDLCALL SDL_GetGamepadInstancePath(SDL_JoystickID instance_id);
+
+/**
+ * Get the player index of a gamepad.
+ *
+ * This can be called before any gamepads are opened.
+ *
+ * \param instance_id the joystick instance ID
+ * \returns the player index of a gamepad, or -1 if it's not available
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetGamepadPlayerIndex
+ * \sa SDL_OpenGamepad
+ */
+extern DECLSPEC int SDLCALL SDL_GetGamepadInstancePlayerIndex(SDL_JoystickID instance_id);
+
+/**
+ * Get the implementation-dependent GUID of a gamepad.
+ *
+ * This can be called before any gamepads are opened.
+ *
+ * \param instance_id the joystick instance ID
+ * \returns the GUID of the selected gamepad. If called on an invalid index,
+ *          this function returns a zero GUID
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetGamepadGUID
+ * \sa SDL_GetGamepadGUIDString
+ */
+extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadInstanceGUID(SDL_JoystickID instance_id);
+
+/**
+ * Get the USB vendor ID of a gamepad, if available.
+ *
+ * This can be called before any gamepads are opened. If the vendor ID isn't
+ * available this function returns 0.
+ *
+ * \param instance_id the joystick instance ID
+ * \returns the USB vendor ID of the selected gamepad. If called on an
+ *          invalid index, this function returns zero
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceVendor(SDL_JoystickID instance_id);
+
+/**
+ * Get the USB product ID of a gamepad, if available.
+ *
+ * This can be called before any gamepads are opened. If the product ID isn't
+ * available this function returns 0.
+ *
+ * \param instance_id the joystick instance ID
+ * \returns the USB product ID of the selected gamepad. If called on an
+ *          invalid index, this function returns zero
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceProduct(SDL_JoystickID instance_id);
+
+/**
+ * Get the product version of a gamepad, if available.
+ *
+ * This can be called before any gamepads are opened. If the product version
+ * isn't available this function returns 0.
+ *
+ * \param instance_id the joystick instance ID
+ * \returns the product version of the selected gamepad. If called on an
+ *          invalid index, this function returns zero
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceProductVersion(SDL_JoystickID instance_id);
 
 /**
  * Get the type of a gamepad.
  *
  * This can be called before any gamepads are opened.
  *
- * \param joystick_index the device_index of a device, from zero to
- *                       SDL_GetNumJoysticks()-1
+ * \param instance_id the joystick instance ID
  * \returns the gamepad type.
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeForIndex(int joystick_index);
+extern DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadInstanceType(SDL_JoystickID instance_id);
 
 /**
  * Get the mapping of a gamepad.
  *
  * This can be called before any gamepads are opened.
  *
- * \param joystick_index the device_index of a device, from zero to
- *                       SDL_GetNumJoysticks()-1
+ * \param instance_id the joystick instance ID
  * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
  *          no mapping is available.
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC char *SDLCALL SDL_GetGamepadMappingForDeviceIndex(int joystick_index);
+extern DECLSPEC char *SDLCALL SDL_GetGamepadInstanceMapping(SDL_JoystickID instance_id);
 
 /**
  * Open a gamepad for use.
  *
- * `joystick_index` is the same as the `device_index` passed to
- * SDL_OpenJoystick().
- *
- * The index passed as an argument refers to the N'th gamepad on the
- * system. This index is not the value which will identify this gamepad in
- * future gamepad events. The joystick's instance id (SDL_JoystickID) will
- * be used there instead.
- *
- * \param joystick_index the device_index of a device, up to
- *                       SDL_GetNumJoysticks()
+ * \param instance_id the joystick instance ID
  * \returns a gamepad identifier or NULL if an error occurred; call
  *          SDL_GetError() for more information.
  *
@@ -381,27 +454,23 @@ extern DECLSPEC char *SDLCALL SDL_GetGamepadMappingForDeviceIndex(int joystick_i
  * \sa SDL_GetGamepadNameForIndex
  * \sa SDL_IsGamepad
  */
-extern DECLSPEC SDL_Gamepad *SDLCALL SDL_OpenGamepad(int joystick_index);
+extern DECLSPEC SDL_Gamepad *SDLCALL SDL_OpenGamepad(SDL_JoystickID instance_id);
 
 /**
- * Get the SDL_Gamepad associated with an instance id.
+ * Get the SDL_Gamepad associated with a joystick instance ID.
  *
- * \param joyid the instance id to get the SDL_Gamepad for
+ * \param instance_id the joystick instance ID of the gamepad
  * \returns an SDL_Gamepad on success or NULL on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromInstanceID(SDL_JoystickID joyid);
+extern DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromInstanceID(SDL_JoystickID instance_id);
 
 /**
  * Get the SDL_Gamepad associated with a player index.
  *
- * Please note that the player index is _not_ the device index, nor is it the
- * instance id!
- *
- * \param player_index the player index, which is not the device index or the
- *                     instance id!
+ * \param player_index the player index, which different from the instance ID
  * \returns the SDL_Gamepad associated with a player index.
  *
  * \since This function is available since SDL 3.0.0.
@@ -442,14 +511,14 @@ extern DECLSPEC const char *SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad);
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetGamepadPathForIndex
+ * \sa SDL_GetGamepadInstancePath
  */
 extern DECLSPEC const char *SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad);
 
 /**
  * Get the type of this currently opened gamepad
  *
- * This is the same name as returned by SDL_GetGamepadTypeForIndex(), but
+ * This is the same name as returned by SDL_GetGamepadInstanceType(), but
  * it takes a gamepad identifier instead of the (unstable) device index.
  *
  * \param gamepad the gamepad object to query.
@@ -559,7 +628,7 @@ extern DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad);
 extern DECLSPEC SDL_bool SDLCALL SDL_IsGamepadConnected(SDL_Gamepad *gamepad);
 
 /**
- * Get the Joystick ID from a Game Controller.
+ * Get the underlying joystick from a gamepad
  *
  * This function will give you a SDL_Joystick object, which allows you to use
  * the SDL_Joystick functions with a SDL_Gamepad object. This would be
@@ -573,7 +642,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsGamepadConnected(SDL_Gamepad *gamepad);
  *
  * \param gamepad the gamepad object that you want to get a
  *                       joystick from
- * \returns a SDL_Joystick object; call SDL_GetError() for more information.
+ * \returns an SDL_Joystick object; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_joystick.h

@@ -24,9 +24,6 @@
  *
  *  Include file for SDL joystick event handling
  *
- * The term "device_index" identifies currently plugged in joystick devices between 0 and SDL_GetNumJoysticks(), with the exact joystick
- *   behind a device_index changing as joysticks are plugged and unplugged.
- *
  * The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
  *   then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
  *
@@ -81,9 +78,9 @@ typedef SDL_GUID SDL_JoystickGUID;
  * 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.
+ * The ID value starts at 1 and increments from there. The value 0 is an invalid ID.
  */
-typedef Sint32 SDL_JoystickID;
+typedef Uint32 SDL_JoystickID;
 
 typedef enum
 {
@@ -119,60 +116,52 @@ typedef enum
 /* Function prototypes */
 
 /**
- * Locking for multi-threaded access to the joystick API
+ * Locking for atomic access to the joystick API
  *
- * If you are using the joystick API or handling events from multiple threads
- * you should use these locking functions to protect access to the joysticks.
- *
- * In particular, you are guaranteed that the joystick list won't change, so
- * the API functions that take a joystick index will be valid, and joystick
- * and game controller events will not be delivered.
- *
- * As of SDL 2.26.0, you can take the joystick lock around reinitializing the
- * joystick subsystem, to prevent other threads from seeing joysticks in an
- * uninitialized state. However, all open joysticks will be closed and SDL
- * functions called with them will fail.
+ * The SDL joystick functions are thread-safe, however you can lock the joysticks
+ * while processing to guarantee that the joystick list won't change and joystick
+ * and gamepad events will not be delivered.
  *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock);
 
-
 /**
- * Unlocking for multi-threaded access to the joystick API
- *
- * If you are using the joystick API or handling events from multiple threads
- * you should use these locking functions to protect access to the joysticks.
- *
- * In particular, you are guaranteed that the joystick list won't change, so
- * the API functions that take a joystick index will be valid, and joystick
- * and game controller events will not be delivered.
+ * Unlocking for atomic access to the joystick API
  *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock);
 
 /**
- * Count the number of joysticks attached to the system.
+ * Return whether there are joysticks connected
  *
- * \returns the number of attached joysticks on success or a negative error
- *          code on failure; call SDL_GetError() for more information.
+ * \returns SDL_TRUE if there are joysticks connected, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetJoysticks
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasJoysticks(void);
+
+/**
+ * Get a list of currently connected joysticks.
+ *
+ * \param count a pointer filled in with the number of joysticks returned
+ * \returns a 0 terminated array of joystick instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetJoystickName
- * \sa SDL_GetJoystickPath
  * \sa SDL_OpenJoystick
  */
-extern DECLSPEC int SDLCALL SDL_GetNumJoysticks(void);
+extern DECLSPEC SDL_JoystickID *SDLCALL SDL_GetJoysticks(int *count);
 
 /**
  * Get the implementation dependent name of a joystick.
  *
  * This can be called before any joysticks are opened.
  *
- * \param device_index the index of the joystick to query (the N'th joystick
- *                     on the system)
+ * \param instance_id the joystick instance ID
  * \returns the name of the selected joystick. If no name can be found, this
  *          function returns NULL; call SDL_GetError() for more information.
  *
@@ -181,15 +170,14 @@ extern DECLSPEC int SDLCALL SDL_GetNumJoysticks(void);
  * \sa SDL_GetJoystickName
  * \sa SDL_OpenJoystick
  */
-extern DECLSPEC const char *SDLCALL SDL_GetJoystickNameForIndex(int device_index);
+extern DECLSPEC const char *SDLCALL SDL_GetJoystickInstanceName(SDL_JoystickID instance_id);
 
 /**
  * Get the implementation dependent path of a joystick.
  *
  * This can be called before any joysticks are opened.
  *
- * \param device_index the index of the joystick to query (the N'th joystick
- *                     on the system)
+ * \param instance_id the joystick instance ID
  * \returns the path of the selected joystick. If no path can be found, this
  *          function returns NULL; call SDL_GetError() for more information.
  *
@@ -198,24 +186,29 @@ extern DECLSPEC const char *SDLCALL SDL_GetJoystickNameForIndex(int device_index
  * \sa SDL_GetJoystickPath
  * \sa SDL_OpenJoystick
  */
-extern DECLSPEC const char *SDLCALL SDL_GetJoystickPathForIndex(int device_index);
+extern DECLSPEC const char *SDLCALL SDL_GetJoystickInstancePath(SDL_JoystickID instance_id);
 
 /**
- * Get the player index of a joystick, or -1 if it's not available This can be
- * called before any joysticks are opened.
+ * Get the player index of a joystick.
+ *
+ * This can be called before any joysticks are opened.
+ *
+ * \param instance_id the joystick instance ID
+ * \returns the player index of a joystick, or -1 if it's not available
  *
  * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetJoystickPlayerIndex
+ * \sa SDL_OpenJoystick
  */
-extern DECLSPEC int SDLCALL SDL_GetJoystickDevicePlayerIndex(int device_index);
+extern DECLSPEC int SDLCALL SDL_GetJoystickInstancePlayerIndex(SDL_JoystickID instance_id);
 
 /**
- * Get the implementation-dependent GUID for the joystick at a given device
- * index.
+ * Get the implementation-dependent GUID of a joystick.
  *
- * This function can be called before any joysticks are opened.
+ * This can be called before any joysticks are opened.
  *
- * \param device_index the index of the joystick to query (the N'th joystick
- *                     on the system
+ * \param instance_id the joystick instance ID
  * \returns the GUID of the selected joystick. If called on an invalid index,
  *          this function returns a zero GUID
  *
@@ -224,7 +217,7 @@ extern DECLSPEC int SDLCALL SDL_GetJoystickDevicePlayerIndex(int device_index);
  * \sa SDL_GetJoystickGUID
  * \sa SDL_GetJoystickGUIDString
  */
-extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickDeviceGUID(int device_index);
+extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickInstanceGUID(SDL_JoystickID instance_id);
 
 /**
  * Get the USB vendor ID of a joystick, if available.
@@ -232,14 +225,13 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickDeviceGUID(int device_in
  * This can be called before any joysticks are opened. If the vendor ID isn't
  * available this function returns 0.
  *
- * \param device_index the index of the joystick to query (the N'th joystick
- *                     on the system
+ * \param instance_id the joystick instance ID
  * \returns the USB vendor ID of the selected joystick. If called on an
  *          invalid index, this function returns zero
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_GetJoystickDeviceVendor(int device_index);
+extern DECLSPEC Uint16 SDLCALL SDL_GetJoystickInstanceVendor(SDL_JoystickID instance_id);
 
 /**
  * Get the USB product ID of a joystick, if available.
@@ -247,14 +239,13 @@ extern DECLSPEC Uint16 SDLCALL SDL_GetJoystickDeviceVendor(int device_index);
  * This can be called before any joysticks are opened. If the product ID isn't
  * available this function returns 0.
  *
- * \param device_index the index of the joystick to query (the N'th joystick
- *                     on the system
+ * \param instance_id the joystick instance ID
  * \returns the USB product ID of the selected joystick. If called on an
  *          invalid index, this function returns zero
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_GetJoystickDeviceProduct(int device_index);
+extern DECLSPEC Uint16 SDLCALL SDL_GetJoystickInstanceProduct(SDL_JoystickID instance_id);
 
 /**
  * Get the product version of a joystick, if available.
@@ -262,70 +253,47 @@ extern DECLSPEC Uint16 SDLCALL SDL_GetJoystickDeviceProduct(int device_index);
  * This can be called before any joysticks are opened. If the product version
  * isn't available this function returns 0.
  *
- * \param device_index the index of the joystick to query (the N'th joystick
- *                     on the system
+ * \param instance_id the joystick instance ID
  * \returns the product version of the selected joystick. If called on an
  *          invalid index, this function returns zero
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_GetJoystickDeviceProductVersion(int device_index);
+extern DECLSPEC Uint16 SDLCALL SDL_GetJoystickInstanceProductVersion(SDL_JoystickID instance_id);
 
 /**
  * Get the type of a joystick, if available.
  *
  * This can be called before any joysticks are opened.
  *
- * \param device_index the index of the joystick to query (the N'th joystick
- *                     on the system
+ * \param instance_id the joystick instance ID
  * \returns the SDL_JoystickType of the selected joystick. If called on an
  *          invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickDeviceType(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.
- *
- * \param device_index the index of the joystick to query (the N'th joystick
- *                     on the system
- * \returns the instance id of the selected joystick. If called on an invalid
- *          index, this function returns zero
- *
- * \since This function is available since SDL 3.0.0.
- */
-extern DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickDeviceInstanceID(int device_index);
+extern DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickInstanceType(SDL_JoystickID instance_id);
 
 /**
  * Open a joystick for use.
  *
- * The `device_index` argument refers to the N'th joystick presently
- * recognized by SDL on the system. It is **NOT** the same as the instance ID
- * used to identify the joystick in future events. See
- * SDL_GetJoystickInstanceID() for more details about instance IDs.
- *
  * The joystick subsystem must be initialized before a joystick can be opened
  * for use.
  *
- * \param device_index the index of the joystick to query
+ * \param instance_id the joystick instance ID
  * \returns a joystick identifier or NULL if an error occurred; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_CloseJoystick
- * \sa SDL_GetJoystickInstanceID
  */
-extern DECLSPEC SDL_Joystick *SDLCALL SDL_OpenJoystick(int device_index);
+extern DECLSPEC SDL_Joystick *SDLCALL SDL_OpenJoystick(SDL_JoystickID instance_id);
 
 /**
- * Get the SDL_Joystick associated with an instance id.
+ * Get the SDL_Joystick associated with an instance ID.
  *
- * \param instance_id the instance id to get the SDL_Joystick for
+ * \param instance_id the instance ID to get the SDL_Joystick for
  * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
  *          for more information.
  *
@@ -347,11 +315,11 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GetJoystickFromPlayerIndex(int player_
 /**
  * Attach a new virtual joystick.
  *
- * \returns the joystick's device index, or -1 if an error occurred.
+ * \returns the joystick instance ID, or 0 if an error occurred; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC int SDLCALL SDL_AttachVirtualJoystick(SDL_JoystickType type,
+extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(SDL_JoystickType type,
                                                       int naxes,
                                                       int nbuttons,
                                                       int nhats);
@@ -398,32 +366,31 @@ typedef struct SDL_VirtualJoystickDesc
 /**
  * Attach a new virtual joystick with extended properties.
  *
- * \returns the joystick's device index, or -1 if an error occurred.
+ * \returns the joystick instance ID, or 0 if an error occurred; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC int SDLCALL SDL_AttachVirtualJoystickEx(const SDL_VirtualJoystickDesc *desc);
+extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystickEx(const SDL_VirtualJoystickDesc *desc);
 
 /**
  * Detach a virtual joystick.
  *
- * \param device_index a value previously returned from
- *                     SDL_AttachVirtualJoystick()
+ * \param instance_id the joystick instance ID, previously returned from SDL_AttachVirtualJoystick()
  * \returns 0 on success, or -1 if an error occurred.
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC int SDLCALL SDL_DetachVirtualJoystick(int device_index);
+extern DECLSPEC int SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id);
 
 /**
- * Query whether or not the joystick at a given device index is virtual.
+ * Query whether or not a joystick is virtual.
  *
- * \param device_index a joystick device index.
+ * \param instance_id the joystick instance ID
  * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(int device_index);
+extern DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id);
 
 /**
  * Set values on an opened, virtual-joystick's axis.
@@ -492,7 +459,7 @@ extern DECLSPEC int SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, in
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetJoystickNameForIndex
+ * \sa SDL_GetJoystickInstanceName
  * \sa SDL_OpenJoystick
  */
 extern DECLSPEC const char *SDLCALL SDL_GetJoystickName(SDL_Joystick *joystick);
@@ -506,7 +473,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetJoystickName(SDL_Joystick *joystick);
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetJoystickPathForIndex
+ * \sa SDL_GetJoystickInstancePath
  */
 extern DECLSPEC const char *SDLCALL SDL_GetJoystickPath(SDL_Joystick *joystick);
 
@@ -546,7 +513,7 @@ extern DECLSPEC void SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick,
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetJoystickDeviceGUID
+ * \sa SDL_GetJoystickInstanceGUID
  * \sa SDL_GetJoystickGUIDString
  */
 extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *joystick);
@@ -634,7 +601,7 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *joyst
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetJoystickDeviceGUID
+ * \sa SDL_GetJoystickInstanceGUID
  * \sa SDL_GetJoystickGUID
  * \sa SDL_GetJoystickGUIDFromString
  */
@@ -671,7 +638,7 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickGUIDFromString(const cha
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetJoystickDeviceGUID
+ * \sa SDL_GetJoystickInstanceGUID
  */
 extern DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_JoystickGUID guid, Uint16 *vendor, Uint16 *product, Uint16 *version, Uint16 *crc16);
 

include/SDL3/SDL_oldnames.h

@@ -160,15 +160,12 @@
 #define SDL_GameControllerHasSensor SDL_GamepadHasSensor
 #define SDL_GameControllerIsSensorEnabled SDL_IsGamepadSensorEnabled
 #define SDL_GameControllerMapping SDL_GetGamepadMapping
-#define SDL_GameControllerMappingForDeviceIndex SDL_GetGamepadMappingForDeviceIndex
 #define SDL_GameControllerMappingForGUID SDL_GetGamepadMappingForGUID
 #define SDL_GameControllerMappingForIndex SDL_GetGamepadMappingForIndex
 #define SDL_GameControllerName SDL_GetGamepadName
-#define SDL_GameControllerNameForIndex SDL_GetGamepadNameForIndex
 #define SDL_GameControllerNumMappings SDL_GetNumGamepadMappings
 #define SDL_GameControllerOpen SDL_OpenGamepad
 #define SDL_GameControllerPath SDL_GetGamepadPath
-#define SDL_GameControllerPathForIndex SDL_GetGamepadPathForIndex
 #define SDL_GameControllerRumble SDL_RumbleGamepad
 #define SDL_GameControllerRumbleTriggers SDL_RumbleGamepadTriggers
 #define SDL_GameControllerSendEffect SDL_SendGamepadEffect
@@ -176,7 +173,6 @@
 #define SDL_GameControllerSetPlayerIndex SDL_SetGamepadPlayerIndex
 #define SDL_GameControllerSetSensorEnabled SDL_SetGamepadSensorEnabled
 #define SDL_GameControllerType SDL_GamepadType
-#define SDL_GameControllerTypeForIndex SDL_GetGamepadTypeForIndex
 #define SDL_GameControllerUpdate SDL_UpdateGamepads
 #define SDL_INIT_GAMECONTROLLER SDL_INIT_GAMEPAD
 #define SDL_IsGameController SDL_IsGamepad
@@ -195,13 +191,6 @@
 #define SDL_JoystickGetAxis SDL_GetJoystickAxis
 #define SDL_JoystickGetAxisInitialState SDL_GetJoystickAxisInitialState
 #define SDL_JoystickGetButton SDL_GetJoystickButton
-#define SDL_JoystickGetDeviceGUID SDL_GetJoystickDeviceGUID
-#define SDL_JoystickGetDeviceInstanceID SDL_GetJoystickDeviceInstanceID
-#define SDL_JoystickGetDevicePlayerIndex SDL_GetJoystickDevicePlayerIndex
-#define SDL_JoystickGetDeviceProduct SDL_GetJoystickDeviceProduct
-#define SDL_JoystickGetDeviceProductVersion SDL_GetJoystickDeviceProductVersion
-#define SDL_JoystickGetDeviceType SDL_GetJoystickDeviceType
-#define SDL_JoystickGetDeviceVendor SDL_GetJoystickDeviceVendor
 #define SDL_JoystickGetFirmwareVersion SDL_GetJoystickFirmwareVersion
 #define SDL_JoystickGetGUID SDL_GetJoystickGUID
 #define SDL_JoystickGetGUIDFromString SDL_GetJoystickGUIDFromString
@@ -216,13 +205,11 @@
 #define SDL_JoystickInstanceID SDL_GetJoystickInstanceID
 #define SDL_JoystickIsVirtual SDL_IsJoystickVirtual
 #define SDL_JoystickName SDL_GetJoystickName
-#define SDL_JoystickNameForIndex SDL_GetJoystickNameForIndex
 #define SDL_JoystickNumAxes SDL_GetNumJoystickAxes
 #define SDL_JoystickNumButtons SDL_GetNumJoystickButtons
 #define SDL_JoystickNumHats SDL_GetNumJoystickHats
 #define SDL_JoystickOpen SDL_OpenJoystick
 #define SDL_JoystickPath SDL_GetJoystickPath
-#define SDL_JoystickPathForIndex SDL_GetJoystickPathForIndex
 #define SDL_JoystickRumble SDL_RumbleJoystick
 #define SDL_JoystickRumbleTriggers SDL_RumbleJoystickTriggers
 #define SDL_JoystickSendEffect SDL_SendJoystickEffect
@@ -557,7 +544,6 @@
 #define SDL_JoystickSetVirtualButton SDL_JoystickSetVirtualButton_renamed_SDL_SetJoystickVirtualButton
 #define SDL_JoystickSetVirtualHat SDL_JoystickSetVirtualHat_renamed_SDL_SetJoystickVirtualHat
 #define SDL_JoystickUpdate SDL_JoystickUpdate_renamed_SDL_UpdateJoysticks
-#define SDL_NumJoysticks SDL_NumJoysticks_renamed_SDL_GetNumJoysticks
 
 /* ##SDL_keycode.h */
 #define KMOD_ALT KMOD_ALT_renamed_SDL_KMOD_ALT
@@ -653,14 +639,9 @@
 #define RW_SEEK_SET RW_SEEK_SET_renamed_SDL_RW_SEEK_SET
 
 /* ##SDL_sensor.h */
-#define SDL_NumSensors SDL_NumSensors_renamed_SDL_GetNumSensors
 #define SDL_SensorClose SDL_SensorClose_renamed_SDL_CloseSensor
 #define SDL_SensorFromInstanceID SDL_SensorFromInstanceID_renamed_SDL_GetSensorFromInstanceID
 #define SDL_SensorGetData SDL_SensorGetData_renamed_SDL_GetSensorData
-#define SDL_SensorGetDeviceInstanceID SDL_SensorGetDeviceInstanceID_renamed_SDL_GetSensorDeviceInstanceID
-#define SDL_SensorGetDeviceName SDL_SensorGetDeviceName_renamed_SDL_GetSensorDeviceName
-#define SDL_SensorGetDeviceNonPortableType SDL_SensorGetDeviceNonPortableType_renamed_SDL_GetSensorDeviceNonPortableType
-#define SDL_SensorGetDeviceType SDL_SensorGetDeviceType_renamed_SDL_GetSensorDeviceType
 #define SDL_SensorGetInstanceID SDL_SensorGetInstanceID_renamed_SDL_GetSensorInstanceID
 #define SDL_SensorGetName SDL_SensorGetName_renamed_SDL_GetSensorName
 #define SDL_SensorGetNonPortableType SDL_SensorGetNonPortableType_renamed_SDL_GetSensorNonPortableType

include/SDL3/SDL_sensor.h

@@ -55,9 +55,9 @@ typedef struct SDL_Sensor SDL_Sensor;
  * This is a unique ID for a sensor for the time it is connected to the system,
  * and is never reused for the lifetime of the application.
  *
- * The ID value starts at 0 and increments from there. The value -1 is an invalid ID.
+ * The ID value starts at 1 and increments from there. The value 0 is an invalid ID.
  */
-typedef Sint32 SDL_SensorID;
+typedef Uint32 SDL_SensorID;
 
 /* The different sensors defined by SDL
  *
@@ -95,7 +95,7 @@ typedef enum
  * -X ... +X : left ... right
  * -Y ... +Y : bottom ... top
  * -Z ... +Z : farther ... closer
- * 
+ *
  * The axis data is not changed when the phone is rotated.
  *
  * \sa SDL_GetDisplayOrientation()
@@ -120,7 +120,7 @@ typedef enum
  * -X ... +X : left ... right
  * -Y ... +Y : bottom ... top
  * -Z ... +Z : farther ... closer
- * 
+ *
  * The axis data is not changed when the phone or controller is rotated.
  *
  * \sa SDL_GetDisplayOrientation()
@@ -129,85 +129,70 @@ typedef enum
 /* Function prototypes */
 
 /**
- * Locking for multi-threaded access to the sensor API
+ * Return whether there are sensors connected
  *
- * If you are using the sensor API or handling events from multiple threads
- * you should use these locking functions to protect access to the sensors.
- *
- * In particular, you are guaranteed that the sensor list won't change, so the
- * API functions that take a sensor index will be valid, and sensor events
- * will not be delivered.
+ * \returns SDL_TRUE if there are sensors connected, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetSensors
  */
-extern DECLSPEC void SDLCALL SDL_LockSensors(void);
-extern DECLSPEC void SDLCALL SDL_UnlockSensors(void);
+extern DECLSPEC SDL_bool SDLCALL SDL_HasSensors(void);
 
 /**
- * Count the number of sensors attached to the system right now.
+ * Get a list of currently connected sensors.
  *
- * \returns the number of sensors detected.
+ * \param count a pointer filled in with the number of sensors returned
+ * \returns a 0 terminated array of sensor instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details.
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC int SDLCALL SDL_GetNumSensors(void);
+extern DECLSPEC SDL_SensorID *SDLCALL SDL_GetSensors(int *count);
 
 /**
  * Get the implementation dependent name of a sensor.
  *
- * \param device_index The sensor to obtain name from
- * \returns the sensor name, or NULL if `device_index` is out of range.
+ * \param instance_id the sensor instance ID
+ * \returns the sensor name, or NULL if `instance_id` is not valid
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC const char *SDLCALL SDL_GetSensorDeviceName(int device_index);
+extern DECLSPEC const char *SDLCALL SDL_GetSensorInstanceName(SDL_SensorID instance_id);
 
 /**
  * Get the type of a sensor.
  *
- * \param device_index The sensor to get the type from
- * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is
- *          out of range.
+ * \param instance_id the sensor instance ID
+ * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is not valid
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorDeviceType(int device_index);
+extern DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorInstanceType(SDL_SensorID instance_id);
 
 /**
  * Get the platform dependent type of a sensor.
  *
- * \param device_index The sensor to check
- * \returns the sensor platform dependent type, or -1 if `device_index` is out
- *          of range.
+ * \param instance_id the sensor instance ID
+ * \returns the sensor platform dependent type, or -1 if `instance_id` is not valid
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC int SDLCALL SDL_GetSensorDeviceNonPortableType(int device_index);
-
-/**
- * Get the instance ID of a sensor.
- *
- * \param device_index The sensor to get instance id from
- * \returns the sensor instance ID, or -1 if `device_index` is out of range.
- *
- * \since This function is available since SDL 3.0.0.
- */
-extern DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorDeviceInstanceID(int device_index);
+extern DECLSPEC int SDLCALL SDL_GetSensorInstanceNonPortableType(SDL_SensorID instance_id);
 
 /**
  * Open a sensor for use.
  *
- * \param device_index The sensor to open
+ * \param instance_id the sensor instance ID
  * \returns an SDL_Sensor sensor object, or NULL if an error occurred.
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC SDL_Sensor *SDLCALL SDL_OpenSensor(int device_index);
+extern DECLSPEC SDL_Sensor *SDLCALL SDL_OpenSensor(SDL_SensorID instance_id);
 
 /**
- * Return the SDL_Sensor associated with an instance id.
+ * Return the SDL_Sensor associated with an instance ID.
  *
- * \param instance_id The sensor from instance id
+ * \param instance_id the sensor instance ID
  * \returns an SDL_Sensor object.
  *
  * \since This function is available since SDL 3.0.0.