From f224af5ac502865ebb986d50ea656e33922fbc13 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Wed, 17 Jan 2024 15:22:35 -0800
Subject: [PATCH] Updated Haptic API for SDL 3.0 conventions
Also removed the XInput haptic support since using the haptic API for rumble is no longer supported.
---
CMakeLists.txt | 14 +-
VisualC-GDK/SDL/SDL.vcxproj | 13 +-
VisualC-GDK/SDL/SDL.vcxproj.filters | 4 +-
VisualC-WinRT/SDL-UWP.vcxproj | 2 -
VisualC-WinRT/SDL-UWP.vcxproj.filters | 6 -
VisualC/SDL/SDL.vcxproj | 2 -
VisualC/SDL/SDL.vcxproj.filters | 6 -
build-scripts/SDL_migration.cocci | 120 +++++
docs/README-migration.md | 59 +++
include/SDL3/SDL_haptic.h | 336 ++++++-------
include/SDL3/SDL_oldnames.h | 52 ++
include/build_config/SDL_build_config.h.cmake | 1 -
.../build_config/SDL_build_config_windows.h | 1 -
.../build_config/SDL_build_config_wingdk.h | 1 -
include/build_config/SDL_build_config_winrt.h | 1 -
include/build_config/SDL_build_config_xbox.h | 1 -
src/dynapi/SDL_dynapi.sym | 57 +--
src/dynapi/SDL_dynapi_overrides.h | 57 +--
src/dynapi/SDL_dynapi_procs.h | 61 +--
src/haptic/SDL_haptic.c | 445 +++++++-----------
src/haptic/SDL_syshaptic.h | 26 +-
src/haptic/android/SDL_syshaptic.c | 37 +-
src/haptic/darwin/SDL_syshaptic.c | 40 +-
src/haptic/dummy/SDL_syshaptic.c | 6 +
src/haptic/linux/SDL_syshaptic.c | 66 ++-
src/haptic/windows/SDL_dinputhaptic.c | 14 +-
src/haptic/windows/SDL_windowshaptic.c | 159 ++-----
src/haptic/windows/SDL_windowshaptic_c.h | 12 +-
src/haptic/windows/SDL_xinputhaptic.c | 443 -----------------
src/haptic/windows/SDL_xinputhaptic_c.h | 53 ---
src/joystick/darwin/SDL_iokitjoystick.c | 2 +-
src/joystick/windows/SDL_windowsjoystick.c | 13 +-
test/testhaptic.c | 83 ++--
test/testhotplug.c | 19 +-
test/testrumble.c | 51 +-
35 files changed, 943 insertions(+), 1320 deletions(-)
delete mode 100644 src/haptic/windows/SDL_xinputhaptic.c
delete mode 100644 src/haptic/windows/SDL_xinputhaptic_c.h
diff --git a/CMakeLists.txt b/CMakeLists.txt
index f28a28ca141a..681eb11a1bcb 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1981,19 +1981,11 @@ elseif(WINDOWS)
set(HAVE_SDL_JOYSTICK TRUE)
if(SDL_HAPTIC)
- if((HAVE_DINPUT_H OR HAVE_XINPUT_H) AND NOT WINDOWS_STORE)
+ if(HAVE_DINPUT_H AND NOT WINDOWS_STORE)
sdl_glob_sources("${SDL3_SOURCE_DIR}/src/haptic/windows/*.c")
- if(HAVE_DINPUT_H)
- set(SDL_HAPTIC_DINPUT 1)
- endif()
- if(HAVE_XINPUT_H)
- set(SDL_HAPTIC_XINPUT 1)
- endif()
- else()
- sdl_glob_sources("${SDL3_SOURCE_DIR}/src/haptic/dummy/*.c")
- set(SDL_HAPTIC_DUMMY 1)
+ set(SDL_HAPTIC_DINPUT 1)
+ set(HAVE_SDL_HAPTIC TRUE)
endif()
- set(HAVE_SDL_HAPTIC TRUE)
endif()
endif()
diff --git a/VisualC-GDK/SDL/SDL.vcxproj b/VisualC-GDK/SDL/SDL.vcxproj
index c7fa0a28db57..d579a1099b69 100644
--- a/VisualC-GDK/SDL/SDL.vcxproj
+++ b/VisualC-GDK/SDL/SDL.vcxproj
@@ -422,7 +422,6 @@
<ClInclude Include="..\..\src\haptic\SDL_syshaptic.h" />
<ClInclude Include="..\..\src\haptic\windows\SDL_dinputhaptic_c.h" />
<ClInclude Include="..\..\src\haptic\windows\SDL_windowshaptic_c.h" />
- <ClInclude Include="..\..\src\haptic\windows\SDL_xinputhaptic_c.h" />
<ClInclude Include="..\..\src\hidapi\hidapi\hidapi.h" />
<ClInclude Include="..\..\src\hidapi\SDL_hidapi_c.h" />
<ClInclude Include="..\..\src\joystick\controller_type.h" />
@@ -636,16 +635,6 @@
<LanguageStandard Condition="'$(Configuration)|$(Platform)'=='Release|Gaming.Xbox.Scarlett.x64'">stdcpp17</LanguageStandard>
<LanguageStandard Condition="'$(Configuration)|$(Platform)'=='Release|Gaming.Xbox.XboxOne.x64'">stdcpp17</LanguageStandard>
</ClCompile>
- <ClCompile Include="..\..\src\haptic\windows\SDL_xinputhaptic.c">
- <LanguageStandard Condition="'$(Configuration)|$(Platform)'=='Debug|Gaming.Xbox.Scarlett.x64'">stdcpp17</LanguageStandard>
- <LanguageStandard Condition="'$(Configuration)|$(Platform)'=='Debug|Gaming.Xbox.XboxOne.x64'">stdcpp17</LanguageStandard>
- <LanguageStandard Condition="'$(Configuration)|$(Platform)'=='Release|Gaming.Xbox.Scarlett.x64'">stdcpp17</LanguageStandard>
- <LanguageStandard Condition="'$(Configuration)|$(Platform)'=='Release|Gaming.Xbox.XboxOne.x64'">stdcpp17</LanguageStandard>
- <CompileAs Condition="'$(Configuration)|$(Platform)'=='Debug|Gaming.Xbox.Scarlett.x64'">CompileAsCpp</CompileAs>
- <CompileAs Condition="'$(Configuration)|$(Platform)'=='Debug|Gaming.Xbox.XboxOne.x64'">CompileAsCpp</CompileAs>
- <CompileAs Condition="'$(Configuration)|$(Platform)'=='Release|Gaming.Xbox.Scarlett.x64'">CompileAsCpp</CompileAs>
- <CompileAs Condition="'$(Configuration)|$(Platform)'=='Release|Gaming.Xbox.XboxOne.x64'">CompileAsCpp</CompileAs>
- </ClCompile>
<ClCompile Include="..\..\src\hidapi\SDL_hidapi.c" />
<ClCompile Include="..\..\src\joystick\controller_type.c" />
<ClCompile Include="..\..\src\joystick\dummy\SDL_sysjoystick.c" />
@@ -834,4 +823,4 @@
<ImportGroup Label="ExtensionTargets">
<Import Project="$(VCTargetsPath)\BuildCustomizations\masm.targets" />
</ImportGroup>
-</Project>
\ No newline at end of file
+</Project>
diff --git a/VisualC-GDK/SDL/SDL.vcxproj.filters b/VisualC-GDK/SDL/SDL.vcxproj.filters
index 4692d46846ed..4414dd92f898 100644
--- a/VisualC-GDK/SDL/SDL.vcxproj.filters
+++ b/VisualC-GDK/SDL/SDL.vcxproj.filters
@@ -49,7 +49,6 @@
<ClCompile Include="..\..\src\haptic\SDL_haptic.c" />
<ClCompile Include="..\..\src\haptic\windows\SDL_dinputhaptic.c" />
<ClCompile Include="..\..\src\haptic\windows\SDL_windowshaptic.c" />
- <ClCompile Include="..\..\src\haptic\windows\SDL_xinputhaptic.c" />
<ClCompile Include="..\..\src\hidapi\SDL_hidapi.c" />
<ClCompile Include="..\..\src\joystick\controller_type.c" />
<ClCompile Include="..\..\src\joystick\dummy\SDL_sysjoystick.c" />
@@ -313,7 +312,6 @@
<ClInclude Include="..\..\src\haptic\SDL_syshaptic.h" />
<ClInclude Include="..\..\src\haptic\windows\SDL_dinputhaptic_c.h" />
<ClInclude Include="..\..\src\haptic\windows\SDL_windowshaptic_c.h" />
- <ClInclude Include="..\..\src\haptic\windows\SDL_xinputhaptic_c.h" />
<ClInclude Include="..\..\src\hidapi\hidapi\hidapi.h" />
<ClInclude Include="..\..\src\hidapi\SDL_hidapi_c.h" />
<ClInclude Include="..\..\src\joystick\controller_type.h" />
@@ -433,4 +431,4 @@
<ItemGroup>
<ResourceCompile Include="..\..\src\core\windows\version.rc" />
</ItemGroup>
-</Project>
\ No newline at end of file
+</Project>
diff --git a/VisualC-WinRT/SDL-UWP.vcxproj b/VisualC-WinRT/SDL-UWP.vcxproj
index 715c6020448c..4f5267b90fa1 100644
--- a/VisualC-WinRT/SDL-UWP.vcxproj
+++ b/VisualC-WinRT/SDL-UWP.vcxproj
@@ -122,7 +122,6 @@
<ClInclude Include="..\src\haptic\SDL_syshaptic.h" />
<ClInclude Include="..\src\haptic\windows\SDL_dinputhaptic_c.h" />
<ClInclude Include="..\src\haptic\windows\SDL_windowshaptic_c.h" />
- <ClInclude Include="..\src\haptic\windows\SDL_xinputhaptic_c.h" />
<ClInclude Include="..\src\joystick\controller_type.h" />
<ClInclude Include="..\src\joystick\SDL_gamepad_c.h" />
<ClInclude Include="..\src\joystick\SDL_gamepad_db.h" />
@@ -326,7 +325,6 @@
<ClCompile Include="..\src\haptic\SDL_haptic.c" />
<ClCompile Include="..\src\haptic\windows\SDL_dinputhaptic.c" />
<ClCompile Include="..\src\haptic\windows\SDL_windowshaptic.c" />
- <ClCompile Include="..\src\haptic\windows\SDL_xinputhaptic.c" />
<ClCompile Include="..\src\hidapi\SDL_hidapi.c" />
<ClCompile Include="..\src\joystick\dummy\SDL_sysjoystick.c" />
<ClCompile Include="..\src\joystick\controller_type.c" />
diff --git a/VisualC-WinRT/SDL-UWP.vcxproj.filters b/VisualC-WinRT/SDL-UWP.vcxproj.filters
index 728fdbbcc1d3..789ec30d3b35 100644
--- a/VisualC-WinRT/SDL-UWP.vcxproj.filters
+++ b/VisualC-WinRT/SDL-UWP.vcxproj.filters
@@ -435,9 +435,6 @@
<ClInclude Include="..\src\SDL_list.h">
<Filter>Source Files</Filter>
</ClInclude>
- <ClInclude Include="..\src\haptic\windows\SDL_xinputhaptic_c.h">
- <Filter>Source Files</Filter>
- </ClInclude>
<ClInclude Include="..\src\haptic\windows\SDL_dinputhaptic_c.h">
<Filter>Source Files</Filter>
</ClInclude>
@@ -855,9 +852,6 @@
<ClCompile Include="..\src\haptic\windows\SDL_windowshaptic.c">
<Filter>Source Files</Filter>
</ClCompile>
- <ClCompile Include="..\src\haptic\windows\SDL_xinputhaptic.c">
- <Filter>Source Files</Filter>
- </ClCompile>
<ClCompile Include="..\src\video\SDL_yuv.c">
<Filter>Source Files</Filter>
</ClCompile>
diff --git a/VisualC/SDL/SDL.vcxproj b/VisualC/SDL/SDL.vcxproj
index 0b5345789220..b10f8269a946 100644
--- a/VisualC/SDL/SDL.vcxproj
+++ b/VisualC/SDL/SDL.vcxproj
@@ -348,7 +348,6 @@
<ClInclude Include="..\..\src\haptic\SDL_syshaptic.h" />
<ClInclude Include="..\..\src\haptic\windows\SDL_dinputhaptic_c.h" />
<ClInclude Include="..\..\src\haptic\windows\SDL_windowshaptic_c.h" />
- <ClInclude Include="..\..\src\haptic\windows\SDL_xinputhaptic_c.h" />
<ClInclude Include="..\..\src\hidapi\hidapi\hidapi.h" />
<ClInclude Include="..\..\src\hidapi\SDL_hidapi_c.h" />
<ClInclude Include="..\..\src\joystick\controller_type.h" />
@@ -515,7 +514,6 @@
<ClCompile Include="..\..\src\haptic\SDL_haptic.c" />
<ClCompile Include="..\..\src\haptic\windows\SDL_dinputhaptic.c" />
<ClCompile Include="..\..\src\haptic\windows\SDL_windowshaptic.c" />
- <ClCompile Include="..\..\src\haptic\windows\SDL_xinputhaptic.c" />
<ClCompile Include="..\..\src\hidapi\SDL_hidapi.c" />
<ClCompile Include="..\..\src\joystick\controller_type.c" />
<ClCompile Include="..\..\src\joystick\dummy\SDL_sysjoystick.c" />
diff --git a/VisualC/SDL/SDL.vcxproj.filters b/VisualC/SDL/SDL.vcxproj.filters
index e53a8eb40d68..6517484f466f 100644
--- a/VisualC/SDL/SDL.vcxproj.filters
+++ b/VisualC/SDL/SDL.vcxproj.filters
@@ -546,9 +546,6 @@
<ClInclude Include="..\..\src\haptic\windows\SDL_windowshaptic_c.h">
<Filter>haptic\windows</Filter>
</ClInclude>
- <ClInclude Include="..\..\src\haptic\windows\SDL_xinputhaptic_c.h">
- <Filter>haptic\windows</Filter>
- </ClInclude>
<ClInclude Include="..\..\src\joystick\hidapi\SDL_hidapijoystick_c.h">
<Filter>joystick\hidapi</Filter>
</ClInclude>
@@ -1050,9 +1047,6 @@
<ClCompile Include="..\..\src\haptic\windows\SDL_windowshaptic.c">
<Filter>haptic\windows</Filter>
</ClCompile>
- <ClCompile Include="..\..\src\haptic\windows\SDL_xinputhaptic.c">
- <Filter>haptic\windows</Filter>
- </ClCompile>
<ClCompile Include="..\..\src\haptic\dummy\SDL_syshaptic.c">
<Filter>haptic\dummy</Filter>
</ClCompile>
diff --git a/build-scripts/SDL_migration.cocci b/build-scripts/SDL_migration.cocci
index 6cb692f30799..bb39f23ea6bb 100644
--- a/build-scripts/SDL_migration.cocci
+++ b/build-scripts/SDL_migration.cocci
@@ -2764,3 +2764,123 @@ expression e1, e2, e3, e4;
@@
- SDL_SoftStretchLinear(e1, e2, e3, e4)
+ SDL_SoftStretch(e1, e2, e3, e4, SDL_SCALEMODE_LINEAR)
+@@
+@@
+- SDL_HapticClose
++ SDL_CloseHaptic
+ (...)
+@@
+@@
+- SDL_HapticOpen
++ SDL_OpenHaptic
+ (...)
+@@
+@@
+- SDL_HapticOpenFromMouse
++ SDL_OpenHapticFromMouse
+ (...)
+@@
+@@
+- SDL_HapticOpenFromJoystick
++ SDL_OpenHapticFromJoystick
+ (...)
+@@
+@@
+- SDL_MouseIsHaptic
++ SDL_IsMouseHaptic
+ (...)
+@@
+@@
+- SDL_JoystickIsHaptic
++ SDL_IsJoystickHaptic
+ (...)
+@@
+@@
+- SDL_HapticNumEffects
++ SDL_GetMaxHapticEffects
+ (...)
+@@
+@@
+- SDL_HapticNumEffectsPlaying
++ SDL_GetMaxHapticEffectsPlaying
+ (...)
+@@
+@@
+- SDL_HapticQuery
++ SDL_GetHapticFeatures
+ (...)
+@@
+@@
+- SDL_HapticNumAxes
++ SDL_GetNumHapticAxes
+ (...)
+@@
+@@
+- SDL_HapticNewEffect
++ SDL_CreateHapticEffect
+ (...)
+@@
+@@
+- SDL_HapticUpdateEffect
++ SDL_UpdateHapticEffect
+ (...)
+@@
+@@
+- SDL_HapticRunEffect
++ SDL_RunHapticEffect
+ (...)
+@@
+@@
+- SDL_HapticStopEffect
++ SDL_StopHapticEffect
+ (...)
+@@
+@@
+- SDL_HapticDestroyEffect
++ SDL_DestroyHapticEffect
+ (...)
+@@
+@@
+- SDL_HapticGetEffectStatus
++ SDL_GetHapticEffectStatus
+ (...)
+@@
+@@
+- SDL_HapticSetGain
++ SDL_SetHapticGain
+ (...)
+@@
+@@
+- SDL_HapticSetAutocenter
++ SDL_SetHapticAutocenter
+ (...)
+@@
+@@
+- SDL_HapticPause
++ SDL_PauseHaptic
+ (...)
+@@
+@@
+- SDL_HapticUnpause
++ SDL_ResumeHaptic
+ (...)
+@@
+@@
+- SDL_HapticStopAll
++ SDL_StopHapticEffects
+ (...)
+@@
+@@
+- SDL_HapticRumbleInit
++ SDL_InitHapticRumble
+ (...)
+@@
+@@
+- SDL_HapticRumblePlay
++ SDL_PlayHapticRumble
+ (...)
+@@
+@@
+- SDL_HapticRumbleStop
++ SDL_StopHapticRumble
+ (...)
diff --git a/docs/README-migration.md b/docs/README-migration.md
index 959fd0def252..5341878f2e23 100644
--- a/docs/README-migration.md
+++ b/docs/README-migration.md
@@ -618,6 +618,65 @@ be dropped into an SDL3 or SDL2 program, to continue to provide this
functionality to your app and aid migration. That is located in the
[SDL_gesture GitHub repository](https://github.com/libsdl-org/SDL_gesture).
+## SDL_haptic.h
+
+Gamepads with simple rumble capability no longer show up in the SDL haptics interface, instead you should use SDL_RumbleGamepad().
+
+Rather than iterating over haptic devices using device index, there is a new function SDL_GetHaptics() to get the current list of haptic devices, and new functions to get information about haptic devices from their instance ID:
+```c
+{
+ if (SDL_InitSubSystem(SDL_INIT_HAPTIC) == 0) {
+ int i, num_haptics;
+ SDL_HapticID *haptics = SDL_GetHaptics(&num_haptics);
+ if (haptics) {
+ for (i = 0; i < num_haptics; ++i) {
+ SDL_HapticID instance_id = haptics[i];
+ const char *name = SDL_GetHapticInstanceName(instance_id);
+
+ SDL_Log("Haptic %" SDL_PRIu32 ": %s\n",
+ instance_id, name ? name : "Unknown");
+ }
+ SDL_free(haptics);
+ }
+ SDL_QuitSubSystem(SDL_INIT_HAPTIC);
+ }
+}
+```
+
+SDL_HapticEffectSupported(), SDL_HapticRumbleSupported(), and SDL_IsJoystickHaptic() now return SDL_bool instead of an optional negative error code.
+
+The following functions have been renamed:
+* SDL_HapticClose() => SDL_CloseHaptic()
+* SDL_HapticDestroyEffect() => SDL_DestroyHapticEffect()
+* SDL_HapticGetEffectStatus() => SDL_GetHapticEffectStatus()
+* SDL_HapticNewEffect() => SDL_CreateHapticEffect()
+* SDL_HapticNumAxes() => SDL_GetNumHapticAxes()
+* SDL_HapticNumEffects() => SDL_GetMaxHapticEffects()
+* SDL_HapticNumEffectsPlaying() => SDL_GetMaxHapticEffectsPlaying()
+* SDL_HapticOpen() => SDL_OpenHaptic()
+* SDL_HapticOpenFromJoystick() => SDL_OpenHapticFromJoystick()
+* SDL_HapticOpenFromMouse() => SDL_OpenHapticFromMouse()
+* SDL_HapticPause() => SDL_PauseHaptic()
+* SDL_HapticQuery() => SDL_GetHapticFeatures()
+* SDL_HapticRumbleInit() => SDL_InitHapticRumble()
+* SDL_HapticRumblePlay() => SDL_PlayHapticRumble()
+* SDL_HapticRumbleStop() => SDL_StopHapticRumble()
+* SDL_HapticRunEffect() => SDL_RunHapticEffect()
+* SDL_HapticSetAutocenter() => SDL_SetHapticAutocenter()
+* SDL_HapticSetGain() => SDL_SetHapticGain()
+* SDL_HapticStopAll() => SDL_StopHapticEffects()
+* SDL_HapticStopEffect() => SDL_StopHapticEffect()
+* SDL_HapticUnpause() => SDL_ResumeHaptic()
+* SDL_HapticUpdateEffect() => SDL_UpdateHapticEffect()
+* SDL_JoystickIsHaptic() => SDL_IsJoystickHaptic()
+* SDL_MouseIsHaptic() => SDL_IsMouseHaptic()
+
+The following functions have been removed:
+* SDL_HapticIndex() - replaced with SDL_GetHapticInstanceID()
+* SDL_HapticName() - replaced with SDL_GetHapticInstanceName()
+* SDL_HapticOpened() - replaced with SDL_GetHapticFromInstanceID()
+* SDL_NumHaptics() - replaced with SDL_GetHaptics()
+
## SDL_hints.h
SDL_AddHintCallback() now returns a standard int result instead of void, returning 0 if the function succeeds or a negative error code if there was an error.
diff --git a/include/SDL3/SDL_haptic.h b/include/SDL3/SDL_haptic.h
index 757099440f7b..3c11021bc3fc 100644
--- a/include/SDL3/SDL_haptic.h
+++ b/include/SDL3/SDL_haptic.h
@@ -27,55 +27,60 @@
* The basic usage is as follows:
* - Initialize the subsystem (::SDL_INIT_HAPTIC).
* - Open a haptic device.
- * - SDL_HapticOpen() to open from index.
- * - SDL_HapticOpenFromJoystick() to open from an existing joystick.
+ * - SDL_OpenHaptic() to open from index.
+ * - SDL_OpenHapticFromJoystick() to open from an existing joystick.
* - Create an effect (::SDL_HapticEffect).
- * - Upload the effect with SDL_HapticNewEffect().
- * - Run the effect with SDL_HapticRunEffect().
- * - (optional) Free the effect with SDL_HapticDestroyEffect().
- * - Close the haptic device with SDL_HapticClose().
+ * - Upload the effect with SDL_CreateHapticEffect().
+ * - Run the effect with SDL_RunHapticEffect().
+ * - (optional) Free the effect with SDL_DestroyHapticEffect().
+ * - Close the haptic device with SDL_CloseHaptic().
*
* \par Simple rumble example:
* \code
- * SDL_Haptic *haptic;
+ * SDL_Haptic *haptic = NULL;
*
* // Open the device
- * haptic = SDL_HapticOpen( 0 );
+ * SDL_HapticID *haptics = SDL_GetHaptics(NULL);
+ * if (haptics) {
+ * haptic = SDL_OpenHaptic(haptics[0]);
+ * SDL_free(haptics);
+ * }
* if (haptic == NULL)
* return -1;
*
* // Initialize simple rumble
- * if (SDL_HapticRumbleInit( haptic ) != 0)
+ * if (SDL_InitHapticRumble(haptic) != 0)
* return -1;
*
* // Play effect at 50% strength for 2 seconds
- * if (SDL_HapticRumblePlay( haptic, 0.5, 2000 ) != 0)
+ * if (SDL_PlayHapticRumble(haptic, 0.5, 2000) != 0)
* return -1;
- * SDL_Delay( 2000 );
+ * SDL_Delay(2000);
*
* // Clean up
- * SDL_HapticClose( haptic );
+ * SDL_CloseHaptic(haptic);
* \endcode
*
* \par Complete example:
* \code
- * int test_haptic( SDL_Joystick * joystick ) {
+ * int test_haptic(SDL_Joystick *joystick)
+ * {
* SDL_Haptic *haptic;
* SDL_HapticEffect effect;
* int effect_id;
*
* // Open the device
- * haptic = SDL_HapticOpenFromJoystick( joystick );
+ * haptic = SDL_OpenHapticFromJoystick(joystick);
* if (haptic == NULL) return -1; // Most likely joystick isn't haptic
*
* // See if it can do sine waves
- * if ((SDL_HapticQuery(haptic) & SDL_HAPTIC_SINE)==0) {
- * SDL_HapticClose(haptic); // No sine effect
+ * if ((SDL_GetHapticFeatures(haptic) & SDL_HAPTIC_SINE)==0) {
+ * SDL_CloseHaptic(haptic); // No sine effect
* return -1;
* }
*
* // Create the effect
- * SDL_memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
+ * SDL_memset(&effect, 0, sizeof(SDL_HapticEffect)); // 0 is safe default
* effect.type = SDL_HAPTIC_SINE;
* effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
* effect.periodic.direction.dir[0] = 18000; // Force comes from south
@@ -86,21 +91,23 @@
* effect.periodic.fade_length = 1000; // Takes 1 second to fade away
*
* // Upload the effect
- * effect_id = SDL_HapticNewEffect( haptic, &effect );
+ * effect_id = SDL_CreateHapticEffect(haptic, &effect);
*
* // Test the effect
- * SDL_HapticRunEffect( haptic, effect_id, 1 );
- * SDL_Delay( 5000); // Wait for the effect to finish
+ * SDL_RunHapticEffect(haptic, effect_id, 1);
+ * SDL_Delay(5000); // Wait for the effect to finish
*
* // We destroy the effect, although closing the device also does this
- * SDL_HapticDestroyEffect( haptic, effect_id );
+ * SDL_DestroyHapticEffect(haptic, effect_id);
*
* // Close the device
- * SDL_HapticClose(haptic);
+ * SDL_CloseHaptic(haptic);
*
* return 0; // Success
* }
* \endcode
+ *
+ * Note that the SDL haptic subsystem is not thread-safe.
*/
#ifndef SDL_haptic_h_
@@ -132,9 +139,9 @@ extern "C" {
*
* The haptic structure used to identify an SDL haptic.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticOpenFromJoystick
- * \sa SDL_HapticClose
+ * \sa SDL_OpenHaptic
+ * \sa SDL_OpenHapticFromJoystick
+ * \sa SDL_CloseHaptic
*/
struct SDL_Haptic;
typedef struct SDL_Haptic SDL_Haptic;
@@ -276,7 +283,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Device supports setting the global gain.
*
- * \sa SDL_HapticSetGain
+ * \sa SDL_SetHapticGain
*/
#define SDL_HAPTIC_GAIN (1u<<12)
@@ -285,7 +292,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Device supports setting autocenter.
*
- * \sa SDL_HapticSetAutocenter
+ * \sa SDL_SetHapticAutocenter
*/
#define SDL_HAPTIC_AUTOCENTER (1u<<13)
@@ -294,7 +301,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Device supports querying effect status.
*
- * \sa SDL_HapticGetEffectStatus
+ * \sa SDL_GetHapticEffectStatus
*/
#define SDL_HAPTIC_STATUS (1u<<14)
@@ -303,8 +310,8 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Devices supports being paused.
*
- * \sa SDL_HapticPause
- * \sa SDL_HapticUnpause
+ * \sa SDL_PauseHaptic
+ * \sa SDL_ResumeHaptic
*/
#define SDL_HAPTIC_PAUSE (1u<<15)
@@ -356,7 +363,7 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* Used to play a device an infinite number of times.
*
- * \sa SDL_HapticRunEffect
+ * \sa SDL_RunHapticEffect
*/
#define SDL_HAPTIC_INFINITY 4294967295U
@@ -455,7 +462,7 @@ typedef struct SDL_Haptic SDL_Haptic;
* \sa SDL_HAPTIC_SPHERICAL
* \sa SDL_HAPTIC_STEERING_AXIS
* \sa SDL_HapticEffect
- * \sa SDL_HapticNumAxes
+ * \sa SDL_GetNumHapticAxes
*/
typedef struct SDL_HapticDirection
{
@@ -819,36 +826,45 @@ typedef union SDL_HapticEffect
SDL_HapticCustom custom; /**< Custom effect. */
} SDL_HapticEffect;
+/**
+ * This is a unique ID for a haptic device for the time it is connected to the system, and is never reused for the lifetime of the application. If the haptic device is disconnected and reconnected, it will get a new ID.
+ *
+ * The ID value starts at 1 and increments from there. The value 0 is an invalid ID.
+ */
+typedef Uint32 SDL_HapticID;
+
/* Function prototypes */
/**
- * Count the number of haptic devices attached to the system.
+ * Get a list of currently connected haptic devices.
*
- * \returns the number of haptic devices detected on the system or a negative
- * error code on failure; call SDL_GetError() for more information.
+ * \param count a pointer filled in with the number of haptic devices returned
+ * \returns a 0 terminated array of haptic device 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_HapticName
+ * \sa SDL_OpenHaptic
*/
-extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
+extern DECLSPEC SDL_HapticID *SDLCALL SDL_GetHaptics(int *count);
/**
* Get the implementation dependent name of a haptic device.
*
- * This can be called before any joysticks are opened. If no name can be
- * found, this function returns NULL.
+ * This can be called before any haptic devices are opened.
*
- * \param device_index index of the device to query.
- * \returns the name of the device or NULL on failure; call SDL_GetError() for
- * more information.
+ * \param instance_id the haptic device instance ID
+ * \returns the name of the selected haptic device. 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_NumHaptics
+ * \sa SDL_GetHapticName
+ * \sa SDL_OpenHaptic
*/
-extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
+extern DECLSPEC const char *SDLCALL SDL_GetHapticInstanceName(SDL_HapticID instance_id);
/**
* Open a haptic device for use.
@@ -857,53 +873,63 @@ extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
* system.
*
* When opening a haptic device, its gain will be set to maximum and
- * autocenter will be disabled. To modify these values use SDL_HapticSetGain()
- * and SDL_HapticSetAutocenter().
+ * autocenter will be disabled. To modify these values use SDL_SetHapticGain()
+ * and SDL_SetHapticAutocenter().
*
- * \param device_index index of the device to open
+ * \param instance_id the haptic device instance ID
* \returns the device identifier or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_HapticClose
- * \sa SDL_HapticIndex
- * \sa SDL_HapticOpenFromJoystick
- * \sa SDL_HapticOpenFromMouse
- * \sa SDL_HapticPause
- * \sa SDL_HapticSetAutocenter
- * \sa SDL_HapticSetGain
- * \sa SDL_HapticStopAll
+ * \sa SDL_CloseHaptic
+ * \sa SDL_OpenHapticFromJoystick
+ * \sa SDL_OpenHapticFromMouse
+ * \sa SDL_PauseHaptic
+ * \sa SDL_SetHapticAutocenter
+ * \sa SDL_SetHapticGain
+ * \sa SDL_StopHapticEffects
*/
-extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
+extern DECLSPEC SDL_Haptic *SDLCALL SDL_OpenHaptic(SDL_HapticID instance_id);
+
/**
- * Check if the haptic device at the designated index has been opened.
+ * Get the SDL_Haptic associated with an instance ID, if it has been opened.
*
- * \param device_index the index of the device to query
- * \returns 1 if it has been opened, 0 if it hasn't or on failure; call
- * SDL_GetError() for more information.
+ * \param instance_id the instance ID to get the SDL_Haptic for
+ * \returns an SDL_Haptic on success or NULL on failure or if it hasn't been
+ * opened yet; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_HapticIndex
- * \sa SDL_HapticOpen
*/
-extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
+extern DECLSPEC SDL_Haptic *SDLCALL SDL_GetHapticFromInstanceID(SDL_HapticID instance_id);
/**
- * Get the index of a haptic device.
+ * Get the instance ID of an opened haptic device.
*
* \param haptic the SDL_Haptic device to query
- * \returns the index of the specified haptic device or a negative error code
- * on failure; call SDL_GetError() for more information.
+ * \returns the instance ID of the specified haptic device on success or 0 on
+ * failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticOpened
+ * \sa SDL_OpenHaptic
*/
-extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
+extern DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticInstanceID(SDL_Haptic *haptic);
+
+/**
+ * Get the implementation dependent name of a haptic device.
+ *
+ * \param haptic the SDL_Haptic obtained from SDL_OpenJoystick()
+ * \returns the name of the selected haptic device. 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_GetHapticInstanceName
+ * \sa SDL_OpenHaptic
+ */
+extern DECLSPEC const char *SDLCALL SDL_GetHapticName(SDL_Haptic *haptic);
/**
* Query whether or not the current mouse has haptic capabilities.
@@ -912,9 +938,9 @@ extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_HapticOpenFromMouse
+ * \sa SDL_OpenHapticFromMouse
*/
-extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
+extern DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void);
/**
* Try to open a haptic device from the current mouse.
@@ -924,24 +950,22 @@ extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_HapticOpen
- * \sa SDL_MouseIsHaptic
+ * \sa SDL_OpenHaptic
+ * \sa SDL_IsMouseHaptic
*/
-extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
+extern DECLSPEC SDL_Haptic *SDLCALL SDL_OpenHapticFromMouse(void);
/**
* Query if a joystick has haptic features.
*
* \param joystick the SDL_Joystick to test for haptic capabilities
- * \returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't, or a
- * negative error code on failure; call SDL_GetError() for more
- * information.
+ * \returns SDL_TRUE if the joystick is haptic or SDL_FALSE if it isn't.
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_HapticOpenFromJoystick
+ * \sa SDL_OpenHapticFromJoystick
*/
-extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
+extern DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick);
/**
* Open a haptic device for use from a joystick device.
@@ -960,30 +984,29 @@ extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_HapticClose
- * \sa SDL_HapticOpen
- * \sa SDL_JoystickIsHaptic
+ * \sa SDL_CloseHaptic
+ * \sa SDL_OpenHaptic
+ * \sa SDL_IsJoystickHaptic
*/
-extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
- joystick);
+extern DECLSPEC SDL_Haptic *SDLCALL SDL_OpenHapticFromJoystick(SDL_Joystick *joystick);
/**
- * Close a haptic device previously opened with SDL_HapticOpen().
+ * Close a haptic device previously opened with SDL_OpenHaptic().
*
* \param haptic the SDL_Haptic device to close
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_HapticOpen
+ * \sa SDL_OpenHaptic
*/
-extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
+extern DECLSPEC void SDLCALL SDL_CloseHaptic(SDL_Haptic *haptic);
/**
* Get the number of effects a haptic device can store.
*
* On some platforms this isn't fully supported, and therefore is an
* approximation. Always check to see if your created effect was actually
- * created and do not rely solely on SDL_HapticNumEffects().
+ * created and do not rely solely on SDL_GetMaxHapticEffects().
*
* \param haptic the SDL_Haptic device to query
* \returns the number of effects the haptic device can store or a negative
@@ -991,10 +1014,10 @@ extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_HapticNumEffectsPlaying
- * \sa SDL_HapticQuery
+ * \sa SDL_GetMaxHapticEffectsPlaying
+ * \sa SDL_GetHapticFeatures
*/
-extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
+extern DECLSPEC int SDLCALL SDL_GetMaxHapticEffects(SDL_Haptic *haptic);
/**
* Get the number of effects a haptic device can play at the same time.
@@ -1008,10 +1031,10 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_HapticNumEffects
- * \sa SDL_HapticQuery
(Patch may be truncated, please check the link at the top of this post.)