Renamed functions to get information from device IDs

Fixes libsdl-org#10237

docs/README-migration.md

@@ -461,7 +461,7 @@ SDL_gamecontroller.h has been renamed SDL_gamepad.h, and all APIs have been rena
 
 The SDL_EVENT_GAMEPAD_ADDED event now provides the joystick instance ID in the which member of the cdevice event structure.
 
-The functions SDL_GetGamepads(), SDL_GetGamepadInstanceName(), SDL_GetGamepadInstancePath(), SDL_GetGamepadInstancePlayerIndex(), SDL_GetGamepadInstanceGUID(), SDL_GetGamepadInstanceVendor(), SDL_GetGamepadInstanceProduct(), SDL_GetGamepadInstanceProductVersion(), and SDL_GetGamepadInstanceType() have been added to directly query the list of available gamepads.
+The functions SDL_GetGamepads(), SDL_GetGamepadNameFromID(), SDL_GetGamepadPathFromID(), SDL_GetGamepadPlayerIndexFromID(), SDL_GetGamepadGUIDFromID(), SDL_GetGamepadVendorFromID(), SDL_GetGamepadProductFromID(), SDL_GetGamepadProductVersionFromID(), and SDL_GetGamepadTypeFromID() have been added to directly query the list of available gamepads.
 
 The gamepad face buttons have been renamed from A/B/X/Y to North/South/East/West to indicate that they are positional rather than hardware-specific. You can use SDL_GetGamepadButtonLabel() to get the labels for the face buttons, e.g. A/B/X/Y or Cross/Circle/Square/Triangle. The hint SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS is ignored, and mappings that use this hint are translated correctly into positional buttons. Applications should provide a way for users to swap between South/East as their accept/cancel buttons, as this varies based on region and muscle memory. You can use an approach similar to the following to handle this:
 
@@ -624,12 +624,12 @@ The following functions have been removed:
 * SDL_GameControllerHasLED() - replaced with SDL_PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN
 * SDL_GameControllerHasRumble() - replaced with SDL_PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN
 * SDL_GameControllerHasRumbleTriggers() - replaced with SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN
-* SDL_GameControllerMappingForDeviceIndex() - replaced with SDL_GetGamepadInstanceMapping()
+* SDL_GameControllerMappingForDeviceIndex() - replaced with SDL_GetGamepadMappingFromID()
 * SDL_GameControllerMappingForIndex() - replaced with SDL_GetGamepadMappings()
-* SDL_GameControllerNameForIndex() - replaced with SDL_GetGamepadInstanceName()
+* SDL_GameControllerNameForIndex() - replaced with SDL_GetGamepadNameFromID()
 * SDL_GameControllerNumMappings() - replaced with SDL_GetGamepadMappings()
-* SDL_GameControllerPathForIndex() - replaced with SDL_GetGamepadInstancePath()
-* SDL_GameControllerTypeForIndex() - replaced with SDL_GetGamepadInstanceType()
+* SDL_GameControllerPathForIndex() - replaced with SDL_GetGamepadPathFromID()
+* SDL_GameControllerTypeForIndex() - replaced with SDL_GetGamepadTypeFromID()
 
 The following symbols have been renamed:
 * SDL_CONTROLLER_AXIS_INVALID => SDL_GAMEPAD_AXIS_INVALID
