Skip to content

Commit

Permalink
Renamed *FromID() to *ForID()
Browse files Browse the repository at this point in the history 
While it makes sense to get an object pointer from an object ID, you want to get object attributes for an ID, otherwise e.g. GetNameFromID() sounds like it's a name ID, not an object ID. This is also consistent with the function naming convention in SDL2.
  • Loading branch information
@slouken
slouken committed Jul 14, 2024
1 parent 0cdc606 commit 2d7156b
Show file tree
Hide file tree
Showing 21 changed files with 215 additions and 215 deletions.
50 changes: 25 additions & 25 deletions docs/README-migration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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_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 functions SDL_GetGamepads(), SDL_GetGamepadNameForID(), SDL_GetGamepadPathForID(), SDL_GetGamepadPlayerIndexForID(), SDL_GetGamepadGUIDForID(), SDL_GetGamepadVendorForID(), SDL_GetGamepadProductForID(), SDL_GetGamepadProductVersionForID(), and SDL_GetGamepadTypeForID() 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:

Expand Down Expand Up @@ -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_GetGamepadMappingFromID()
* SDL_GameControllerMappingForDeviceIndex() - replaced with SDL_GetGamepadMappingForID()
* SDL_GameControllerMappingForIndex() - replaced with SDL_GetGamepadMappings()
* SDL_GameControllerNameForIndex() - replaced with SDL_GetGamepadNameFromID()
* SDL_GameControllerNameForIndex() - replaced with SDL_GetGamepadNameForID()
* SDL_GameControllerNumMappings() - replaced with SDL_GetGamepadMappings()
* SDL_GameControllerPathForIndex() - replaced with SDL_GetGamepadPathFromID()
* SDL_GameControllerTypeForIndex() - replaced with SDL_GetGamepadTypeFromID()
* SDL_GameControllerPathForIndex() - replaced with SDL_GetGamepadPathForID()
* SDL_GameControllerTypeForIndex() - replaced with SDL_GetGamepadTypeForID()

The following symbols have been renamed:
* SDL_CONTROLLER_AXIS_INVALID => SDL_GAMEPAD_AXIS_INVALID
Expand Down Expand Up @@ -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_GetHapticNameFromID(instance_id);
const char *name = SDL_GetHapticNameForID(instance_id);

SDL_Log("Haptic %" SDL_PRIu32 ": %s\n",
instance_id, name ? name : "Unknown");
Expand Down Expand Up @@ -742,7 +742,7 @@ The following functions have been renamed:

The following functions have been removed:
* SDL_HapticIndex() - replaced with SDL_GetHapticID()
* SDL_HapticName() - replaced with SDL_GetHapticNameFromID()
* SDL_HapticName() - replaced with SDL_GetHapticNameForID()
* SDL_HapticOpened() - replaced with SDL_GetHapticFromID()
* SDL_NumHaptics() - replaced with SDL_GetHaptics()

Expand Down Expand Up @@ -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_GetJoystickNameFromID(instance_id);
const char *path = SDL_GetJoystickPathFromID(instance_id);
const char *name = SDL_GetJoystickNameForID(instance_id);
const char *path = SDL_GetJoystickPathForID(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_GetJoystickVendorFromID(instance_id), SDL_GetJoystickProductFromID(instance_id));
instance_id, name ? name : "Unknown", path ? ", " : "", path ? path : "", SDL_GetJoystickVendorForID(instance_id), SDL_GetJoystickProductForID(instance_id));
}
SDL_free(joysticks);
}
Expand All @@ -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_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.
The functions SDL_GetJoysticks(), SDL_GetJoystickNameForID(), SDL_GetJoystickPathForID(), SDL_GetJoystickPlayerIndexForID(), SDL_GetJoystickGUIDForID(), SDL_GetJoystickVendorForID(), SDL_GetJoystickProductForID(), SDL_GetJoystickProductVersionForID(), and SDL_GetJoystickTypeForID() 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.

