include/SDL_gamecontroller.h
changeset 6690 9548c8a58103
child 6795 f445268492a7
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/include/SDL_gamecontroller.h	Mon Nov 26 16:37:54 2012 -0800
     1.3 @@ -0,0 +1,257 @@
     1.4 +/*
     1.5 +  Simple DirectMedia Layer
     1.6 +  Copyright (C) 1997-2012 Sam Lantinga <slouken@libsdl.org>
     1.7 +
     1.8 +  This software is provided 'as-is', without any express or implied
     1.9 +  warranty.  In no event will the authors be held liable for any damages
    1.10 +  arising from the use of this software.
    1.11 +
    1.12 +  Permission is granted to anyone to use this software for any purpose,
    1.13 +  including commercial applications, and to alter it and redistribute it
    1.14 +  freely, subject to the following restrictions:
    1.15 +
    1.16 +  1. The origin of this software must not be misrepresented; you must not
    1.17 +     claim that you wrote the original software. If you use this software
    1.18 +     in a product, an acknowledgment in the product documentation would be
    1.19 +     appreciated but is not required.
    1.20 +  2. Altered source versions must be plainly marked as such, and must not be
    1.21 +     misrepresented as being the original software.
    1.22 +  3. This notice may not be removed or altered from any source distribution.
    1.23 +*/
    1.24 +
    1.25 +/**
    1.26 + *  \file SDL_gamecontroller.h
    1.27 + *  
    1.28 + *  Include file for SDL game controller event handling
    1.29 + */
    1.30 +
    1.31 +#ifndef _SDL_gamecontroller_h
    1.32 +#define _SDL_gamecontroller_h
    1.33 +
    1.34 +#include "SDL_stdinc.h"
    1.35 +#include "SDL_error.h"
    1.36 +#include "SDL_joystick.h"
    1.37 +
    1.38 +#include "begin_code.h"
    1.39 +/* Set up for C function definitions, even when using C++ */
    1.40 +#ifdef __cplusplus
    1.41 +/* *INDENT-OFF* */
    1.42 +extern "C" {
    1.43 +/* *INDENT-ON* */
    1.44 +#endif
    1.45 +
    1.46 +/**
    1.47 + *  \file SDL_gamecontroller.h
    1.48 + *
    1.49 + *  In order to use these functions, SDL_Init() must have been called
    1.50 + *  with the ::SDL_INIT_JOYSTICK flag.  This causes SDL to scan the system
    1.51 + *  for game controllers, and load appropriate drivers.
    1.52 + */
    1.53 +
    1.54 +/* The gamecontroller structure used to identify an SDL game controller */
    1.55 +struct _SDL_GameController;
    1.56 +typedef struct _SDL_GameController SDL_GameController;
    1.57 +
    1.58 +
    1.59 +typedef enum 
    1.60 +{
    1.61 +	SDL_CONTROLLER_BINDTYPE_NONE = 0,
    1.62 +	SDL_CONTROLLER_BINDTYPE_BUTTON,
    1.63 +	SDL_CONTROLLER_BINDTYPE_AXIS,
    1.64 +	SDL_CONTROLLER_BINDTYPE_HAT,
    1.65 +} SDL_CONTROLLER_BINDTYPE;
    1.66 +/**
    1.67 + *  get the sdl joystick layer binding for this controller button/axis mapping
    1.68 + */
    1.69 +struct _SDL_GameControllerHatBind
    1.70 +{
    1.71 +	int hat;
    1.72 +	int hat_mask;
    1.73 +};
    1.74 +
    1.75 +typedef struct _SDL_GameControllerButtonBind
    1.76 +{
    1.77 +	SDL_CONTROLLER_BINDTYPE m_eBindType;
    1.78 +	union
    1.79 +	{
    1.80 +		int button;
    1.81 +		int axis;
    1.82 +		struct _SDL_GameControllerHatBind hat;
    1.83 +	};
    1.84 +
    1.85 +} SDL_GameControllerButtonBind;
    1.86 +
    1.87 +
    1.88 +/**
    1.89 + *  To count the number of game controllers in the system for the following:
    1.90 + *	int nJoysticks = SDL_NumJoysticks();
    1.91 + *	int nGameControllers = 0;
    1.92 + *	for ( int i = 0; i < nJoysticks; i++ ) {
    1.93 + *		if ( SDL_IsGameController(i) ) {
    1.94 + *			nGameControllers++;
    1.95 + *		}
    1.96 + *  }
    1.97 + *
    1.98 + *  Using the SDL_HINT_GAMECONTROLLERCONFIG hint you can add support for controllers SDL is unaware of or cause an existing controller to have a different binding. The format is:
    1.99 + *	guid,name,mappings
   1.100 + *
   1.101 + *  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.
   1.102 + *  Under Windows there is a reserved GUID of "xinput" that covers any XInput devices.
   1.103 + *	The mapping format for joystick is: 
   1.104 + *		bX - a joystick button, index X
   1.105 + *		hX.Y - hat X with value Y
   1.106 + *		aX - axis X of the joystick
   1.107 + *  Buttons can be used as a controller axis and vice versa.
   1.108 + *
   1.109 + *  This string shows an example of a valid mapping for a controller
   1.110 + * 	"341a3608000000000000504944564944,Aferglow 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",
   1.111 + *
   1.112 + */
   1.113 +
   1.114 +
   1.115 +/**
   1.116 + *  Is the joystick on this index supported by the game controller interface?
   1.117 + *		returns 1 if supported, 0 otherwise.
   1.118 + */
   1.119 +extern DECLSPEC int SDLCALL SDL_IsGameController(int joystick_index);
   1.120 +
   1.121 +
   1.122 +/**
   1.123 + *  Get the implementation dependent name of a game controller.
   1.124 + *  This can be called before any controllers are opened.
   1.125 + *  If no name can be found, this function returns NULL.
   1.126 + */
   1.127 +extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index);
   1.128 +
   1.129 +/**
   1.130 + *  Open a game controller for use.  
   1.131 + *  The index passed as an argument refers to the N'th game controller on the system.  
   1.132 + *  This index is the value which will identify this controller in future controller
   1.133 + *  events.
   1.134 + *  
   1.135 + *  \return A controller identifier, or NULL if an error occurred.
   1.136 + */
   1.137 +extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index);
   1.138 +
   1.139 +/**
   1.140 + *  Return the name for this currently opened controller
   1.141 + */
   1.142 +extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController * gamecontroller);
   1.143 +	
   1.144 +/**
   1.145 + *  Returns 1 if the controller has been opened and currently connected, or 0 if it has not.
   1.146 + */
   1.147 +extern DECLSPEC int SDLCALL SDL_GameControllerGetAttached(SDL_GameController * gamecontroller);
   1.148 +
   1.149 +/**
   1.150 + *  Get the underlying joystick object used by a controller
   1.151 + */
   1.152 +extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController * gamecontroller);
   1.153 +
   1.154 +/**
   1.155 + *  Enable/disable controller event polling.
   1.156 + *  
   1.157 + *  If controller events are disabled, you must call SDL_GameControllerUpdate()
   1.158 + *  yourself and check the state of the controller when you want controller
   1.159 + *  information.
   1.160 + *  
   1.161 + *  The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
   1.162 + */
   1.163 +extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state);
   1.164 +
   1.165 +/**
   1.166 + *  The list of axii available from a controller
   1.167 + */
   1.168 +typedef enum 
   1.169 +{
   1.170 +	SDL_CONTROLLER_AXIS_INVALID = -1,
   1.171 +	SDL_CONTROLLER_AXIS_LEFTX,
   1.172 +	SDL_CONTROLLER_AXIS_LEFTY,
   1.173 +	SDL_CONTROLLER_AXIS_RIGHTX,
   1.174 +	SDL_CONTROLLER_AXIS_RIGHTY,
   1.175 +	SDL_CONTROLLER_AXIS_TRIGGERLEFT,
   1.176 +	SDL_CONTROLLER_AXIS_TRIGGERRIGHT,
   1.177 +	SDL_CONTROLLER_AXIS_MAX
   1.178 +} SDL_CONTROLLER_AXIS;
   1.179 +
   1.180 +/**
   1.181 + *  turn this string into a axis mapping
   1.182 + */
   1.183 +extern DECLSPEC SDL_CONTROLLER_AXIS SDLCALL SDL_GameControllerGetAxisFromString(const char *pchString);
   1.184 +
   1.185 +/**
   1.186 + *  get the sdl joystick layer binding for this controller button mapping
   1.187 + */
   1.188 +extern DECLSPEC SDL_GameControllerButtonBind SDLCALL SDL_GameControllerGetBindForAxis(SDL_GameController * gamecontroller, SDL_CONTROLLER_AXIS button);
   1.189 +
   1.190 +/**
   1.191 + *  Get the current state of an axis control on a game controller.
   1.192 + *  
   1.193 + *  The state is a value ranging from -32768 to 32767.
   1.194 + *  
   1.195 + *  The axis indices start at index 0.
   1.196 + */
   1.197 +extern DECLSPEC Sint16 SDLCALL SDL_GameControllerGetAxis(SDL_GameController * gamecontroller,
   1.198 +                                                   SDL_CONTROLLER_AXIS axis);
   1.199 +
   1.200 +/**
   1.201 + *  The list of buttons available from a controller
   1.202 + */
   1.203 +typedef enum
   1.204 +{
   1.205 +	SDL_CONTROLLER_BUTTON_INVALID = -1,
   1.206 +	SDL_CONTROLLER_BUTTON_A,
   1.207 +	SDL_CONTROLLER_BUTTON_B,
   1.208 +	SDL_CONTROLLER_BUTTON_X,
   1.209 +	SDL_CONTROLLER_BUTTON_Y,
   1.210 +	SDL_CONTROLLER_BUTTON_BACK,
   1.211 +	SDL_CONTROLLER_BUTTON_GUIDE,
   1.212 +	SDL_CONTROLLER_BUTTON_START,
   1.213 +	SDL_CONTROLLER_BUTTON_LEFTSTICK,
   1.214 +	SDL_CONTROLLER_BUTTON_RIGHTSTICK,
   1.215 +	SDL_CONTROLLER_BUTTON_LEFTSHOULDER,
   1.216 +	SDL_CONTROLLER_BUTTON_RIGHTSHOULDER,
   1.217 +	SDL_CONTROLLER_BUTTON_DPAD_UP,
   1.218 +	SDL_CONTROLLER_BUTTON_DPAD_DOWN,
   1.219 +	SDL_CONTROLLER_BUTTON_DPAD_LEFT,
   1.220 +	SDL_CONTROLLER_BUTTON_DPAD_RIGHT,
   1.221 +	SDL_CONTROLLER_BUTTON_MAX
   1.222 +} SDL_CONTROLLER_BUTTON;
   1.223 +
   1.224 +/**
   1.225 + *  turn this string into a button mapping
   1.226 + */
   1.227 +extern DECLSPEC SDL_CONTROLLER_BUTTON SDLCALL SDL_GameControllerGetButtonFromString(const char *pchString);
   1.228 +
   1.229 +
   1.230 +/**
   1.231 + *  get the sdl joystick layer binding for this controller button mapping
   1.232 + */
   1.233 +extern DECLSPEC SDL_GameControllerButtonBind SDLCALL SDL_GameControllerGetBindForButton(SDL_GameController * gamecontroller, SDL_CONTROLLER_BUTTON button);
   1.234 +
   1.235 +
   1.236 +/**
   1.237 + *  Get the current state of a button on a game controller.
   1.238 + *  
   1.239 + *  The button indices start at index 0.
   1.240 + */
   1.241 +extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController * gamecontroller,
   1.242 +                                                    SDL_CONTROLLER_BUTTON button);
   1.243 +
   1.244 +/**
   1.245 + *  Close a controller previously opened with SDL_GameControllerOpen().
   1.246 + */
   1.247 +extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController * gamecontrollerk);
   1.248 +
   1.249 +
   1.250 +/* Ends C function definitions when using C++ */
   1.251 +#ifdef __cplusplus
   1.252 +/* *INDENT-OFF* */
   1.253 +}
   1.254 +/* *INDENT-ON* */
   1.255 +#endif
   1.256 +#include "close_code.h"
   1.257 +
   1.258 +#endif /* _SDL_gamecontroller_h */
   1.259 +
   1.260 +/* vi: set ts=4 sw=4 expandtab: */