SDL: Renamed SDL_AttachVirtualJoystickEx() to SDL_AttachVirtualJoystick()

From bcbf09acdef71b550e837c8aaca67b08b6a38f0f Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Thu, 9 May 2024 13:51:33 -0700
Subject: [PATCH] Renamed SDL_AttachVirtualJoystickEx() to
 SDL_AttachVirtualJoystick()

The shorthand version of this function didn't allow specifying a controller name, which seems pretty important. It seems like anyone actually implementing a virtual joystick is going to want to use some of the extended functionality.
---
 build-scripts/SDL_migration.cocci |  7 +------
 docs/README-migration.md          |  6 +++---
 include/SDL3/SDL_joystick.h       | 28 +++-------------------------
 include/SDL3/SDL_oldnames.h       |  6 ++----
 src/dynapi/SDL_dynapi.sym         |  3 +--
 src/dynapi/SDL_dynapi_overrides.h |  3 +--
 src/dynapi/SDL_dynapi_procs.h     |  5 ++---
 src/joystick/SDL_joystick.c       | 14 +-------------
 test/testautomation_joystick.c    |  6 +++---
 test/testcontroller.c             |  2 +-
 10 files changed, 18 insertions(+), 62 deletions(-)

diff --git a/build-scripts/SDL_migration.cocci b/build-scripts/SDL_migration.cocci
index dae96a779a6bc..42e29d0ea60de 100644
--- a/build-scripts/SDL_migration.cocci
+++ b/build-scripts/SDL_migration.cocci
@@ -1292,13 +1292,8 @@ typedef SDL_GameControllerButton, SDL_GamepadButton;
 + SDL_JOYSTICK_TYPE_GAMEPAD
 @@
 @@
-- SDL_JoystickAttachVirtual
-+ SDL_AttachVirtualJoystick
-  (...)
-@@
-@@
 - SDL_JoystickAttachVirtualEx
-+ SDL_AttachVirtualJoystickEx
++ SDL_AttachVirtualJoystick
   (...)
 @@
 @@
diff --git a/docs/README-migration.md b/docs/README-migration.md
index 268944b9c6e07..ee56c09fe94ce 100644
--- a/docs/README-migration.md
+++ b/docs/README-migration.md
@@ -794,13 +794,12 @@ The SDL_EVENT_JOYSTICK_ADDED event now provides the joystick instance ID in the
 
 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.
 
-SDL_AttachVirtualJoystick() and SDL_AttachVirtualJoystickEx() now return the joystick instance ID instead of a device index, and return 0 if there was an error.
+SDL_AttachVirtualJoystick() now returns the joystick instance ID instead of a device index, and returns 0 if there was an error.
 
 SDL_VirtualJoystickDesc no longer takes a struct version; if we need to extend this in the future, we'll make a second struct and a second SDL_AttachVirtualJoystickEx-style function that uses it. Just zero the struct and don't set a version.
 
 The following functions have been renamed:
-* SDL_JoystickAttachVirtual() => SDL_AttachVirtualJoystick()
-* SDL_JoystickAttachVirtualEx() => SDL_AttachVirtualJoystickEx()
+* SDL_JoystickAttachVirtualEx() => SDL_AttachVirtualJoystick()
 * SDL_JoystickClose() => SDL_CloseJoystick()
 * SDL_JoystickDetachVirtual() => SDL_DetachVirtualJoystick()
 * SDL_JoystickFromInstanceID() => SDL_GetJoystickFromInstanceID()
@@ -844,6 +843,7 @@ The following symbols have been renamed:
 * SDL_JOYSTICK_TYPE_GAMECONTROLLER => SDL_JOYSTICK_TYPE_GAMEPAD
 
 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()
diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h
index f0f12482f46f6..9c759f063b4f6 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -390,26 +390,6 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GetJoystickFromInstanceID(SDL_Joystick
  */
 extern DECLSPEC SDL_Joystick *SDLCALL SDL_GetJoystickFromPlayerIndex(int player_index);
 
-/**
- * Attach a new virtual joystick.
- *
- * \param type type of joystick
- * \param naxes number of axes
- * \param nbuttons number of buttons
- * \param nhats number of hats
- * \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.
- *
- * \sa SDL_AttachVirtualJoystickEx
- * \sa SDL_DetachVirtualJoystick
- */
-extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(SDL_JoystickType type,
-                                                      int naxes,
-                                                      int nbuttons,
-                                                      int nhats);
-
 /**
  * The structure that defines an extended virtual joystick description
  *
@@ -417,7 +397,7 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(SDL_JoystickTyp
  *
  * \since This struct is available since SDL 3.0.0.
  *
- * \sa SDL_AttachVirtualJoystickEx
+ * \sa SDL_AttachVirtualJoystick
  */
 typedef struct SDL_VirtualJoystickDesc
 {
@@ -444,7 +424,7 @@ typedef struct SDL_VirtualJoystickDesc
 } SDL_VirtualJoystickDesc;
 
 /**
- * Attach a new virtual joystick with extended properties.
+ * Attach a new virtual joystick.
  *
  * \param desc Joystick description
  * \returns the joystick instance ID, or 0 if an error occurred; call
@@ -452,10 +432,9 @@ typedef struct SDL_VirtualJoystickDesc
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_AttachVirtualJoystick
  * \sa SDL_DetachVirtualJoystick
  */
-extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystickEx(const SDL_VirtualJoystickDesc *desc);
+extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_VirtualJoystickDesc *desc);
 
 /**
  * Detach a virtual joystick.
@@ -468,7 +447,6 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystickEx(const SDL_Vir
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AttachVirtualJoystick
- * \sa SDL_AttachVirtualJoystickEx
  */
 extern DECLSPEC int SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id);
 
diff --git a/include/SDL3/SDL_oldnames.h b/include/SDL3/SDL_oldnames.h
index 4b9bc3893adb8..22946372f36c8 100644
--- a/include/SDL3/SDL_oldnames.h
+++ b/include/SDL3/SDL_oldnames.h
@@ -295,8 +295,7 @@
 
 /* ##SDL_joystick.h */
 #define SDL_JOYSTICK_TYPE_GAMECONTROLLER SDL_JOYSTICK_TYPE_GAMEPAD
-#define SDL_JoystickAttachVirtual SDL_AttachVirtualJoystick
-#define SDL_JoystickAttachVirtualEx SDL_AttachVirtualJoystickEx
+#define SDL_JoystickAttachVirtualEx SDL_AttachVirtualJoystick
 #define SDL_JoystickClose SDL_CloseJoystick
 #define SDL_JoystickDetachVirtual SDL_DetachVirtualJoystick
 #define SDL_JoystickFromInstanceID SDL_GetJoystickFromInstanceID
@@ -803,8 +802,7 @@
 
 /* ##SDL_joystick.h */
 #define SDL_JOYSTICK_TYPE_GAMECONTROLLER SDL_JOYSTICK_TYPE_GAMECONTROLLER_renamed_SDL_JOYSTICK_TYPE_GAMEPAD
-#define SDL_JoystickAttachVirtual SDL_JoystickAttachVirtual_renamed_SDL_AttachVirtualJoystick
-#define SDL_JoystickAttachVirtualEx SDL_JoystickAttachVirtualEx_renamed_SDL_AttachVirtualJoystickEx
+#define SDL_JoystickAttachVirtualEx SDL_JoystickAttachVirtualEx_renamed_SDL_AttachVirtualJoystick
 #define SDL_JoystickClose SDL_JoystickClose_renamed_SDL_CloseJoystick
 #define SDL_JoystickDetachVirtual SDL_JoystickDetachVirtual_renamed_SDL_DetachVirtualJoystick
 #define SDL_JoystickFromInstanceID SDL_JoystickFromInstanceID_renamed_SDL_GetJoystickFromInstanceID