Expand Down Expand Up @@ -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_GetJoystickGUIDFromID()
* SDL_JoystickGetDeviceGUID() - replaced with SDL_GetJoystickGUIDForID()
* SDL_JoystickGetDeviceInstanceID()
* 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_JoystickGetDevicePlayerIndex() - replaced with SDL_GetJoystickPlayerIndexForID()
* SDL_JoystickGetDeviceProduct() - replaced with SDL_GetJoystickProductForID()
* SDL_JoystickGetDeviceProductVersion() - replaced with SDL_GetJoystickProductVersionForID()
* SDL_JoystickGetDeviceType() - replaced with SDL_GetJoystickTypeForID()
* SDL_JoystickGetDeviceVendor() - replaced with SDL_GetJoystickVendorForID()
* 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_GetJoystickNameFromID()
* SDL_JoystickPathForIndex() - replaced with SDL_GetJoystickPathFromID()
* SDL_JoystickNameForIndex() - replaced with SDL_GetJoystickNameForID()
* SDL_JoystickPathForIndex() - replaced with SDL_GetJoystickPathForID()
* SDL_NumJoysticks() - replaced with SDL_GetJoysticks()
* SDL_VIRTUAL_JOYSTICK_DESC_VERSION - no longer needed, version info has been removed from SDL_VirtualJoystickDesc.

Expand Down Expand Up @@ -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_GetSensorNameFromID(sensors[i]),
SDL_GetSensorTypeFromID(sensors[i]),
SDL_GetSensorNonPortableTypeFromID(sensors[i]));
SDL_GetSensorNameForID(sensors[i]),
SDL_GetSensorTypeForID(sensors[i]),
SDL_GetSensorNonPortableTypeForID(sensors[i]));
}
SDL_free(sensors);
}
Expand All @@ -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_GetSensorNameFromID()
* SDL_SensorGetDeviceNonPortableType() - replaced with SDL_GetSensorNonPortableTypeFromID()
* SDL_SensorGetDeviceType() - replaced with SDL_GetSensorTypeFromID()
* SDL_SensorGetDeviceName() - replaced with SDL_GetSensorNameForID()
* SDL_SensorGetDeviceNonPortableType() - replaced with SDL_GetSensorNonPortableTypeForID()
* SDL_SensorGetDeviceType() - replaced with SDL_GetSensorTypeForID()
* SDL_UnlockSensors()

## SDL_shape.h
Expand Down
42 changes: 21 additions & 21 deletions include/SDL3/SDL_gamepad.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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_GetJoystickGUIDFromID
* \sa SDL_GetJoystickGUIDForID
* \sa SDL_GetJoystickGUID
*/
extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_JoystickGUID guid);
Expand All @@ -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_GetGamepadMappingFromID
* \sa SDL_GetGamepadMappingForID
* \sa SDL_GetGamepadMappingForGUID
* \sa SDL_SetGamepadMapping
*/
Expand Down Expand Up @@ -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_GetGamepadNameFromID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID instance_id);

/**
* Get the implementation dependent path of a gamepad.
Expand All @@ -529,7 +529,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadNameFromID(SDL_JoystickID
* \sa SDL_GetGamepadPath
* \sa SDL_GetGamepads
*/
extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadPathFromID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadPathForID(SDL_JoystickID instance_id);

/**
* Get the player index of a gamepad.
Expand All @@ -544,7 +544,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadPathFromID(SDL_JoystickID
* \sa SDL_GetGamepadPlayerIndex
* \sa SDL_GetGamepads
*/
extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexFromID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexForID(SDL_JoystickID instance_id);

/**
* Get the implementation-dependent GUID of a gamepad.
Expand All @@ -561,7 +561,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexFromID(SDL_JoystickID i
* \sa SDL_GetGamepadGUIDString
* \sa SDL_GetGamepads
*/
extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadGUIDFromID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadGUIDForID(SDL_JoystickID instance_id);

