include/SDL_gamecontroller.h
author Ryan C. Gordon <icculus@icculus.org>
Thu, 28 May 2015 01:54:52 -0400
changeset 9671 0e1f57b051f4
parent 9619 b94b6d0bff0f
child 9916 9429bc102632
permissions -rw-r--r--
Windows GetBasePath should use GetModuleFileNameExW() and check for overflows.

Apparently you might get strange paths from GetModuleFileName(), such as
short path names or UNC filenames, so this avoids that problem. Since you have
to tapdance with linking different libraries and defining macros depending on
what Windows you plan to target, we dynamically load the API we need, which
works on all versions of Windows (on Win7, it'll load a compatibility wrapper
for the newer API location).

What a mess.

This also now does the right thing if there isn't enough space to store the
path, looping with a larger allocated buffer each try.

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