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