1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22#include "SDL_internal.h"
23
24#ifndef SDL_syshaptic_h_
25#define SDL_syshaptic_h_
26
27// Set up for C function definitions, even when using C++
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32struct haptic_effect
33{
34 SDL_HapticEffect effect; // The current event
35 struct haptic_hweffect *hweffect; // The hardware behind the event
36};
37
38/*
39 * The real SDL_Haptic struct.
40 */
41struct SDL_Haptic
42{
43 SDL_HapticID instance_id; // Device instance, monotonically increasing from 0
44 char *name; // Device name - system dependent
45
46 struct haptic_effect *effects; // Allocated effects
47 int neffects; // Maximum amount of effects
48 int nplaying; // Maximum amount of effects to play at the same time
49 Uint32 supported; // Supported effects and features
50 int naxes; // Number of axes on the device.
51
52 struct haptic_hwdata *hwdata; // Driver dependent
53 int ref_count; // Count for multiple opens
54
55 int rumble_id; // ID of rumble effect for simple rumble API.
56 SDL_HapticEffect rumble_effect; // Rumble effect.
57 struct SDL_Haptic *next; // pointer to next haptic we have allocated
58};
59
60/*
61 * Scans the system for haptic devices.
62 *
63 * Returns number of devices on success, -1 on error.
64 */
65extern bool SDL_SYS_HapticInit(void);
66
67// Function to return the number of haptic devices plugged in right now
68extern int SDL_SYS_NumHaptics(void);
69
70/*
71 * Gets the instance ID of the haptic device
72 */
73extern SDL_HapticID SDL_SYS_HapticInstanceID(int index);
74
75/*
76 * Gets the device dependent name of the haptic device
77 */
78extern const char *SDL_SYS_HapticName(int index);
79
80/*
81 * Opens the haptic device for usage. The haptic device should have
82 * the index value set previously.
83 */
84extern bool SDL_SYS_HapticOpen(SDL_Haptic *haptic);
85
86/*
87 * Returns the index of the haptic core pointer or -1 if none is found.
88 */
89extern int SDL_SYS_HapticMouse(void);
90
91/*
92 * Checks to see if the joystick has haptic capabilities.
93 */
94extern bool SDL_SYS_JoystickIsHaptic(SDL_Joystick *joystick);
95
96/*
97 * Opens the haptic device for usage using the same device as
98 * the joystick.
99 */
100extern bool SDL_SYS_HapticOpenFromJoystick(SDL_Haptic *haptic,
101 SDL_Joystick *joystick);
102/*
103 * Checks to see if haptic device and joystick device are the same.
104 *
105 * Returns true if they are the same, false if they aren't.
106 */
107extern bool SDL_SYS_JoystickSameHaptic(SDL_Haptic *haptic,
108 SDL_Joystick *joystick);
109
110/*
111 * Closes a haptic device after usage.
112 */
113extern void SDL_SYS_HapticClose(SDL_Haptic *haptic);
114
115/*
116 * Performs a cleanup on the haptic subsystem.
117 */
118extern void SDL_SYS_HapticQuit(void);
119
120/*
121 * Creates a new haptic effect on the haptic device using base
122 * as a template for the effect.
123 */
124extern bool SDL_SYS_HapticNewEffect(SDL_Haptic *haptic,
125 struct haptic_effect *effect,
126 const SDL_HapticEffect *base);
127
128/*
129 * Updates the haptic effect on the haptic device using data
130 * as a template.
131 */
132extern bool SDL_SYS_HapticUpdateEffect(SDL_Haptic *haptic,
133 struct haptic_effect *effect,
134 const SDL_HapticEffect *data);
135
136/*
137 * Runs the effect on the haptic device.
138 */
139extern bool SDL_SYS_HapticRunEffect(SDL_Haptic *haptic,
140 struct haptic_effect *effect,
141 Uint32 iterations);
142
143/*
144 * Stops the effect on the haptic device.
145 */
146extern bool SDL_SYS_HapticStopEffect(SDL_Haptic *haptic,
147 struct haptic_effect *effect);
148
149/*
150 * Cleanups up the effect on the haptic device.
151 */
152extern void SDL_SYS_HapticDestroyEffect(SDL_Haptic *haptic,
153 struct haptic_effect *effect);
154
155/*
156 * Queries the device for the status of effect.
157 *
158 * Returns 0 if device is stopped, >0 if device is playing and
159 * -1 on error.
160 */
161extern int SDL_SYS_HapticGetEffectStatus(SDL_Haptic *haptic,
162 struct haptic_effect *effect);
163
164/*
165 * Sets the global gain of the haptic device.
166 */
167extern bool SDL_SYS_HapticSetGain(SDL_Haptic *haptic, int gain);
168
169/*
170 * Sets the autocenter feature of the haptic device.
171 */
172extern bool SDL_SYS_HapticSetAutocenter(SDL_Haptic *haptic, int autocenter);
173
174/*
175 * Pauses the haptic device.
176 */
177extern bool SDL_SYS_HapticPause(SDL_Haptic *haptic);
178
179/*
180 * Unpauses the haptic device.
181 */
182extern bool SDL_SYS_HapticResume(SDL_Haptic *haptic);
183
184/*
185 * Stops all the currently playing haptic effects on the device.
186 */
187extern bool SDL_SYS_HapticStopAll(SDL_Haptic *haptic);
188
189// Ends C function definitions when using C++
190#ifdef __cplusplus
191}
192#endif
193
194#endif // SDL_syshaptic_h_
195