|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. The origin of this software must not be misrepresented; you must not
|
|
|
14 claim that you wrote the original software. If you use this software
|
|
|
15 in a product, an acknowledgment in the product documentation would be
|
|
|
16 appreciated but is not required.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 /**
|
|
|
23 * # CategoryGamepad
|
|
|
24 *
|
|
|
25 * SDL provides a low-level joystick API, which just treats joysticks as an
|
|
|
26 * arbitrary pile of buttons, axes, and hat switches. If you're planning to
|
|
|
27 * write your own control configuration screen, this can give you a lot of
|
|
|
28 * flexibility, but that's a lot of work, and most things that we consider
|
|
|
29 * "joysticks" now are actually console-style gamepads. So SDL provides the
|
|
|
30 * gamepad API on top of the lower-level joystick functionality.
|
|
|
31 *
|
|
|
32 * The difference between a joystick and a gamepad is that a gamepad tells you
|
|
|
33 * _where_ a button or axis is on the device. You don't speak to gamepads in
|
|
|
34 * terms of arbitrary numbers like "button 3" or "axis 2" but in standard
|
|
|
35 * locations: the d-pad, the shoulder buttons, triggers, A/B/X/Y (or
|
|
|
36 * X/O/Square/Triangle, if you will).
|
|
|
37 *
|
|
|
38 * One turns a joystick into a gamepad by providing a magic configuration
|
|
|
39 * string, which tells SDL the details of a specific device: when you see this
|
|
|
40 * specific hardware, if button 2 gets pressed, this is actually D-Pad Up,
|
|
|
41 * etc.
|
|
|
42 *
|
|
|
43 * SDL has many popular controllers configured out of the box, and users can
|
|
|
44 * add their own controller details through an environment variable if it's
|
|
|
45 * otherwise unknown to SDL.
|
|
|
46 *
|
|
|
47 * In order to use these functions, SDL_Init() must have been called with the
|
|
|
48 * SDL_INIT_GAMEPAD flag. This causes SDL to scan the system for gamepads, and
|
|
|
49 * load appropriate drivers.
|
|
|
50 *
|
|
|
51 * If you're using SDL gamepad support in a Steam game, you must call
|
|
|
52 * SteamAPI_InitEx() before calling SDL_Init().
|
|
|
53 *
|
|
|
54 * If you would like to receive gamepad updates while the application is in
|
|
|
55 * the background, you should set the following hint before calling
|
|
|
56 * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS
|
|
|
57 *
|
|
|
58 * Gamepads support various optional features such as rumble, color LEDs,
|
|
|
59 * touchpad, gyro, etc. The support for these features varies depending on the
|
|
|
60 * controller and OS support available. You can check for LED and rumble
|
|
|
61 * capabilities at runtime by calling SDL_GetGamepadProperties() and checking
|
|
|
62 * the various capability properties. You can check for touchpad by calling
|
|
|
63 * SDL_GetNumGamepadTouchpads() and check for gyro and accelerometer by
|
|
|
64 * calling SDL_GamepadHasSensor().
|
|
|
65 *
|
|
|
66 * By default SDL will try to use the most capable driver available, but you
|
|
|
67 * can tune which OS drivers to use with the various joystick hints in
|
|
|
68 * SDL_hints.h.
|
|
|
69 *
|
|
|
70 * Your application should always support gamepad hotplugging. On some
|
|
|
71 * platforms like Xbox, Steam Deck, etc., this is a requirement for
|
|
|
72 * certification. On other platforms, like macOS and Windows when using
|
|
|
73 * Windows.Gaming.Input, controllers may not be available at startup and will
|
|
|
74 * come in at some point after you've started processing events.
|
|
|
75 */
|
|
|
76
|
|
|
77 #ifndef SDL_gamepad_h_
|
|
|
78 #define SDL_gamepad_h_
|
|
|
79
|
|
|
80 #include <SDL3/SDL_stdinc.h>
|
|
|
81 #include <SDL3/SDL_error.h>
|
|
|
82 #include <SDL3/SDL_guid.h>
|
|
|
83 #include <SDL3/SDL_iostream.h>
|
|
|
84 #include <SDL3/SDL_joystick.h>
|
|
|
85 #include <SDL3/SDL_power.h>
|
|
|
86 #include <SDL3/SDL_properties.h>
|
|
|
87 #include <SDL3/SDL_sensor.h>
|
|
|
88
|
|
|
89 #include <SDL3/SDL_begin_code.h>
|
|
|
90 /* Set up for C function definitions, even when using C++ */
|
|
|
91 #ifdef __cplusplus
|
|
|
92 extern "C" {
|
|
|
93 #endif
|
|
|
94
|
|
|
95 /**
|
|
|
96 * The structure used to identify an SDL gamepad
|
|
|
97 *
|
|
|
98 * \since This struct is available since SDL 3.2.0.
|
|
|
99 */
|
|
|
100 typedef struct SDL_Gamepad SDL_Gamepad;
|
|
|
101
|
|
|
102 /**
|
|
|
103 * Standard gamepad types.
|
|
|
104 *
|
|
|
105 * This type does not necessarily map to first-party controllers from
|
|
|
106 * Microsoft/Sony/Nintendo; in many cases, third-party controllers can report
|
|
|
107 * as these, either because they were designed for a specific console, or they
|
|
|
108 * simply most closely match that console's controllers (does it have A/B/X/Y
|
|
|
109 * buttons or X/O/Square/Triangle? Does it have a touchpad? etc).
|
|
|
110 */
|
|
|
111 typedef enum SDL_GamepadType
|
|
|
112 {
|
|
|
113 SDL_GAMEPAD_TYPE_UNKNOWN = 0,
|
|
|
114 SDL_GAMEPAD_TYPE_STANDARD,
|
|
|
115 SDL_GAMEPAD_TYPE_XBOX360,
|
|
|
116 SDL_GAMEPAD_TYPE_XBOXONE,
|
|
|
117 SDL_GAMEPAD_TYPE_PS3,
|
|
|
118 SDL_GAMEPAD_TYPE_PS4,
|
|
|
119 SDL_GAMEPAD_TYPE_PS5,
|
|
|
120 SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_PRO,
|
|
|
121 SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT,
|
|
|
122 SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT,
|
|
|
123 SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR,
|
|
|
124 SDL_GAMEPAD_TYPE_GAMECUBE,
|
|
|
125 SDL_GAMEPAD_TYPE_COUNT
|
|
|
126 } SDL_GamepadType;
|
|
|
127
|
|
|
128 /**
|
|
|
129 * The list of buttons available on a gamepad
|
|
|
130 *
|
|
|
131 * For controllers that use a diamond pattern for the face buttons, the
|
|
|
132 * south/east/west/north buttons below correspond to the locations in the
|
|
|
133 * diamond pattern. For Xbox controllers, this would be A/B/X/Y, for Nintendo
|
|
|
134 * Switch controllers, this would be B/A/Y/X, for GameCube controllers this
|
|
|
135 * would be A/X/B/Y, for PlayStation controllers this would be
|
|
|
136 * Cross/Circle/Square/Triangle.
|
|
|
137 *
|
|
|
138 * For controllers that don't use a diamond pattern for the face buttons, the
|
|
|
139 * south/east/west/north buttons indicate the buttons labeled A, B, C, D, or
|
|
|
140 * 1, 2, 3, 4, or for controllers that aren't labeled, they are the primary,
|
|
|
141 * secondary, etc. buttons.
|
|
|
142 *
|
|
|
143 * The activate action is often the south button and the cancel action is
|
|
|
144 * often the east button, but in some regions this is reversed, so your game
|
|
|
145 * should allow remapping actions based on user preferences.
|
|
|
146 *
|
|
|
147 * You can query the labels for the face buttons using
|
|
|
148 * SDL_GetGamepadButtonLabel()
|
|
|
149 *
|
|
|
150 * \since This enum is available since SDL 3.2.0.
|
|
|
151 */
|
|
|
152 typedef enum SDL_GamepadButton
|
|
|
153 {
|
|
|
154 SDL_GAMEPAD_BUTTON_INVALID = -1,
|
|
|
155 SDL_GAMEPAD_BUTTON_SOUTH, /**< Bottom face button (e.g. Xbox A button) */
|
|
|
156 SDL_GAMEPAD_BUTTON_EAST, /**< Right face button (e.g. Xbox B button) */
|
|
|
157 SDL_GAMEPAD_BUTTON_WEST, /**< Left face button (e.g. Xbox X button) */
|
|
|
158 SDL_GAMEPAD_BUTTON_NORTH, /**< Top face button (e.g. Xbox Y button) */
|
|
|
159 SDL_GAMEPAD_BUTTON_BACK,
|
|
|
160 SDL_GAMEPAD_BUTTON_GUIDE,
|
|
|
161 SDL_GAMEPAD_BUTTON_START,
|
|
|
162 SDL_GAMEPAD_BUTTON_LEFT_STICK,
|
|
|
163 SDL_GAMEPAD_BUTTON_RIGHT_STICK,
|
|
|
164 SDL_GAMEPAD_BUTTON_LEFT_SHOULDER,
|
|
|
165 SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER,
|
|
|
166 SDL_GAMEPAD_BUTTON_DPAD_UP,
|
|
|
167 SDL_GAMEPAD_BUTTON_DPAD_DOWN,
|
|
|
168 SDL_GAMEPAD_BUTTON_DPAD_LEFT,
|
|
|
169 SDL_GAMEPAD_BUTTON_DPAD_RIGHT,
|
|
|
170 SDL_GAMEPAD_BUTTON_MISC1, /**< Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */
|
|
|
171 SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /**< Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1, DualSense Edge RB button, Right Joy-Con SR button) */
|
|
|
172 SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /**< Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3, DualSense Edge LB button, Left Joy-Con SL button) */
|
|
|
173 SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /**< Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2, DualSense Edge right Fn button, Right Joy-Con SL button) */
|
|
|
174 SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /**< Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4, DualSense Edge left Fn button, Left Joy-Con SR button) */
|
|
|
175 SDL_GAMEPAD_BUTTON_TOUCHPAD, /**< PS4/PS5 touchpad button */
|
|
|
176 SDL_GAMEPAD_BUTTON_MISC2, /**< Additional button */
|
|
|
177 SDL_GAMEPAD_BUTTON_MISC3, /**< Additional button (e.g. Nintendo GameCube left trigger click) */
|
|
|
178 SDL_GAMEPAD_BUTTON_MISC4, /**< Additional button (e.g. Nintendo GameCube right trigger click) */
|
|
|
179 SDL_GAMEPAD_BUTTON_MISC5, /**< Additional button */
|
|
|
180 SDL_GAMEPAD_BUTTON_MISC6, /**< Additional button */
|
|
|
181 SDL_GAMEPAD_BUTTON_COUNT
|
|
|
182 } SDL_GamepadButton;
|
|
|
183
|
|
|
184 /**
|
|
|
185 * The set of gamepad button labels
|
|
|
186 *
|
|
|
187 * This isn't a complete set, just the face buttons to make it easy to show
|
|
|
188 * button prompts.
|
|
|
189 *
|
|
|
190 * For a complete set, you should look at the button and gamepad type and have
|
|
|
191 * a set of symbols that work well with your art style.
|
|
|
192 *
|
|
|
193 * \since This enum is available since SDL 3.2.0.
|
|
|
194 */
|
|
|
195 typedef enum SDL_GamepadButtonLabel
|
|
|
196 {
|
|
|
197 SDL_GAMEPAD_BUTTON_LABEL_UNKNOWN,
|
|
|
198 SDL_GAMEPAD_BUTTON_LABEL_A,
|
|
|
199 SDL_GAMEPAD_BUTTON_LABEL_B,
|
|
|
200 SDL_GAMEPAD_BUTTON_LABEL_X,
|
|
|
201 SDL_GAMEPAD_BUTTON_LABEL_Y,
|
|
|
202 SDL_GAMEPAD_BUTTON_LABEL_CROSS,
|
|
|
203 SDL_GAMEPAD_BUTTON_LABEL_CIRCLE,
|
|
|
204 SDL_GAMEPAD_BUTTON_LABEL_SQUARE,
|
|
|
205 SDL_GAMEPAD_BUTTON_LABEL_TRIANGLE
|
|
|
206 } SDL_GamepadButtonLabel;
|
|
|
207
|
|
|
208 /**
|
|
|
209 * The list of axes available on a gamepad
|
|
|
210 *
|
|
|
211 * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to
|
|
|
212 * SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though
|
|
|
213 * advanced UI will allow users to set or autodetect the dead zone, which
|
|
|
214 * varies between gamepads.
|
|
|
215 *
|
|
|
216 * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully
|
|
|
217 * pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the
|
|
|
218 * same range that will be reported by the lower-level SDL_GetJoystickAxis().
|
|
|
219 *
|
|
|
220 * \since This enum is available since SDL 3.2.0.
|
|
|
221 */
|
|
|
222 typedef enum SDL_GamepadAxis
|
|
|
223 {
|
|
|
224 SDL_GAMEPAD_AXIS_INVALID = -1,
|
|
|
225 SDL_GAMEPAD_AXIS_LEFTX,
|
|
|
226 SDL_GAMEPAD_AXIS_LEFTY,
|
|
|
227 SDL_GAMEPAD_AXIS_RIGHTX,
|
|
|
228 SDL_GAMEPAD_AXIS_RIGHTY,
|
|
|
229 SDL_GAMEPAD_AXIS_LEFT_TRIGGER,
|
|
|
230 SDL_GAMEPAD_AXIS_RIGHT_TRIGGER,
|
|
|
231 SDL_GAMEPAD_AXIS_COUNT
|
|
|
232 } SDL_GamepadAxis;
|
|
|
233
|
|
|
234 /**
|
|
|
235 * Types of gamepad control bindings.
|
|
|
236 *
|
|
|
237 * A gamepad is a collection of bindings that map arbitrary joystick buttons,
|
|
|
238 * axes and hat switches to specific positions on a generic console-style
|
|
|
239 * gamepad. This enum is used as part of SDL_GamepadBinding to specify those
|
|
|
240 * mappings.
|
|
|
241 *
|
|
|
242 * \since This enum is available since SDL 3.2.0.
|
|
|
243 */
|
|
|
244 typedef enum SDL_GamepadBindingType
|
|
|
245 {
|
|
|
246 SDL_GAMEPAD_BINDTYPE_NONE = 0,
|
|
|
247 SDL_GAMEPAD_BINDTYPE_BUTTON,
|
|
|
248 SDL_GAMEPAD_BINDTYPE_AXIS,
|
|
|
249 SDL_GAMEPAD_BINDTYPE_HAT
|
|
|
250 } SDL_GamepadBindingType;
|
|
|
251
|
|
|
252 /**
|
|
|
253 * A mapping between one joystick input to a gamepad control.
|
|
|
254 *
|
|
|
255 * A gamepad has a collection of several bindings, to say, for example, when
|
|
|
256 * joystick button number 5 is pressed, that should be treated like the
|
|
|
257 * gamepad's "start" button.
|
|
|
258 *
|
|
|
259 * SDL has these bindings built-in for many popular controllers, and can add
|
|
|
260 * more with a simple text string. Those strings are parsed into a collection
|
|
|
261 * of these structs to make it easier to operate on the data.
|
|
|
262 *
|
|
|
263 * \since This struct is available since SDL 3.2.0.
|
|
|
264 *
|
|
|
265 * \sa SDL_GetGamepadBindings
|
|
|
266 */
|
|
|
267 typedef struct SDL_GamepadBinding
|
|
|
268 {
|
|
|
269 SDL_GamepadBindingType input_type;
|
|
|
270 union
|
|
|
271 {
|
|
|
272 int button;
|
|
|
273
|
|
|
274 struct
|
|
|
275 {
|
|
|
276 int axis;
|
|
|
277 int axis_min;
|
|
|
278 int axis_max;
|
|
|
279 } axis;
|
|
|
280
|
|
|
281 struct
|
|
|
282 {
|
|
|
283 int hat;
|
|
|
284 int hat_mask;
|
|
|
285 } hat;
|
|
|
286
|
|
|
287 } input;
|
|
|
288
|
|
|
289 SDL_GamepadBindingType output_type;
|
|
|
290 union
|
|
|
291 {
|
|
|
292 SDL_GamepadButton button;
|
|
|
293
|
|
|
294 struct
|
|
|
295 {
|
|
|
296 SDL_GamepadAxis axis;
|
|
|
297 int axis_min;
|
|
|
298 int axis_max;
|
|
|
299 } axis;
|
|
|
300
|
|
|
301 } output;
|
|
|
302 } SDL_GamepadBinding;
|
|
|
303
|
|
|
304
|
|
|
305 /**
|
|
|
306 * Add support for gamepads that SDL is unaware of or change the binding of an
|
|
|
307 * existing gamepad.
|
|
|
308 *
|
|
|
309 * The mapping string has the format "GUID,name,mapping", where GUID is the
|
|
|
310 * string value from SDL_GUIDToString(), name is the human readable string for
|
|
|
311 * the device and mappings are gamepad mappings to joystick ones. Under
|
|
|
312 * Windows there is a reserved GUID of "xinput" that covers all XInput
|
|
|
313 * devices. The mapping format for joystick is:
|
|
|
314 *
|
|
|
315 * - `bX`: a joystick button, index X
|
|
|
316 * - `hX.Y`: hat X with value Y
|
|
|
317 * - `aX`: axis X of the joystick
|
|
|
318 *
|
|
|
319 * Buttons can be used as a gamepad axes and vice versa.
|
|
|
320 *
|
|
|
321 * If a device with this GUID is already plugged in, SDL will generate an
|
|
|
322 * SDL_EVENT_GAMEPAD_ADDED event.
|
|
|
323 *
|
|
|
324 * This string shows an example of a valid mapping for a gamepad:
|
|
|
325 *
|
|
|
326 * ```c
|
|
|
327 * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
|
|
|
328 * ```
|
|
|
329 *
|
|
|
330 * \param mapping the mapping string.
|
|
|
331 * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
|
|
|
332 * -1 on failure; call SDL_GetError() for more information.
|
|
|
333 *
|
|
|
334 * \threadsafety It is safe to call this function from any thread.
|
|
|
335 *
|
|
|
336 * \since This function is available since SDL 3.2.0.
|
|
|
337 *
|
|
|
338 * \sa SDL_AddGamepadMappingsFromFile
|
|
|
339 * \sa SDL_AddGamepadMappingsFromIO
|
|
|
340 * \sa SDL_GetGamepadMapping
|
|
|
341 * \sa SDL_GetGamepadMappingForGUID
|
|
|
342 * \sa SDL_HINT_GAMECONTROLLERCONFIG
|
|
|
343 * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE
|
|
|
344 * \sa SDL_EVENT_GAMEPAD_ADDED
|
|
|
345 */
|
|
|
346 extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping);
|
|
|
347
|
|
|
348 /**
|
|
|
349 * Load a set of gamepad mappings from an SDL_IOStream.
|
|
|
350 *
|
|
|
351 * You can call this function several times, if needed, to load different
|
|
|
352 * database files.
|
|
|
353 *
|
|
|
354 * If a new mapping is loaded for an already known gamepad GUID, the later
|
|
|
355 * version will overwrite the one currently loaded.
|
|
|
356 *
|
|
|
357 * Any new mappings for already plugged in controllers will generate
|
|
|
358 * SDL_EVENT_GAMEPAD_ADDED events.
|
|
|
359 *
|
|
|
360 * Mappings not belonging to the current platform or with no platform field
|
|
|
361 * specified will be ignored (i.e. mappings for Linux will be ignored in
|
|
|
362 * Windows, etc).
|
|
|
363 *
|
|
|
364 * This function will load the text database entirely in memory before
|
|
|
365 * processing it, so take this into consideration if you are in a memory
|
|
|
366 * constrained environment.
|
|
|
367 *
|
|
|
368 * \param src the data stream for the mappings to be added.
|
|
|
369 * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even
|
|
|
370 * in the case of an error.
|
|
|
371 * \returns the number of mappings added or -1 on failure; call SDL_GetError()
|
|
|
372 * for more information.
|
|
|
373 *
|
|
|
374 * \threadsafety It is safe to call this function from any thread.
|
|
|
375 *
|
|
|
376 * \since This function is available since SDL 3.2.0.
|
|
|
377 *
|
|
|
378 * \sa SDL_AddGamepadMapping
|
|
|
379 * \sa SDL_AddGamepadMappingsFromFile
|
|
|
380 * \sa SDL_GetGamepadMapping
|
|
|
381 * \sa SDL_GetGamepadMappingForGUID
|
|
|
382 * \sa SDL_HINT_GAMECONTROLLERCONFIG
|
|
|
383 * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE
|
|
|
384 * \sa SDL_EVENT_GAMEPAD_ADDED
|
|
|
385 */
|
|
|
386 extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, bool closeio);
|
|
|
387
|
|
|
388 /**
|
|
|
389 * Load a set of gamepad mappings from a file.
|
|
|
390 *
|
|
|
391 * You can call this function several times, if needed, to load different
|
|
|
392 * database files.
|
|
|
393 *
|
|
|
394 * If a new mapping is loaded for an already known gamepad GUID, the later
|
|
|
395 * version will overwrite the one currently loaded.
|
|
|
396 *
|
|
|
397 * Any new mappings for already plugged in controllers will generate
|
|
|
398 * SDL_EVENT_GAMEPAD_ADDED events.
|
|
|
399 *
|
|
|
400 * Mappings not belonging to the current platform or with no platform field
|
|
|
401 * specified will be ignored (i.e. mappings for Linux will be ignored in
|
|
|
402 * Windows, etc).
|
|
|
403 *
|
|
|
404 * \param file the mappings file to load.
|
|
|
405 * \returns the number of mappings added or -1 on failure; call SDL_GetError()
|
|
|
406 * for more information.
|
|
|
407 *
|
|
|
408 * \threadsafety It is safe to call this function from any thread.
|
|
|
409 *
|
|
|
410 * \since This function is available since SDL 3.2.0.
|
|
|
411 *
|
|
|
412 * \sa SDL_AddGamepadMapping
|
|
|
413 * \sa SDL_AddGamepadMappingsFromIO
|
|
|
414 * \sa SDL_GetGamepadMapping
|
|
|
415 * \sa SDL_GetGamepadMappingForGUID
|
|
|
416 * \sa SDL_HINT_GAMECONTROLLERCONFIG
|
|
|
417 * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE
|
|
|
418 * \sa SDL_EVENT_GAMEPAD_ADDED
|
|
|
419 */
|
|
|
420 extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file);
|
|
|
421
|
|
|
422 /**
|
|
|
423 * Reinitialize the SDL mapping database to its initial state.
|
|
|
424 *
|
|
|
425 * This will generate gamepad events as needed if device mappings change.
|
|
|
426 *
|
|
|
427 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
428 * information.
|
|
|
429 *
|
|
|
430 * \threadsafety It is safe to call this function from any thread.
|
|
|
431 *
|
|
|
432 * \since This function is available since SDL 3.2.0.
|
|
|
433 */
|
|
|
434 extern SDL_DECLSPEC bool SDLCALL SDL_ReloadGamepadMappings(void);
|
|
|
435
|
|
|
436 /**
|
|
|
437 * Get the current gamepad mappings.
|
|
|
438 *
|
|
|
439 * \param count a pointer filled in with the number of mappings returned, can
|
|
|
440 * be NULL.
|
|
|
441 * \returns an array of the mapping strings, NULL-terminated, or NULL on
|
|
|
442 * failure; call SDL_GetError() for more information. This is a
|
|
|
443 * single allocation that should be freed with SDL_free() when it is
|
|
|
444 * no longer needed.
|
|
|
445 *
|
|
|
446 * \threadsafety It is safe to call this function from any thread.
|
|
|
447 *
|
|
|
448 * \since This function is available since SDL 3.2.0.
|
|
|
449 */
|
|
|
450 extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count);
|
|
|
451
|
|
|
452 /**
|
|
|
453 * Get the gamepad mapping string for a given GUID.
|
|
|
454 *
|
|
|
455 * \param guid a structure containing the GUID for which a mapping is desired.
|
|
|
456 * \returns a mapping string or NULL on failure; call SDL_GetError() for more
|
|
|
457 * information. This should be freed with SDL_free() when it is no
|
|
|
458 * longer needed.
|
|
|
459 *
|
|
|
460 * \threadsafety It is safe to call this function from any thread.
|
|
|
461 *
|
|
|
462 * \since This function is available since SDL 3.2.0.
|
|
|
463 *
|
|
|
464 * \sa SDL_GetJoystickGUIDForID
|
|
|
465 * \sa SDL_GetJoystickGUID
|
|
|
466 */
|
|
|
467 extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID guid);
|
|
|
468
|
|
|
469 /**
|
|
|
470 * Get the current mapping of a gamepad.
|
|
|
471 *
|
|
|
472 * Details about mappings are discussed with SDL_AddGamepadMapping().
|
|
|
473 *
|
|
|
474 * \param gamepad the gamepad you want to get the current mapping for.
|
|
|
475 * \returns a string that has the gamepad's mapping or NULL if no mapping is
|
|
|
476 * available; call SDL_GetError() for more information. This should
|
|
|
477 * be freed with SDL_free() when it is no longer needed.
|
|
|
478 *
|
|
|
479 * \threadsafety It is safe to call this function from any thread.
|
|
|
480 *
|
|
|
481 * \since This function is available since SDL 3.2.0.
|
|
|
482 *
|
|
|
483 * \sa SDL_AddGamepadMapping
|
|
|
484 * \sa SDL_GetGamepadMappingForID
|
|
|
485 * \sa SDL_GetGamepadMappingForGUID
|
|
|
486 * \sa SDL_SetGamepadMapping
|
|
|
487 */
|
|
|
488 extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad);
|
|
|
489
|
|
|
490 /**
|
|
|
491 * Set the current mapping of a joystick or gamepad.
|
|
|
492 *
|
|
|
493 * Details about mappings are discussed with SDL_AddGamepadMapping().
|
|
|
494 *
|
|
|
495 * \param instance_id the joystick instance ID.
|
|
|
496 * \param mapping the mapping to use for this device, or NULL to clear the
|
|
|
497 * mapping.
|
|
|
498 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
499 * information.
|
|
|
500 *
|
|
|
501 * \threadsafety It is safe to call this function from any thread.
|
|
|
502 *
|
|
|
503 * \since This function is available since SDL 3.2.0.
|
|
|
504 *
|
|
|
505 * \sa SDL_AddGamepadMapping
|
|
|
506 * \sa SDL_GetGamepadMapping
|
|
|
507 */
|
|
|
508 extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping);
|
|
|
509
|
|
|
510 /**
|
|
|
511 * Return whether a gamepad is currently connected.
|
|
|
512 *
|
|
|
513 * \returns true if a gamepad is connected, false otherwise.
|
|
|
514 *
|
|
|
515 * \threadsafety It is safe to call this function from any thread.
|
|
|
516 *
|
|
|
517 * \since This function is available since SDL 3.2.0.
|
|
|
518 *
|
|
|
519 * \sa SDL_GetGamepads
|
|
|
520 */
|
|
|
521 extern SDL_DECLSPEC bool SDLCALL SDL_HasGamepad(void);
|
|
|
522
|
|
|
523 /**
|
|
|
524 * Get a list of currently connected gamepads.
|
|
|
525 *
|
|
|
526 * \param count a pointer filled in with the number of gamepads returned, may
|
|
|
527 * be NULL.
|
|
|
528 * \returns a 0 terminated array of joystick instance IDs or NULL on failure;
|
|
|
529 * call SDL_GetError() for more information. This should be freed
|
|
|
530 * with SDL_free() when it is no longer needed.
|
|
|
531 *
|
|
|
532 * \threadsafety It is safe to call this function from any thread.
|
|
|
533 *
|
|
|
534 * \since This function is available since SDL 3.2.0.
|
|
|
535 *
|
|
|
536 * \sa SDL_HasGamepad
|
|
|
537 * \sa SDL_OpenGamepad
|
|
|
538 */
|
|
|
539 extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetGamepads(int *count);
|
|
|
540
|
|
|
541 /**
|
|
|
542 * Check if the given joystick is supported by the gamepad interface.
|
|
|
543 *
|
|
|
544 * \param instance_id the joystick instance ID.
|
|
|
545 * \returns true if the given joystick is supported by the gamepad interface,
|
|
|
546 * false if it isn't or it's an invalid index.
|
|
|
547 *
|
|
|
548 * \threadsafety It is safe to call this function from any thread.
|
|
|
549 *
|
|
|
550 * \since This function is available since SDL 3.2.0.
|
|
|
551 *
|
|
|
552 * \sa SDL_GetJoysticks
|
|
|
553 * \sa SDL_OpenGamepad
|
|
|
554 */
|
|
|
555 extern SDL_DECLSPEC bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id);
|
|
|
556
|
|
|
557 /**
|
|
|
558 * Get the implementation dependent name of a gamepad.
|
|
|
559 *
|
|
|
560 * This can be called before any gamepads are opened.
|
|
|
561 *
|
|
|
562 * \param instance_id the joystick instance ID.
|
|
|
563 * \returns the name of the selected gamepad. If no name can be found, this
|
|
|
564 * function returns NULL; call SDL_GetError() for more information.
|
|
|
565 *
|
|
|
566 * \threadsafety It is safe to call this function from any thread.
|
|
|
567 *
|
|
|
568 * \since This function is available since SDL 3.2.0.
|
|
|
569 *
|
|
|
570 * \sa SDL_GetGamepadName
|
|
|
571 * \sa SDL_GetGamepads
|
|
|
572 */
|
|
|
573 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID instance_id);
|
|
|
574
|
|
|
575 /**
|
|
|
576 * Get the implementation dependent path of a gamepad.
|
|
|
577 *
|
|
|
578 * This can be called before any gamepads are opened.
|
|
|
579 *
|
|
|
580 * \param instance_id the joystick instance ID.
|
|
|
581 * \returns the path of the selected gamepad. If no path can be found, this
|
|
|
582 * function returns NULL; call SDL_GetError() for more information.
|
|
|
583 *
|
|
|
584 * \threadsafety It is safe to call this function from any thread.
|
|
|
585 *
|
|
|
586 * \since This function is available since SDL 3.2.0.
|
|
|
587 *
|
|
|
588 * \sa SDL_GetGamepadPath
|
|
|
589 * \sa SDL_GetGamepads
|
|
|
590 */
|
|
|
591 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPathForID(SDL_JoystickID instance_id);
|
|
|
592
|
|
|
593 /**
|
|
|
594 * Get the player index of a gamepad.
|
|
|
595 *
|
|
|
596 * This can be called before any gamepads are opened.
|
|
|
597 *
|
|
|
598 * \param instance_id the joystick instance ID.
|
|
|
599 * \returns the player index of a gamepad, or -1 if it's not available.
|
|
|
600 *
|
|
|
601 * \threadsafety It is safe to call this function from any thread.
|
|
|
602 *
|
|
|
603 * \since This function is available since SDL 3.2.0.
|
|
|
604 *
|
|
|
605 * \sa SDL_GetGamepadPlayerIndex
|
|
|
606 * \sa SDL_GetGamepads
|
|
|
607 */
|
|
|
608 extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexForID(SDL_JoystickID instance_id);
|
|
|
609
|
|
|
610 /**
|
|
|
611 * Get the implementation-dependent GUID of a gamepad.
|
|
|
612 *
|
|
|
613 * This can be called before any gamepads are opened.
|
|
|
614 *
|
|
|
615 * \param instance_id the joystick instance ID.
|
|
|
616 * \returns the GUID of the selected gamepad. If called on an invalid index,
|
|
|
617 * this function returns a zero GUID.
|
|
|
618 *
|
|
|
619 * \threadsafety It is safe to call this function from any thread.
|
|
|
620 *
|
|
|
621 * \since This function is available since SDL 3.2.0.
|
|
|
622 *
|
|
|
623 * \sa SDL_GUIDToString
|
|
|
624 * \sa SDL_GetGamepads
|
|
|
625 */
|
|
|
626 extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetGamepadGUIDForID(SDL_JoystickID instance_id);
|
|
|
627
|
|
|
628 /**
|
|
|
629 * Get the USB vendor ID of a gamepad, if available.
|
|
|
630 *
|
|
|
631 * This can be called before any gamepads are opened. If the vendor ID isn't
|
|
|
632 * available this function returns 0.
|
|
|
633 *
|
|
|
634 * \param instance_id the joystick instance ID.
|
|
|
635 * \returns the USB vendor ID of the selected gamepad. If called on an invalid
|
|
|
636 * index, this function returns zero.
|
|
|
637 *
|
|
|
638 * \threadsafety It is safe to call this function from any thread.
|
|
|
639 *
|
|
|
640 * \since This function is available since SDL 3.2.0.
|
|
|
641 *
|
|
|
642 * \sa SDL_GetGamepadVendor
|
|
|
643 * \sa SDL_GetGamepads
|
|
|
644 */
|
|
|
645 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorForID(SDL_JoystickID instance_id);
|
|
|
646
|
|
|
647 /**
|
|
|
648 * Get the USB product ID of a gamepad, if available.
|
|
|
649 *
|
|
|
650 * This can be called before any gamepads are opened. If the product ID isn't
|
|
|
651 * available this function returns 0.
|
|
|
652 *
|
|
|
653 * \param instance_id the joystick instance ID.
|
|
|
654 * \returns the USB product ID of the selected gamepad. If called on an
|
|
|
655 * invalid index, this function returns zero.
|
|
|
656 *
|
|
|
657 * \threadsafety It is safe to call this function from any thread.
|
|
|
658 *
|
|
|
659 * \since This function is available since SDL 3.2.0.
|
|
|
660 *
|
|
|
661 * \sa SDL_GetGamepadProduct
|
|
|
662 * \sa SDL_GetGamepads
|
|
|
663 */
|
|
|
664 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductForID(SDL_JoystickID instance_id);
|
|
|
665
|
|
|
666 /**
|
|
|
667 * Get the product version of a gamepad, if available.
|
|
|
668 *
|
|
|
669 * This can be called before any gamepads are opened. If the product version
|
|
|
670 * isn't available this function returns 0.
|
|
|
671 *
|
|
|
672 * \param instance_id the joystick instance ID.
|
|
|
673 * \returns the product version of the selected gamepad. If called on an
|
|
|
674 * invalid index, this function returns zero.
|
|
|
675 *
|
|
|
676 * \threadsafety It is safe to call this function from any thread.
|
|
|
677 *
|
|
|
678 * \since This function is available since SDL 3.2.0.
|
|
|
679 *
|
|
|
680 * \sa SDL_GetGamepadProductVersion
|
|
|
681 * \sa SDL_GetGamepads
|
|
|
682 */
|
|
|
683 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionForID(SDL_JoystickID instance_id);
|
|
|
684
|
|
|
685 /**
|
|
|
686 * Get the type of a gamepad.
|
|
|
687 *
|
|
|
688 * This can be called before any gamepads are opened.
|
|
|
689 *
|
|
|
690 * \param instance_id the joystick instance ID.
|
|
|
691 * \returns the gamepad type.
|
|
|
692 *
|
|
|
693 * \threadsafety It is safe to call this function from any thread.
|
|
|
694 *
|
|
|
695 * \since This function is available since SDL 3.2.0.
|
|
|
696 *
|
|
|
697 * \sa SDL_GetGamepadType
|
|
|
698 * \sa SDL_GetGamepads
|
|
|
699 * \sa SDL_GetRealGamepadTypeForID
|
|
|
700 */
|
|
|
701 extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeForID(SDL_JoystickID instance_id);
|
|
|
702
|
|
|
703 /**
|
|
|
704 * Get the type of a gamepad, ignoring any mapping override.
|
|
|
705 *
|
|
|
706 * This can be called before any gamepads are opened.
|
|
|
707 *
|
|
|
708 * \param instance_id the joystick instance ID.
|
|
|
709 * \returns the gamepad type.
|
|
|
710 *
|
|
|
711 * \threadsafety It is safe to call this function from any thread.
|
|
|
712 *
|
|
|
713 * \since This function is available since SDL 3.2.0.
|
|
|
714 *
|
|
|
715 * \sa SDL_GetGamepadTypeForID
|
|
|
716 * \sa SDL_GetGamepads
|
|
|
717 * \sa SDL_GetRealGamepadType
|
|
|
718 */
|
|
|
719 extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_JoystickID instance_id);
|
|
|
720
|
|
|
721 /**
|
|
|
722 * Get the mapping of a gamepad.
|
|
|
723 *
|
|
|
724 * This can be called before any gamepads are opened.
|
|
|
725 *
|
|
|
726 * \param instance_id the joystick instance ID.
|
|
|
727 * \returns the mapping string. Returns NULL if no mapping is available. This
|
|
|
728 * should be freed with SDL_free() when it is no longer needed.
|
|
|
729 *
|
|
|
730 * \threadsafety It is safe to call this function from any thread.
|
|
|
731 *
|
|
|
732 * \since This function is available since SDL 3.2.0.
|
|
|
733 *
|
|
|
734 * \sa SDL_GetGamepads
|
|
|
735 * \sa SDL_GetGamepadMapping
|
|
|
736 */
|
|
|
737 extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForID(SDL_JoystickID instance_id);
|
|
|
738
|
|
|
739 /**
|
|
|
740 * Open a gamepad for use.
|
|
|
741 *
|
|
|
742 * \param instance_id the joystick instance ID.
|
|
|
743 * \returns a gamepad identifier or NULL if an error occurred; call
|
|
|
744 * SDL_GetError() for more information.
|
|
|
745 *
|
|
|
746 * \threadsafety It is safe to call this function from any thread.
|
|
|
747 *
|
|
|
748 * \since This function is available since SDL 3.2.0.
|
|
|
749 *
|
|
|
750 * \sa SDL_CloseGamepad
|
|
|
751 * \sa SDL_IsGamepad
|
|
|
752 */
|
|
|
753 extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_OpenGamepad(SDL_JoystickID instance_id);
|
|
|
754
|
|
|
755 /**
|
|
|
756 * Get the SDL_Gamepad associated with a joystick instance ID, if it has been
|
|
|
757 * opened.
|
|
|
758 *
|
|
|
759 * \param instance_id the joystick instance ID of the gamepad.
|
|
|
760 * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been
|
|
|
761 * opened yet; call SDL_GetError() for more information.
|
|
|
762 *
|
|
|
763 * \threadsafety It is safe to call this function from any thread.
|
|
|
764 *
|
|
|
765 * \since This function is available since SDL 3.2.0.
|
|
|
766 */
|
|
|
767 extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID instance_id);
|
|
|
768
|
|
|
769 /**
|
|
|
770 * Get the SDL_Gamepad associated with a player index.
|
|
|
771 *
|
|
|
772 * \param player_index the player index, which different from the instance ID.
|
|
|
773 * \returns the SDL_Gamepad associated with a player index.
|
|
|
774 *
|
|
|
775 * \threadsafety It is safe to call this function from any thread.
|
|
|
776 *
|
|
|
777 * \since This function is available since SDL 3.2.0.
|
|
|
778 *
|
|
|
779 * \sa SDL_GetGamepadPlayerIndex
|
|
|
780 * \sa SDL_SetGamepadPlayerIndex
|
|
|
781 */
|
|
|
782 extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromPlayerIndex(int player_index);
|
|
|
783
|
|
|
784 /**
|
|
|
785 * Get the properties associated with an opened gamepad.
|
|
|
786 *
|
|
|
787 * These properties are shared with the underlying joystick object.
|
|
|
788 *
|
|
|
789 * The following read-only properties are provided by SDL:
|
|
|
790 *
|
|
|
791 * - `SDL_PROP_GAMEPAD_CAP_MONO_LED_BOOLEAN`: true if this gamepad has an LED
|
|
|
792 * that has adjustable brightness
|
|
|
793 * - `SDL_PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN`: true if this gamepad has an LED
|
|
|
794 * that has adjustable color
|
|
|
795 * - `SDL_PROP_GAMEPAD_CAP_PLAYER_LED_BOOLEAN`: true if this gamepad has a
|
|
|
796 * player LED
|
|
|
797 * - `SDL_PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN`: true if this gamepad has
|
|
|
798 * left/right rumble
|
|
|
799 * - `SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN`: true if this gamepad has
|
|
|
800 * simple trigger rumble
|
|
|
801 *
|
|
|
802 * \param gamepad a gamepad identifier previously returned by
|
|
|
803 * SDL_OpenGamepad().
|
|
|
804 * \returns a valid property ID on success or 0 on failure; call
|
|
|
805 * SDL_GetError() for more information.
|
|
|
806 *
|
|
|
807 * \threadsafety It is safe to call this function from any thread.
|
|
|
808 *
|
|
|
809 * \since This function is available since SDL 3.2.0.
|
|
|
810 */
|
|
|
811 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepad *gamepad);
|
|
|
812
|
|
|
813 #define SDL_PROP_GAMEPAD_CAP_MONO_LED_BOOLEAN SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN
|
|
|
814 #define SDL_PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN
|
|
|
815 #define SDL_PROP_GAMEPAD_CAP_PLAYER_LED_BOOLEAN SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN
|
|
|
816 #define SDL_PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN
|
|
|
817 #define SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN
|
|
|
818
|
|
|
819 /**
|
|
|
820 * Get the instance ID of an opened gamepad.
|
|
|
821 *
|
|
|
822 * \param gamepad a gamepad identifier previously returned by
|
|
|
823 * SDL_OpenGamepad().
|
|
|
824 * \returns the instance ID of the specified gamepad on success or 0 on
|
|
|
825 * failure; call SDL_GetError() for more information.
|
|
|
826 *
|
|
|
827 * \threadsafety It is safe to call this function from any thread.
|
|
|
828 *
|
|
|
829 * \since This function is available since SDL 3.2.0.
|
|
|
830 */
|
|
|
831 extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad);
|
|
|
832
|
|
|
833 /**
|
|
|
834 * Get the implementation-dependent name for an opened gamepad.
|
|
|
835 *
|
|
|
836 * \param gamepad a gamepad identifier previously returned by
|
|
|
837 * SDL_OpenGamepad().
|
|
|
838 * \returns the implementation dependent name for the gamepad, or NULL if
|
|
|
839 * there is no name or the identifier passed is invalid.
|
|
|
840 *
|
|
|
841 * \threadsafety It is safe to call this function from any thread.
|
|
|
842 *
|
|
|
843 * \since This function is available since SDL 3.2.0.
|
|
|
844 *
|
|
|
845 * \sa SDL_GetGamepadNameForID
|
|
|
846 */
|
|
|
847 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad);
|
|
|
848
|
|
|
849 /**
|
|
|
850 * Get the implementation-dependent path for an opened gamepad.
|
|
|
851 *
|
|
|
852 * \param gamepad a gamepad identifier previously returned by
|
|
|
853 * SDL_OpenGamepad().
|
|
|
854 * \returns the implementation dependent path for the gamepad, or NULL if
|
|
|
855 * there is no path or the identifier passed is invalid.
|
|
|
856 *
|
|
|
857 * \threadsafety It is safe to call this function from any thread.
|
|
|
858 *
|
|
|
859 * \since This function is available since SDL 3.2.0.
|
|
|
860 *
|
|
|
861 * \sa SDL_GetGamepadPathForID
|
|
|
862 */
|
|
|
863 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad);
|
|
|
864
|
|
|
865 /**
|
|
|
866 * Get the type of an opened gamepad.
|
|
|
867 *
|
|
|
868 * \param gamepad the gamepad object to query.
|
|
|
869 * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not
|
|
|
870 * available.
|
|
|
871 *
|
|
|
872 * \threadsafety It is safe to call this function from any thread.
|
|
|
873 *
|
|
|
874 * \since This function is available since SDL 3.2.0.
|
|
|
875 *
|
|
|
876 * \sa SDL_GetGamepadTypeForID
|
|
|
877 */
|
|
|
878 extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *gamepad);
|
|
|
879
|
|
|
880 /**
|
|
|
881 * Get the type of an opened gamepad, ignoring any mapping override.
|
|
|
882 *
|
|
|
883 * \param gamepad the gamepad object to query.
|
|
|
884 * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not
|
|
|
885 * available.
|
|
|
886 *
|
|
|
887 * \threadsafety It is safe to call this function from any thread.
|
|
|
888 *
|
|
|
889 * \since This function is available since SDL 3.2.0.
|
|
|
890 *
|
|
|
891 * \sa SDL_GetRealGamepadTypeForID
|
|
|
892 */
|
|
|
893 extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadType(SDL_Gamepad *gamepad);
|
|
|
894
|
|
|
895 /**
|
|
|
896 * Get the player index of an opened gamepad.
|
|
|
897 *
|
|
|
898 * For XInput gamepads this returns the XInput user index.
|
|
|
899 *
|
|
|
900 * \param gamepad the gamepad object to query.
|
|
|
901 * \returns the player index for gamepad, or -1 if it's not available.
|
|
|
902 *
|
|
|
903 * \threadsafety It is safe to call this function from any thread.
|
|
|
904 *
|
|
|
905 * \since This function is available since SDL 3.2.0.
|
|
|
906 *
|
|
|
907 * \sa SDL_SetGamepadPlayerIndex
|
|
|
908 */
|
|
|
909 extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad);
|
|
|
910
|
|
|
911 /**
|
|
|
912 * Set the player index of an opened gamepad.
|
|
|
913 *
|
|
|
914 * \param gamepad the gamepad object to adjust.
|
|
|
915 * \param player_index player index to assign to this gamepad, or -1 to clear
|
|
|
916 * the player index and turn off player LEDs.
|
|
|
917 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
918 * information.
|
|
|
919 *
|
|
|
920 * \threadsafety It is safe to call this function from any thread.
|
|
|
921 *
|
|
|
922 * \since This function is available since SDL 3.2.0.
|
|
|
923 *
|
|
|
924 * \sa SDL_GetGamepadPlayerIndex
|
|
|
925 */
|
|
|
926 extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index);
|
|
|
927
|
|
|
928 /**
|
|
|
929 * Get the USB vendor ID of an opened gamepad, if available.
|
|
|
930 *
|
|
|
931 * If the vendor ID isn't available this function returns 0.
|
|
|
932 *
|
|
|
933 * \param gamepad the gamepad object to query.
|
|
|
934 * \returns the USB vendor ID, or zero if unavailable.
|
|
|
935 *
|
|
|
936 * \threadsafety It is safe to call this function from any thread.
|
|
|
937 *
|
|
|
938 * \since This function is available since SDL 3.2.0.
|
|
|
939 *
|
|
|
940 * \sa SDL_GetGamepadVendorForID
|
|
|
941 */
|
|
|
942 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad);
|
|
|
943
|
|
|
944 /**
|
|
|
945 * Get the USB product ID of an opened gamepad, if available.
|
|
|
946 *
|
|
|
947 * If the product ID isn't available this function returns 0.
|
|
|
948 *
|
|
|
949 * \param gamepad the gamepad object to query.
|
|
|
950 * \returns the USB product ID, or zero if unavailable.
|
|
|
951 *
|
|
|
952 * \threadsafety It is safe to call this function from any thread.
|
|
|
953 *
|
|
|
954 * \since This function is available since SDL 3.2.0.
|
|
|
955 *
|
|
|
956 * \sa SDL_GetGamepadProductForID
|
|
|
957 */
|
|
|
958 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad);
|
|
|
959
|
|
|
960 /**
|
|
|
961 * Get the product version of an opened gamepad, if available.
|
|
|
962 *
|
|
|
963 * If the product version isn't available this function returns 0.
|
|
|
964 *
|
|
|
965 * \param gamepad the gamepad object to query.
|
|
|
966 * \returns the USB product version, or zero if unavailable.
|
|
|
967 *
|
|
|
968 * \threadsafety It is safe to call this function from any thread.
|
|
|
969 *
|
|
|
970 * \since This function is available since SDL 3.2.0.
|
|
|
971 *
|
|
|
972 * \sa SDL_GetGamepadProductVersionForID
|
|
|
973 */
|
|
|
974 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersion(SDL_Gamepad *gamepad);
|
|
|
975
|
|
|
976 /**
|
|
|
977 * Get the firmware version of an opened gamepad, if available.
|
|
|
978 *
|
|
|
979 * If the firmware version isn't available this function returns 0.
|
|
|
980 *
|
|
|
981 * \param gamepad the gamepad object to query.
|
|
|
982 * \returns the gamepad firmware version, or zero if unavailable.
|
|
|
983 *
|
|
|
984 * \threadsafety It is safe to call this function from any thread.
|
|
|
985 *
|
|
|
986 * \since This function is available since SDL 3.2.0.
|
|
|
987 */
|
|
|
988 extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepad);
|
|
|
989
|
|
|
990 /**
|
|
|
991 * Get the serial number of an opened gamepad, if available.
|
|
|
992 *
|
|
|
993 * Returns the serial number of the gamepad, or NULL if it is not available.
|
|
|
994 *
|
|
|
995 * \param gamepad the gamepad object to query.
|
|
|
996 * \returns the serial number, or NULL if unavailable.
|
|
|
997 *
|
|
|
998 * \threadsafety It is safe to call this function from any thread.
|
|
|
999 *
|
|
|
1000 * \since This function is available since SDL 3.2.0.
|
|
|
1001 */
|
|
|
1002 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad);
|
|
|
1003
|
|
|
1004 /**
|
|
|
1005 * Get the Steam Input handle of an opened gamepad, if available.
|
|
|
1006 *
|
|
|
1007 * Returns an InputHandle_t for the gamepad that can be used with Steam Input
|
|
|
1008 * API: https://partner.steamgames.com/doc/api/ISteamInput
|
|
|
1009 *
|
|
|
1010 * \param gamepad the gamepad object to query.
|
|
|
1011 * \returns the gamepad handle, or 0 if unavailable.
|
|
|
1012 *
|
|
|
1013 * \threadsafety It is safe to call this function from any thread.
|
|
|
1014 *
|
|
|
1015 * \since This function is available since SDL 3.2.0.
|
|
|
1016 */
|
|
|
1017 extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepad);
|
|
|
1018
|
|
|
1019 /**
|
|
|
1020 * Get the connection state of a gamepad.
|
|
|
1021 *
|
|
|
1022 * \param gamepad the gamepad object to query.
|
|
|
1023 * \returns the connection state on success or
|
|
|
1024 * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError()
|
|
|
1025 * for more information.
|
|
|
1026 *
|
|
|
1027 * \threadsafety It is safe to call this function from any thread.
|
|
|
1028 *
|
|
|
1029 * \since This function is available since SDL 3.2.0.
|
|
|
1030 */
|
|
|
1031 extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnectionState(SDL_Gamepad *gamepad);
|
|
|
1032
|
|
|
1033 /**
|
|
|
1034 * Get the battery state of a gamepad.
|
|
|
1035 *
|
|
|
1036 * You should never take a battery status as absolute truth. Batteries
|
|
|
1037 * (especially failing batteries) are delicate hardware, and the values
|
|
|
1038 * reported here are best estimates based on what that hardware reports. It's
|
|
|
1039 * not uncommon for older batteries to lose stored power much faster than it
|
|
|
1040 * reports, or completely drain when reporting it has 20 percent left, etc.
|
|
|
1041 *
|
|
|
1042 * \param gamepad the gamepad object to query.
|
|
|
1043 * \param percent a pointer filled in with the percentage of battery life
|
|
|
1044 * left, between 0 and 100, or NULL to ignore. This will be
|
|
|
1045 * filled in with -1 we can't determine a value or there is no
|
|
|
1046 * battery.
|
|
|
1047 * \returns the current battery state.
|
|
|
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 extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *gamepad, int *percent);
|
|
|
1054
|
|
|
1055 /**
|
|
|
1056 * Check if a gamepad has been opened and is currently connected.
|
|
|
1057 *
|
|
|
1058 * \param gamepad a gamepad identifier previously returned by
|
|
|
1059 * SDL_OpenGamepad().
|
|
|
1060 * \returns true if the gamepad has been opened and is currently connected, or
|
|
|
1061 * false if not.
|
|
|
1062 *
|
|
|
1063 * \threadsafety It is safe to call this function from any thread.
|
|
|
1064 *
|
|
|
1065 * \since This function is available since SDL 3.2.0.
|
|
|
1066 */
|
|
|
1067 extern SDL_DECLSPEC bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
|
|
|
1068
|
|
|
1069 /**
|
|
|
1070 * Get the underlying joystick from a gamepad.
|
|
|
1071 *
|
|
|
1072 * This function will give you a SDL_Joystick object, which allows you to use
|
|
|
1073 * the SDL_Joystick functions with a SDL_Gamepad object. This would be useful
|
|
|
1074 * for getting a joystick's position at any given time, even if it hasn't
|
|
|
1075 * moved (moving it would produce an event, which would have the axis' value).
|
|
|
1076 *
|
|
|
1077 * The pointer returned is owned by the SDL_Gamepad. You should not call
|
|
|
1078 * SDL_CloseJoystick() on it, for example, since doing so will likely cause
|
|
|
1079 * SDL to crash.
|
|
|
1080 *
|
|
|
1081 * \param gamepad the gamepad object that you want to get a joystick from.
|
|
|
1082 * \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError()
|
|
|
1083 * 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 extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepad);
|
|
|
1090
|
|
|
1091 /**
|
|
|
1092 * Set the state of gamepad event processing.
|
|
|
1093 *
|
|
|
1094 * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself
|
|
|
1095 * and check the state of the gamepad when you want gamepad information.
|
|
|
1096 *
|
|
|
1097 * \param enabled whether to process gamepad events or not.
|
|
|
1098 *
|
|
|
1099 * \threadsafety It is safe to call this function from any thread.
|
|
|
1100 *
|
|
|
1101 * \since This function is available since SDL 3.2.0.
|
|
|
1102 *
|
|
|
1103 * \sa SDL_GamepadEventsEnabled
|
|
|
1104 * \sa SDL_UpdateGamepads
|
|
|
1105 */
|
|
|
1106 extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(bool enabled);
|
|
|
1107
|
|
|
1108 /**
|
|
|
1109 * Query the state of gamepad event processing.
|
|
|
1110 *
|
|
|
1111 * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself
|
|
|
1112 * and check the state of the gamepad when you want gamepad information.
|
|
|
1113 *
|
|
|
1114 * \returns true if gamepad events are being processed, false otherwise.
|
|
|
1115 *
|
|
|
1116 * \threadsafety It is safe to call this function from any thread.
|
|
|
1117 *
|
|
|
1118 * \since This function is available since SDL 3.2.0.
|
|
|
1119 *
|
|
|
1120 * \sa SDL_SetGamepadEventsEnabled
|
|
|
1121 */
|
|
|
1122 extern SDL_DECLSPEC bool SDLCALL SDL_GamepadEventsEnabled(void);
|
|
|
1123
|
|
|
1124 /**
|
|
|
1125 * Get the SDL joystick layer bindings for a gamepad.
|
|
|
1126 *
|
|
|
1127 * \param gamepad a gamepad.
|
|
|
1128 * \param count a pointer filled in with the number of bindings returned.
|
|
|
1129 * \returns a NULL terminated array of pointers to bindings or NULL on
|
|
|
1130 * failure; call SDL_GetError() for more information. This is a
|
|
|
1131 * single allocation that should be freed with SDL_free() when it is
|
|
|
1132 * no longer needed.
|
|
|
1133 *
|
|
|
1134 * \threadsafety It is safe to call this function from any thread.
|
|
|
1135 *
|
|
|
1136 * \since This function is available since SDL 3.2.0.
|
|
|
1137 */
|
|
|
1138 extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gamepad *gamepad, int *count);
|
|
|
1139
|
|
|
1140 /**
|
|
|
1141 * Manually pump gamepad updates if not using the loop.
|
|
|
1142 *
|
|
|
1143 * This function is called automatically by the event loop if events are
|
|
|
1144 * enabled. Under such circumstances, it will not be necessary to call this
|
|
|
1145 * function.
|
|
|
1146 *
|
|
|
1147 * \threadsafety It is safe to call this function from any thread.
|
|
|
1148 *
|
|
|
1149 * \since This function is available since SDL 3.2.0.
|
|
|
1150 */
|
|
|
1151 extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void);
|
|
|
1152
|
|
|
1153 /**
|
|
|
1154 * Convert a string into SDL_GamepadType enum.
|
|
|
1155 *
|
|
|
1156 * This function is called internally to translate SDL_Gamepad mapping strings
|
|
|
1157 * for the underlying joystick device into the consistent SDL_Gamepad mapping.
|
|
|
1158 * You do not normally need to call this function unless you are parsing
|
|
|
1159 * SDL_Gamepad mappings in your own code.
|
|
|
1160 *
|
|
|
1161 * \param str string representing a SDL_GamepadType type.
|
|
|
1162 * \returns the SDL_GamepadType enum corresponding to the input string, or
|
|
|
1163 * `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found.
|
|
|
1164 *
|
|
|
1165 * \threadsafety It is safe to call this function from any thread.
|
|
|
1166 *
|
|
|
1167 * \since This function is available since SDL 3.2.0.
|
|
|
1168 *
|
|
|
1169 * \sa SDL_GetGamepadStringForType
|
|
|
1170 */
|
|
|
1171 extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const char *str);
|
|
|
1172
|
|
|
1173 /**
|
|
|
1174 * Convert from an SDL_GamepadType enum to a string.
|
|
|
1175 *
|
|
|
1176 * \param type an enum value for a given SDL_GamepadType.
|
|
|
1177 * \returns a string for the given type, or NULL if an invalid type is
|
|
|
1178 * specified. The string returned is of the format used by
|
|
|
1179 * SDL_Gamepad mapping strings.
|
|
|
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 *
|
|
|
1185 * \sa SDL_GetGamepadTypeFromString
|
|
|
1186 */
|
|
|
1187 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForType(SDL_GamepadType type);
|
|
|
1188
|
|
|
1189 /**
|
|
|
1190 * Convert a string into SDL_GamepadAxis enum.
|
|
|
1191 *
|
|
|
1192 * This function is called internally to translate SDL_Gamepad mapping strings
|
|
|
1193 * for the underlying joystick device into the consistent SDL_Gamepad mapping.
|
|
|
1194 * You do not normally need to call this function unless you are parsing
|
|
|
1195 * SDL_Gamepad mappings in your own code.
|
|
|
1196 *
|
|
|
1197 * Note specially that "righttrigger" and "lefttrigger" map to
|
|
|
1198 * `SDL_GAMEPAD_AXIS_RIGHT_TRIGGER` and `SDL_GAMEPAD_AXIS_LEFT_TRIGGER`,
|
|
|
1199 * respectively.
|
|
|
1200 *
|
|
|
1201 * \param str string representing a SDL_Gamepad axis.
|
|
|
1202 * \returns the SDL_GamepadAxis enum corresponding to the input string, or
|
|
|
1203 * `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
|
|
|
1204 *
|
|
|
1205 * \threadsafety It is safe to call this function from any thread.
|
|
|
1206 *
|
|
|
1207 * \since This function is available since SDL 3.2.0.
|
|
|
1208 *
|
|
|
1209 * \sa SDL_GetGamepadStringForAxis
|
|
|
1210 */
|
|
|
1211 extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const char *str);
|
|
|
1212
|
|
|
1213 /**
|
|
|
1214 * Convert from an SDL_GamepadAxis enum to a string.
|
|
|
1215 *
|
|
|
1216 * \param axis an enum value for a given SDL_GamepadAxis.
|
|
|
1217 * \returns a string for the given axis, or NULL if an invalid axis is
|
|
|
1218 * specified. The string returned is of the format used by
|
|
|
1219 * SDL_Gamepad mapping strings.
|
|
|
1220 *
|
|
|
1221 * \threadsafety It is safe to call this function from any thread.
|
|
|
1222 *
|
|
|
1223 * \since This function is available since SDL 3.2.0.
|
|
|
1224 *
|
|
|
1225 * \sa SDL_GetGamepadAxisFromString
|
|
|
1226 */
|
|
|
1227 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_GamepadAxis axis);
|
|
|
1228
|
|
|
1229 /**
|
|
|
1230 * Query whether a gamepad has a given axis.
|
|
|
1231 *
|
|
|
1232 * This merely reports whether the gamepad's mapping defined this axis, as
|
|
|
1233 * that is all the information SDL has about the physical device.
|
|
|
1234 *
|
|
|
1235 * \param gamepad a gamepad.
|
|
|
1236 * \param axis an axis enum value (an SDL_GamepadAxis value).
|
|
|
1237 * \returns true if the gamepad has this axis, false otherwise.
|
|
|
1238 *
|
|
|
1239 * \threadsafety It is safe to call this function from any thread.
|
|
|
1240 *
|
|
|
1241 * \since This function is available since SDL 3.2.0.
|
|
|
1242 *
|
|
|
1243 * \sa SDL_GamepadHasButton
|
|
|
1244 * \sa SDL_GetGamepadAxis
|
|
|
1245 */
|
|
|
1246 extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis);
|
|
|
1247
|
|
|
1248 /**
|
|
|
1249 * Get the current state of an axis control on a gamepad.
|
|
|
1250 *
|
|
|
1251 * The axis indices start at index 0.
|
|
|
1252 *
|
|
|
1253 * For thumbsticks, the state is a value ranging from -32768 (up/left) to
|
|
|
1254 * 32767 (down/right).
|
|
|
1255 *
|
|
|
1256 * Triggers range from 0 when released to 32767 when fully pressed, and never
|
|
|
1257 * return a negative value. Note that this differs from the value reported by
|
|
|
1258 * the lower-level SDL_GetJoystickAxis(), which normally uses the full range.
|
|
|
1259 *
|
|
|
1260 * Note that for invalid gamepads or axes, this will return 0. Zero is also a
|
|
|
1261 * valid value in normal operation; usually it means a centered axis.
|
|
|
1262 *
|
|
|
1263 * \param gamepad a gamepad.
|
|
|
1264 * \param axis an axis index (one of the SDL_GamepadAxis values).
|
|
|
1265 * \returns axis state.
|
|
|
1266 *
|
|
|
1267 * \threadsafety It is safe to call this function from any thread.
|
|
|
1268 *
|
|
|
1269 * \since This function is available since SDL 3.2.0.
|
|
|
1270 *
|
|
|
1271 * \sa SDL_GamepadHasAxis
|
|
|
1272 * \sa SDL_GetGamepadButton
|
|
|
1273 */
|
|
|
1274 extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis);
|
|
|
1275
|
|
|
1276 /**
|
|
|
1277 * Convert a string into an SDL_GamepadButton enum.
|
|
|
1278 *
|
|
|
1279 * This function is called internally to translate SDL_Gamepad mapping strings
|
|
|
1280 * for the underlying joystick device into the consistent SDL_Gamepad mapping.
|
|
|
1281 * You do not normally need to call this function unless you are parsing
|
|
|
1282 * SDL_Gamepad mappings in your own code.
|
|
|
1283 *
|
|
|
1284 * \param str string representing a SDL_Gamepad button.
|
|
|
1285 * \returns the SDL_GamepadButton enum corresponding to the input string, or
|
|
|
1286 * `SDL_GAMEPAD_BUTTON_INVALID` if no match was found.
|
|
|
1287 *
|
|
|
1288 * \threadsafety It is safe to call this function from any thread.
|
|
|
1289 *
|
|
|
1290 * \since This function is available since SDL 3.2.0.
|
|
|
1291 *
|
|
|
1292 * \sa SDL_GetGamepadStringForButton
|
|
|
1293 */
|
|
|
1294 extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(const char *str);
|
|
|
1295
|
|
|
1296 /**
|
|
|
1297 * Convert from an SDL_GamepadButton enum to a string.
|
|
|
1298 *
|
|
|
1299 * \param button an enum value for a given SDL_GamepadButton.
|
|
|
1300 * \returns a string for the given button, or NULL if an invalid button is
|
|
|
1301 * specified. The string returned is of the format used by
|
|
|
1302 * SDL_Gamepad mapping strings.
|
|
|
1303 *
|
|
|
1304 * \threadsafety It is safe to call this function from any thread.
|
|
|
1305 *
|
|
|
1306 * \since This function is available since SDL 3.2.0.
|
|
|
1307 *
|
|
|
1308 * \sa SDL_GetGamepadButtonFromString
|
|
|
1309 */
|
|
|
1310 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForButton(SDL_GamepadButton button);
|
|
|
1311
|
|
|
1312 /**
|
|
|
1313 * Query whether a gamepad has a given button.
|
|
|
1314 *
|
|
|
1315 * This merely reports whether the gamepad's mapping defined this button, as
|
|
|
1316 * that is all the information SDL has about the physical device.
|
|
|
1317 *
|
|
|
1318 * \param gamepad a gamepad.
|
|
|
1319 * \param button a button enum value (an SDL_GamepadButton value).
|
|
|
1320 * \returns true if the gamepad has this button, false otherwise.
|
|
|
1321 *
|
|
|
1322 * \threadsafety It is safe to call this function from any thread.
|
|
|
1323 *
|
|
|
1324 * \since This function is available since SDL 3.2.0.
|
|
|
1325 *
|
|
|
1326 * \sa SDL_GamepadHasAxis
|
|
|
1327 */
|
|
|
1328 extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button);
|
|
|
1329
|
|
|
1330 /**
|
|
|
1331 * Get the current state of a button on a gamepad.
|
|
|
1332 *
|
|
|
1333 * \param gamepad a gamepad.
|
|
|
1334 * \param button a button index (one of the SDL_GamepadButton values).
|
|
|
1335 * \returns true if the button is pressed, false otherwise.
|
|
|
1336 *
|
|
|
1337 * \threadsafety It is safe to call this function from any thread.
|
|
|
1338 *
|
|
|
1339 * \since This function is available since SDL 3.2.0.
|
|
|
1340 *
|
|
|
1341 * \sa SDL_GamepadHasButton
|
|
|
1342 * \sa SDL_GetGamepadAxis
|
|
|
1343 */
|
|
|
1344 extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button);
|
|
|
1345
|
|
|
1346 /**
|
|
|
1347 * Get the label of a button on a gamepad.
|
|
|
1348 *
|
|
|
1349 * \param type the type of gamepad to check.
|
|
|
1350 * \param button a button index (one of the SDL_GamepadButton values).
|
|
|
1351 * \returns the SDL_GamepadButtonLabel enum corresponding to the button label.
|
|
|
1352 *
|
|
|
1353 * \threadsafety It is safe to call this function from any thread.
|
|
|
1354 *
|
|
|
1355 * \since This function is available since SDL 3.2.0.
|
|
|
1356 *
|
|
|
1357 * \sa SDL_GetGamepadButtonLabel
|
|
|
1358 */
|
|
|
1359 extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForType(SDL_GamepadType type, SDL_GamepadButton button);
|
|
|
1360
|
|
|
1361 /**
|
|
|
1362 * Get the label of a button on a gamepad.
|
|
|
1363 *
|
|
|
1364 * \param gamepad a gamepad.
|
|
|
1365 * \param button a button index (one of the SDL_GamepadButton values).
|
|
|
1366 * \returns the SDL_GamepadButtonLabel enum corresponding to the button label.
|
|
|
1367 *
|
|
|
1368 * \threadsafety It is safe to call this function from any thread.
|
|
|
1369 *
|
|
|
1370 * \since This function is available since SDL 3.2.0.
|
|
|
1371 *
|
|
|
1372 * \sa SDL_GetGamepadButtonLabelForType
|
|
|
1373 */
|
|
|
1374 extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL_Gamepad *gamepad, SDL_GamepadButton button);
|
|
|
1375
|
|
|
1376 /**
|
|
|
1377 * Get the number of touchpads on a gamepad.
|
|
|
1378 *
|
|
|
1379 * \param gamepad a gamepad.
|
|
|
1380 * \returns number of touchpads.
|
|
|
1381 *
|
|
|
1382 * \threadsafety It is safe to call this function from any thread.
|
|
|
1383 *
|
|
|
1384 * \since This function is available since SDL 3.2.0.
|
|
|
1385 *
|
|
|
1386 * \sa SDL_GetNumGamepadTouchpadFingers
|
|
|
1387 */
|
|
|
1388 extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad);
|
|
|
1389
|
|
|
1390 /**
|
|
|
1391 * Get the number of supported simultaneous fingers on a touchpad on a game
|
|
|
1392 * gamepad.
|
|
|
1393 *
|
|
|
1394 * \param gamepad a gamepad.
|
|
|
1395 * \param touchpad a touchpad.
|
|
|
1396 * \returns number of supported simultaneous fingers.
|
|
|
1397 *
|
|
|
1398 * \threadsafety It is safe to call this function from any thread.
|
|
|
1399 *
|
|
|
1400 * \since This function is available since SDL 3.2.0.
|
|
|
1401 *
|
|
|
1402 * \sa SDL_GetGamepadTouchpadFinger
|
|
|
1403 * \sa SDL_GetNumGamepadTouchpads
|
|
|
1404 */
|
|
|
1405 extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *gamepad, int touchpad);
|
|
|
1406
|
|
|
1407 /**
|
|
|
1408 * Get the current state of a finger on a touchpad on a gamepad.
|
|
|
1409 *
|
|
|
1410 * \param gamepad a gamepad.
|
|
|
1411 * \param touchpad a touchpad.
|
|
|
1412 * \param finger a finger.
|
|
|
1413 * \param down a pointer filled with true if the finger is down, false
|
|
|
1414 * otherwise, may be NULL.
|
|
|
1415 * \param x a pointer filled with the x position, normalized 0 to 1, with the
|
|
|
1416 * origin in the upper left, may be NULL.
|
|
|
1417 * \param y a pointer filled with the y position, normalized 0 to 1, with the
|
|
|
1418 * origin in the upper left, may be NULL.
|
|
|
1419 * \param pressure a pointer filled with pressure value, may be NULL.
|
|
|
1420 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1421 * information.
|
|
|
1422 *
|
|
|
1423 * \threadsafety It is safe to call this function from any thread.
|
|
|
1424 *
|
|
|
1425 * \since This function is available since SDL 3.2.0.
|
|
|
1426 *
|
|
|
1427 * \sa SDL_GetNumGamepadTouchpadFingers
|
|
|
1428 */
|
|
|
1429 extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, bool *down, float *x, float *y, float *pressure);
|
|
|
1430
|
|
|
1431 /**
|
|
|
1432 * Return whether a gamepad has a particular sensor.
|
|
|
1433 *
|
|
|
1434 * \param gamepad the gamepad to query.
|
|
|
1435 * \param type the type of sensor to query.
|
|
|
1436 * \returns true if the sensor exists, false otherwise.
|
|
|
1437 *
|
|
|
1438 * \threadsafety It is safe to call this function from any thread.
|
|
|
1439 *
|
|
|
1440 * \since This function is available since SDL 3.2.0.
|
|
|
1441 *
|
|
|
1442 * \sa SDL_GetGamepadSensorData
|
|
|
1443 * \sa SDL_GetGamepadSensorDataRate
|
|
|
1444 * \sa SDL_SetGamepadSensorEnabled
|
|
|
1445 */
|
|
|
1446 extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type);
|
|
|
1447
|
|
|
1448 /**
|
|
|
1449 * Set whether data reporting for a gamepad sensor is enabled.
|
|
|
1450 *
|
|
|
1451 * \param gamepad the gamepad to update.
|
|
|
1452 * \param type the type of sensor to enable/disable.
|
|
|
1453 * \param enabled whether data reporting should be enabled.
|
|
|
1454 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1455 * information.
|
|
|
1456 *
|
|
|
1457 * \threadsafety It is safe to call this function from any thread.
|
|
|
1458 *
|
|
|
1459 * \since This function is available since SDL 3.2.0.
|
|
|
1460 *
|
|
|
1461 * \sa SDL_GamepadHasSensor
|
|
|
1462 * \sa SDL_GamepadSensorEnabled
|
|
|
1463 */
|
|
|
1464 extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, bool enabled);
|
|
|
1465
|
|
|
1466 /**
|
|
|
1467 * Query whether sensor data reporting is enabled for a gamepad.
|
|
|
1468 *
|
|
|
1469 * \param gamepad the gamepad to query.
|
|
|
1470 * \param type the type of sensor to query.
|
|
|
1471 * \returns true if the sensor is enabled, false otherwise.
|
|
|
1472 *
|
|
|
1473 * \threadsafety It is safe to call this function from any thread.
|
|
|
1474 *
|
|
|
1475 * \since This function is available since SDL 3.2.0.
|
|
|
1476 *
|
|
|
1477 * \sa SDL_SetGamepadSensorEnabled
|
|
|
1478 */
|
|
|
1479 extern SDL_DECLSPEC bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type);
|
|
|
1480
|
|
|
1481 /**
|
|
|
1482 * Get the data rate (number of events per second) of a gamepad sensor.
|
|
|
1483 *
|
|
|
1484 * \param gamepad the gamepad to query.
|
|
|
1485 * \param type the type of sensor to query.
|
|
|
1486 * \returns the data rate, or 0.0f if the data rate is not available.
|
|
|
1487 *
|
|
|
1488 * \threadsafety It is safe to call this function from any thread.
|
|
|
1489 *
|
|
|
1490 * \since This function is available since SDL 3.2.0.
|
|
|
1491 */
|
|
|
1492 extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad, SDL_SensorType type);
|
|
|
1493
|
|
|
1494 /**
|
|
|
1495 * Get the current state of a gamepad sensor.
|
|
|
1496 *
|
|
|
1497 * The number of values and interpretation of the data is sensor dependent.
|
|
|
1498 * See the remarks in SDL_SensorType for details for each type of sensor.
|
|
|
1499 *
|
|
|
1500 * \param gamepad the gamepad to query.
|
|
|
1501 * \param type the type of sensor to query.
|
|
|
1502 * \param data a pointer filled with the current sensor state.
|
|
|
1503 * \param num_values the number of values to write to data.
|
|
|
1504 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1505 * information.
|
|
|
1506 *
|
|
|
1507 * \threadsafety It is safe to call this function from any thread.
|
|
|
1508 *
|
|
|
1509 * \since This function is available since SDL 3.2.0.
|
|
|
1510 */
|
|
|
1511 extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values);
|
|
|
1512
|
|
|
1513 /**
|
|
|
1514 * Start a rumble effect on a gamepad.
|
|
|
1515 *
|
|
|
1516 * Each call to this function cancels any previous rumble effect, and calling
|
|
|
1517 * it with 0 intensity stops any rumbling.
|
|
|
1518 *
|
|
|
1519 * This function requires you to process SDL events or call
|
|
|
1520 * SDL_UpdateJoysticks() to update rumble state.
|
|
|
1521 *
|
|
|
1522 * \param gamepad the gamepad to vibrate.
|
|
|
1523 * \param low_frequency_rumble the intensity of the low frequency (left)
|
|
|
1524 * rumble motor, from 0 to 0xFFFF.
|
|
|
1525 * \param high_frequency_rumble the intensity of the high frequency (right)
|
|
|
1526 * rumble motor, from 0 to 0xFFFF.
|
|
|
1527 * \param duration_ms the duration of the rumble effect, in milliseconds.
|
|
|
1528 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1529 * information.
|
|
|
1530 *
|
|
|
1531 * \threadsafety It is safe to call this function from any thread.
|
|
|
1532 *
|
|
|
1533 * \since This function is available since SDL 3.2.0.
|
|
|
1534 */
|
|
|
1535 extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
|
|
|
1536
|
|
|
1537 /**
|
|
|
1538 * Start a rumble effect in the gamepad's triggers.
|
|
|
1539 *
|
|
|
1540 * Each call to this function cancels any previous trigger rumble effect, and
|
|
|
1541 * calling it with 0 intensity stops any rumbling.
|
|
|
1542 *
|
|
|
1543 * Note that this is rumbling of the _triggers_ and not the gamepad as a
|
|
|
1544 * whole. This is currently only supported on Xbox One gamepads. If you want
|
|
|
1545 * the (more common) whole-gamepad rumble, use SDL_RumbleGamepad() instead.
|
|
|
1546 *
|
|
|
1547 * This function requires you to process SDL events or call
|
|
|
1548 * SDL_UpdateJoysticks() to update rumble state.
|
|
|
1549 *
|
|
|
1550 * \param gamepad the gamepad to vibrate.
|
|
|
1551 * \param left_rumble the intensity of the left trigger rumble motor, from 0
|
|
|
1552 * to 0xFFFF.
|
|
|
1553 * \param right_rumble the intensity of the right trigger rumble motor, from 0
|
|
|
1554 * to 0xFFFF.
|
|
|
1555 * \param duration_ms the duration of the rumble effect, in milliseconds.
|
|
|
1556 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1557 * information.
|
|
|
1558 *
|
|
|
1559 * \threadsafety It is safe to call this function from any thread.
|
|
|
1560 *
|
|
|
1561 * \since This function is available since SDL 3.2.0.
|
|
|
1562 *
|
|
|
1563 * \sa SDL_RumbleGamepad
|
|
|
1564 */
|
|
|
1565 extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
|
|
|
1566
|
|
|
1567 /**
|
|
|
1568 * Update a gamepad's LED color.
|
|
|
1569 *
|
|
|
1570 * An example of a joystick LED is the light on the back of a PlayStation 4's
|
|
|
1571 * DualShock 4 controller.
|
|
|
1572 *
|
|
|
1573 * For gamepads with a single color LED, the maximum of the RGB values will be
|
|
|
1574 * used as the LED brightness.
|
|
|
1575 *
|
|
|
1576 * \param gamepad the gamepad to update.
|
|
|
1577 * \param red the intensity of the red LED.
|
|
|
1578 * \param green the intensity of the green LED.
|
|
|
1579 * \param blue the intensity of the blue LED.
|
|
|
1580 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1581 * information.
|
|
|
1582 *
|
|
|
1583 * \threadsafety It is safe to call this function from any thread.
|
|
|
1584 *
|
|
|
1585 * \since This function is available since SDL 3.2.0.
|
|
|
1586 */
|
|
|
1587 extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue);
|
|
|
1588
|
|
|
1589 /**
|
|
|
1590 * Send a gamepad specific effect packet.
|
|
|
1591 *
|
|
|
1592 * \param gamepad the gamepad to affect.
|
|
|
1593 * \param data the data to send to the gamepad.
|
|
|
1594 * \param size the size of the data to send to the gamepad.
|
|
|
1595 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1596 * information.
|
|
|
1597 *
|
|
|
1598 * \threadsafety It is safe to call this function from any thread.
|
|
|
1599 *
|
|
|
1600 * \since This function is available since SDL 3.2.0.
|
|
|
1601 */
|
|
|
1602 extern SDL_DECLSPEC bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size);
|
|
|
1603
|
|
|
1604 /**
|
|
|
1605 * Close a gamepad previously opened with SDL_OpenGamepad().
|
|
|
1606 *
|
|
|
1607 * \param gamepad a gamepad identifier previously returned by
|
|
|
1608 * SDL_OpenGamepad().
|
|
|
1609 *
|
|
|
1610 * \threadsafety It is safe to call this function from any thread.
|
|
|
1611 *
|
|
|
1612 * \since This function is available since SDL 3.2.0.
|
|
|
1613 *
|
|
|
1614 * \sa SDL_OpenGamepad
|
|
|
1615 */
|
|
|
1616 extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad);
|
|
|
1617
|
|
|
1618 /**
|
|
|
1619 * Return the sfSymbolsName for a given button on a gamepad on Apple
|
|
|
1620 * platforms.
|
|
|
1621 *
|
|
|
1622 * \param gamepad the gamepad to query.
|
|
|
1623 * \param button a button on the gamepad.
|
|
|
1624 * \returns the sfSymbolsName or NULL if the name can't be found.
|
|
|
1625 *
|
|
|
1626 * \threadsafety It is safe to call this function from any thread.
|
|
|
1627 *
|
|
|
1628 * \since This function is available since SDL 3.2.0.
|
|
|
1629 *
|
|
|
1630 * \sa SDL_GetGamepadAppleSFSymbolsNameForAxis
|
|
|
1631 */
|
|
|
1632 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButton(SDL_Gamepad *gamepad, SDL_GamepadButton button);
|
|
|
1633
|
|
|
1634 /**
|
|
|
1635 * Return the sfSymbolsName for a given axis on a gamepad on Apple platforms.
|
|
|
1636 *
|
|
|
1637 * \param gamepad the gamepad to query.
|
|
|
1638 * \param axis an axis on the gamepad.
|
|
|
1639 * \returns the sfSymbolsName or NULL if the name can't be found.
|
|
|
1640 *
|
|
|
1641 * \threadsafety It is safe to call this function from any thread.
|
|
|
1642 *
|
|
|
1643 * \since This function is available since SDL 3.2.0.
|
|
|
1644 *
|
|
|
1645 * \sa SDL_GetGamepadAppleSFSymbolsNameForButton
|
|
|
1646 */
|
|
|
1647 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis);
|
|
|
1648
|
|
|
1649
|
|
|
1650 /* Ends C function definitions when using C++ */
|
|
|
1651 #ifdef __cplusplus
|
|
|
1652 }
|
|
|
1653 #endif
|
|
|
1654 #include <SDL3/SDL_close_code.h>
|
|
|
1655
|
|
|
1656 #endif /* SDL_gamepad_h_ */
|
