]>
Commit | Line | Data |
---|---|---|
1 | /* | |
2 | Simple DirectMedia Layer | |
3 | Copyright (C) 1997-2013 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 | * \file SDL_gamecontroller.h | |
24 | * | |
25 | * Include file for SDL game controller event handling | |
26 | */ | |
27 | ||
28 | #ifndef _SDL_gamecontroller_h | |
29 | #define _SDL_gamecontroller_h | |
30 | ||
31 | #include "SDL_stdinc.h" | |
32 | #include "SDL_error.h" | |
33 | #include "SDL_joystick.h" | |
34 | ||
35 | #include "begin_code.h" | |
36 | /* Set up for C function definitions, even when using C++ */ | |
37 | #ifdef __cplusplus | |
38 | extern "C" { | |
39 | #endif | |
40 | ||
41 | /** | |
42 | * \file SDL_gamecontroller.h | |
43 | * | |
44 | * In order to use these functions, SDL_Init() must have been called | |
45 | * with the ::SDL_INIT_JOYSTICK flag. This causes SDL to scan the system | |
46 | * for game controllers, and load appropriate drivers. | |
47 | * | |
48 | * If you would like to receive controller updates while the application | |
49 | * is in the background, you should set the following hint before calling | |
50 | * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS | |
51 | */ | |
52 | ||
53 | /* The gamecontroller structure used to identify an SDL game controller */ | |
54 | struct _SDL_GameController; | |
55 | typedef struct _SDL_GameController SDL_GameController; | |
56 | ||
57 | ||
58 | typedef enum | |
59 | { | |
60 | SDL_CONTROLLER_BINDTYPE_NONE = 0, | |
61 | SDL_CONTROLLER_BINDTYPE_BUTTON, | |
62 | SDL_CONTROLLER_BINDTYPE_AXIS, | |
63 | SDL_CONTROLLER_BINDTYPE_HAT | |
64 | } SDL_GameControllerBindType; | |
65 | ||
66 | /** | |
67 | * Get the SDL joystick layer binding for this controller button/axis mapping | |
68 | */ | |
69 | typedef struct SDL_GameControllerButtonBind | |
70 | { | |
71 | SDL_GameControllerBindType bindType; | |
72 | union | |
73 | { | |
74 | int button; | |
75 | int axis; | |
76 | struct { | |
77 | int hat; | |
78 | int hat_mask; | |
79 | } hat; | |
80 | } value; | |
81 | ||
82 | } SDL_GameControllerButtonBind; | |
83 | ||
84 | ||
85 | /** | |
86 | * To count the number of game controllers in the system for the following: | |
87 | * int nJoysticks = SDL_NumJoysticks(); | |
88 | * int nGameControllers = 0; | |
89 | * for ( int i = 0; i < nJoysticks; i++ ) { | |
90 | * if ( SDL_IsGameController(i) ) { | |
91 | * nGameControllers++; | |
92 | * } | |
93 | * } | |
94 | * | |
95 | * Using the SDL_HINT_GAMECONTROLLERCONFIG hint or the SDL_GameControllerAddMapping you can add support for controllers SDL is unaware of or cause an existing controller to have a different binding. The format is: | |
96 | * guid,name,mappings | |
97 | * | |
98 | * Where GUID is the string value from SDL_JoystickGetGUIDString(), name is the human readable string for the device and mappings are controller mappings to joystick ones. | |
99 | * Under Windows there is a reserved GUID of "xinput" that covers any XInput devices. | |
100 | * The mapping format for joystick is: | |
101 | * bX - a joystick button, index X | |
102 | * hX.Y - hat X with value Y | |
103 | * aX - axis X of the joystick | |
104 | * Buttons can be used as a controller axis and vice versa. | |
105 | * | |
106 | * This string shows an example of a valid mapping for a controller | |
107 | * "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", | |
108 | * | |
109 | */ | |
110 | ||
111 | /** | |
112 | * Add or update an existing mapping configuration | |
113 | * | |
114 | * \return 1 if mapping is added, 0 if updated, -1 on error | |
115 | */ | |
116 | extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping( const char* mappingString ); | |
117 | ||
118 | /** | |
119 | * Get a mapping string for a GUID | |
120 | * | |
121 | * \return the mapping string. Must be freed with SDL_free. Returns NULL if no mapping is available | |
122 | */ | |
123 | extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID( SDL_JoystickGUID guid ); | |
124 | ||
125 | /** | |
126 | * Get a mapping string for an open GameController | |
127 | * | |
128 | * \return the mapping string. Must be freed with SDL_free. Returns NULL if no mapping is available | |
129 | */ | |
130 | extern DECLSPEC char * SDLCALL SDL_GameControllerMapping( SDL_GameController * gamecontroller ); | |
131 | ||
132 | /** | |
133 | * Is the joystick on this index supported by the game controller interface? | |
134 | */ | |
135 | extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index); | |
136 | ||
137 | ||
138 | /** | |
139 | * Get the implementation dependent name of a game controller. | |
140 | * This can be called before any controllers are opened. | |
141 | * If no name can be found, this function returns NULL. | |
142 | */ | |
143 | extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index); | |
144 | ||
145 | /** | |
146 | * Open a game controller for use. | |
147 | * The index passed as an argument refers to the N'th game controller on the system. | |
148 | * This index is the value which will identify this controller in future controller | |
149 | * events. | |
150 | * | |
151 | * \return A controller identifier, or NULL if an error occurred. | |
152 | */ | |
153 | extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index); | |
154 | ||
155 | /** | |
156 | * Return the name for this currently opened controller | |
157 | */ | |
158 | extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *gamecontroller); | |
159 | ||
160 | /** | |
161 | * Returns SDL_TRUE if the controller has been opened and currently connected, | |
162 | * or SDL_FALSE if it has not. | |
163 | */ | |
164 | extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameController *gamecontroller); | |
165 | ||
166 | /** | |
167 | * Get the underlying joystick object used by a controller | |
168 | */ | |
169 | extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController *gamecontroller); | |
170 | ||
171 | /** | |
172 | * Enable/disable controller event polling. | |
173 | * | |
174 | * If controller events are disabled, you must call SDL_GameControllerUpdate() | |
175 | * yourself and check the state of the controller when you want controller | |
176 | * information. | |
177 | * | |
178 | * The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE. | |
179 | */ | |
180 | extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state); | |
181 | ||
182 | /** | |
183 | * Update the current state of the open game controllers. | |
184 | * | |
185 | * This is called automatically by the event loop if any game controller | |
186 | * events are enabled. | |
187 | */ | |
188 | extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void); | |
189 | ||
190 | ||
191 | /** | |
192 | * The list of axes available from a controller | |
193 | */ | |
194 | typedef enum | |
195 | { | |
196 | SDL_CONTROLLER_AXIS_INVALID = -1, | |
197 | SDL_CONTROLLER_AXIS_LEFTX, | |
198 | SDL_CONTROLLER_AXIS_LEFTY, | |
199 | SDL_CONTROLLER_AXIS_RIGHTX, | |
200 | SDL_CONTROLLER_AXIS_RIGHTY, | |
201 | SDL_CONTROLLER_AXIS_TRIGGERLEFT, | |
202 | SDL_CONTROLLER_AXIS_TRIGGERRIGHT, | |
203 | SDL_CONTROLLER_AXIS_MAX | |
204 | } SDL_GameControllerAxis; | |
205 | ||
206 | /** | |
207 | * turn this string into a axis mapping | |
208 | */ | |
209 | extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *pchString); | |
210 | ||
211 | /** | |
212 | * turn this axis enum into a string mapping | |
213 | */ | |
214 | extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameControllerAxis axis); | |
215 | ||
216 | /** | |
217 | * Get the SDL joystick layer binding for this controller button mapping | |
218 | */ | |
219 | extern DECLSPEC SDL_GameControllerButtonBind SDLCALL | |
220 | SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller, | |
221 | SDL_GameControllerAxis axis); | |
222 | ||
223 | /** | |
224 | * Get the current state of an axis control on a game controller. | |
225 | * | |
226 | * The state is a value ranging from -32768 to 32767. | |
227 | * | |
228 | * The axis indices start at index 0. | |
229 | */ | |
230 | extern DECLSPEC Sint16 SDLCALL | |
231 | SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, | |
232 | SDL_GameControllerAxis axis); | |
233 | ||
234 | /** | |
235 | * The list of buttons available from a controller | |
236 | */ | |
237 | typedef enum | |
238 | { | |
239 | SDL_CONTROLLER_BUTTON_INVALID = -1, | |
240 | SDL_CONTROLLER_BUTTON_A, | |
241 | SDL_CONTROLLER_BUTTON_B, | |
242 | SDL_CONTROLLER_BUTTON_X, | |
243 | SDL_CONTROLLER_BUTTON_Y, | |
244 | SDL_CONTROLLER_BUTTON_BACK, | |
245 | SDL_CONTROLLER_BUTTON_GUIDE, | |
246 | SDL_CONTROLLER_BUTTON_START, | |
247 | SDL_CONTROLLER_BUTTON_LEFTSTICK, | |
248 | SDL_CONTROLLER_BUTTON_RIGHTSTICK, | |
249 | SDL_CONTROLLER_BUTTON_LEFTSHOULDER, | |
250 | SDL_CONTROLLER_BUTTON_RIGHTSHOULDER, | |
251 | SDL_CONTROLLER_BUTTON_DPAD_UP, | |
252 | SDL_CONTROLLER_BUTTON_DPAD_DOWN, | |
253 | SDL_CONTROLLER_BUTTON_DPAD_LEFT, | |
254 | SDL_CONTROLLER_BUTTON_DPAD_RIGHT, | |
255 | SDL_CONTROLLER_BUTTON_MAX | |
256 | } SDL_GameControllerButton; | |
257 | ||
258 | /** | |
259 | * turn this string into a button mapping | |
260 | */ | |
261 | extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *pchString); | |
262 | ||
263 | /** | |
264 | * turn this button enum into a string mapping | |
265 | */ | |
266 | extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_GameControllerButton button); | |
267 | ||
268 | /** | |
269 | * Get the SDL joystick layer binding for this controller button mapping | |
270 | */ | |
271 | extern DECLSPEC SDL_GameControllerButtonBind SDLCALL | |
272 | SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller, | |
273 | SDL_GameControllerButton button); | |
274 | ||
275 | ||
276 | /** | |
277 | * Get the current state of a button on a game controller. | |
278 | * | |
279 | * The button indices start at index 0. | |
280 | */ | |
281 | extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *gamecontroller, | |
282 | SDL_GameControllerButton button); | |
283 | ||
284 | /** | |
285 | * Close a controller previously opened with SDL_GameControllerOpen(). | |
286 | */ | |
287 | extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller); | |
288 | ||
289 | ||
290 | /* Ends C function definitions when using C++ */ | |
291 | #ifdef __cplusplus | |
292 | } | |
293 | #endif | |
294 | #include "close_code.h" | |
295 | ||
296 | #endif /* _SDL_gamecontroller_h */ | |
297 | ||
298 | /* vi: set ts=4 sw=4 expandtab: */ |