1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383
//! Module for SDL joystick event handling. //! //! The term `device_index` identifies currently plugged in joystick devices //! between 0 and SDL_NumJoysticks(), with the exact joystick behind a //! device_index changing as joysticks are plugged and unplugged. //! //! The term `instance_id` is the current instantiation of a joystick device in //! the system, if the joystick is removed and then re-inserted then it will get //! a new instance_id, instance_id's are monotonically increasing identifiers of //! a joystick plugged in. //! //! The term `JoystickGUID` is a stable 128-bit identifier for a joystick device //! that does not change over time, it identifies class of the device (a X360 //! wired controller for example). This identifier is platform dependent. //! //! In order to use these functions, [`SDL_Init`] must have been called //! with the [`SDL_INIT_JOYSTICK`] flag. This causes SDL to scan the system //! for joysticks, and load appropriate drivers. //! //! If you would like to receive joystick updates while the application //! is in the background, you should set the //! [`SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS`] hint before calling //! `SDL_Init`. //! //! See Also: [`gamecontroller`](crate::gamecontroller) use crate::{c_char, c_int, c_void, stdinc::*}; /// The `SDL_Joystick` type is an opaque structure. #[derive(Debug)] #[repr(transparent)] pub struct SDL_Joystick(c_void); /// A structure that encodes the stable unique id for a joystick device. #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] #[repr(C)] #[allow(missing_docs)] pub struct SDL_JoystickGUID { pub data: [u8; 16], } /// This is a unique ID for a joystick for the time it is connected to the /// system. /// /// It is never reused for the lifetime of the application. If the joystick is /// disconnected and reconnected, it will get a new ID. /// /// The ID value starts at 0 and increments from there. /// /// The value -1 is an invalid ID. #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] #[repr(transparent)] pub struct SDL_JoystickID(pub i32); /// The general physical category of a joystick device. /// /// See `SDL_JOYSTICK_TYPE_*` #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] #[repr(transparent)] pub struct SDL_JoystickType(pub i32); #[allow(missing_docs)] pub const SDL_JOYSTICK_TYPE_UNKNOWN: SDL_JoystickType = SDL_JoystickType(0); #[allow(missing_docs)] pub const SDL_JOYSTICK_TYPE_GAMECONTROLLER: SDL_JoystickType = SDL_JoystickType(1); #[allow(missing_docs)] pub const SDL_JOYSTICK_TYPE_WHEEL: SDL_JoystickType = SDL_JoystickType(2); #[allow(missing_docs)] pub const SDL_JOYSTICK_TYPE_ARCADE_STICK: SDL_JoystickType = SDL_JoystickType(3); #[allow(missing_docs)] pub const SDL_JOYSTICK_TYPE_FLIGHT_STICK: SDL_JoystickType = SDL_JoystickType(4); #[allow(missing_docs)] pub const SDL_JOYSTICK_TYPE_DANCE_PAD: SDL_JoystickType = SDL_JoystickType(5); #[allow(missing_docs)] pub const SDL_JOYSTICK_TYPE_GUITAR: SDL_JoystickType = SDL_JoystickType(6); #[allow(missing_docs)] pub const SDL_JOYSTICK_TYPE_DRUM_KIT: SDL_JoystickType = SDL_JoystickType(7); #[allow(missing_docs)] pub const SDL_JOYSTICK_TYPE_ARCADE_PAD: SDL_JoystickType = SDL_JoystickType(8); #[allow(missing_docs)] pub const SDL_JOYSTICK_TYPE_THROTTLE: SDL_JoystickType = SDL_JoystickType(9); /// The power level of a joystick. /// /// See `SDL_JOYSTICK_POWER_*` #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] #[repr(transparent)] pub struct SDL_JoystickPowerLevel(pub i32); /// The power level is unknown. pub const SDL_JOYSTICK_POWER_UNKNOWN: SDL_JoystickPowerLevel = SDL_JoystickPowerLevel(-1); /// <= 5% pub const SDL_JOYSTICK_POWER_EMPTY: SDL_JoystickPowerLevel = SDL_JoystickPowerLevel(0); /// <= 20% pub const SDL_JOYSTICK_POWER_LOW: SDL_JoystickPowerLevel = SDL_JoystickPowerLevel(1); /// <= 70% pub const SDL_JOYSTICK_POWER_MEDIUM: SDL_JoystickPowerLevel = SDL_JoystickPowerLevel(2); /// <= 100% pub const SDL_JOYSTICK_POWER_FULL: SDL_JoystickPowerLevel = SDL_JoystickPowerLevel(3); /// This joystick is wired to the rest of the system. pub const SDL_JOYSTICK_POWER_WIRED: SDL_JoystickPowerLevel = SDL_JoystickPowerLevel(4); /// Honestly, this particular constant is probably pointless. pub const SDL_JOYSTICK_POWER_MAX: SDL_JoystickPowerLevel = SDL_JoystickPowerLevel(5); /// A joystick axis uses the `i16` range, so this is just `i16::MAX` pub const SDL_JOYSTICK_AXIS_MAX: i16 = 32767; /// A joystick axis uses the `i16` range, so this is just `i16::MIN` pub const SDL_JOYSTICK_AXIS_MIN: i16 = -32768; #[allow(missing_docs)] pub const SDL_HAT_CENTERED: u8 = 0x00; #[allow(missing_docs)] pub const SDL_HAT_UP: u8 = 0x01; #[allow(missing_docs)] pub const SDL_HAT_RIGHT: u8 = 0x02; #[allow(missing_docs)] pub const SDL_HAT_DOWN: u8 = 0x04; #[allow(missing_docs)] pub const SDL_HAT_LEFT: u8 = 0x08; #[allow(missing_docs)] pub const SDL_HAT_RIGHTUP: u8 = SDL_HAT_RIGHT | SDL_HAT_UP; #[allow(missing_docs)] pub const SDL_HAT_RIGHTDOWN: u8 = SDL_HAT_RIGHT | SDL_HAT_DOWN; #[allow(missing_docs)] pub const SDL_HAT_LEFTUP: u8 = SDL_HAT_LEFT | SDL_HAT_UP; #[allow(missing_docs)] pub const SDL_HAT_LEFTDOWN: u8 = SDL_HAT_LEFT | SDL_HAT_DOWN; extern "C" { /// Locking for multi-threaded access to the joystick API /// /// If you are using the joystick API or handling events from multiple threads /// you should use these locking functions to protect access to the joysticks. /// /// In particular, you are guaranteed that the joystick list won't change, so /// the API functions that take a joystick index will be valid, and joystick /// and game controller events will not be delivered. pub fn SDL_LockJoysticks(); /// See [`SDL_LockJoysticks`] pub fn SDL_UnlockJoysticks(); /// Count the number of joysticks attached to the system right now pub fn SDL_NumJoysticks() -> c_int; /// Get the implementation dependent name of a joystick. /// /// This can be called before any joysticks are opened. If no name can be /// found, this function returns NULL. /// /// This is borrowed memory, do no free it. pub fn SDL_JoystickNameForIndex(device_index: c_int) -> *const c_char; /// Get the player index of a joystick, or -1 if it's not available. /// /// This can be called before any joysticks are opened. pub fn SDL_JoystickGetDevicePlayerIndex(device_index: c_int) -> c_int; /// Return the GUID for the joystick at this index. /// /// This can be called before any joysticks are opened. pub fn SDL_JoystickGetDeviceGUID(device_index: c_int) -> SDL_JoystickGUID; /// Get the USB vendor ID of a joystick, if available. /// /// This can be called before any joysticks are opened. /// /// If the vendor ID isn't available this function returns 0. pub fn SDL_JoystickGetDeviceVendor(device_index: c_int) -> Uint16; /// Get the USB product ID of a joystick, if available. /// /// This can be called before any joysticks are opened. /// /// If the product ID isn't available this function returns 0. pub fn SDL_JoystickGetDeviceProduct(device_index: c_int) -> Uint16; /// Get the product version of a joystick, if available. /// /// This can be called before any joysticks are opened. /// /// If the product version isn't available this function returns 0. pub fn SDL_JoystickGetDeviceProductVersion(device_index: c_int) -> Uint16; /// Get the type of a joystick, if available. /// /// This can be called before any joysticks are opened. pub fn SDL_JoystickGetDeviceType(device_index: c_int) -> SDL_JoystickType; /// Get the instance ID of a joystick. /// /// This can be called before any joysticks are opened. /// /// If the index is out of range, this function will return -1. pub fn SDL_JoystickGetDeviceInstanceID(device_index: c_int) -> SDL_JoystickID; /// Open a joystick for use. /// /// The index passed as an argument refers to the N'th joystick on the system. /// This index is not the value which will identify this joystick in future /// joystick events. The joystick's instance id ([`SDL_JoystickID`]) will be /// used there instead. /// /// **Return:** A joystick identifier, or NULL if an error occurred. pub fn SDL_JoystickOpen(device_index: c_int) -> *mut SDL_Joystick; /// Return the SDL_Joystick associated with an instance id. pub fn SDL_JoystickFromInstanceID( instance_id: SDL_JoystickID, ) -> *mut SDL_Joystick; /// Return the SDL_Joystick associated with a player index. pub fn SDL_JoystickFromPlayerIndex(player_index: c_int) -> *mut SDL_Joystick; /// Return the name for this currently opened joystick. /// /// If no name can be found, this function returns NULL. pub fn SDL_JoystickName(joystick: *mut SDL_Joystick) -> *const c_char; /// Get the player index of an opened joystick, or -1 if it's not available. /// /// For XInput controllers this returns the XInput user index. pub fn SDL_JoystickGetPlayerIndex(joystick: *mut SDL_Joystick) -> c_int; /// Set the player index of an opened joystick. pub fn SDL_JoystickSetPlayerIndex( joystick: *mut SDL_Joystick, player_index: c_int, ); /// Return the GUID for this opened joystick. pub fn SDL_JoystickGetGUID(joystick: *mut SDL_Joystick) -> SDL_JoystickGUID; /// Get the USB vendor ID of an opened joystick, if available. /// /// If the vendor ID isn't available this function returns 0. pub fn SDL_JoystickGetVendor(joystick: *mut SDL_Joystick) -> Uint16; /// Get the USB product ID of an opened joystick, if available. /// /// If the product ID isn't available this function returns 0. pub fn SDL_JoystickGetProduct(joystick: *mut SDL_Joystick) -> Uint16; /// Get the product version of an opened joystick, if available. /// /// If the product ID isn't available this function returns 0. pub fn SDL_JoystickGetProductVersion(joystick: *mut SDL_Joystick) -> Uint16; /// Get the type of an opened joystick. pub fn SDL_JoystickGetType(joystick: *mut SDL_Joystick) -> SDL_JoystickType; /// Return a string representation for this guid. /// /// `pszGUID` must point to at least 33 bytes. 32 for the string, plus a NULL /// terminator. pub fn SDL_JoystickGetGUIDString( guid: SDL_JoystickGUID, pszGUID: *mut c_char, cbGUID: c_int, ); /// Convert a string into a joystick guid pub fn SDL_JoystickGetGUIDFromString( pchGUID: *const c_char, ) -> SDL_JoystickGUID; /// Returns `SDL_TRUE` if the joystick has been opened and it is currently /// connected, or `SDL_FALSE` if it has not. pub fn SDL_JoystickGetAttached(joystick: *mut SDL_Joystick) -> SDL_bool; /// Get the instance ID of an opened joystick or -1 if the joystick is /// invalid. pub fn SDL_JoystickInstanceID(joystick: *mut SDL_Joystick) -> SDL_JoystickID; /// Get the number of general axis controls on a joystick. pub fn SDL_JoystickNumAxes(joystick: *mut SDL_Joystick) -> c_int; /// Get the number of trackballs on a joystick. /// /// Joystick trackballs have only relative motion events associated with them. /// There's no "absolute" position to poll. pub fn SDL_JoystickNumBalls(joystick: *mut SDL_Joystick) -> c_int; /// Get the number of POV hats on a joystick. pub fn SDL_JoystickNumHats(joystick: *mut SDL_Joystick) -> c_int; /// Get the number of buttons on a joystick. pub fn SDL_JoystickNumButtons(joystick: *mut SDL_Joystick) -> c_int; /// Update the current state of the open joysticks. /// /// This is called automatically by the event loop if any joystick events are /// enabled. pub fn SDL_JoystickUpdate(); /// Enable/disable joystick event polling. /// /// If joystick events are disabled, you must call [`SDL_JoystickUpdate`] /// yourself and check the state of the joystick when you want joystick /// information. /// /// The state can be one of [`SDL_QUERY`], [`SDL_ENABLE`], or [`SDL_IGNORE`]. pub fn SDL_JoystickEventState(state: c_int) -> c_int; /// Get the current state of an axis control on a joystick. /// /// The state is a value ranging from -32768 to 32767. /// /// The axis indices start at index 0. pub fn SDL_JoystickGetAxis( joystick: *mut SDL_Joystick, axis: c_int, ) -> Sint16; /// Get the initial state of an axis control on a joystick. /// /// The state is a value ranging from -32768 to 32767. /// /// The axis indices start at index 0. /// /// **Returns:** `SDL_TRUE` if this axis has any initial value, or `SDL_FALSE` /// if not. pub fn SDL_JoystickGetAxisInitialState( joystick: *mut SDL_Joystick, axis: c_int, state: *mut Sint16, ) -> SDL_bool; /// Get the current state of a POV hat on a joystick. /// /// The hat indices start at index 0. /// /// **Returns:** The return value is one of the `SDL_HAT_*` constants. pub fn SDL_JoystickGetHat(joystick: *mut SDL_Joystick, hat: c_int) -> u8; /// Get the ball axis change since the last poll. /// /// **Return:** 0, or -1 if you passed it invalid parameters. /// /// The ball indices start at index 0. pub fn SDL_JoystickGetBall( joystick: *mut SDL_Joystick, ball: c_int, dx: *mut c_int, dy: *mut c_int, ) -> c_int; /// Get the current state of a button on a joystick. /// /// The button indices start at index 0. pub fn SDL_JoystickGetButton( joystick: *mut SDL_Joystick, button: c_int, ) -> Uint8; /// Trigger a rumble effect. /// /// Each call to this function cancels any previous rumble effect, and calling /// it with 0 intensity stops any rumbling. /// /// * `joystick` The joystick to vibrate. /// * `low_frequency_rumble` The intensity of the low frequency (left) rumble /// motor, from 0 to 0xFFFF. /// * `high_frequency_rumble` The intensity of the high frequency (right) /// rumble motor, from 0 to 0xFFFF. /// * `duration_ms` The duration of the rumble effect, in milliseconds. /// /// **Returns:** 0, or -1 if rumble isn't supported on this joystick pub fn SDL_JoystickRumble( joystick: *mut SDL_Joystick, low_frequency_rumble: Uint16, high_frequency_rumble: Uint16, duration_ms: Uint32, ) -> c_int; /// Close a joystick previously opened with [`SDL_JoystickOpen`]. pub fn SDL_JoystickClose(joystick: *mut SDL_Joystick); /// Return the battery level of this joystick. pub fn SDL_JoystickCurrentPowerLevel( joystick: *mut SDL_Joystick, ) -> SDL_JoystickPowerLevel; }