@@ -700,7 +700,7 @@ Rather than iterating over haptic devices using device index, there is a new fun
         if (haptics) {
             for (i = 0; i < num_haptics; ++i) {
                 SDL_HapticID instance_id = haptics[i];
-                const char *name = SDL_GetHapticInstanceName(instance_id);
+                const char *name = SDL_GetHapticNameFromID(instance_id);
 
                 SDL_Log("Haptic %" SDL_PRIu32 ": %s\n",
                         instance_id, name ? name : "Unknown");
@@ -741,8 +741,8 @@ The following functions have been renamed:
 * SDL_MouseIsHaptic() => SDL_IsMouseHaptic()
 
 The following functions have been removed:
-* SDL_HapticIndex() - replaced with SDL_GetHapticInstanceID()
-* SDL_HapticName() - replaced with SDL_GetHapticInstanceName()
+* SDL_HapticIndex() - replaced with SDL_GetHapticID()
+* SDL_HapticName() - replaced with SDL_GetHapticNameFromID()
 * SDL_HapticOpened() - replaced with SDL_GetHapticFromInstanceID()
 * SDL_NumHaptics() - replaced with SDL_GetHaptics()
 
@@ -830,11 +830,11 @@ Rather than iterating over joysticks using device index, there is a new function
         if (joysticks) {
             for (i = 0; i < num_joysticks; ++i) {
                 SDL_JoystickID instance_id = joysticks[i];
-                const char *name = SDL_GetJoystickInstanceName(instance_id);
-                const char *path = SDL_GetJoystickInstancePath(instance_id);
+                const char *name = SDL_GetJoystickNameFromID(instance_id);
+                const char *path = SDL_GetJoystickPathFromID(instance_id);
 
                 SDL_Log("Joystick %" SDL_PRIu32 ": %s%s%s VID 0x%.4x, PID 0x%.4x\n",
-                        instance_id, name ? name : "Unknown", path ? ", " : "", path ? path : "", SDL_GetJoystickInstanceVendor(instance_id), SDL_GetJoystickInstanceProduct(instance_id));
+                        instance_id, name ? name : "Unknown", path ? ", " : "", path ? path : "", SDL_GetJoystickVendorFromID(instance_id), SDL_GetJoystickProductFromID(instance_id));
             }
             SDL_free(joysticks);
         }
@@ -845,7 +845,7 @@ Rather than iterating over joysticks using device index, there is a new function
 
 The SDL_EVENT_JOYSTICK_ADDED event now provides the joystick instance ID in the `which` member of the jdevice event structure.
 
-The functions SDL_GetJoysticks(), SDL_GetJoystickInstanceName(), SDL_GetJoystickInstancePath(), SDL_GetJoystickInstancePlayerIndex(), SDL_GetJoystickInstanceGUID(), SDL_GetJoystickInstanceVendor(), SDL_GetJoystickInstanceProduct(), SDL_GetJoystickInstanceProductVersion(), and SDL_GetJoystickInstanceType() have been added to directly query the list of available joysticks.
+The functions SDL_GetJoysticks(), SDL_GetJoystickNameFromID(), SDL_GetJoystickPathFromID(), SDL_GetJoystickPlayerIndexFromID(), SDL_GetJoystickGUIDFromID(), SDL_GetJoystickVendorFromID(), SDL_GetJoystickProductFromID(), SDL_GetJoystickProductVersionFromID(), and SDL_GetJoystickTypeFromID() have been added to directly query the list of available joysticks.
 
 SDL_AttachVirtualJoystick() now returns the joystick instance ID instead of a device index, and returns 0 if there was an error.
 
@@ -873,7 +873,7 @@ The following functions have been renamed:
 * SDL_JoystickGetSerial() => SDL_GetJoystickSerial()
 * SDL_JoystickGetType() => SDL_GetJoystickType()
 * SDL_JoystickGetVendor() => SDL_GetJoystickVendor()
-* SDL_JoystickInstanceID() => SDL_GetJoystickInstanceID()
+* SDL_JoystickInstanceID() => SDL_GetJoystickID()
 * SDL_JoystickIsVirtual() => SDL_IsJoystickVirtual()
 * SDL_JoystickName() => SDL_GetJoystickName()
 * SDL_JoystickNumAxes() => SDL_GetNumJoystickAxes()
@@ -899,18 +899,18 @@ The following functions have been removed:
 * SDL_JoystickAttachVirtual() - replaced with SDL_AttachVirtualJoystick()
 * SDL_JoystickCurrentPowerLevel() - replaced with SDL_GetJoystickConnectionState() and SDL_GetJoystickPowerInfo()
 * SDL_JoystickEventState() - replaced with SDL_SetJoystickEventsEnabled() and SDL_JoystickEventsEnabled()
-* SDL_JoystickGetDeviceGUID() - replaced with SDL_GetJoystickInstanceGUID()
+* SDL_JoystickGetDeviceGUID() - replaced with SDL_GetJoystickGUIDFromID()
 * SDL_JoystickGetDeviceInstanceID()
-* SDL_JoystickGetDevicePlayerIndex() - replaced with SDL_GetJoystickInstancePlayerIndex()
-* SDL_JoystickGetDeviceProduct() - replaced with SDL_GetJoystickInstanceProduct()
-* SDL_JoystickGetDeviceProductVersion() - replaced with SDL_GetJoystickInstanceProductVersion()
-* SDL_JoystickGetDeviceType() - replaced with SDL_GetJoystickInstanceType()
-* SDL_JoystickGetDeviceVendor() - replaced with SDL_GetJoystickInstanceVendor()
+* SDL_JoystickGetDevicePlayerIndex() - replaced with SDL_GetJoystickPlayerIndexFromID()
+* SDL_JoystickGetDeviceProduct() - replaced with SDL_GetJoystickProductFromID()
+* SDL_JoystickGetDeviceProductVersion() - replaced with SDL_GetJoystickProductVersionFromID()
+* SDL_JoystickGetDeviceType() - replaced with SDL_GetJoystickTypeFromID()
+* SDL_JoystickGetDeviceVendor() - replaced with SDL_GetJoystickVendorFromID()
 * SDL_JoystickHasLED() - replaced with SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN
 * SDL_JoystickHasRumble() - replaced with SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN
 * SDL_JoystickHasRumbleTriggers() - replaced with SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN
-* SDL_JoystickNameForIndex() - replaced with SDL_GetJoystickInstanceName()
-* SDL_JoystickPathForIndex() - replaced with SDL_GetJoystickInstancePath()
+* SDL_JoystickNameForIndex() - replaced with SDL_GetJoystickNameFromID()
+* SDL_JoystickPathForIndex() - replaced with SDL_GetJoystickPathFromID()
 * SDL_NumJoysticks() - replaced with SDL_GetJoysticks()
 * SDL_VIRTUAL_JOYSTICK_DESC_VERSION - no longer needed, version info has been removed from SDL_VirtualJoystickDesc.
 
@@ -1571,9 +1571,9 @@ Rather than iterating over sensors using device index, there is a new function S
             for (i = 0; i < num_sensors; ++i) {
                 SDL_Log("Sensor %" SDL_PRIu32 ": %s, type %d, platform type %d\n",
                         sensors[i],
-                        SDL_GetSensorInstanceName(sensors[i]),
-                        SDL_GetSensorInstanceType(sensors[i]),
-                        SDL_GetSensorInstanceNonPortableType(sensors[i]));
+                        SDL_GetSensorNameFromID(sensors[i]),
+                        SDL_GetSensorTypeFromID(sensors[i]),
+                        SDL_GetSensorNonPortableTypeFromID(sensors[i]));
             }
             SDL_free(sensors);
         }
