SDL standard library
Embed:
(wiki syntax)
Show/hide line numbers
SDL_gamecontroller.h
Go to the documentation of this file.
00001 /* 00002 Simple DirectMedia Layer 00003 Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org> 00004 00005 This software is provided 'as-is', without any express or implied 00006 warranty. In no event will the authors be held liable for any damages 00007 arising from the use of this software. 00008 00009 Permission is granted to anyone to use this software for any purpose, 00010 including commercial applications, and to alter it and redistribute it 00011 freely, subject to the following restrictions: 00012 00013 1. The origin of this software must not be misrepresented; you must not 00014 claim that you wrote the original software. If you use this software 00015 in a product, an acknowledgment in the product documentation would be 00016 appreciated but is not required. 00017 2. Altered source versions must be plainly marked as such, and must not be 00018 misrepresented as being the original software. 00019 3. This notice may not be removed or altered from any source distribution. 00020 */ 00021 00022 /** 00023 * \file SDL_gamecontroller.h 00024 * 00025 * Include file for SDL game controller event handling 00026 */ 00027 00028 #ifndef _SDL_gamecontroller_h 00029 #define _SDL_gamecontroller_h 00030 00031 #include "SDL_stdinc.h" 00032 #include "SDL_error.h" 00033 #include "SDL_rwops.h" 00034 #include "SDL_joystick.h" 00035 00036 #include "begin_code.h" 00037 /* Set up for C function definitions, even when using C++ */ 00038 #ifdef __cplusplus 00039 extern "C" { 00040 #endif 00041 00042 /** 00043 * \file SDL_gamecontroller.h 00044 * 00045 * In order to use these functions, SDL_Init() must have been called 00046 * with the ::SDL_INIT_JOYSTICK flag. This causes SDL to scan the system 00047 * for game controllers, and load appropriate drivers. 00048 * 00049 * If you would like to receive controller updates while the application 00050 * is in the background, you should set the following hint before calling 00051 * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS 00052 */ 00053 00054 /* The gamecontroller structure used to identify an SDL game controller */ 00055 struct _SDL_GameController; 00056 typedef struct _SDL_GameController SDL_GameController; 00057 00058 00059 typedef enum 00060 { 00061 SDL_CONTROLLER_BINDTYPE_NONE = 0, 00062 SDL_CONTROLLER_BINDTYPE_BUTTON, 00063 SDL_CONTROLLER_BINDTYPE_AXIS, 00064 SDL_CONTROLLER_BINDTYPE_HAT 00065 } SDL_GameControllerBindType; 00066 00067 /** 00068 * Get the SDL joystick layer binding for this controller button/axis mapping 00069 */ 00070 typedef struct SDL_GameControllerButtonBind 00071 { 00072 SDL_GameControllerBindType bindType; 00073 union 00074 { 00075 int button; 00076 int axis; 00077 struct { 00078 int hat; 00079 int hat_mask; 00080 } hat; 00081 } value; 00082 00083 } SDL_GameControllerButtonBind; 00084 00085 00086 /** 00087 * To count the number of game controllers in the system for the following: 00088 * int nJoysticks = SDL_NumJoysticks(); 00089 * int nGameControllers = 0; 00090 * for ( int i = 0; i < nJoysticks; i++ ) { 00091 * if ( SDL_IsGameController(i) ) { 00092 * nGameControllers++; 00093 * } 00094 * } 00095 * 00096 * 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: 00097 * guid,name,mappings 00098 * 00099 * 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. 00100 * Under Windows there is a reserved GUID of "xinput" that covers any XInput devices. 00101 * The mapping format for joystick is: 00102 * bX - a joystick button, index X 00103 * hX.Y - hat X with value Y 00104 * aX - axis X of the joystick 00105 * Buttons can be used as a controller axis and vice versa. 00106 * 00107 * This string shows an example of a valid mapping for a controller 00108 * "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", 00109 * 00110 */ 00111 00112 /** 00113 * Load a set of mappings from a seekable SDL data stream (memory or file), filtered by the current SDL_GetPlatform() 00114 * A community sourced database of controllers is available at https://raw.github.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt 00115 * 00116 * If \c freerw is non-zero, the stream will be closed after being read. 00117 * 00118 * \return number of mappings added, -1 on error 00119 */ 00120 extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW( SDL_RWops * rw, int freerw ); 00121 00122 /** 00123 * Load a set of mappings from a file, filtered by the current SDL_GetPlatform() 00124 * 00125 * Convenience macro. 00126 */ 00127 #define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1) 00128 00129 /** 00130 * Add or update an existing mapping configuration 00131 * 00132 * \return 1 if mapping is added, 0 if updated, -1 on error 00133 */ 00134 extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping( const char* mappingString ); 00135 00136 /** 00137 * Get a mapping string for a GUID 00138 * 00139 * \return the mapping string. Must be freed with SDL_free. Returns NULL if no mapping is available 00140 */ 00141 extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID( SDL_JoystickGUID guid ); 00142 00143 /** 00144 * Get a mapping string for an open GameController 00145 * 00146 * \return the mapping string. Must be freed with SDL_free. Returns NULL if no mapping is available 00147 */ 00148 extern DECLSPEC char * SDLCALL SDL_GameControllerMapping( SDL_GameController * gamecontroller ); 00149 00150 /** 00151 * Is the joystick on this index supported by the game controller interface? 00152 */ 00153 extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index); 00154 00155 00156 /** 00157 * Get the implementation dependent name of a game controller. 00158 * This can be called before any controllers are opened. 00159 * If no name can be found, this function returns NULL. 00160 */ 00161 extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index); 00162 00163 /** 00164 * Open a game controller for use. 00165 * The index passed as an argument refers to the N'th game controller on the system. 00166 * This index is the value which will identify this controller in future controller 00167 * events. 00168 * 00169 * \return A controller identifier, or NULL if an error occurred. 00170 */ 00171 extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index); 00172 00173 /** 00174 * Return the name for this currently opened controller 00175 */ 00176 extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *gamecontroller); 00177 00178 /** 00179 * Returns SDL_TRUE if the controller has been opened and currently connected, 00180 * or SDL_FALSE if it has not. 00181 */ 00182 extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameController *gamecontroller); 00183 00184 /** 00185 * Get the underlying joystick object used by a controller 00186 */ 00187 extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController *gamecontroller); 00188 00189 /** 00190 * Enable/disable controller event polling. 00191 * 00192 * If controller events are disabled, you must call SDL_GameControllerUpdate() 00193 * yourself and check the state of the controller when you want controller 00194 * information. 00195 * 00196 * The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE. 00197 */ 00198 extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state); 00199 00200 /** 00201 * Update the current state of the open game controllers. 00202 * 00203 * This is called automatically by the event loop if any game controller 00204 * events are enabled. 00205 */ 00206 extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void); 00207 00208 00209 /** 00210 * The list of axes available from a controller 00211 */ 00212 typedef enum 00213 { 00214 SDL_CONTROLLER_AXIS_INVALID = -1, 00215 SDL_CONTROLLER_AXIS_LEFTX, 00216 SDL_CONTROLLER_AXIS_LEFTY, 00217 SDL_CONTROLLER_AXIS_RIGHTX, 00218 SDL_CONTROLLER_AXIS_RIGHTY, 00219 SDL_CONTROLLER_AXIS_TRIGGERLEFT, 00220 SDL_CONTROLLER_AXIS_TRIGGERRIGHT, 00221 SDL_CONTROLLER_AXIS_MAX 00222 } SDL_GameControllerAxis; 00223 00224 /** 00225 * turn this string into a axis mapping 00226 */ 00227 extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *pchString); 00228 00229 /** 00230 * turn this axis enum into a string mapping 00231 */ 00232 extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameControllerAxis axis); 00233 00234 /** 00235 * Get the SDL joystick layer binding for this controller button mapping 00236 */ 00237 extern DECLSPEC SDL_GameControllerButtonBind SDLCALL 00238 SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller, 00239 SDL_GameControllerAxis axis); 00240 00241 /** 00242 * Get the current state of an axis control on a game controller. 00243 * 00244 * The state is a value ranging from -32768 to 32767. 00245 * 00246 * The axis indices start at index 0. 00247 */ 00248 extern DECLSPEC Sint16 SDLCALL 00249 SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, 00250 SDL_GameControllerAxis axis); 00251 00252 /** 00253 * The list of buttons available from a controller 00254 */ 00255 typedef enum 00256 { 00257 SDL_CONTROLLER_BUTTON_INVALID = -1, 00258 SDL_CONTROLLER_BUTTON_A, 00259 SDL_CONTROLLER_BUTTON_B, 00260 SDL_CONTROLLER_BUTTON_X, 00261 SDL_CONTROLLER_BUTTON_Y, 00262 SDL_CONTROLLER_BUTTON_BACK, 00263 SDL_CONTROLLER_BUTTON_GUIDE, 00264 SDL_CONTROLLER_BUTTON_START, 00265 SDL_CONTROLLER_BUTTON_LEFTSTICK, 00266 SDL_CONTROLLER_BUTTON_RIGHTSTICK, 00267 SDL_CONTROLLER_BUTTON_LEFTSHOULDER, 00268 SDL_CONTROLLER_BUTTON_RIGHTSHOULDER, 00269 SDL_CONTROLLER_BUTTON_DPAD_UP, 00270 SDL_CONTROLLER_BUTTON_DPAD_DOWN, 00271 SDL_CONTROLLER_BUTTON_DPAD_LEFT, 00272 SDL_CONTROLLER_BUTTON_DPAD_RIGHT, 00273 SDL_CONTROLLER_BUTTON_MAX 00274 } SDL_GameControllerButton; 00275 00276 /** 00277 * turn this string into a button mapping 00278 */ 00279 extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *pchString); 00280 00281 /** 00282 * turn this button enum into a string mapping 00283 */ 00284 extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_GameControllerButton button); 00285 00286 /** 00287 * Get the SDL joystick layer binding for this controller button mapping 00288 */ 00289 extern DECLSPEC SDL_GameControllerButtonBind SDLCALL 00290 SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller, 00291 SDL_GameControllerButton button); 00292 00293 00294 /** 00295 * Get the current state of a button on a game controller. 00296 * 00297 * The button indices start at index 0. 00298 */ 00299 extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *gamecontroller, 00300 SDL_GameControllerButton button); 00301 00302 /** 00303 * Close a controller previously opened with SDL_GameControllerOpen(). 00304 */ 00305 extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller); 00306 00307 00308 /* Ends C function definitions when using C++ */ 00309 #ifdef __cplusplus 00310 } 00311 #endif 00312 #include "close_code.h" 00313 00314 #endif /* _SDL_gamecontroller_h */ 00315 00316 /* vi: set ts=4 sw=4 expandtab: */
Generated on Tue Jul 12 2022 13:56:24 by 1.7.2