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