diff --git a/src/dynapi/SDL_dynapi.sym b/src/dynapi/SDL_dynapi.sym
index 6f4c658e1e77b..0eec501b1e16c 100644
--- a/src/dynapi/SDL_dynapi.sym
+++ b/src/dynapi/SDL_dynapi.sym
@@ -28,7 +28,6 @@ SDL3_0.0.0 {
     SDL_AtomicSet;
     SDL_AtomicSetPtr;
     SDL_AttachVirtualJoystick;
-    SDL_AttachVirtualJoystickEx;
     SDL_AudioDevicePaused;
     SDL_BindAudioStream;
     SDL_BindAudioStreams;
@@ -203,6 +202,7 @@ SDL3_0.0.0 {
     SDL_GetCurrentTime;
     SDL_GetCurrentVideoDriver;
     SDL_GetCursor;
+    SDL_GetDateTimeLocalePreferences;
     SDL_GetDayOfWeek;
     SDL_GetDayOfYear;
     SDL_GetDaysInMonth;
@@ -1015,7 +1015,6 @@ SDL3_0.0.0 {
     SDL_wcsnstr;
     SDL_wcsstr;
     SDL_wcstol;
-    SDL_GetDateTimeLocalePreferences;
     # extra symbols go here (don't modify this line)
   local: *;
 };
diff --git a/src/dynapi/SDL_dynapi_overrides.h b/src/dynapi/SDL_dynapi_overrides.h
index bfd37314fa20f..7acba407509c9 100644
--- a/src/dynapi/SDL_dynapi_overrides.h
+++ b/src/dynapi/SDL_dynapi_overrides.h
@@ -53,7 +53,6 @@
 #define SDL_AtomicSet SDL_AtomicSet_REAL
 #define SDL_AtomicSetPtr SDL_AtomicSetPtr_REAL
 #define SDL_AttachVirtualJoystick SDL_AttachVirtualJoystick_REAL
-#define SDL_AttachVirtualJoystickEx SDL_AttachVirtualJoystickEx_REAL
 #define SDL_AudioDevicePaused SDL_AudioDevicePaused_REAL
 #define SDL_BindAudioStream SDL_BindAudioStream_REAL
 #define SDL_BindAudioStreams SDL_BindAudioStreams_REAL
@@ -228,6 +227,7 @@
 #define SDL_GetCurrentTime SDL_GetCurrentTime_REAL
 #define SDL_GetCurrentVideoDriver SDL_GetCurrentVideoDriver_REAL
 #define SDL_GetCursor SDL_GetCursor_REAL
+#define SDL_GetDateTimeLocalePreferences SDL_GetDateTimeLocalePreferences_REAL
 #define SDL_GetDayOfWeek SDL_GetDayOfWeek_REAL
 #define SDL_GetDayOfYear SDL_GetDayOfYear_REAL
 #define SDL_GetDaysInMonth SDL_GetDaysInMonth_REAL
@@ -1039,4 +1039,3 @@
 #define SDL_wcsnstr SDL_wcsnstr_REAL
 #define SDL_wcsstr SDL_wcsstr_REAL
 #define SDL_wcstol SDL_wcstol_REAL
-#define SDL_GetDateTimeLocalePreferences SDL_GetDateTimeLocalePreferences_REAL
diff --git a/src/dynapi/SDL_dynapi_procs.h b/src/dynapi/SDL_dynapi_procs.h
index 6d904fb16eff0..ba3e936bb537a 100644
--- a/src/dynapi/SDL_dynapi_procs.h
+++ b/src/dynapi/SDL_dynapi_procs.h
@@ -92,8 +92,7 @@ SDL_DYNAPI_PROC(int,SDL_AtomicGet,(SDL_AtomicInt *a),(a),return)
 SDL_DYNAPI_PROC(void*,SDL_AtomicGetPtr,(void **a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_AtomicSet,(SDL_AtomicInt *a, int b),(a,b),return)
 SDL_DYNAPI_PROC(void*,SDL_AtomicSetPtr,(void **a, void *b),(a,b),return)
-SDL_DYNAPI_PROC(SDL_JoystickID,SDL_AttachVirtualJoystick,(SDL_JoystickType a, int b, int c, int d),(a,b,c,d),return)
-SDL_DYNAPI_PROC(SDL_JoystickID,SDL_AttachVirtualJoystickEx,(const SDL_VirtualJoystickDesc *a),(a),return)
+SDL_DYNAPI_PROC(SDL_JoystickID,SDL_AttachVirtualJoystick,(const SDL_VirtualJoystickDesc *a),(a),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_AudioDevicePaused,(SDL_AudioDeviceID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_BindAudioStream,(SDL_AudioDeviceID a, SDL_AudioStream *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_BindAudioStreams,(SDL_AudioDeviceID a, SDL_AudioStream **b, int c),(a,b,c),return)
@@ -266,6 +265,7 @@ SDL_DYNAPI_PROC(SDL_ThreadID,SDL_GetCurrentThreadID,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_GetCurrentTime,(SDL_Time *a),(a),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetCurrentVideoDriver,(void),(),return)
 SDL_DYNAPI_PROC(SDL_Cursor*,SDL_GetCursor,(void),(),return)
+SDL_DYNAPI_PROC(int,SDL_GetDateTimeLocalePreferences,(SDL_DateFormat *a, SDL_TimeFormat *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_GetDayOfWeek,(int a, int b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(int,SDL_GetDayOfYear,(int a, int b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(int,SDL_GetDaysInMonth,(int a, int b),(a,b),return)
@@ -1055,4 +1055,3 @@ SDL_DYNAPI_PROC(size_t,SDL_wcsnlen,(const wchar_t *a, size_t b),(a,b),return)
 SDL_DYNAPI_PROC(wchar_t*,SDL_wcsnstr,(const wchar_t *a, const wchar_t *b, size_t c),(a,b,c),return)
 SDL_DYNAPI_PROC(wchar_t*,SDL_wcsstr,(const wchar_t *a, const wchar_t *b),(a,b),return)
 SDL_DYNAPI_PROC(long,SDL_wcstol,(const wchar_t *a, wchar_t **b, int c),(a,b,c),return)
-SDL_DYNAPI_PROC(int,SDL_GetDateTimeLocalePreferences,(SDL_DateFormat *a, SDL_TimeFormat *b),(a,b),return)
diff --git a/src/joystick/SDL_joystick.c b/src/joystick/SDL_joystick.c
index e79f216d160ae..fbd67bbd7c506 100644
--- a/src/joystick/SDL_joystick.c
+++ b/src/joystick/SDL_joystick.c
@@ -1167,19 +1167,7 @@ SDL_Joystick *SDL_OpenJoystick(SDL_JoystickID instance_id)
     return joystick;
 }
 
-SDL_JoystickID SDL_AttachVirtualJoystick(SDL_JoystickType type, int naxes, int nbuttons, int nhats)
-{
-    SDL_VirtualJoystickDesc desc;
-
-    SDL_zero(desc);
-    desc.type = (Uint16)type;
-    desc.naxes = (Uint16)naxes;
-    desc.nbuttons = (Uint16)nbuttons;
-    desc.nhats = (Uint16)nhats;
-    return SDL_AttachVirtualJoystickEx(&desc);
-}
-
-SDL_JoystickID SDL_AttachVirtualJoystickEx(const SDL_VirtualJoystickDesc *desc)
+SDL_JoystickID SDL_AttachVirtualJoystick(const SDL_VirtualJoystickDesc *desc)
 {
 #ifdef SDL_JOYSTICK_VIRTUAL
     SDL_JoystickID retval;
diff --git a/test/testautomation_joystick.c b/test/testautomation_joystick.c
index 226cc90228df1..9e9fdd297eaf1 100644
--- a/test/testautomation_joystick.c
+++ b/test/testautomation_joystick.c
@@ -14,7 +14,7 @@
 /**
  * Check virtual joystick creation
  *
- * \sa SDL_AttachVirtualJoystickEx
+ * \sa SDL_AttachVirtualJoystick
  */
 static int TestVirtualJoystick(void *arg)
 {
@@ -34,8 +34,8 @@ static int TestVirtualJoystick(void *arg)
     desc.vendor_id = USB_VENDOR_NVIDIA;
     desc.product_id = USB_PRODUCT_NVIDIA_SHIELD_CONTROLLER_V104;
     desc.name = "Virtual NVIDIA SHIELD Controller";
-    device_id = SDL_AttachVirtualJoystickEx(&desc);
-    SDLTest_AssertCheck(device_id > 0, "SDL_AttachVirtualJoystickEx()");
+    device_id = SDL_AttachVirtualJoystick(&desc);
+    SDLTest_AssertCheck(device_id > 0, "SDL_AttachVirtualJoystick()");
     SDLTest_AssertCheck(SDL_IsJoystickVirtual(device_id), "SDL_IsJoystickVirtual()");
     if (device_id > 0) {
         joystick = SDL_OpenJoystick(device_id);
diff --git a/test/testcontroller.c b/test/testcontroller.c
index 8c450ac6c3e91..038d765cdfeba 100644
--- a/test/testcontroller.c
+++ b/test/testcontroller.c
@@ -1125,7 +1125,7 @@ static void OpenVirtualGamepad(void)
     desc.RumbleTriggers = VirtualGamepadRumbleTriggers;
     desc.SetLED = VirtualGamepadSetLED;
 
-    virtual_id = SDL_AttachVirtualJoystickEx(&desc);
+    virtual_id = SDL_AttachVirtualJoystick(&desc);
     if (virtual_id == 0) {
         SDL_Log("Couldn't attach virtual device: %s\n", SDL_GetError());
     } else {