@@ -1589,7 +1589,7 @@ The following functions have been renamed:
 * SDL_SensorClose() => SDL_CloseSensor()
 * SDL_SensorFromInstanceID() => SDL_GetSensorFromInstanceID()
 * SDL_SensorGetData() => SDL_GetSensorData()
-* SDL_SensorGetInstanceID() => SDL_GetSensorInstanceID()
+* SDL_SensorGetInstanceID() => SDL_GetSensorID()
 * SDL_SensorGetName() => SDL_GetSensorName()
 * SDL_SensorGetNonPortableType() => SDL_GetSensorNonPortableType()
 * SDL_SensorGetType() => SDL_GetSensorType()
@@ -1600,9 +1600,9 @@ The following functions have been removed:
 * SDL_LockSensors()
 * SDL_NumSensors() - replaced with SDL_GetSensors()
 * SDL_SensorGetDeviceInstanceID()
-* SDL_SensorGetDeviceName() - replaced with SDL_GetSensorInstanceName()
-* SDL_SensorGetDeviceNonPortableType() - replaced with SDL_GetSensorInstanceNonPortableType()
-* SDL_SensorGetDeviceType() - replaced with SDL_GetSensorInstanceType()
+* SDL_SensorGetDeviceName() - replaced with SDL_GetSensorNameFromID()
+* SDL_SensorGetDeviceNonPortableType() - replaced with SDL_GetSensorNonPortableTypeFromID()
+* SDL_SensorGetDeviceType() - replaced with SDL_GetSensorTypeFromID()
 * SDL_UnlockSensors()
 
 ## SDL_shape.h

include/SDL3/SDL_gamepad.h

@@ -412,7 +412,7 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count);
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetJoystickInstanceGUID
+ * \sa SDL_GetJoystickGUIDFromID
  * \sa SDL_GetJoystickGUID
  */
 extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_JoystickGUID guid);
@@ -431,7 +431,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_JoystickGUID
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AddGamepadMapping
- * \sa SDL_GetGamepadInstanceMapping
+ * \sa SDL_GetGamepadMappingFromID
  * \sa SDL_GetGamepadMappingForGUID
  * \sa SDL_SetGamepadMapping
  */
@@ -511,7 +511,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id);
  * \sa SDL_GetGamepadName
  * \sa SDL_GetGamepads
  */
-extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadInstanceName(SDL_JoystickID instance_id);
+extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadNameFromID(SDL_JoystickID instance_id);
 
 /**
  * Get the implementation dependent path of a gamepad.
@@ -529,7 +529,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadInstanceName(SDL_JoystickI
  * \sa SDL_GetGamepadPath
  * \sa SDL_GetGamepads
  */
-extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadInstancePath(SDL_JoystickID instance_id);
+extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadPathFromID(SDL_JoystickID instance_id);
 
 /**
  * Get the player index of a gamepad.
@@ -544,7 +544,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadInstancePath(SDL_JoystickI
  * \sa SDL_GetGamepadPlayerIndex
  * \sa SDL_GetGamepads
  */
-extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadInstancePlayerIndex(SDL_JoystickID instance_id);
+extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexFromID(SDL_JoystickID instance_id);
 
 /**
  * Get the implementation-dependent GUID of a gamepad.
@@ -561,7 +561,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadInstancePlayerIndex(SDL_JoystickID
  * \sa SDL_GetGamepadGUIDString
  * \sa SDL_GetGamepads
  */
-extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadInstanceGUID(SDL_JoystickID instance_id);
+extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadGUIDFromID(SDL_JoystickID instance_id);
 
 /**
  * Get the USB vendor ID of a gamepad, if available.
@@ -578,7 +578,7 @@ extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadInstanceGUID(SDL_Joys
  * \sa SDL_GetGamepadVendor
  * \sa SDL_GetGamepads
  */
-extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceVendor(SDL_JoystickID instance_id);
+extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorFromID(SDL_JoystickID instance_id);
 
 /**
  * Get the USB product ID of a gamepad, if available.
@@ -595,7 +595,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceVendor(SDL_JoystickID i
  * \sa SDL_GetGamepadProduct
  * \sa SDL_GetGamepads
  */
-extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceProduct(SDL_JoystickID instance_id);
+extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductFromID(SDL_JoystickID instance_id);
 
 /**
  * Get the product version of a gamepad, if available.
@@ -612,7 +612,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceProduct(SDL_JoystickID
  * \sa SDL_GetGamepadProductVersion
  * \sa SDL_GetGamepads
  */
-extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceProductVersion(SDL_JoystickID instance_id);
+extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionFromID(SDL_JoystickID instance_id);
 
 /**
  * Get the type of a gamepad.
@@ -628,7 +628,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceProductVersion(SDL_Joys
  * \sa SDL_GetGamepads
  * \sa SDL_GetRealGamepadInstanceType
  */
-extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadInstanceType(SDL_JoystickID instance_id);
+extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromID(SDL_JoystickID instance_id);
 
 /**
  * Get the type of a gamepad, ignoring any mapping override.
@@ -640,7 +640,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadInstanceType(SDL_Joyst
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetGamepadInstanceType
+ * \sa SDL_GetGamepadTypeFromID
  * \sa SDL_GetGamepads
  * \sa SDL_GetRealGamepadType
  */
@@ -660,7 +660,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadInstanceType(SDL_J
  * \sa SDL_GetGamepads
  * \sa SDL_GetGamepadMapping
  */
-extern SDL_DECLSPEC char *SDLCALL SDL_GetGamepadInstanceMapping(SDL_JoystickID instance_id);
+extern SDL_DECLSPEC char *SDLCALL SDL_GetGamepadMappingFromID(SDL_JoystickID instance_id);
 
 /**
  * Open a gamepad for use.
@@ -744,7 +744,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepa
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadInstanceID(SDL_Gamepad *gamepad);
+extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad);
 
 /**
  * Get the implementation-dependent name for an opened gamepad.
@@ -758,7 +758,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadInstanceID(SDL_Gamepad
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetGamepadInstanceName
+ * \sa SDL_GetGamepadNameFromID
  */
 extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad);
 
@@ -774,7 +774,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad)
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetGamepadInstancePath
+ * \sa SDL_GetGamepadPathFromID
  */
 extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad);
 
@@ -787,7 +787,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad)
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetGamepadInstanceType
+ * \sa SDL_GetGamepadTypeFromID
  */
 extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *gamepad);
 
@@ -843,7 +843,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad,
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetGamepadInstanceVendor
+ * \sa SDL_GetGamepadVendorFromID
  */
 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad);
 
@@ -857,7 +857,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad);
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetGamepadInstanceProduct
+ * \sa SDL_GetGamepadProductFromID
  */
 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad);
 
@@ -871,7 +871,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad);
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetGamepadInstanceProductVersion
+ * \sa SDL_GetGamepadProductVersionFromID
  */
 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersion(SDL_Gamepad *gamepad);
 

include/SDL3/SDL_haptic.h

@@ -961,7 +961,7 @@ extern SDL_DECLSPEC SDL_HapticID *SDLCALL SDL_GetHaptics(int *count);
  * \sa SDL_GetHapticName
  * \sa SDL_OpenHaptic
  */
-extern SDL_DECLSPEC const char *SDLCALL SDL_GetHapticInstanceName(SDL_HapticID instance_id);
+extern SDL_DECLSPEC const char *SDLCALL SDL_GetHapticNameFromID(SDL_HapticID instance_id);
 
 /**
  * Open a haptic device for use.
@@ -1009,7 +1009,7 @@ extern SDL_DECLSPEC SDL_Haptic *SDLCALL SDL_GetHapticFromInstanceID(SDL_HapticID
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticInstanceID(SDL_Haptic *haptic);
+extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic);
 
 /**
  * Get the implementation dependent name of a haptic device.
@@ -1023,7 +1023,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticInstanceID(SDL_Haptic *hap
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetHapticInstanceName
+ * \sa SDL_GetHapticNameFromID
  */
 extern SDL_DECLSPEC const char *SDLCALL SDL_GetHapticName(SDL_Haptic *haptic);