/**
* Get the USB vendor ID of a gamepad, if available.
Expand All @@ -578,7 +578,7 @@ extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadGUIDFromID(SDL_Joysti
* \sa SDL_GetGamepadVendor
* \sa SDL_GetGamepads
*/
extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorFromID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorForID(SDL_JoystickID instance_id);

/**
* Get the USB product ID of a gamepad, if available.
Expand All @@ -595,7 +595,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorFromID(SDL_JoystickID ins
* \sa SDL_GetGamepadProduct
* \sa SDL_GetGamepads
*/
extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductFromID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductForID(SDL_JoystickID instance_id);

/**
* Get the product version of a gamepad, if available.
Expand All @@ -612,7 +612,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductFromID(SDL_JoystickID in
* \sa SDL_GetGamepadProductVersion
* \sa SDL_GetGamepads
*/
extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionFromID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionForID(SDL_JoystickID instance_id);

/**
* Get the type of a gamepad.
Expand All @@ -626,9 +626,9 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionFromID(SDL_Joysti
*
* \sa SDL_GetGamepadType
* \sa SDL_GetGamepads
* \sa SDL_GetRealGamepadTypeFromID
* \sa SDL_GetRealGamepadTypeForID
*/
extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeForID(SDL_JoystickID instance_id);

/**
* Get the type of a gamepad, ignoring any mapping override.
Expand All @@ -640,11 +640,11 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromID(SDL_Joystic
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetGamepadTypeFromID
* \sa SDL_GetGamepadTypeForID
* \sa SDL_GetGamepads
* \sa SDL_GetRealGamepadType
*/
extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeFromID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_JoystickID instance_id);

/**
* Get the mapping of a gamepad.
Expand All @@ -660,7 +660,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeFromID(SDL_Joy
* \sa SDL_GetGamepads
* \sa SDL_GetGamepadMapping
*/
extern SDL_DECLSPEC char *SDLCALL SDL_GetGamepadMappingFromID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC char *SDLCALL SDL_GetGamepadMappingForID(SDL_JoystickID instance_id);

/**
* Open a gamepad for use.
Expand Down Expand Up @@ -758,7 +758,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetGamepadNameFromID
* \sa SDL_GetGamepadNameForID
*/
extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad);

Expand All @@ -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_GetGamepadPathFromID
* \sa SDL_GetGamepadPathForID
*/
extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad);

Expand All @@ -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_GetGamepadTypeFromID
* \sa SDL_GetGamepadTypeForID
*/
extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *gamepad);

Expand All @@ -800,7 +800,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *game
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetRealGamepadTypeFromID
* \sa SDL_GetRealGamepadTypeForID
*/
extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadType(SDL_Gamepad *gamepad);

Expand Down Expand Up @@ -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_GetGamepadVendorFromID
* \sa SDL_GetGamepadVendorForID
*/
extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad);

Expand All @@ -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_GetGamepadProductFromID
* \sa SDL_GetGamepadProductForID
*/
extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad);

Expand All @@ -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_GetGamepadProductVersionFromID
* \sa SDL_GetGamepadProductVersionForID
*/
extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersion(SDL_Gamepad *gamepad);

Expand Down
4 changes: 2 additions & 2 deletions include/SDL3/SDL_haptic.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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_GetHapticNameFromID(SDL_HapticID instance_id);
extern SDL_DECLSPEC const char *SDLCALL SDL_GetHapticNameForID(SDL_HapticID instance_id);

/**
* Open a haptic device for use.
Expand Down Expand Up @@ -1023,7 +1023,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic);
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetHapticNameFromID
* \sa SDL_GetHapticNameForID
*/
extern SDL_DECLSPEC const char *SDLCALL SDL_GetHapticName(SDL_Haptic *haptic);

Expand Down
Loading

0 comments on commit 2d7156b

Please sign in to comment.