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#include "SDL_internal.h"
22
23#ifndef SDL_sysjoystick_h_
24#define SDL_sysjoystick_h_
25
26// This is the system specific header for the SDL joystick API
27#include "SDL_joystick_c.h"
28
29// Set up for C function definitions, even when using C++
30#ifdef __cplusplus
31extern "C" {
32#endif
33
34// The SDL joystick structure
35
36typedef struct SDL_JoystickAxisInfo
37{
38 Sint16 initial_value; // Initial axis state
39 Sint16 value; // Current axis state
40 Sint16 zero; // Zero point on the axis (-32768 for triggers)
41 bool has_initial_value; // Whether we've seen a value on the axis yet
42 bool has_second_value; // Whether we've seen a second value on the axis yet
43 bool sent_initial_value; // Whether we've sent the initial axis value
44 bool sending_initial_value; // Whether we are sending the initial axis value
45} SDL_JoystickAxisInfo;
46
47typedef struct SDL_JoystickBallData
48{
49 int dx;
50 int dy;
51} SDL_JoystickBallData;
52
53typedef struct SDL_JoystickTouchpadFingerInfo
54{
55 bool down;
56 float x;
57 float y;
58 float pressure;
59} SDL_JoystickTouchpadFingerInfo;
60
61typedef struct SDL_JoystickTouchpadInfo
62{
63 int nfingers;
64 SDL_JoystickTouchpadFingerInfo *fingers;
65} SDL_JoystickTouchpadInfo;
66
67typedef struct SDL_JoystickSensorInfo
68{
69 SDL_SensorType type;
70 bool enabled;
71 float rate;
72 float data[3]; // If this needs to expand, update SDL_GamepadSensorEvent
73} SDL_JoystickSensorInfo;
74
75#define _guarded SDL_GUARDED_BY(SDL_joystick_lock)
76
77struct SDL_Joystick
78{
79 SDL_JoystickID instance_id _guarded; // Device instance, monotonically increasing from 0
80 char *name _guarded; // Joystick name - system dependent
81 char *path _guarded; // Joystick path - system dependent
82 char *serial _guarded; // Joystick serial
83 SDL_GUID guid _guarded; // Joystick guid
84 Uint16 firmware_version _guarded; // Firmware version, if available
85 Uint64 steam_handle _guarded; // Steam controller API handle
86 bool swap_face_buttons _guarded; // Whether we should swap face buttons
87
88 int naxes _guarded; // Number of axis controls on the joystick
89 SDL_JoystickAxisInfo *axes _guarded;
90
91 int nballs _guarded; // Number of trackballs on the joystick
92 SDL_JoystickBallData *balls _guarded; // Current ball motion deltas
93
94 int nhats _guarded; // Number of hats on the joystick
95 Uint8 *hats _guarded; // Current hat states
96
97 int nbuttons _guarded; // Number of buttons on the joystick
98 bool *buttons _guarded; // Current button states
99
100 int ntouchpads _guarded; // Number of touchpads on the joystick
101 SDL_JoystickTouchpadInfo *touchpads _guarded; // Current touchpad states
102
103 int nsensors _guarded; // Number of sensors on the joystick
104 int nsensors_enabled _guarded;
105 SDL_JoystickSensorInfo *sensors _guarded;
106
107 Uint16 low_frequency_rumble _guarded;
108 Uint16 high_frequency_rumble _guarded;
109 Uint64 rumble_expiration _guarded;
110 Uint64 rumble_resend _guarded;
111
112 Uint16 left_trigger_rumble _guarded;
113 Uint16 right_trigger_rumble _guarded;
114 Uint64 trigger_rumble_expiration _guarded;
115
116 Uint8 led_red _guarded;
117 Uint8 led_green _guarded;
118 Uint8 led_blue _guarded;
119 Uint64 led_expiration _guarded;
120
121 bool attached _guarded;
122 SDL_JoystickConnectionState connection_state _guarded;
123 SDL_PowerState battery_state _guarded;
124 int battery_percent _guarded;
125
126 bool delayed_guide_button _guarded; // true if this device has the guide button event delayed
127
128 SDL_SensorID accel_sensor _guarded;
129 SDL_Sensor *accel _guarded;
130 SDL_SensorID gyro_sensor _guarded;
131 SDL_Sensor *gyro _guarded;
132 float sensor_transform[3][3] _guarded;
133
134 Uint64 update_complete _guarded;
135
136 struct SDL_JoystickDriver *driver _guarded;
137
138 struct joystick_hwdata *hwdata _guarded; // Driver dependent information
139
140 SDL_PropertiesID props _guarded;
141
142 int ref_count _guarded; // Reference count for multiple opens
143
144 struct SDL_Joystick *next _guarded; // pointer to next joystick we have allocated
145};
146
147#undef _guarded
148
149// Device bus definitions
150#define SDL_HARDWARE_BUS_UNKNOWN 0x00
151#define SDL_HARDWARE_BUS_USB 0x03
152#define SDL_HARDWARE_BUS_BLUETOOTH 0x05
153#define SDL_HARDWARE_BUS_VIRTUAL 0xFF
154
155// Macro to combine a USB vendor ID and product ID into a single Uint32 value
156#define MAKE_VIDPID(VID, PID) (((Uint32)(VID)) << 16 | (PID))
157
158typedef struct SDL_JoystickDriver
159{
160 /* Function to scan the system for joysticks.
161 * Joystick 0 should be the system default joystick.
162 * This function should return 0, or -1 on an unrecoverable error.
163 */
164 bool (*Init)(void);
165
166 // Function to return the number of joystick devices plugged in right now
167 int (*GetCount)(void);
168
169 // Function to cause any queued joystick insertions to be processed
170 void (*Detect)(void);
171
172 // Function to determine whether a device is currently detected by this driver
173 bool (*IsDevicePresent)(Uint16 vendor_id, Uint16 product_id, Uint16 version, const char *name);
174
175 // Function to get the device-dependent name of a joystick
176 const char *(*GetDeviceName)(int device_index);
177
178 // Function to get the device-dependent path of a joystick
179 const char *(*GetDevicePath)(int device_index);
180
181 // Function to get the Steam virtual gamepad slot of a joystick
182 int (*GetDeviceSteamVirtualGamepadSlot)(int device_index);
183
184 // Function to get the player index of a joystick
185 int (*GetDevicePlayerIndex)(int device_index);
186
187 // Function to set the player index of a joystick
188 void (*SetDevicePlayerIndex)(int device_index, int player_index);
189
190 // Function to return the stable GUID for a plugged in device
191 SDL_GUID (*GetDeviceGUID)(int device_index);
192
193 // Function to get the current instance id of the joystick located at device_index
194 SDL_JoystickID (*GetDeviceInstanceID)(int device_index);
195
196 /* Function to open a joystick for use.
197 The joystick to open is specified by the device index.
198 This should fill the nbuttons and naxes fields of the joystick structure.
199 It returns 0, or -1 if there is an error.
200 */
201 bool (*Open)(SDL_Joystick *joystick, int device_index);
202
203 // Rumble functionality
204 bool (*Rumble)(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble);
205 bool (*RumbleTriggers)(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble);
206
207 // LED functionality
208 bool (*SetLED)(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);
209
210 // General effects
211 bool (*SendEffect)(SDL_Joystick *joystick, const void *data, int size);
212
213 // Sensor functionality
214 bool (*SetSensorsEnabled)(SDL_Joystick *joystick, bool enabled);
215
216 /* Function to update the state of a joystick - called as a device poll.
217 * This function shouldn't update the joystick structure directly,
218 * but instead should call SDL_PrivateJoystick*() to deliver events
219 * and update joystick device state.
220 */
221 void (*Update)(SDL_Joystick *joystick);
222
223 // Function to close a joystick after use
224 void (*Close)(SDL_Joystick *joystick);
225
226 // Function to perform any system-specific joystick related cleanup
227 void (*Quit)(void);
228
229 // Function to get the autodetected controller mapping; returns false if there isn't any.
230 bool (*GetGamepadMapping)(int device_index, SDL_GamepadMapping *out);
231
232} SDL_JoystickDriver;
233
234// Windows and Mac OSX has a limit of MAX_DWORD / 1000, Linux kernel has a limit of 0xFFFF
235#define SDL_MAX_RUMBLE_DURATION_MS 0xFFFF
236
237/* Dualshock4 only rumbles for about 5 seconds max, resend rumble command every 2 seconds
238 * to make long rumble work. */
239#define SDL_RUMBLE_RESEND_MS 2000
240
241#define SDL_LED_MIN_REPEAT_MS 5000
242
243// The available joystick drivers
244extern SDL_JoystickDriver SDL_PRIVATE_JoystickDriver;
245extern SDL_JoystickDriver SDL_ANDROID_JoystickDriver;
246extern SDL_JoystickDriver SDL_BSD_JoystickDriver;
247extern SDL_JoystickDriver SDL_DARWIN_JoystickDriver;
248extern SDL_JoystickDriver SDL_DUMMY_JoystickDriver;
249extern SDL_JoystickDriver SDL_EMSCRIPTEN_JoystickDriver;
250extern SDL_JoystickDriver SDL_HAIKU_JoystickDriver;
251extern SDL_JoystickDriver SDL_HIDAPI_JoystickDriver;
252extern SDL_JoystickDriver SDL_RAWINPUT_JoystickDriver;
253extern SDL_JoystickDriver SDL_IOS_JoystickDriver;
254extern SDL_JoystickDriver SDL_LINUX_JoystickDriver;
255extern SDL_JoystickDriver SDL_VIRTUAL_JoystickDriver;
256extern SDL_JoystickDriver SDL_WGI_JoystickDriver;
257extern SDL_JoystickDriver SDL_WINDOWS_JoystickDriver;
258extern SDL_JoystickDriver SDL_WINMM_JoystickDriver;
259extern SDL_JoystickDriver SDL_PS2_JoystickDriver;
260extern SDL_JoystickDriver SDL_PSP_JoystickDriver;
261extern SDL_JoystickDriver SDL_VITA_JoystickDriver;
262extern SDL_JoystickDriver SDL_N3DS_JoystickDriver;
263extern SDL_JoystickDriver SDL_GAMEINPUT_JoystickDriver;
264
265// Ends C function definitions when using C++
266#ifdef __cplusplus
267}
268#endif
269
270#endif // SDL_sysjoystick_h_
271