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