|
1
|
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 /**
|
|
|
23 * # CategoryJoystick
|
|
|
24 *
|
|
|
25 * SDL joystick support.
|
|
|
26 *
|
|
|
27 * This is the lower-level joystick handling. If you want the simpler option,
|
|
|
28 * where what each button does is well-defined, you should use the gamepad API
|
|
|
29 * instead.
|
|
|
30 *
|
|
|
31 * The term "instance_id" is the current instantiation of a joystick device in
|
|
|
32 * the system. If the joystick is removed and then re-inserted then it will
|
|
|
33 * get a new instance_id. instance_id's are monotonically increasing
|
|
|
34 * identifiers of a joystick plugged in.
|
|
|
35 *
|
|
|
36 * The term "player_index" is the number assigned to a player on a specific
|
|
|
37 * controller. For XInput controllers this returns the XInput user index. Many
|
|
|
38 * joysticks will not be able to supply this information.
|
|
|
39 *
|
|
|
40 * SDL_GUID is used as a stable 128-bit identifier for a joystick device that
|
|
|
41 * does not change over time. It identifies class of the device (a X360 wired
|
|
|
42 * controller for example). This identifier is platform dependent.
|
|
|
43 *
|
|
|
44 * In order to use these functions, SDL_Init() must have been called with the
|
|
|
45 * SDL_INIT_JOYSTICK flag. This causes SDL to scan the system for joysticks,
|
|
|
46 * and load appropriate drivers.
|
|
|
47 *
|
|
|
48 * If you would like to receive joystick updates while the application is in
|
|
|
49 * the background, you should set the following hint before calling
|
|
|
50 * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS
|
|
|
51 *
|
|
|
52 * SDL can provide virtual joysticks as well: the app defines an imaginary
|
|
|
53 * controller with SDL_AttachVirtualJoystick(), and then can provide inputs
|
|
|
54 * for it via SDL_SetJoystickVirtualAxis(), SDL_SetJoystickVirtualButton(),
|
|
|
55 * etc. As this data is supplied, it will look like a normal joystick to SDL,
|
|
|
56 * just not backed by a hardware driver. This has been used to make unusual
|
|
|
57 * devices, like VR headset controllers, look like normal joysticks, or
|
|
|
58 * provide recording/playback of game inputs, etc.
|
|
|
59 */
|
|
|
60
|
|
|
61 #ifndef SDL_joystick_h_
|
|
|
62 #define SDL_joystick_h_
|
|
|
63
|
|
|
64 #include <SDL3/SDL_stdinc.h>
|
|
|
65 #include <SDL3/SDL_error.h>
|
|
|
66 #include <SDL3/SDL_guid.h>
|
|
|
67 #include <SDL3/SDL_mutex.h>
|
|
|
68 #include <SDL3/SDL_power.h>
|
|
|
69 #include <SDL3/SDL_properties.h>
|
|
|
70 #include <SDL3/SDL_sensor.h>
|
|
|
71
|
|
|
72 #include <SDL3/SDL_begin_code.h>
|
|
|
73 /* Set up for C function definitions, even when using C++ */
|
|
|
74 #ifdef __cplusplus
|
|
|
75 extern "C" {
|
|
|
76 #endif
|
|
|
77
|
|
|
78 #ifdef SDL_THREAD_SAFETY_ANALYSIS
|
|
|
79 /*
|
|
|
80 * This is not an exported symbol from SDL, this is only in the headers to
|
|
|
81 * help Clang's thread safety analysis tools to function. Do not attempt
|
|
|
82 * to access this symbol from your app, it will not work!
|
|
|
83 */
|
|
|
84 extern SDL_Mutex *SDL_joystick_lock;
|
|
|
85 #endif
|
|
|
86
|
|
|
87 /**
|
|
|
88 * The joystick structure used to identify an SDL joystick.
|
|
|
89 *
|
|
|
90 * This is opaque data.
|
|
|
91 *
|
|
|
92 * \since This struct is available since SDL 3.2.0.
|
|
|
93 */
|
|
|
94 typedef struct SDL_Joystick SDL_Joystick;
|
|
|
95
|
|
|
96 /**
|
|
|
97 * This is a unique ID for a joystick for the time it is connected to the
|
|
|
98 * system, and is never reused for the lifetime of the application.
|
|
|
99 *
|
|
|
100 * If the joystick is disconnected and reconnected, it will get a new ID.
|
|
|
101 *
|
|
|
102 * The value 0 is an invalid ID.
|
|
|
103 *
|
|
|
104 * \since This datatype is available since SDL 3.2.0.
|
|
|
105 */
|
|
|
106 typedef Uint32 SDL_JoystickID;
|
|
|
107
|
|
|
108 /**
|
|
|
109 * An enum of some common joystick types.
|
|
|
110 *
|
|
|
111 * In some cases, SDL can identify a low-level joystick as being a certain
|
|
|
112 * type of device, and will report it through SDL_GetJoystickType (or
|
|
|
113 * SDL_GetJoystickTypeForID).
|
|
|
114 *
|
|
|
115 * This is by no means a complete list of everything that can be plugged into
|
|
|
116 * a computer.
|
|
|
117 *
|
|
|
118 * You may refer to
|
|
|
119 * [XInput Controller Types](https://learn.microsoft.com/en-us/windows/win32/xinput/xinput-and-controller-subtypes)
|
|
|
120 * table for a general understanding of each joystick type.
|
|
|
121 *
|
|
|
122 * \since This enum is available since SDL 3.2.0.
|
|
|
123 */
|
|
|
124 typedef enum SDL_JoystickType
|
|
|
125 {
|
|
|
126 SDL_JOYSTICK_TYPE_UNKNOWN,
|
|
|
127 SDL_JOYSTICK_TYPE_GAMEPAD,
|
|
|
128 SDL_JOYSTICK_TYPE_WHEEL,
|
|
|
129 SDL_JOYSTICK_TYPE_ARCADE_STICK,
|
|
|
130 SDL_JOYSTICK_TYPE_FLIGHT_STICK,
|
|
|
131 SDL_JOYSTICK_TYPE_DANCE_PAD,
|
|
|
132 SDL_JOYSTICK_TYPE_GUITAR,
|
|
|
133 SDL_JOYSTICK_TYPE_DRUM_KIT,
|
|
|
134 SDL_JOYSTICK_TYPE_ARCADE_PAD,
|
|
|
135 SDL_JOYSTICK_TYPE_THROTTLE,
|
|
|
136 SDL_JOYSTICK_TYPE_COUNT
|
|
|
137 } SDL_JoystickType;
|
|
|
138
|
|
|
139 /**
|
|
|
140 * Possible connection states for a joystick device.
|
|
|
141 *
|
|
|
142 * This is used by SDL_GetJoystickConnectionState to report how a device is
|
|
|
143 * connected to the system.
|
|
|
144 *
|
|
|
145 * \since This enum is available since SDL 3.2.0.
|
|
|
146 */
|
|
|
147 typedef enum SDL_JoystickConnectionState
|
|
|
148 {
|
|
|
149 SDL_JOYSTICK_CONNECTION_INVALID = -1,
|
|
|
150 SDL_JOYSTICK_CONNECTION_UNKNOWN,
|
|
|
151 SDL_JOYSTICK_CONNECTION_WIRED,
|
|
|
152 SDL_JOYSTICK_CONNECTION_WIRELESS
|
|
|
153 } SDL_JoystickConnectionState;
|
|
|
154
|
|
|
155 /**
|
|
|
156 * The largest value an SDL_Joystick's axis can report.
|
|
|
157 *
|
|
|
158 * \since This macro is available since SDL 3.2.0.
|
|
|
159 *
|
|
|
160 * \sa SDL_JOYSTICK_AXIS_MIN
|
|
|
161 */
|
|
|
162 #define SDL_JOYSTICK_AXIS_MAX 32767
|
|
|
163
|
|
|
164 /**
|
|
|
165 * The smallest value an SDL_Joystick's axis can report.
|
|
|
166 *
|
|
|
167 * This is a negative number!
|
|
|
168 *
|
|
|
169 * \since This macro is available since SDL 3.2.0.
|
|
|
170 *
|
|
|
171 * \sa SDL_JOYSTICK_AXIS_MAX
|
|
|
172 */
|
|
|
173 #define SDL_JOYSTICK_AXIS_MIN -32768
|
|
|
174
|
|
|
175
|
|
|
176 /* Function prototypes */
|
|
|
177
|
|
|
178 /**
|
|
|
179 * Locking for atomic access to the joystick API.
|
|
|
180 *
|
|
|
181 * The SDL joystick functions are thread-safe, however you can lock the
|
|
|
182 * joysticks while processing to guarantee that the joystick list won't change
|
|
|
183 * and joystick and gamepad events will not be delivered.
|
|
|
184 *
|
|
|
185 * \threadsafety It is safe to call this function from any thread.
|
|
|
186 *
|
|
|
187 * \since This function is available since SDL 3.2.0.
|
|
|
188 */
|
|
|
189 extern SDL_DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock);
|
|
|
190
|
|
|
191 /**
|
|
|
192 * Unlocking for atomic access to the joystick API.
|
|
|
193 *
|
|
|
194 * \threadsafety This should be called from the same thread that called
|
|
|
195 * SDL_LockJoysticks().
|
|
|
196 *
|
|
|
197 * \since This function is available since SDL 3.2.0.
|
|
|
198 */
|
|
|
199 extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock);
|
|
|
200
|
|
|
201 /**
|
|
|
202 * Return whether a joystick is currently connected.
|
|
|
203 *
|
|
|
204 * \returns true if a joystick is connected, false otherwise.
|
|
|
205 *
|
|
|
206 * \threadsafety It is safe to call this function from any thread.
|
|
|
207 *
|
|
|
208 * \since This function is available since SDL 3.2.0.
|
|
|
209 *
|
|
|
210 * \sa SDL_GetJoysticks
|
|
|
211 */
|
|
|
212 extern SDL_DECLSPEC bool SDLCALL SDL_HasJoystick(void);
|
|
|
213
|
|
|
214 /**
|
|
|
215 * Get a list of currently connected joysticks.
|
|
|
216 *
|
|
|
217 * \param count a pointer filled in with the number of joysticks returned, may
|
|
|
218 * be NULL.
|
|
|
219 * \returns a 0 terminated array of joystick instance IDs or NULL on failure;
|
|
|
220 * call SDL_GetError() for more information. This should be freed
|
|
|
221 * with SDL_free() when it is no longer needed.
|
|
|
222 *
|
|
|
223 * \threadsafety It is safe to call this function from any thread.
|
|
|
224 *
|
|
|
225 * \since This function is available since SDL 3.2.0.
|
|
|
226 *
|
|
|
227 * \sa SDL_HasJoystick
|
|
|
228 * \sa SDL_OpenJoystick
|
|
|
229 */
|
|
|
230 extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count);
|
|
|
231
|
|
|
232 /**
|
|
|
233 * Get the implementation dependent name of a joystick.
|
|
|
234 *
|
|
|
235 * This can be called before any joysticks are opened.
|
|
|
236 *
|
|
|
237 * \param instance_id the joystick instance ID.
|
|
|
238 * \returns the name of the selected joystick. If no name can be found, this
|
|
|
239 * function returns NULL; call SDL_GetError() for more information.
|
|
|
240 *
|
|
|
241 * \threadsafety It is safe to call this function from any thread.
|
|
|
242 *
|
|
|
243 * \since This function is available since SDL 3.2.0.
|
|
|
244 *
|
|
|
245 * \sa SDL_GetJoystickName
|
|
|
246 * \sa SDL_GetJoysticks
|
|
|
247 */
|
|
|
248 extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID instance_id);
|
|
|
249
|
|
|
250 /**
|
|
|
251 * Get the implementation dependent path of a joystick.
|
|
|
252 *
|
|
|
253 * This can be called before any joysticks are opened.
|
|
|
254 *
|
|
|
255 * \param instance_id the joystick instance ID.
|
|
|
256 * \returns the path of the selected joystick. If no path can be found, this
|
|
|
257 * function returns NULL; call SDL_GetError() for more information.
|
|
|
258 *
|
|
|
259 * \threadsafety It is safe to call this function from any thread.
|
|
|
260 *
|
|
|
261 * \since This function is available since SDL 3.2.0.
|
|
|
262 *
|
|
|
263 * \sa SDL_GetJoystickPath
|
|
|
264 * \sa SDL_GetJoysticks
|
|
|
265 */
|
|
|
266 extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPathForID(SDL_JoystickID instance_id);
|
|
|
267
|
|
|
268 /**
|
|
|
269 * Get the player index of a joystick.
|
|
|
270 *
|
|
|
271 * This can be called before any joysticks are opened.
|
|
|
272 *
|
|
|
273 * \param instance_id the joystick instance ID.
|
|
|
274 * \returns the player index of a joystick, or -1 if it's not available.
|
|
|
275 *
|
|
|
276 * \threadsafety It is safe to call this function from any thread.
|
|
|
277 *
|
|
|
278 * \since This function is available since SDL 3.2.0.
|
|
|
279 *
|
|
|
280 * \sa SDL_GetJoystickPlayerIndex
|
|
|
281 * \sa SDL_GetJoysticks
|
|
|
282 */
|
|
|
283 extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndexForID(SDL_JoystickID instance_id);
|
|
|
284
|
|
|
285 /**
|
|
|
286 * Get the implementation-dependent GUID of a joystick.
|
|
|
287 *
|
|
|
288 * This can be called before any joysticks are opened.
|
|
|
289 *
|
|
|
290 * \param instance_id the joystick instance ID.
|
|
|
291 * \returns the GUID of the selected joystick. If called with an invalid
|
|
|
292 * instance_id, this function returns a zero GUID.
|
|
|
293 *
|
|
|
294 * \threadsafety It is safe to call this function from any thread.
|
|
|
295 *
|
|
|
296 * \since This function is available since SDL 3.2.0.
|
|
|
297 *
|
|
|
298 * \sa SDL_GetJoystickGUID
|
|
|
299 * \sa SDL_GUIDToString
|
|
|
300 */
|
|
|
301 extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUIDForID(SDL_JoystickID instance_id);
|
|
|
302
|
|
|
303 /**
|
|
|
304 * Get the USB vendor ID of a joystick, if available.
|
|
|
305 *
|
|
|
306 * This can be called before any joysticks are opened. If the vendor ID isn't
|
|
|
307 * available this function returns 0.
|
|
|
308 *
|
|
|
309 * \param instance_id the joystick instance ID.
|
|
|
310 * \returns the USB vendor ID of the selected joystick. If called with an
|
|
|
311 * invalid instance_id, this function returns 0.
|
|
|
312 *
|
|
|
313 * \threadsafety It is safe to call this function from any thread.
|
|
|
314 *
|
|
|
315 * \since This function is available since SDL 3.2.0.
|
|
|
316 *
|
|
|
317 * \sa SDL_GetJoystickVendor
|
|
|
318 * \sa SDL_GetJoysticks
|
|
|
319 */
|
|
|
320 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendorForID(SDL_JoystickID instance_id);
|
|
|
321
|
|
|
322 /**
|
|
|
323 * Get the USB product ID of a joystick, if available.
|
|
|
324 *
|
|
|
325 * This can be called before any joysticks are opened. If the product ID isn't
|
|
|
326 * available this function returns 0.
|
|
|
327 *
|
|
|
328 * \param instance_id the joystick instance ID.
|
|
|
329 * \returns the USB product ID of the selected joystick. If called with an
|
|
|
330 * invalid instance_id, this function returns 0.
|
|
|
331 *
|
|
|
332 * \threadsafety It is safe to call this function from any thread.
|
|
|
333 *
|
|
|
334 * \since This function is available since SDL 3.2.0.
|
|
|
335 *
|
|
|
336 * \sa SDL_GetJoystickProduct
|
|
|
337 * \sa SDL_GetJoysticks
|
|
|
338 */
|
|
|
339 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductForID(SDL_JoystickID instance_id);
|
|
|
340
|
|
|
341 /**
|
|
|
342 * Get the product version of a joystick, if available.
|
|
|
343 *
|
|
|
344 * This can be called before any joysticks are opened. If the product version
|
|
|
345 * isn't available this function returns 0.
|
|
|
346 *
|
|
|
347 * \param instance_id the joystick instance ID.
|
|
|
348 * \returns the product version of the selected joystick. If called with an
|
|
|
349 * invalid instance_id, this function returns 0.
|
|
|
350 *
|
|
|
351 * \threadsafety It is safe to call this function from any thread.
|
|
|
352 *
|
|
|
353 * \since This function is available since SDL 3.2.0.
|
|
|
354 *
|
|
|
355 * \sa SDL_GetJoystickProductVersion
|
|
|
356 * \sa SDL_GetJoysticks
|
|
|
357 */
|
|
|
358 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersionForID(SDL_JoystickID instance_id);
|
|
|
359
|
|
|
360 /**
|
|
|
361 * Get the type of a joystick, if available.
|
|
|
362 *
|
|
|
363 * This can be called before any joysticks are opened.
|
|
|
364 *
|
|
|
365 * \param instance_id the joystick instance ID.
|
|
|
366 * \returns the SDL_JoystickType of the selected joystick. If called with an
|
|
|
367 * invalid instance_id, this function returns
|
|
|
368 * `SDL_JOYSTICK_TYPE_UNKNOWN`.
|
|
|
369 *
|
|
|
370 * \threadsafety It is safe to call this function from any thread.
|
|
|
371 *
|
|
|
372 * \since This function is available since SDL 3.2.0.
|
|
|
373 *
|
|
|
374 * \sa SDL_GetJoystickType
|
|
|
375 * \sa SDL_GetJoysticks
|
|
|
376 */
|
|
|
377 extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_JoystickID instance_id);
|
|
|
378
|
|
|
379 /**
|
|
|
380 * Open a joystick for use.
|
|
|
381 *
|
|
|
382 * The joystick subsystem must be initialized before a joystick can be opened
|
|
|
383 * for use.
|
|
|
384 *
|
|
|
385 * \param instance_id the joystick instance ID.
|
|
|
386 * \returns a joystick identifier or NULL on failure; call SDL_GetError() for
|
|
|
387 * more information.
|
|
|
388 *
|
|
|
389 * \threadsafety It is safe to call this function from any thread.
|
|
|
390 *
|
|
|
391 * \since This function is available since SDL 3.2.0.
|
|
|
392 *
|
|
|
393 * \sa SDL_CloseJoystick
|
|
|
394 */
|
|
|
395 extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_OpenJoystick(SDL_JoystickID instance_id);
|
|
|
396
|
|
|
397 /**
|
|
|
398 * Get the SDL_Joystick associated with an instance ID, if it has been opened.
|
|
|
399 *
|
|
|
400 * \param instance_id the instance ID to get the SDL_Joystick for.
|
|
|
401 * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been
|
|
|
402 * opened yet; call SDL_GetError() for more information.
|
|
|
403 *
|
|
|
404 * \threadsafety It is safe to call this function from any thread.
|
|
|
405 *
|
|
|
406 * \since This function is available since SDL 3.2.0.
|
|
|
407 */
|
|
|
408 extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID instance_id);
|
|
|
409
|
|
|
410 /**
|
|
|
411 * Get the SDL_Joystick associated with a player index.
|
|
|
412 *
|
|
|
413 * \param player_index the player index to get the SDL_Joystick for.
|
|
|
414 * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
|
|
|
415 * for more information.
|
|
|
416 *
|
|
|
417 * \threadsafety It is safe to call this function from any thread.
|
|
|
418 *
|
|
|
419 * \since This function is available since SDL 3.2.0.
|
|
|
420 *
|
|
|
421 * \sa SDL_GetJoystickPlayerIndex
|
|
|
422 * \sa SDL_SetJoystickPlayerIndex
|
|
|
423 */
|
|
|
424 extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromPlayerIndex(int player_index);
|
|
|
425
|
|
|
426 /**
|
|
|
427 * The structure that describes a virtual joystick touchpad.
|
|
|
428 *
|
|
|
429 * \since This struct is available since SDL 3.2.0.
|
|
|
430 *
|
|
|
431 * \sa SDL_VirtualJoystickDesc
|
|
|
432 */
|
|
|
433 typedef struct SDL_VirtualJoystickTouchpadDesc
|
|
|
434 {
|
|
|
435 Uint16 nfingers; /**< the number of simultaneous fingers on this touchpad */
|
|
|
436 Uint16 padding[3];
|
|
|
437 } SDL_VirtualJoystickTouchpadDesc;
|
|
|
438
|
|
|
439 /**
|
|
|
440 * The structure that describes a virtual joystick sensor.
|
|
|
441 *
|
|
|
442 * \since This struct is available since SDL 3.2.0.
|
|
|
443 *
|
|
|
444 * \sa SDL_VirtualJoystickDesc
|
|
|
445 */
|
|
|
446 typedef struct SDL_VirtualJoystickSensorDesc
|
|
|
447 {
|
|
|
448 SDL_SensorType type; /**< the type of this sensor */
|
|
|
449 float rate; /**< the update frequency of this sensor, may be 0.0f */
|
|
|
450 } SDL_VirtualJoystickSensorDesc;
|
|
|
451
|
|
|
452 /**
|
|
|
453 * The structure that describes a virtual joystick.
|
|
|
454 *
|
|
|
455 * This structure should be initialized using SDL_INIT_INTERFACE(). All
|
|
|
456 * elements of this structure are optional.
|
|
|
457 *
|
|
|
458 * \since This struct is available since SDL 3.2.0.
|
|
|
459 *
|
|
|
460 * \sa SDL_AttachVirtualJoystick
|
|
|
461 * \sa SDL_INIT_INTERFACE
|
|
|
462 * \sa SDL_VirtualJoystickSensorDesc
|
|
|
463 * \sa SDL_VirtualJoystickTouchpadDesc
|
|
|
464 */
|
|
|
465 typedef struct SDL_VirtualJoystickDesc
|
|
|
466 {
|
|
|
467 Uint32 version; /**< the version of this interface */
|
|
|
468 Uint16 type; /**< `SDL_JoystickType` */
|
|
|
469 Uint16 padding; /**< unused */
|
|
|
470 Uint16 vendor_id; /**< the USB vendor ID of this joystick */
|
|
|
471 Uint16 product_id; /**< the USB product ID of this joystick */
|
|
|
472 Uint16 naxes; /**< the number of axes on this joystick */
|
|
|
473 Uint16 nbuttons; /**< the number of buttons on this joystick */
|
|
|
474 Uint16 nballs; /**< the number of balls on this joystick */
|
|
|
475 Uint16 nhats; /**< the number of hats on this joystick */
|
|
|
476 Uint16 ntouchpads; /**< the number of touchpads on this joystick, requires `touchpads` to point at valid descriptions */
|
|
|
477 Uint16 nsensors; /**< the number of sensors on this joystick, requires `sensors` to point at valid descriptions */
|
|
|
478 Uint16 padding2[2]; /**< unused */
|
|
|
479 Uint32 button_mask; /**< A mask of which buttons are valid for this controller
|
|
|
480 e.g. (1 << SDL_GAMEPAD_BUTTON_SOUTH) */
|
|
|
481 Uint32 axis_mask; /**< A mask of which axes are valid for this controller
|
|
|
482 e.g. (1 << SDL_GAMEPAD_AXIS_LEFTX) */
|
|
|
483 const char *name; /**< the name of the joystick */
|
|
|
484 const SDL_VirtualJoystickTouchpadDesc *touchpads; /**< A pointer to an array of touchpad descriptions, required if `ntouchpads` is > 0 */
|
|
|
485 const SDL_VirtualJoystickSensorDesc *sensors; /**< A pointer to an array of sensor descriptions, required if `nsensors` is > 0 */
|
|
|
486
|
|
|
487 void *userdata; /**< User data pointer passed to callbacks */
|
|
|
488 void (SDLCALL *Update)(void *userdata); /**< Called when the joystick state should be updated */
|
|
|
489 void (SDLCALL *SetPlayerIndex)(void *userdata, int player_index); /**< Called when the player index is set */
|
|
|
490 bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */
|
|
|
491 bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */
|
|
|
492 bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */
|
|
|
493 bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */
|
|
|
494 bool (SDLCALL *SetSensorsEnabled)(void *userdata, bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */
|
|
|
495 void (SDLCALL *Cleanup)(void *userdata); /**< Cleans up the userdata when the joystick is detached */
|
|
|
496 } SDL_VirtualJoystickDesc;
|
|
|
497
|
|
|
498 /* Check the size of SDL_VirtualJoystickDesc
|
|
|
499 *
|
|
|
500 * If this assert fails, either the compiler is padding to an unexpected size,
|
|
|
501 * or the interface has been updated and this should be updated to match and
|
|
|
502 * the code using this interface should be updated to handle the old version.
|
|
|
503 */
|
|
|
504 SDL_COMPILE_TIME_ASSERT(SDL_VirtualJoystickDesc_SIZE,
|
|
|
505 (sizeof(void *) == 4 && sizeof(SDL_VirtualJoystickDesc) == 84) ||
|
|
|
506 (sizeof(void *) == 8 && sizeof(SDL_VirtualJoystickDesc) == 136));
|
|
|
507
|
|
|
508 /**
|
|
|
509 * Attach a new virtual joystick.
|
|
|
510 *
|
|
|
511 * Apps can create virtual joysticks, that exist without hardware directly
|
|
|
512 * backing them, and have program-supplied inputs. Once attached, a virtual
|
|
|
513 * joystick looks like any other joystick that SDL can access. These can be
|
|
|
514 * used to make other things look like joysticks, or provide pre-recorded
|
|
|
515 * input, etc.
|
|
|
516 *
|
|
|
517 * Once attached, the app can send joystick inputs to the new virtual joystick
|
|
|
518 * using SDL_SetJoystickVirtualAxis(), etc.
|
|
|
519 *
|
|
|
520 * When no longer needed, the virtual joystick can be removed by calling
|
|
|
521 * SDL_DetachVirtualJoystick().
|
|
|
522 *
|
|
|
523 * \param desc joystick description, initialized using SDL_INIT_INTERFACE().
|
|
|
524 * \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for
|
|
|
525 * more information.
|
|
|
526 *
|
|
|
527 * \threadsafety It is safe to call this function from any thread.
|
|
|
528 *
|
|
|
529 * \since This function is available since SDL 3.2.0.
|
|
|
530 *
|
|
|
531 * \sa SDL_DetachVirtualJoystick
|
|
|
532 * \sa SDL_SetJoystickVirtualAxis
|
|
|
533 * \sa SDL_SetJoystickVirtualButton
|
|
|
534 * \sa SDL_SetJoystickVirtualBall
|
|
|
535 * \sa SDL_SetJoystickVirtualHat
|
|
|
536 * \sa SDL_SetJoystickVirtualTouchpad
|
|
|
537 * \sa SDL_SetJoystickVirtualSensorData
|
|
|
538 */
|
|
|
539 extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_VirtualJoystickDesc *desc);
|
|
|
540
|
|
|
541 /**
|
|
|
542 * Detach a virtual joystick.
|
|
|
543 *
|
|
|
544 * \param instance_id the joystick instance ID, previously returned from
|
|
|
545 * SDL_AttachVirtualJoystick().
|
|
|
546 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
547 * information.
|
|
|
548 *
|
|
|
549 * \threadsafety It is safe to call this function from any thread.
|
|
|
550 *
|
|
|
551 * \since This function is available since SDL 3.2.0.
|
|
|
552 *
|
|
|
553 * \sa SDL_AttachVirtualJoystick
|
|
|
554 */
|
|
|
555 extern SDL_DECLSPEC bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id);
|
|
|
556
|
|
|
557 /**
|
|
|
558 * Query whether or not a joystick is virtual.
|
|
|
559 *
|
|
|
560 * \param instance_id the joystick instance ID.
|
|
|
561 * \returns true if the joystick is virtual, false otherwise.
|
|
|
562 *
|
|
|
563 * \threadsafety It is safe to call this function from any thread.
|
|
|
564 *
|
|
|
565 * \since This function is available since SDL 3.2.0.
|
|
|
566 */
|
|
|
567 extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id);
|
|
|
568
|
|
|
569 /**
|
|
|
570 * Set the state of an axis on an opened virtual joystick.
|
|
|
571 *
|
|
|
572 * Please note that values set here will not be applied until the next call to
|
|
|
573 * SDL_UpdateJoysticks, which can either be called directly, or can be called
|
|
|
574 * indirectly through various other SDL APIs, including, but not limited to
|
|
|
575 * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
|
|
|
576 * SDL_WaitEvent.
|
|
|
577 *
|
|
|
578 * Note that when sending trigger axes, you should scale the value to the full
|
|
|
579 * range of Sint16. For example, a trigger at rest would have the value of
|
|
|
580 * `SDL_JOYSTICK_AXIS_MIN`.
|
|
|
581 *
|
|
|
582 * \param joystick the virtual joystick on which to set state.
|
|
|
583 * \param axis the index of the axis on the virtual joystick to update.
|
|
|
584 * \param value the new value for the specified axis.
|
|
|
585 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
586 * information.
|
|
|
587 *
|
|
|
588 * \threadsafety It is safe to call this function from any thread.
|
|
|
589 *
|
|
|
590 * \since This function is available since SDL 3.2.0.
|
|
|
591 *
|
|
|
592 * \sa SDL_SetJoystickVirtualButton
|
|
|
593 * \sa SDL_SetJoystickVirtualBall
|
|
|
594 * \sa SDL_SetJoystickVirtualHat
|
|
|
595 * \sa SDL_SetJoystickVirtualTouchpad
|
|
|
596 * \sa SDL_SetJoystickVirtualSensorData
|
|
|
597 */
|
|
|
598 extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value);
|
|
|
599
|
|
|
600 /**
|
|
|
601 * Generate ball motion on an opened virtual joystick.
|
|
|
602 *
|
|
|
603 * Please note that values set here will not be applied until the next call to
|
|
|
604 * SDL_UpdateJoysticks, which can either be called directly, or can be called
|
|
|
605 * indirectly through various other SDL APIs, including, but not limited to
|
|
|
606 * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
|
|
|
607 * SDL_WaitEvent.
|
|
|
608 *
|
|
|
609 * \param joystick the virtual joystick on which to set state.
|
|
|
610 * \param ball the index of the ball on the virtual joystick to update.
|
|
|
611 * \param xrel the relative motion on the X axis.
|
|
|
612 * \param yrel the relative motion on the Y axis.
|
|
|
613 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
614 * information.
|
|
|
615 *
|
|
|
616 * \threadsafety It is safe to call this function from any thread.
|
|
|
617 *
|
|
|
618 * \since This function is available since SDL 3.2.0.
|
|
|
619 *
|
|
|
620 * \sa SDL_SetJoystickVirtualAxis
|
|
|
621 * \sa SDL_SetJoystickVirtualButton
|
|
|
622 * \sa SDL_SetJoystickVirtualHat
|
|
|
623 * \sa SDL_SetJoystickVirtualTouchpad
|
|
|
624 * \sa SDL_SetJoystickVirtualSensorData
|
|
|
625 */
|
|
|
626 extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel);
|
|
|
627
|
|
|
628 /**
|
|
|
629 * Set the state of a button on an opened virtual joystick.
|
|
|
630 *
|
|
|
631 * Please note that values set here will not be applied until the next call to
|
|
|
632 * SDL_UpdateJoysticks, which can either be called directly, or can be called
|
|
|
633 * indirectly through various other SDL APIs, including, but not limited to
|
|
|
634 * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
|
|
|
635 * SDL_WaitEvent.
|
|
|
636 *
|
|
|
637 * \param joystick the virtual joystick on which to set state.
|
|
|
638 * \param button the index of the button on the virtual joystick to update.
|
|
|
639 * \param down true if the button is pressed, false otherwise.
|
|
|
640 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
641 * information.
|
|
|
642 *
|
|
|
643 * \threadsafety It is safe to call this function from any thread.
|
|
|
644 *
|
|
|
645 * \since This function is available since SDL 3.2.0.
|
|
|
646 *
|
|
|
647 * \sa SDL_SetJoystickVirtualAxis
|
|
|
648 * \sa SDL_SetJoystickVirtualBall
|
|
|
649 * \sa SDL_SetJoystickVirtualHat
|
|
|
650 * \sa SDL_SetJoystickVirtualTouchpad
|
|
|
651 * \sa SDL_SetJoystickVirtualSensorData
|
|
|
652 */
|
|
|
653 extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, bool down);
|
|
|
654
|
|
|
655 /**
|
|
|
656 * Set the state of a hat on an opened virtual joystick.
|
|
|
657 *
|
|
|
658 * Please note that values set here will not be applied until the next call to
|
|
|
659 * SDL_UpdateJoysticks, which can either be called directly, or can be called
|
|
|
660 * indirectly through various other SDL APIs, including, but not limited to
|
|
|
661 * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
|
|
|
662 * SDL_WaitEvent.
|
|
|
663 *
|
|
|
664 * \param joystick the virtual joystick on which to set state.
|
|
|
665 * \param hat the index of the hat on the virtual joystick to update.
|
|
|
666 * \param value the new value for the specified hat.
|
|
|
667 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
668 * information.
|
|
|
669 *
|
|
|
670 * \threadsafety It is safe to call this function from any thread.
|
|
|
671 *
|
|
|
672 * \since This function is available since SDL 3.2.0.
|
|
|
673 *
|
|
|
674 * \sa SDL_SetJoystickVirtualAxis
|
|
|
675 * \sa SDL_SetJoystickVirtualButton
|
|
|
676 * \sa SDL_SetJoystickVirtualBall
|
|
|
677 * \sa SDL_SetJoystickVirtualTouchpad
|
|
|
678 * \sa SDL_SetJoystickVirtualSensorData
|
|
|
679 */
|
|
|
680 extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value);
|
|
|
681
|
|
|
682 /**
|
|
|
683 * Set touchpad finger state on an opened virtual joystick.
|
|
|
684 *
|
|
|
685 * Please note that values set here will not be applied until the next call to
|
|
|
686 * SDL_UpdateJoysticks, which can either be called directly, or can be called
|
|
|
687 * indirectly through various other SDL APIs, including, but not limited to
|
|
|
688 * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
|
|
|
689 * SDL_WaitEvent.
|
|
|
690 *
|
|
|
691 * \param joystick the virtual joystick on which to set state.
|
|
|
692 * \param touchpad the index of the touchpad on the virtual joystick to
|
|
|
693 * update.
|
|
|
694 * \param finger the index of the finger on the touchpad to set.
|
|
|
695 * \param down true if the finger is pressed, false if the finger is released.
|
|
|
696 * \param x the x coordinate of the finger on the touchpad, normalized 0 to 1,
|
|
|
697 * with the origin in the upper left.
|
|
|
698 * \param y the y coordinate of the finger on the touchpad, normalized 0 to 1,
|
|
|
699 * with the origin in the upper left.
|
|
|
700 * \param pressure the pressure of the finger.
|
|
|
701 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
702 * information.
|
|
|
703 *
|
|
|
704 * \threadsafety It is safe to call this function from any thread.
|
|
|
705 *
|
|
|
706 * \since This function is available since SDL 3.2.0.
|
|
|
707 *
|
|
|
708 * \sa SDL_SetJoystickVirtualAxis
|
|
|
709 * \sa SDL_SetJoystickVirtualButton
|
|
|
710 * \sa SDL_SetJoystickVirtualBall
|
|
|
711 * \sa SDL_SetJoystickVirtualHat
|
|
|
712 * \sa SDL_SetJoystickVirtualSensorData
|
|
|
713 */
|
|
|
714 extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, bool down, float x, float y, float pressure);
|
|
|
715
|
|
|
716 /**
|
|
|
717 * Send a sensor update for an opened virtual joystick.
|
|
|
718 *
|
|
|
719 * Please note that values set here will not be applied until the next call to
|
|
|
720 * SDL_UpdateJoysticks, which can either be called directly, or can be called
|
|
|
721 * indirectly through various other SDL APIs, including, but not limited to
|
|
|
722 * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
|
|
|
723 * SDL_WaitEvent.
|
|
|
724 *
|
|
|
725 * \param joystick the virtual joystick on which to set state.
|
|
|
726 * \param type the type of the sensor on the virtual joystick to update.
|
|
|
727 * \param sensor_timestamp a 64-bit timestamp in nanoseconds associated with
|
|
|
728 * the sensor reading.
|
|
|
729 * \param data the data associated with the sensor reading.
|
|
|
730 * \param num_values the number of values pointed to by `data`.
|
|
|
731 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
732 * information.
|
|
|
733 *
|
|
|
734 * \threadsafety It is safe to call this function from any thread.
|
|
|
735 *
|
|
|
736 * \since This function is available since SDL 3.2.0.
|
|
|
737 *
|
|
|
738 * \sa SDL_SetJoystickVirtualAxis
|
|
|
739 * \sa SDL_SetJoystickVirtualButton
|
|
|
740 * \sa SDL_SetJoystickVirtualBall
|
|
|
741 * \sa SDL_SetJoystickVirtualHat
|
|
|
742 * \sa SDL_SetJoystickVirtualTouchpad
|
|
|
743 */
|
|
|
744 extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values);
|
|
|
745
|
|
|
746 /**
|
|
|
747 * Get the properties associated with a joystick.
|
|
|
748 *
|
|
|
749 * The following read-only properties are provided by SDL:
|
|
|
750 *
|
|
|
751 * - `SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN`: true if this joystick has an
|
|
|
752 * LED that has adjustable brightness
|
|
|
753 * - `SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN`: true if this joystick has an LED
|
|
|
754 * that has adjustable color
|
|
|
755 * - `SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN`: true if this joystick has a
|
|
|
756 * player LED
|
|
|
757 * - `SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN`: true if this joystick has
|
|
|
758 * left/right rumble
|
|
|
759 * - `SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN`: true if this joystick has
|
|
|
760 * simple trigger rumble
|
|
|
761 *
|
|
|
762 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
763 * \returns a valid property ID on success or 0 on failure; call
|
|
|
764 * SDL_GetError() for more information.
|
|
|
765 *
|
|
|
766 * \threadsafety It is safe to call this function from any thread.
|
|
|
767 *
|
|
|
768 * \since This function is available since SDL 3.2.0.
|
|
|
769 */
|
|
|
770 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick);
|
|
|
771
|
|
|
772 #define SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN "SDL.joystick.cap.mono_led"
|
|
|
773 #define SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN "SDL.joystick.cap.rgb_led"
|
|
|
774 #define SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN "SDL.joystick.cap.player_led"
|
|
|
775 #define SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN "SDL.joystick.cap.rumble"
|
|
|
776 #define SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN "SDL.joystick.cap.trigger_rumble"
|
|
|
777
|
|
|
778 /**
|
|
|
779 * Get the implementation dependent name of a joystick.
|
|
|
780 *
|
|
|
781 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
782 * \returns the name of the selected joystick. If no name can be found, this
|
|
|
783 * function returns NULL; call SDL_GetError() for more information.
|
|
|
784 *
|
|
|
785 * \threadsafety It is safe to call this function from any thread.
|
|
|
786 *
|
|
|
787 * \since This function is available since SDL 3.2.0.
|
|
|
788 *
|
|
|
789 * \sa SDL_GetJoystickNameForID
|
|
|
790 */
|
|
|
791 extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joystick);
|
|
|
792
|
|
|
793 /**
|
|
|
794 * Get the implementation dependent path of a joystick.
|
|
|
795 *
|
|
|
796 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
797 * \returns the path of the selected joystick. If no path can be found, this
|
|
|
798 * function returns NULL; call SDL_GetError() for more information.
|
|
|
799 *
|
|
|
800 * \threadsafety It is safe to call this function from any thread.
|
|
|
801 *
|
|
|
802 * \since This function is available since SDL 3.2.0.
|
|
|
803 *
|
|
|
804 * \sa SDL_GetJoystickPathForID
|
|
|
805 */
|
|
|
806 extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPath(SDL_Joystick *joystick);
|
|
|
807
|
|
|
808 /**
|
|
|
809 * Get the player index of an opened joystick.
|
|
|
810 *
|
|
|
811 * For XInput controllers this returns the XInput user index. Many joysticks
|
|
|
812 * will not be able to supply this information.
|
|
|
813 *
|
|
|
814 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
815 * \returns the player index, or -1 if it's not available.
|
|
|
816 *
|
|
|
817 * \threadsafety It is safe to call this function from any thread.
|
|
|
818 *
|
|
|
819 * \since This function is available since SDL 3.2.0.
|
|
|
820 *
|
|
|
821 * \sa SDL_SetJoystickPlayerIndex
|
|
|
822 */
|
|
|
823 extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystick);
|
|
|
824
|
|
|
825 /**
|
|
|
826 * Set the player index of an opened joystick.
|
|
|
827 *
|
|
|
828 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
829 * \param player_index player index to assign to this joystick, or -1 to clear
|
|
|
830 * the player index and turn off player LEDs.
|
|
|
831 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
832 * information.
|
|
|
833 *
|
|
|
834 * \threadsafety It is safe to call this function from any thread.
|
|
|
835 *
|
|
|
836 * \since This function is available since SDL 3.2.0.
|
|
|
837 *
|
|
|
838 * \sa SDL_GetJoystickPlayerIndex
|
|
|
839 */
|
|
|
840 extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index);
|
|
|
841
|
|
|
842 /**
|
|
|
843 * Get the implementation-dependent GUID for the joystick.
|
|
|
844 *
|
|
|
845 * This function requires an open joystick.
|
|
|
846 *
|
|
|
847 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
848 * \returns the GUID of the given joystick. If called on an invalid index,
|
|
|
849 * this function returns a zero GUID; call SDL_GetError() for more
|
|
|
850 * information.
|
|
|
851 *
|
|
|
852 * \threadsafety It is safe to call this function from any thread.
|
|
|
853 *
|
|
|
854 * \since This function is available since SDL 3.2.0.
|
|
|
855 *
|
|
|
856 * \sa SDL_GetJoystickGUIDForID
|
|
|
857 * \sa SDL_GUIDToString
|
|
|
858 */
|
|
|
859 extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *joystick);
|
|
|
860
|
|
|
861 /**
|
|
|
862 * Get the USB vendor ID of an opened joystick, if available.
|
|
|
863 *
|
|
|
864 * If the vendor ID isn't available this function returns 0.
|
|
|
865 *
|
|
|
866 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
867 * \returns the USB vendor ID of the selected joystick, or 0 if unavailable.
|
|
|
868 *
|
|
|
869 * \threadsafety It is safe to call this function from any thread.
|
|
|
870 *
|
|
|
871 * \since This function is available since SDL 3.2.0.
|
|
|
872 *
|
|
|
873 * \sa SDL_GetJoystickVendorForID
|
|
|
874 */
|
|
|
875 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendor(SDL_Joystick *joystick);
|
|
|
876
|
|
|
877 /**
|
|
|
878 * Get the USB product ID of an opened joystick, if available.
|
|
|
879 *
|
|
|
880 * If the product ID isn't available this function returns 0.
|
|
|
881 *
|
|
|
882 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
883 * \returns the USB product ID of the selected joystick, or 0 if unavailable.
|
|
|
884 *
|
|
|
885 * \threadsafety It is safe to call this function from any thread.
|
|
|
886 *
|
|
|
887 * \since This function is available since SDL 3.2.0.
|
|
|
888 *
|
|
|
889 * \sa SDL_GetJoystickProductForID
|
|
|
890 */
|
|
|
891 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProduct(SDL_Joystick *joystick);
|
|
|
892
|
|
|
893 /**
|
|
|
894 * Get the product version of an opened joystick, if available.
|
|
|
895 *
|
|
|
896 * If the product version isn't available this function returns 0.
|
|
|
897 *
|
|
|
898 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
899 * \returns the product version of the selected joystick, or 0 if unavailable.
|
|
|
900 *
|
|
|
901 * \threadsafety It is safe to call this function from any thread.
|
|
|
902 *
|
|
|
903 * \since This function is available since SDL 3.2.0.
|
|
|
904 *
|
|
|
905 * \sa SDL_GetJoystickProductVersionForID
|
|
|
906 */
|
|
|
907 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersion(SDL_Joystick *joystick);
|
|
|
908
|
|
|
909 /**
|
|
|
910 * Get the firmware version of an opened joystick, if available.
|
|
|
911 *
|
|
|
912 * If the firmware version isn't available this function returns 0.
|
|
|
913 *
|
|
|
914 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
915 * \returns the firmware version of the selected joystick, or 0 if
|
|
|
916 * unavailable.
|
|
|
917 *
|
|
|
918 * \threadsafety It is safe to call this function from any thread.
|
|
|
919 *
|
|
|
920 * \since This function is available since SDL 3.2.0.
|
|
|
921 */
|
|
|
922 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *joystick);
|
|
|
923
|
|
|
924 /**
|
|
|
925 * Get the serial number of an opened joystick, if available.
|
|
|
926 *
|
|
|
927 * Returns the serial number of the joystick, or NULL if it is not available.
|
|
|
928 *
|
|
|
929 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
930 * \returns the serial number of the selected joystick, or NULL if
|
|
|
931 * unavailable.
|
|
|
932 *
|
|
|
933 * \threadsafety It is safe to call this function from any thread.
|
|
|
934 *
|
|
|
935 * \since This function is available since SDL 3.2.0.
|
|
|
936 */
|
|
|
937 extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick);
|
|
|
938
|
|
|
939 /**
|
|
|
940 * Get the type of an opened joystick.
|
|
|
941 *
|
|
|
942 * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
|
|
|
943 * \returns the SDL_JoystickType of the selected joystick.
|
|
|
944 *
|
|
|
945 * \threadsafety It is safe to call this function from any thread.
|
|
|
946 *
|
|
|
947 * \since This function is available since SDL 3.2.0.
|
|
|
948 *
|
|
|
949 * \sa SDL_GetJoystickTypeForID
|
|
|
950 */
|
|
|
951 extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *joystick);
|
|
|
952
|
|
|
953 /**
|
|
|
954 * Get the device information encoded in a SDL_GUID structure.
|
|
|
955 *
|
|
|
956 * \param guid the SDL_GUID you wish to get info about.
|
|
|
957 * \param vendor a pointer filled in with the device VID, or 0 if not
|
|
|
958 * available.
|
|
|
959 * \param product a pointer filled in with the device PID, or 0 if not
|
|
|
960 * available.
|
|
|
961 * \param version a pointer filled in with the device version, or 0 if not
|
|
|
962 * available.
|
|
|
963 * \param crc16 a pointer filled in with a CRC used to distinguish different
|
|
|
964 * products with the same VID/PID, or 0 if not available.
|
|
|
965 *
|
|
|
966 * \threadsafety It is safe to call this function from any thread.
|
|
|
967 *
|
|
|
968 * \since This function is available since SDL 3.2.0.
|
|
|
969 *
|
|
|
970 * \sa SDL_GetJoystickGUIDForID
|
|
|
971 */
|
|
|
972 extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_GUID guid, Uint16 *vendor, Uint16 *product, Uint16 *version, Uint16 *crc16);
|
|
|
973
|
|
|
974 /**
|
|
|
975 * Get the status of a specified joystick.
|
|
|
976 *
|
|
|
977 * \param joystick the joystick to query.
|
|
|
978 * \returns true if the joystick has been opened, false if it has not; call
|
|
|
979 * SDL_GetError() for more information.
|
|
|
980 *
|
|
|
981 * \threadsafety It is safe to call this function from any thread.
|
|
|
982 *
|
|
|
983 * \since This function is available since SDL 3.2.0.
|
|
|
984 */
|
|
|
985 extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick);
|
|
|
986
|
|
|
987 /**
|
|
|
988 * Get the instance ID of an opened joystick.
|
|
|
989 *
|
|
|
990 * \param joystick an SDL_Joystick structure containing joystick information.
|
|
|
991 * \returns the instance ID of the specified joystick on success or 0 on
|
|
|
992 * failure; call SDL_GetError() for more information.
|
|
|
993 *
|
|
|
994 * \threadsafety It is safe to call this function from any thread.
|
|
|
995 *
|
|
|
996 * \since This function is available since SDL 3.2.0.
|
|
|
997 */
|
|
|
998 extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joystick);
|
|
|
999
|
|
|
1000 /**
|
|
|
1001 * Get the number of general axis controls on a joystick.
|
|
|
1002 *
|
|
|
1003 * Often, the directional pad on a game controller will either look like 4
|
|
|
1004 * separate buttons or a POV hat, and not axes, but all of this is up to the
|
|
|
1005 * device and platform.
|
|
|
1006 *
|
|
|
1007 * \param joystick an SDL_Joystick structure containing joystick information.
|
|
|
1008 * \returns the number of axis controls/number of axes on success or -1 on
|
|
|
1009 * failure; call SDL_GetError() for more information.
|
|
|
1010 *
|
|
|
1011 * \threadsafety It is safe to call this function from any thread.
|
|
|
1012 *
|
|
|
1013 * \since This function is available since SDL 3.2.0.
|
|
|
1014 *
|
|
|
1015 * \sa SDL_GetJoystickAxis
|
|
|
1016 * \sa SDL_GetNumJoystickBalls
|
|
|
1017 * \sa SDL_GetNumJoystickButtons
|
|
|
1018 * \sa SDL_GetNumJoystickHats
|
|
|
1019 */
|
|
|
1020 extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick);
|
|
|
1021
|
|
|
1022 /**
|
|
|
1023 * Get the number of trackballs on a joystick.
|
|
|
1024 *
|
|
|
1025 * Joystick trackballs have only relative motion events associated with them
|
|
|
1026 * and their state cannot be polled.
|
|
|
1027 *
|
|
|
1028 * Most joysticks do not have trackballs.
|
|
|
1029 *
|
|
|
1030 * \param joystick an SDL_Joystick structure containing joystick information.
|
|
|
1031 * \returns the number of trackballs on success or -1 on failure; call
|
|
|
1032 * SDL_GetError() for more information.
|
|
|
1033 *
|
|
|
1034 * \threadsafety It is safe to call this function from any thread.
|
|
|
1035 *
|
|
|
1036 * \since This function is available since SDL 3.2.0.
|
|
|
1037 *
|
|
|
1038 * \sa SDL_GetJoystickBall
|
|
|
1039 * \sa SDL_GetNumJoystickAxes
|
|
|
1040 * \sa SDL_GetNumJoystickButtons
|
|
|
1041 * \sa SDL_GetNumJoystickHats
|
|
|
1042 */
|
|
|
1043 extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(SDL_Joystick *joystick);
|
|
|
1044
|
|
|
1045 /**
|
|
|
1046 * Get the number of POV hats on a joystick.
|
|
|
1047 *
|
|
|
1048 * \param joystick an SDL_Joystick structure containing joystick information.
|
|
|
1049 * \returns the number of POV hats on success or -1 on failure; call
|
|
|
1050 * SDL_GetError() for more information.
|
|
|
1051 *
|
|
|
1052 * \threadsafety It is safe to call this function from any thread.
|
|
|
1053 *
|
|
|
1054 * \since This function is available since SDL 3.2.0.
|
|
|
1055 *
|
|
|
1056 * \sa SDL_GetJoystickHat
|
|
|
1057 * \sa SDL_GetNumJoystickAxes
|
|
|
1058 * \sa SDL_GetNumJoystickBalls
|
|
|
1059 * \sa SDL_GetNumJoystickButtons
|
|
|
1060 */
|
|
|
1061 extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick);
|
|
|
1062
|
|
|
1063 /**
|
|
|
1064 * Get the number of buttons on a joystick.
|
|
|
1065 *
|
|
|
1066 * \param joystick an SDL_Joystick structure containing joystick information.
|
|
|
1067 * \returns the number of buttons on success or -1 on failure; call
|
|
|
1068 * SDL_GetError() for more information.
|
|
|
1069 *
|
|
|
1070 * \threadsafety It is safe to call this function from any thread.
|
|
|
1071 *
|
|
|
1072 * \since This function is available since SDL 3.2.0.
|
|
|
1073 *
|
|
|
1074 * \sa SDL_GetJoystickButton
|
|
|
1075 * \sa SDL_GetNumJoystickAxes
|
|
|
1076 * \sa SDL_GetNumJoystickBalls
|
|
|
1077 * \sa SDL_GetNumJoystickHats
|
|
|
1078 */
|
|
|
1079 extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick);
|
|
|
1080
|
|
|
1081 /**
|
|
|
1082 * Set the state of joystick event processing.
|
|
|
1083 *
|
|
|
1084 * If joystick events are disabled, you must call SDL_UpdateJoysticks()
|
|
|
1085 * yourself and check the state of the joystick when you want joystick
|
|
|
1086 * information.
|
|
|
1087 *
|
|
|
1088 * \param enabled whether to process joystick events or not.
|
|
|
1089 *
|
|
|
1090 * \threadsafety It is safe to call this function from any thread.
|
|
|
1091 *
|
|
|
1092 * \since This function is available since SDL 3.2.0.
|
|
|
1093 *
|
|
|
1094 * \sa SDL_JoystickEventsEnabled
|
|
|
1095 * \sa SDL_UpdateJoysticks
|
|
|
1096 */
|
|
|
1097 extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(bool enabled);
|
|
|
1098
|
|
|
1099 /**
|
|
|
1100 * Query the state of joystick event processing.
|
|
|
1101 *
|
|
|
1102 * If joystick events are disabled, you must call SDL_UpdateJoysticks()
|
|
|
1103 * yourself and check the state of the joystick when you want joystick
|
|
|
1104 * information.
|
|
|
1105 *
|
|
|
1106 * \returns true if joystick events are being processed, false otherwise.
|
|
|
1107 *
|
|
|
1108 * \threadsafety It is safe to call this function from any thread.
|
|
|
1109 *
|
|
|
1110 * \since This function is available since SDL 3.2.0.
|
|
|
1111 *
|
|
|
1112 * \sa SDL_SetJoystickEventsEnabled
|
|
|
1113 */
|
|
|
1114 extern SDL_DECLSPEC bool SDLCALL SDL_JoystickEventsEnabled(void);
|
|
|
1115
|
|
|
1116 /**
|
|
|
1117 * Update the current state of the open joysticks.
|
|
|
1118 *
|
|
|
1119 * This is called automatically by the event loop if any joystick events are
|
|
|
1120 * enabled.
|
|
|
1121 *
|
|
|
1122 * \threadsafety It is safe to call this function from any thread.
|
|
|
1123 *
|
|
|
1124 * \since This function is available since SDL 3.2.0.
|
|
|
1125 */
|
|
|
1126 extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void);
|
|
|
1127
|
|
|
1128 /**
|
|
|
1129 * Get the current state of an axis control on a joystick.
|
|
|
1130 *
|
|
|
1131 * SDL makes no promises about what part of the joystick any given axis refers
|
|
|
1132 * to. Your game should have some sort of configuration UI to let users
|
|
|
1133 * specify what each axis should be bound to. Alternately, SDL's higher-level
|
|
|
1134 * Game Controller API makes a great effort to apply order to this lower-level
|
|
|
1135 * interface, so you know that a specific axis is the "left thumb stick," etc.
|
|
|
1136 *
|
|
|
1137 * The value returned by SDL_GetJoystickAxis() is a signed integer (-32768 to
|
|
|
1138 * 32767) representing the current position of the axis. It may be necessary
|
|
|
1139 * to impose certain tolerances on these values to account for jitter.
|
|
|
1140 *
|
|
|
1141 * \param joystick an SDL_Joystick structure containing joystick information.
|
|
|
1142 * \param axis the axis to query; the axis indices start at index 0.
|
|
|
1143 * \returns a 16-bit signed integer representing the current position of the
|
|
|
1144 * axis or 0 on failure; call SDL_GetError() for more information.
|
|
|
1145 *
|
|
|
1146 * \threadsafety It is safe to call this function from any thread.
|
|
|
1147 *
|
|
|
1148 * \since This function is available since SDL 3.2.0.
|
|
|
1149 *
|
|
|
1150 * \sa SDL_GetNumJoystickAxes
|
|
|
1151 */
|
|
|
1152 extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, int axis);
|
|
|
1153
|
|
|
1154 /**
|
|
|
1155 * Get the initial state of an axis control on a joystick.
|
|
|
1156 *
|
|
|
1157 * The state is a value ranging from -32768 to 32767.
|
|
|
1158 *
|
|
|
1159 * The axis indices start at index 0.
|
|
|
1160 *
|
|
|
1161 * \param joystick an SDL_Joystick structure containing joystick information.
|
|
|
1162 * \param axis the axis to query; the axis indices start at index 0.
|
|
|
1163 * \param state upon return, the initial value is supplied here.
|
|
|
1164 * \returns true if this axis has any initial value, or false if not.
|
|
|
1165 *
|
|
|
1166 * \threadsafety It is safe to call this function from any thread.
|
|
|
1167 *
|
|
|
1168 * \since This function is available since SDL 3.2.0.
|
|
|
1169 */
|
|
|
1170 extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state);
|
|
|
1171
|
|
|
1172 /**
|
|
|
1173 * Get the ball axis change since the last poll.
|
|
|
1174 *
|
|
|
1175 * Trackballs can only return relative motion since the last call to
|
|
|
1176 * SDL_GetJoystickBall(), these motion deltas are placed into `dx` and `dy`.
|
|
|
1177 *
|
|
|
1178 * Most joysticks do not have trackballs.
|
|
|
1179 *
|
|
|
1180 * \param joystick the SDL_Joystick to query.
|
|
|
1181 * \param ball the ball index to query; ball indices start at index 0.
|
|
|
1182 * \param dx stores the difference in the x axis position since the last poll.
|
|
|
1183 * \param dy stores the difference in the y axis position since the last poll.
|
|
|
1184 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1185 * information.
|
|
|
1186 *
|
|
|
1187 * \threadsafety It is safe to call this function from any thread.
|
|
|
1188 *
|
|
|
1189 * \since This function is available since SDL 3.2.0.
|
|
|
1190 *
|
|
|
1191 * \sa SDL_GetNumJoystickBalls
|
|
|
1192 */
|
|
|
1193 extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy);
|
|
|
1194
|
|
|
1195 /**
|
|
|
1196 * Get the current state of a POV hat on a joystick.
|
|
|
1197 *
|
|
|
1198 * The returned value will be one of the `SDL_HAT_*` values.
|
|
|
1199 *
|
|
|
1200 * \param joystick an SDL_Joystick structure containing joystick information.
|
|
|
1201 * \param hat the hat index to get the state from; indices start at index 0.
|
|
|
1202 * \returns the current hat position.
|
|
|
1203 *
|
|
|
1204 * \threadsafety It is safe to call this function from any thread.
|
|
|
1205 *
|
|
|
1206 * \since This function is available since SDL 3.2.0.
|
|
|
1207 *
|
|
|
1208 * \sa SDL_GetNumJoystickHats
|
|
|
1209 */
|
|
|
1210 extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int hat);
|
|
|
1211
|
|
|
1212 #define SDL_HAT_CENTERED 0x00u
|
|
|
1213 #define SDL_HAT_UP 0x01u
|
|
|
1214 #define SDL_HAT_RIGHT 0x02u
|
|
|
1215 #define SDL_HAT_DOWN 0x04u
|
|
|
1216 #define SDL_HAT_LEFT 0x08u
|
|
|
1217 #define SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP)
|
|
|
1218 #define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN)
|
|
|
1219 #define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP)
|
|
|
1220 #define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN)
|
|
|
1221
|
|
|
1222 /**
|
|
|
1223 * Get the current state of a button on a joystick.
|
|
|
1224 *
|
|
|
1225 * \param joystick an SDL_Joystick structure containing joystick information.
|
|
|
1226 * \param button the button index to get the state from; indices start at
|
|
|
1227 * index 0.
|
|
|
1228 * \returns true if the button is pressed, false otherwise.
|
|
|
1229 *
|
|
|
1230 * \threadsafety It is safe to call this function from any thread.
|
|
|
1231 *
|
|
|
1232 * \since This function is available since SDL 3.2.0.
|
|
|
1233 *
|
|
|
1234 * \sa SDL_GetNumJoystickButtons
|
|
|
1235 */
|
|
|
1236 extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button);
|
|
|
1237
|
|
|
1238 /**
|
|
|
1239 * Start a rumble effect.
|
|
|
1240 *
|
|
|
1241 * Each call to this function cancels any previous rumble effect, and calling
|
|
|
1242 * it with 0 intensity stops any rumbling.
|
|
|
1243 *
|
|
|
1244 * This function requires you to process SDL events or call
|
|
|
1245 * SDL_UpdateJoysticks() to update rumble state.
|
|
|
1246 *
|
|
|
1247 * \param joystick the joystick to vibrate.
|
|
|
1248 * \param low_frequency_rumble the intensity of the low frequency (left)
|
|
|
1249 * rumble motor, from 0 to 0xFFFF.
|
|
|
1250 * \param high_frequency_rumble the intensity of the high frequency (right)
|
|
|
1251 * rumble motor, from 0 to 0xFFFF.
|
|
|
1252 * \param duration_ms the duration of the rumble effect, in milliseconds.
|
|
|
1253 * \returns true, or false if rumble isn't supported on this joystick.
|
|
|
1254 *
|
|
|
1255 * \threadsafety It is safe to call this function from any thread.
|
|
|
1256 *
|
|
|
1257 * \since This function is available since SDL 3.2.0.
|
|
|
1258 */
|
|
|
1259 extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
|
|
|
1260
|
|
|
1261 /**
|
|
|
1262 * Start a rumble effect in the joystick's triggers.
|
|
|
1263 *
|
|
|
1264 * Each call to this function cancels any previous trigger rumble effect, and
|
|
|
1265 * calling it with 0 intensity stops any rumbling.
|
|
|
1266 *
|
|
|
1267 * Note that this is rumbling of the _triggers_ and not the game controller as
|
|
|
1268 * a whole. This is currently only supported on Xbox One controllers. If you
|
|
|
1269 * want the (more common) whole-controller rumble, use SDL_RumbleJoystick()
|
|
|
1270 * instead.
|
|
|
1271 *
|
|
|
1272 * This function requires you to process SDL events or call
|
|
|
1273 * SDL_UpdateJoysticks() to update rumble state.
|
|
|
1274 *
|
|
|
1275 * \param joystick the joystick to vibrate.
|
|
|
1276 * \param left_rumble the intensity of the left trigger rumble motor, from 0
|
|
|
1277 * to 0xFFFF.
|
|
|
1278 * \param right_rumble the intensity of the right trigger rumble motor, from 0
|
|
|
1279 * to 0xFFFF.
|
|
|
1280 * \param duration_ms the duration of the rumble effect, in milliseconds.
|
|
|
1281 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1282 * information.
|
|
|
1283 *
|
|
|
1284 * \threadsafety It is safe to call this function from any thread.
|
|
|
1285 *
|
|
|
1286 * \since This function is available since SDL 3.2.0.
|
|
|
1287 *
|
|
|
1288 * \sa SDL_RumbleJoystick
|
|
|
1289 */
|
|
|
1290 extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
|
|
|
1291
|
|
|
1292 /**
|
|
|
1293 * Update a joystick's LED color.
|
|
|
1294 *
|
|
|
1295 * An example of a joystick LED is the light on the back of a PlayStation 4's
|
|
|
1296 * DualShock 4 controller.
|
|
|
1297 *
|
|
|
1298 * For joysticks with a single color LED, the maximum of the RGB values will
|
|
|
1299 * be used as the LED brightness.
|
|
|
1300 *
|
|
|
1301 * \param joystick the joystick to update.
|
|
|
1302 * \param red the intensity of the red LED.
|
|
|
1303 * \param green the intensity of the green LED.
|
|
|
1304 * \param blue the intensity of the blue LED.
|
|
|
1305 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1306 * information.
|
|
|
1307 *
|
|
|
1308 * \threadsafety It is safe to call this function from any thread.
|
|
|
1309 *
|
|
|
1310 * \since This function is available since SDL 3.2.0.
|
|
|
1311 */
|
|
|
1312 extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);
|
|
|
1313
|
|
|
1314 /**
|
|
|
1315 * Send a joystick specific effect packet.
|
|
|
1316 *
|
|
|
1317 * \param joystick the joystick to affect.
|
|
|
1318 * \param data the data to send to the joystick.
|
|
|
1319 * \param size the size of the data to send to the joystick.
|
|
|
1320 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1321 * information.
|
|
|
1322 *
|
|
|
1323 * \threadsafety It is safe to call this function from any thread.
|
|
|
1324 *
|
|
|
1325 * \since This function is available since SDL 3.2.0.
|
|
|
1326 */
|
|
|
1327 extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size);
|
|
|
1328
|
|
|
1329 /**
|
|
|
1330 * Close a joystick previously opened with SDL_OpenJoystick().
|
|
|
1331 *
|
|
|
1332 * \param joystick the joystick device to close.
|
|
|
1333 *
|
|
|
1334 * \threadsafety It is safe to call this function from any thread.
|
|
|
1335 *
|
|
|
1336 * \since This function is available since SDL 3.2.0.
|
|
|
1337 *
|
|
|
1338 * \sa SDL_OpenJoystick
|
|
|
1339 */
|
|
|
1340 extern SDL_DECLSPEC void SDLCALL SDL_CloseJoystick(SDL_Joystick *joystick);
|
|
|
1341
|
|
|
1342 /**
|
|
|
1343 * Get the connection state of a joystick.
|
|
|
1344 *
|
|
|
1345 * \param joystick the joystick to query.
|
|
|
1346 * \returns the connection state on success or
|
|
|
1347 * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError()
|
|
|
1348 * for more information.
|
|
|
1349 *
|
|
|
1350 * \threadsafety It is safe to call this function from any thread.
|
|
|
1351 *
|
|
|
1352 * \since This function is available since SDL 3.2.0.
|
|
|
1353 */
|
|
|
1354 extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectionState(SDL_Joystick *joystick);
|
|
|
1355
|
|
|
1356 /**
|
|
|
1357 * Get the battery state of a joystick.
|
|
|
1358 *
|
|
|
1359 * You should never take a battery status as absolute truth. Batteries
|
|
|
1360 * (especially failing batteries) are delicate hardware, and the values
|
|
|
1361 * reported here are best estimates based on what that hardware reports. It's
|
|
|
1362 * not uncommon for older batteries to lose stored power much faster than it
|
|
|
1363 * reports, or completely drain when reporting it has 20 percent left, etc.
|
|
|
1364 *
|
|
|
1365 * \param joystick the joystick to query.
|
|
|
1366 * \param percent a pointer filled in with the percentage of battery life
|
|
|
1367 * left, between 0 and 100, or NULL to ignore. This will be
|
|
|
1368 * filled in with -1 we can't determine a value or there is no
|
|
|
1369 * battery.
|
|
|
1370 * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure;
|
|
|
1371 * call SDL_GetError() for more information.
|
|
|
1372 *
|
|
|
1373 * \threadsafety It is safe to call this function from any thread.
|
|
|
1374 *
|
|
|
1375 * \since This function is available since SDL 3.2.0.
|
|
|
1376 */
|
|
|
1377 extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetJoystickPowerInfo(SDL_Joystick *joystick, int *percent);
|
|
|
1378
|
|
|
1379 /* Ends C function definitions when using C++ */
|
|
|
1380 #ifdef __cplusplus
|
|
|
1381 }
|
|
|
1382 #endif
|
|
|
1383 #include <SDL3/SDL_close_code.h>
|
|
|
1384
|
|
|
1385 #endif /* SDL_joystick_h_ */
|
