SDL_gamecontroller.h File Reference

#include "SDL_stdinc.h"
#include "SDL_error.h"
#include "SDL_rwops.h"
#include "SDL_joystick.h"
#include "begin_code.h"
#include "close_code.h"

Include dependency graph for SDL_gamecontroller.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	SDL_GameControllerButtonBind

Macros
#define	SDL_GameControllerAddMappingsFromFile(file)   SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)

Enumerations
enum	SDL_GameControllerBindType {   SDL_CONTROLLER_BINDTYPE_NONE = 0,   SDL_CONTROLLER_BINDTYPE_BUTTON,   SDL_CONTROLLER_BINDTYPE_AXIS,   SDL_CONTROLLER_BINDTYPE_HAT }
enum	SDL_GameControllerAxis {   SDL_CONTROLLER_AXIS_INVALID = -1,   SDL_CONTROLLER_AXIS_LEFTX,   SDL_CONTROLLER_AXIS_LEFTY,   SDL_CONTROLLER_AXIS_RIGHTX,   SDL_CONTROLLER_AXIS_RIGHTY,   SDL_CONTROLLER_AXIS_TRIGGERLEFT,   SDL_CONTROLLER_AXIS_TRIGGERRIGHT,   SDL_CONTROLLER_AXIS_MAX }
enum	SDL_GameControllerButton {   SDL_CONTROLLER_BUTTON_INVALID = -1,   SDL_CONTROLLER_BUTTON_A,   SDL_CONTROLLER_BUTTON_B,   SDL_CONTROLLER_BUTTON_X,   SDL_CONTROLLER_BUTTON_Y,   SDL_CONTROLLER_BUTTON_BACK,   SDL_CONTROLLER_BUTTON_GUIDE,   SDL_CONTROLLER_BUTTON_START,   SDL_CONTROLLER_BUTTON_LEFTSTICK,   SDL_CONTROLLER_BUTTON_RIGHTSTICK,   SDL_CONTROLLER_BUTTON_LEFTSHOULDER,   SDL_CONTROLLER_BUTTON_RIGHTSHOULDER,   SDL_CONTROLLER_BUTTON_DPAD_UP,   SDL_CONTROLLER_BUTTON_DPAD_DOWN,   SDL_CONTROLLER_BUTTON_DPAD_LEFT,   SDL_CONTROLLER_BUTTON_DPAD_RIGHT,   SDL_CONTROLLER_BUTTON_MAX }

Functions
int	SDL_GameControllerAddMappingsFromRW (SDL_RWops *rw, int freerw)
int	SDL_GameControllerAddMapping (const char *mappingString)
int	SDL_GameControllerNumMappings (void)
char *	SDL_GameControllerMappingForIndex (int mapping_index)
char *	SDL_GameControllerMappingForGUID (SDL_JoystickGUID guid)
char *	SDL_GameControllerMapping (SDL_GameController *gamecontroller)
SDL_bool	SDL_IsGameController (int joystick_index)
const char *	SDL_GameControllerNameForIndex (int joystick_index)
char *	SDL_GameControllerMappingForDeviceIndex (int joystick_index)
SDL_GameController *	SDL_GameControllerOpen (int joystick_index)
SDL_GameController *	SDL_GameControllerFromInstanceID (SDL_JoystickID joyid)
const char *	SDL_GameControllerName (SDL_GameController *gamecontroller)
int	SDL_GameControllerGetPlayerIndex (SDL_GameController *gamecontroller)
Uint16	SDL_GameControllerGetVendor (SDL_GameController *gamecontroller)
Uint16	SDL_GameControllerGetProduct (SDL_GameController *gamecontroller)
Uint16	SDL_GameControllerGetProductVersion (SDL_GameController *gamecontroller)
SDL_bool	SDL_GameControllerGetAttached (SDL_GameController *gamecontroller)
SDL_Joystick *	SDL_GameControllerGetJoystick (SDL_GameController *gamecontroller)
int	SDL_GameControllerEventState (int state)
void	SDL_GameControllerUpdate (void)
SDL_GameControllerAxis	SDL_GameControllerGetAxisFromString (const char *pchString)
const char *	SDL_GameControllerGetStringForAxis (SDL_GameControllerAxis axis)
SDL_GameControllerButtonBind	SDL_GameControllerGetBindForAxis (SDL_GameController *gamecontroller, SDL_GameControllerAxis axis)
Sint16	SDL_GameControllerGetAxis (SDL_GameController *gamecontroller, SDL_GameControllerAxis axis)
SDL_GameControllerButton	SDL_GameControllerGetButtonFromString (const char *pchString)
const char *	SDL_GameControllerGetStringForButton (SDL_GameControllerButton button)
SDL_GameControllerButtonBind	SDL_GameControllerGetBindForButton (SDL_GameController *gamecontroller, SDL_GameControllerButton button)
Uint8	SDL_GameControllerGetButton (SDL_GameController *gamecontroller, SDL_GameControllerButton button)
int	SDL_GameControllerRumble (SDL_GameController *gamecontroller, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms)
void	SDL_GameControllerClose (SDL_GameController *gamecontroller)

Detailed Description

Include file for SDL game controller event handling

In order to use these functions, SDL_Init() must have been called with the SDL_INIT_GAMECONTROLLER flag. This causes SDL to scan the system for game controllers, and load appropriate drivers.

If you would like to receive controller updates while the application is in the background, you should set the following hint before calling SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS

Definition in file SDL_gamecontroller.h.

Macro Definition Documentation

#define SDL_GameControllerAddMappingsFromFile

(

file

)

SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)

Load a set of mappings from a file, filtered by the current SDL_GetPlatform()

Convenience macro.

Definition at line 129 of file SDL_gamecontroller.h.

Referenced by main(), and SDL_GameControllerInitMappings().

Enumeration Type Documentation

enum SDL_GameControllerAxis

The list of axes available from a controller

Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though advanced UI will allow users to set or autodetect the dead zone, which varies between controllers.

Trigger axis values range from 0 to SDL_JOYSTICK_AXIS_MAX.

Enumerator:

SDL_CONTROLLER_AXIS_INVALID
SDL_CONTROLLER_AXIS_LEFTX
SDL_CONTROLLER_AXIS_LEFTY
SDL_CONTROLLER_AXIS_RIGHTX
SDL_CONTROLLER_AXIS_RIGHTY
SDL_CONTROLLER_AXIS_TRIGGERLEFT
SDL_CONTROLLER_AXIS_TRIGGERRIGHT
SDL_CONTROLLER_AXIS_MAX

Definition at line 272 of file SDL_gamecontroller.h.

{
    SDL_CONTROLLER_AXIS_INVALID = -1,
    SDL_CONTROLLER_AXIS_LEFTX,
    SDL_CONTROLLER_AXIS_LEFTY,
    SDL_CONTROLLER_AXIS_RIGHTX,
    SDL_CONTROLLER_AXIS_RIGHTY,
    SDL_CONTROLLER_AXIS_TRIGGERLEFT,
    SDL_CONTROLLER_AXIS_TRIGGERRIGHT,
    SDL_CONTROLLER_AXIS_MAX
} SDL_GameControllerAxis;

enum SDL_GameControllerBindType

Enumerator:

SDL_CONTROLLER_BINDTYPE_NONE
SDL_CONTROLLER_BINDTYPE_BUTTON
SDL_CONTROLLER_BINDTYPE_AXIS
SDL_CONTROLLER_BINDTYPE_HAT

Definition at line 61 of file SDL_gamecontroller.h.

{
    SDL_CONTROLLER_BINDTYPE_NONE = 0,
    SDL_CONTROLLER_BINDTYPE_BUTTON,
    SDL_CONTROLLER_BINDTYPE_AXIS,
    SDL_CONTROLLER_BINDTYPE_HAT
} SDL_GameControllerBindType;

enum SDL_GameControllerButton

The list of buttons available from a controller

Enumerator:

SDL_CONTROLLER_BUTTON_INVALID
SDL_CONTROLLER_BUTTON_A
SDL_CONTROLLER_BUTTON_B
SDL_CONTROLLER_BUTTON_X
SDL_CONTROLLER_BUTTON_Y
SDL_CONTROLLER_BUTTON_BACK
SDL_CONTROLLER_BUTTON_GUIDE
SDL_CONTROLLER_BUTTON_START
SDL_CONTROLLER_BUTTON_LEFTSTICK
SDL_CONTROLLER_BUTTON_RIGHTSTICK
SDL_CONTROLLER_BUTTON_LEFTSHOULDER
SDL_CONTROLLER_BUTTON_RIGHTSHOULDER
SDL_CONTROLLER_BUTTON_DPAD_UP
SDL_CONTROLLER_BUTTON_DPAD_DOWN
SDL_CONTROLLER_BUTTON_DPAD_LEFT
SDL_CONTROLLER_BUTTON_DPAD_RIGHT
SDL_CONTROLLER_BUTTON_MAX

Definition at line 316 of file SDL_gamecontroller.h.

{
    SDL_CONTROLLER_BUTTON_INVALID = -1,
    SDL_CONTROLLER_BUTTON_A,
    SDL_CONTROLLER_BUTTON_B,
    SDL_CONTROLLER_BUTTON_X,
    SDL_CONTROLLER_BUTTON_Y,
    SDL_CONTROLLER_BUTTON_BACK,
    SDL_CONTROLLER_BUTTON_GUIDE,
    SDL_CONTROLLER_BUTTON_START,
    SDL_CONTROLLER_BUTTON_LEFTSTICK,
    SDL_CONTROLLER_BUTTON_RIGHTSTICK,
    SDL_CONTROLLER_BUTTON_LEFTSHOULDER,
    SDL_CONTROLLER_BUTTON_RIGHTSHOULDER,
    SDL_CONTROLLER_BUTTON_DPAD_UP,
    SDL_CONTROLLER_BUTTON_DPAD_DOWN,
    SDL_CONTROLLER_BUTTON_DPAD_LEFT,
    SDL_CONTROLLER_BUTTON_DPAD_RIGHT,
    SDL_CONTROLLER_BUTTON_MAX
} SDL_GameControllerButton;

Function Documentation

int SDL_GameControllerAddMapping

(

const char *

mappingString

)

Add or update an existing mapping configuration

Returns

1 if mapping is added, 0 if updated, -1 on error

Definition at line 1186 of file SDL_gamecontroller.c.

References SDL_CONTROLLER_MAPPING_PRIORITY_API, and SDL_PrivateGameControllerAddMapping().

{
    return SDL_PrivateGameControllerAddMapping(mappingString, SDL_CONTROLLER_MAPPING_PRIORITY_API);
}

int SDL_GameControllerAddMappingsFromRW	(	SDL_RWops *	rw,
		int	freerw
	)

To count the number of game controllers in the system for the following: int nJoysticks = SDL_NumJoysticks(); int nGameControllers = 0; for (int i = 0; i < nJoysticks; i++) { if (SDL_IsGameController(i)) { nGameControllers++; } }

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: guid,name,mappings

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. Under Windows there is a reserved GUID of "xinput" that covers any XInput devices. The mapping format for joystick is: bX - a joystick button, index X hX.Y - hat X with value Y aX - axis X of the joystick Buttons can be used as a controller axis and vice versa.

This string shows an example of a valid mapping for a controller "03000000341a00003608000000000000,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", Load a set of mappings from a seekable SDL data stream (memory or file), filtered by the current SDL_GetPlatform() A community sourced database of controllers is available at https://raw.github.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt

If freerw is non-zero, the stream will be closed after being read.

Returns

number of mappings added, -1 on error

Definition at line 1064 of file SDL_gamecontroller.c.

References sort_controllers::controllers, NULL, SDL_arraysize, SDL_CONTROLLER_PLATFORM_FIELD, SDL_free, SDL_GameControllerAddMapping, SDL_GetPlatform, SDL_malloc, SDL_RWclose, SDL_RWread, SDL_RWsize, SDL_SetError, SDL_strchr, SDL_strlcpy, SDL_strlen, SDL_strncasecmp, and SDL_strstr.

{
    const char *platform = SDL_GetPlatform();
    int controllers = 0;
    char *buf, *line, *line_end, *tmp, *comma, line_platform[64];
    size_t db_size, platform_len;
    
    if (rw == NULL) {
        return SDL_SetError("Invalid RWops");
    }
    db_size = (size_t)SDL_RWsize(rw);
    
    buf = (char *)SDL_malloc(db_size + 1);
    if (buf == NULL) {
        if (freerw) {
            SDL_RWclose(rw);
        }
        return SDL_SetError("Could not allocate space to read DB into memory");
    }
    
    if (SDL_RWread(rw, buf, db_size, 1) != 1) {
        if (freerw) {
            SDL_RWclose(rw);
        }
        SDL_free(buf);
        return SDL_SetError("Could not read DB");
    }
    
    if (freerw) {
        SDL_RWclose(rw);
    }
    
    buf[db_size] = '\0';
    line = buf;
    
    while (line < buf + db_size) {
        line_end = SDL_strchr(line, '\n');
        if (line_end != NULL) {
            *line_end = '\0';
        } else {
            line_end = buf + db_size;
        }
        
        /* Extract and verify the platform */
        tmp = SDL_strstr(line, SDL_CONTROLLER_PLATFORM_FIELD);
        if (tmp != NULL) {
            tmp += SDL_strlen(SDL_CONTROLLER_PLATFORM_FIELD);
            comma = SDL_strchr(tmp, ',');
            if (comma != NULL) {
                platform_len = comma - tmp + 1;
                if (platform_len + 1 < SDL_arraysize(line_platform)) {
                    SDL_strlcpy(line_platform, tmp, platform_len);
                    if (SDL_strncasecmp(line_platform, platform, platform_len) == 0 &&
                        SDL_GameControllerAddMapping(line) > 0) {
                        controllers++;
                    }
                }
            }
        }
        
        line = line_end + 1;
    }

    SDL_free(buf);
    return controllers;
}

void SDL_GameControllerClose

(

SDL_GameController *

gamecontroller

)

Close a controller previously opened with SDL_GameControllerOpen().

Definition at line 1860 of file SDL_gamecontroller.c.

References NULL, SDL_free, SDL_gamecontrollers, SDL_JoystickClose, SDL_LockJoysticks, and SDL_UnlockJoysticks.

{
    SDL_GameController *gamecontrollerlist, *gamecontrollerlistprev;

    if (!gamecontroller)
        return;

    SDL_LockJoysticks();

    /* First decrement ref count */
    if (--gamecontroller->ref_count > 0) {
        SDL_UnlockJoysticks();
        return;
    }

    SDL_JoystickClose(gamecontroller->joystick);

    gamecontrollerlist = SDL_gamecontrollers;
    gamecontrollerlistprev = NULL;
    while (gamecontrollerlist) {
        if (gamecontroller == gamecontrollerlist) {
            if (gamecontrollerlistprev) {
                /* unlink this entry */
                gamecontrollerlistprev->next = gamecontrollerlist->next;
            } else {
                SDL_gamecontrollers = gamecontroller->next;
            }
            break;
        }
        gamecontrollerlistprev = gamecontrollerlist;
        gamecontrollerlist = gamecontrollerlist->next;
    }

    SDL_free(gamecontroller->bindings);
    SDL_free(gamecontroller->last_match_axis);
    SDL_free(gamecontroller->last_hat_mask);
    SDL_free(gamecontroller);

    SDL_UnlockJoysticks();
}

int SDL_GameControllerEventState

(

int

state

)

Enable/disable controller event polling.

If controller events are disabled, you must call SDL_GameControllerUpdate() yourself and check the state of the controller when you want controller information.

The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE.

Definition at line 2031 of file SDL_gamecontroller.c.

References i, SDL_arraysize, SDL_CONTROLLERAXISMOTION, SDL_CONTROLLERBUTTONDOWN, SDL_CONTROLLERBUTTONUP, SDL_CONTROLLERDEVICEADDED, SDL_CONTROLLERDEVICEREMAPPED, SDL_CONTROLLERDEVICEREMOVED, SDL_ENABLE, SDL_EventState, SDL_IGNORE, and SDL_QUERY.

{
#if SDL_EVENTS_DISABLED
    return SDL_IGNORE;
#else
    const Uint32 event_list[] = {
        SDL_CONTROLLERAXISMOTION, SDL_CONTROLLERBUTTONDOWN, SDL_CONTROLLERBUTTONUP,
        SDL_CONTROLLERDEVICEADDED, SDL_CONTROLLERDEVICEREMOVED, SDL_CONTROLLERDEVICEREMAPPED,
    };
    unsigned int i;

    switch (state) {
    case SDL_QUERY:
        state = SDL_IGNORE;
        for (i = 0; i < SDL_arraysize(event_list); ++i) {
            state = SDL_EventState(event_list[i], SDL_QUERY);
            if (state == SDL_ENABLE) {
                break;
            }
        }
        break;
    default:
        for (i = 0; i < SDL_arraysize(event_list); ++i) {
            SDL_EventState(event_list[i], state);
        }
        break;
    }
    return (state);
#endif /* SDL_EVENTS_DISABLED */
}

SDL_GameController* SDL_GameControllerFromInstanceID

(

SDL_JoystickID

joyid

)

Return the SDL_GameController associated with an instance id.

Definition at line 1772 of file SDL_gamecontroller.c.

References NULL, SDL_gamecontrollers, SDL_LockJoysticks, and SDL_UnlockJoysticks.

{
    SDL_GameController *gamecontroller;

    SDL_LockJoysticks();
    gamecontroller = SDL_gamecontrollers;
    while (gamecontroller) {
        if (gamecontroller->joystick->instance_id == joyid) {
            SDL_UnlockJoysticks();
            return gamecontroller;
        }
        gamecontroller = gamecontroller->next;
    }
    SDL_UnlockJoysticks();
    return NULL;
}

SDL_bool SDL_GameControllerGetAttached

(

SDL_GameController *

gamecontroller

)

Returns SDL_TRUE if the controller has been opened and currently connected, or SDL_FALSE if it has not.

Definition at line 1748 of file SDL_gamecontroller.c.

References SDL_FALSE, and SDL_JoystickGetAttached.

{
    if (!gamecontroller)
        return SDL_FALSE;

    return SDL_JoystickGetAttached(gamecontroller->joystick);
}

Sint16 SDL_GameControllerGetAxis	(	SDL_GameController *	gamecontroller,
		SDL_GameControllerAxis	axis
	)

Get the current state of an axis control on a game controller.

The state is a value ranging from -32768 to 32767 (except for the triggers, which range from 0 to 32767).

The axis indices start at index 0.

Definition at line 1612 of file SDL_gamecontroller.c.

References SDL_ExtendedGameControllerBind::axis, SDL_ExtendedGameControllerBind::button, SDL_ExtendedGameControllerBind::hat, i, SDL_ExtendedGameControllerBind::input, SDL_ExtendedGameControllerBind::inputType, SDL_ExtendedGameControllerBind::output, SDL_ExtendedGameControllerBind::outputType, SDL_CONTROLLER_BINDTYPE_AXIS, SDL_CONTROLLER_BINDTYPE_BUTTON, SDL_CONTROLLER_BINDTYPE_HAT, SDL_JoystickGetAxis, SDL_JoystickGetButton, SDL_JoystickGetHat, and SDL_PRESSED.

{
    int i;

    if (!gamecontroller)
        return 0;

    for (i = 0; i < gamecontroller->num_bindings; ++i) {
        SDL_ExtendedGameControllerBind *binding = &gamecontroller->bindings[i];
        if (binding->outputType == SDL_CONTROLLER_BINDTYPE_AXIS && binding->output.axis.axis == axis) {
            int value = 0;
            SDL_bool valid_input_range;
            SDL_bool valid_output_range;

            if (binding->inputType == SDL_CONTROLLER_BINDTYPE_AXIS) {
                value = SDL_JoystickGetAxis(gamecontroller->joystick, binding->input.axis.axis);
                if (binding->input.axis.axis_min < binding->input.axis.axis_max) {
                    valid_input_range = (value >= binding->input.axis.axis_min && value <= binding->input.axis.axis_max);
                } else {
                    valid_input_range = (value >= binding->input.axis.axis_max && value <= binding->input.axis.axis_min);
                }
                if (valid_input_range) {
                    if (binding->input.axis.axis_min != binding->output.axis.axis_min || binding->input.axis.axis_max != binding->output.axis.axis_max) {
                        float normalized_value = (float)(value - binding->input.axis.axis_min) / (binding->input.axis.axis_max - binding->input.axis.axis_min);
                        value = binding->output.axis.axis_min + (int)(normalized_value * (binding->output.axis.axis_max - binding->output.axis.axis_min));
                    }
                }
            } else if (binding->inputType == SDL_CONTROLLER_BINDTYPE_BUTTON) {
                value = SDL_JoystickGetButton(gamecontroller->joystick, binding->input.button);
                if (value == SDL_PRESSED) {
                    value = binding->output.axis.axis_max;
                }
            } else if (binding->inputType == SDL_CONTROLLER_BINDTYPE_HAT) {
                int hat_mask = SDL_JoystickGetHat(gamecontroller->joystick, binding->input.hat.hat);
                if (hat_mask & binding->input.hat.hat_mask) {
                    value = binding->output.axis.axis_max;
                }
            }

            if (binding->output.axis.axis_min < binding->output.axis.axis_max) {
                valid_output_range = (value >= binding->output.axis.axis_min && value <= binding->output.axis.axis_max);
            } else {
                valid_output_range = (value >= binding->output.axis.axis_max && value <= binding->output.axis.axis_min);
            }
            /* If the value is zero, there might be another binding that makes it non-zero */
            if (value != 0 && valid_output_range) {
                return (Sint16)value;
            }
        }
    }
    return 0;
}

SDL_GameControllerAxis SDL_GameControllerGetAxisFromString

(

const char *

pchString

)

turn this string into a axis mapping

Definition at line 461 of file SDL_gamecontroller.c.

References map_StringForControllerAxis, SDL_CONTROLLER_AXIS_INVALID, and SDL_strcasecmp.

{
    int entry;

    if (pchString && (*pchString == '+' || *pchString == '-')) {
        ++pchString;
    }

    if (!pchString || !pchString[0]) {
        return SDL_CONTROLLER_AXIS_INVALID;
    }

    for (entry = 0; map_StringForControllerAxis[entry]; ++entry) {
        if (!SDL_strcasecmp(pchString, map_StringForControllerAxis[entry]))
            return (SDL_GameControllerAxis) entry;
    }
    return SDL_CONTROLLER_AXIS_INVALID;
}

SDL_GameControllerButtonBind SDL_GameControllerGetBindForAxis	(	SDL_GameController *	gamecontroller,
		SDL_GameControllerAxis	axis
	)

Get the SDL joystick layer binding for this controller button mapping

Definition at line 1793 of file SDL_gamecontroller.c.

References SDL_ExtendedGameControllerBind::axis, SDL_GameControllerButtonBind::axis, SDL_GameControllerButtonBind::bindType, SDL_ExtendedGameControllerBind::button, SDL_GameControllerButtonBind::button, SDL_ExtendedGameControllerBind::hat, SDL_GameControllerButtonBind::hat, i, SDL_ExtendedGameControllerBind::input, SDL_ExtendedGameControllerBind::inputType, SDL_ExtendedGameControllerBind::output, SDL_ExtendedGameControllerBind::outputType, SDL_CONTROLLER_AXIS_INVALID, SDL_CONTROLLER_BINDTYPE_AXIS, SDL_CONTROLLER_BINDTYPE_BUTTON, SDL_CONTROLLER_BINDTYPE_HAT, SDL_zero, and SDL_GameControllerButtonBind::value.

{
    int i;
    SDL_GameControllerButtonBind bind;
    SDL_zero(bind);

    if (!gamecontroller || axis == SDL_CONTROLLER_AXIS_INVALID)
        return bind;

    for (i = 0; i < gamecontroller->num_bindings; ++i) {
        SDL_ExtendedGameControllerBind *binding = &gamecontroller->bindings[i];
        if (binding->outputType == SDL_CONTROLLER_BINDTYPE_AXIS && binding->output.axis.axis == axis) {
            bind.bindType = binding->inputType;
            if (binding->inputType == SDL_CONTROLLER_BINDTYPE_AXIS) {
                /* FIXME: There might be multiple axes bound now that we have axis ranges... */
                bind.value.axis = binding->input.axis.axis;
            } else if (binding->inputType == SDL_CONTROLLER_BINDTYPE_BUTTON) {
                bind.value.button = binding->input.button;
            } else if (binding->inputType == SDL_CONTROLLER_BINDTYPE_HAT) {
                bind.value.hat.hat = binding->input.hat.hat;
                bind.value.hat.hat_mask = binding->input.hat.hat_mask;
            }
            break;
        }
    }
    return bind;
}

SDL_GameControllerButtonBind SDL_GameControllerGetBindForButton	(	SDL_GameController *	gamecontroller,
		SDL_GameControllerButton	button
	)

Get the SDL joystick layer binding for this controller button mapping

Definition at line 1825 of file SDL_gamecontroller.c.

References SDL_ExtendedGameControllerBind::axis, SDL_GameControllerButtonBind::axis, SDL_GameControllerButtonBind::bindType, SDL_ExtendedGameControllerBind::button, SDL_GameControllerButtonBind::button, SDL_ExtendedGameControllerBind::hat, SDL_GameControllerButtonBind::hat, i, SDL_ExtendedGameControllerBind::input, SDL_ExtendedGameControllerBind::inputType, SDL_ExtendedGameControllerBind::output, SDL_ExtendedGameControllerBind::outputType, SDL_CONTROLLER_BINDTYPE_AXIS, SDL_CONTROLLER_BINDTYPE_BUTTON, SDL_CONTROLLER_BINDTYPE_HAT, SDL_CONTROLLER_BUTTON_INVALID, SDL_zero, and SDL_GameControllerButtonBind::value.

{
    int i;
    SDL_GameControllerButtonBind bind;
    SDL_zero(bind);

    if (!gamecontroller || button == SDL_CONTROLLER_BUTTON_INVALID)
        return bind;

    for (i = 0; i < gamecontroller->num_bindings; ++i) {
        SDL_ExtendedGameControllerBind *binding = &gamecontroller->bindings[i];
        if (binding->outputType == SDL_CONTROLLER_BINDTYPE_BUTTON && binding->output.button == button) {
            bind.bindType = binding->inputType;
            if (binding->inputType == SDL_CONTROLLER_BINDTYPE_AXIS) {
                bind.value.axis = binding->input.axis.axis;
            } else if (binding->inputType == SDL_CONTROLLER_BINDTYPE_BUTTON) {
                bind.value.button = binding->input.button;
            } else if (binding->inputType == SDL_CONTROLLER_BINDTYPE_HAT) {
                bind.value.hat.hat = binding->input.hat.hat;
                bind.value.hat.hat_mask = binding->input.hat.hat_mask;
            }
            break;
        }
    }
    return bind;
}

Uint8 SDL_GameControllerGetButton	(	SDL_GameController *	gamecontroller,
		SDL_GameControllerButton	button
	)

Get the current state of a button on a game controller.

The button indices start at index 0.

Definition at line 1669 of file SDL_gamecontroller.c.

References SDL_ExtendedGameControllerBind::axis, SDL_ExtendedGameControllerBind::button, SDL_ExtendedGameControllerBind::hat, i, SDL_ExtendedGameControllerBind::input, SDL_ExtendedGameControllerBind::inputType, SDL_ExtendedGameControllerBind::output, SDL_ExtendedGameControllerBind::outputType, SDL_CONTROLLER_BINDTYPE_AXIS, SDL_CONTROLLER_BINDTYPE_BUTTON, SDL_CONTROLLER_BINDTYPE_HAT, SDL_JoystickGetAxis, SDL_JoystickGetButton, SDL_JoystickGetHat, SDL_PRESSED, and SDL_RELEASED.

{
    int i;

    if (!gamecontroller)
        return 0;

    for (i = 0; i < gamecontroller->num_bindings; ++i) {
        SDL_ExtendedGameControllerBind *binding = &gamecontroller->bindings[i];
        if (binding->outputType == SDL_CONTROLLER_BINDTYPE_BUTTON && binding->output.button == button) {
            if (binding->inputType == SDL_CONTROLLER_BINDTYPE_AXIS) {
                SDL_bool valid_input_range;

                int value = SDL_JoystickGetAxis(gamecontroller->joystick, binding->input.axis.axis);
                int threshold = binding->input.axis.axis_min + (binding->input.axis.axis_max - binding->input.axis.axis_min) / 2;
                if (binding->input.axis.axis_min < binding->input.axis.axis_max) {
                    valid_input_range = (value >= binding->input.axis.axis_min && value <= binding->input.axis.axis_max);
                    if (valid_input_range) {
                        return (value >= threshold) ? SDL_PRESSED : SDL_RELEASED;
                    }
                } else {
                    valid_input_range = (value >= binding->input.axis.axis_max && value <= binding->input.axis.axis_min);
                    if (valid_input_range) {
                        return (value <= threshold) ? SDL_PRESSED : SDL_RELEASED;
                    }
                }
            } else if (binding->inputType == SDL_CONTROLLER_BINDTYPE_BUTTON) {
                return SDL_JoystickGetButton(gamecontroller->joystick, binding->input.button);
            } else if (binding->inputType == SDL_CONTROLLER_BINDTYPE_HAT) {
                int hat_mask = SDL_JoystickGetHat(gamecontroller->joystick, binding->input.hat.hat);
                return (hat_mask & binding->input.hat.hat_mask) ? SDL_PRESSED : SDL_RELEASED;
            }
        }
    }
    return SDL_RELEASED;
}

SDL_GameControllerButton SDL_GameControllerGetButtonFromString

(

const char *

pchString

)

turn this string into a button mapping

Definition at line 513 of file SDL_gamecontroller.c.

References map_StringForControllerButton, SDL_CONTROLLER_BUTTON_INVALID, and SDL_strcasecmp.

{
    int entry;
    if (!pchString || !pchString[0])
        return SDL_CONTROLLER_BUTTON_INVALID;

    for (entry = 0; map_StringForControllerButton[entry]; ++entry) {
        if (SDL_strcasecmp(pchString, map_StringForControllerButton[entry]) == 0)
            return (SDL_GameControllerButton) entry;
    }
    return SDL_CONTROLLER_BUTTON_INVALID;
}

SDL_Joystick* SDL_GameControllerGetJoystick

(

SDL_GameController *

gamecontroller

)

Get the underlying joystick object used by a controller

Definition at line 1759 of file SDL_gamecontroller.c.

References NULL.

{
    if (!gamecontroller)
        return NULL;

    return gamecontroller->joystick;
}

int SDL_GameControllerGetPlayerIndex

(

SDL_GameController *

gamecontroller

)

Get the player index of an opened game controller, or -1 if it's not available

For XInput controllers this returns the XInput user index.

Definition at line 1720 of file SDL_gamecontroller.c.

References SDL_GameControllerGetJoystick, and SDL_JoystickGetPlayerIndex.

{
    return SDL_JoystickGetPlayerIndex(SDL_GameControllerGetJoystick(gamecontroller));
}

Uint16 SDL_GameControllerGetProduct

(

SDL_GameController *

gamecontroller

)

Get the USB product ID of an opened controller, if available. If the product ID isn't available this function returns 0.

Definition at line 1732 of file SDL_gamecontroller.c.

References SDL_GameControllerGetJoystick, and SDL_JoystickGetProduct.

{
    return SDL_JoystickGetProduct(SDL_GameControllerGetJoystick(gamecontroller));
}

Uint16 SDL_GameControllerGetProductVersion

(

SDL_GameController *

gamecontroller

)

Get the product version of an opened controller, if available. If the product version isn't available this function returns 0.

Definition at line 1738 of file SDL_gamecontroller.c.

References SDL_GameControllerGetJoystick, and SDL_JoystickGetProductVersion.

{
    return SDL_JoystickGetProductVersion(SDL_GameControllerGetJoystick(gamecontroller));
}

const char* SDL_GameControllerGetStringForAxis

(

SDL_GameControllerAxis

axis

)

turn this axis enum into a string mapping

Definition at line 483 of file SDL_gamecontroller.c.

References axis, map_StringForControllerAxis, NULL, SDL_CONTROLLER_AXIS_INVALID, and SDL_CONTROLLER_AXIS_MAX.

{
    if (axis > SDL_CONTROLLER_AXIS_INVALID && axis < SDL_CONTROLLER_AXIS_MAX) {
        return map_StringForControllerAxis[axis];
    }
    return NULL;
}

const char* SDL_GameControllerGetStringForButton

(

SDL_GameControllerButton

button

)

turn this button enum into a string mapping

Definition at line 529 of file SDL_gamecontroller.c.

References axis, map_StringForControllerButton, NULL, SDL_CONTROLLER_BUTTON_INVALID, and SDL_CONTROLLER_BUTTON_MAX.

{
    if (axis > SDL_CONTROLLER_BUTTON_INVALID && axis < SDL_CONTROLLER_BUTTON_MAX) {
        return map_StringForControllerButton[axis];
    }
    return NULL;
}

Uint16 SDL_GameControllerGetVendor

(

SDL_GameController *

gamecontroller

)

Get the USB vendor ID of an opened controller, if available. If the vendor ID isn't available this function returns 0.

Definition at line 1726 of file SDL_gamecontroller.c.

References SDL_GameControllerGetJoystick, and SDL_JoystickGetVendor.

{
    return SDL_JoystickGetVendor(SDL_GameControllerGetJoystick(gamecontroller));
}

char* SDL_GameControllerMapping

(

SDL_GameController *

gamecontroller

)

Get a mapping string for an open GameController

Returns

the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available

Definition at line 1270 of file SDL_gamecontroller.c.

References NULL, and SDL_GameControllerMappingForGUID.

{
    if (!gamecontroller) {
        return NULL;
    }

    return SDL_GameControllerMappingForGUID(gamecontroller->joystick->guid);
}

char* SDL_GameControllerMappingForDeviceIndex

(

int

joystick_index

)

Get the mapping of a game controller. This can be called before any controllers are opened.

Returns

the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available

Get the mapping of a game controller. This can be called before any controllers are opened. If no mapping can be found, this function returns NULL.

Definition at line 1403 of file SDL_gamecontroller.c.

References ControllerMapping_t::mapping, ControllerMapping_t::name, NULL, SDL_JoystickGetDeviceGUID, SDL_JoystickGetGUIDString, SDL_LockJoysticks, SDL_malloc, SDL_OutOfMemory, SDL_PrivateGetControllerMapping(), SDL_snprintf, SDL_strlen, and SDL_UnlockJoysticks.

{
    char *pMappingString = NULL;
    ControllerMapping_t *mapping;

    SDL_LockJoysticks();
    mapping = SDL_PrivateGetControllerMapping(joystick_index);
    if (mapping) {
        SDL_JoystickGUID guid;
        char pchGUID[33];
        size_t needed;
        guid = SDL_JoystickGetDeviceGUID(joystick_index);
        SDL_JoystickGetGUIDString(guid, pchGUID, sizeof(pchGUID));
        /* allocate enough memory for GUID + ',' + name + ',' + mapping + \0 */
        needed = SDL_strlen(pchGUID) + 1 + SDL_strlen(mapping->name) + 1 + SDL_strlen(mapping->mapping) + 1;
        pMappingString = SDL_malloc(needed);
        if (!pMappingString) {
            SDL_OutOfMemory();
            SDL_UnlockJoysticks();
            return NULL;
        }
        SDL_snprintf(pMappingString, needed, "%s,%s,%s", pchGUID, mapping->name, mapping->mapping);
    }
    SDL_UnlockJoysticks();
    return pMappingString;
}

char* SDL_GameControllerMappingForGUID

(

SDL_JoystickGUID

guid

)

Get a mapping string for a GUID

Returns

the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available

Definition at line 1246 of file SDL_gamecontroller.c.

References ControllerMapping_t::mapping, ControllerMapping_t::name, NULL, SDL_FALSE, SDL_JoystickGetGUIDString, SDL_malloc, SDL_OutOfMemory, SDL_PrivateGetControllerMappingForGUID(), SDL_snprintf, and SDL_strlen.

{
    char *pMappingString = NULL;
    ControllerMapping_t *mapping = SDL_PrivateGetControllerMappingForGUID(&guid, SDL_FALSE);
    if (mapping) {
        char pchGUID[33];
        size_t needed;
        SDL_JoystickGetGUIDString(guid, pchGUID, sizeof(pchGUID));
        /* allocate enough memory for GUID + ',' + name + ',' + mapping + \0 */
        needed = SDL_strlen(pchGUID) + 1 + SDL_strlen(mapping->name) + 1 + SDL_strlen(mapping->mapping) + 1;
        pMappingString = SDL_malloc(needed);
        if (!pMappingString) {
            SDL_OutOfMemory();
            return NULL;
        }
        SDL_snprintf(pMappingString, needed, "%s,%s,%s", pchGUID, mapping->name, mapping->mapping);
    }
    return pMappingString;
}

char* SDL_GameControllerMappingForIndex

(

int

mapping_index

)

Get the mapping at a particular index.

Returns

the mapping string. Must be freed with SDL_free(). Returns NULL if the index is out of range.

Definition at line 1213 of file SDL_gamecontroller.c.

References ControllerMapping_t::guid, ControllerMapping_t::mapping, ControllerMapping_t::name, ControllerMapping_t::next, NULL, SDL_JoystickGetGUIDString, SDL_malloc, SDL_memcmp, SDL_OutOfMemory, SDL_snprintf, and SDL_strlen.

{
    ControllerMapping_t *mapping;

    for (mapping = s_pSupportedControllers; mapping; mapping = mapping->next) {
        if (SDL_memcmp(&mapping->guid, &s_zeroGUID, sizeof(mapping->guid)) == 0) {
            continue;
        }
        if (mapping_index == 0) {
            char *pMappingString;
            char pchGUID[33];
            size_t needed;

            SDL_JoystickGetGUIDString(mapping->guid, pchGUID, sizeof(pchGUID));
            /* allocate enough memory for GUID + ',' + name + ',' + mapping + \0 */
            needed = SDL_strlen(pchGUID) + 1 + SDL_strlen(mapping->name) + 1 + SDL_strlen(mapping->mapping) + 1;
            pMappingString = SDL_malloc(needed);
            if (!pMappingString) {
                SDL_OutOfMemory();
                return NULL;
            }
            SDL_snprintf(pMappingString, needed, "%s,%s,%s", pchGUID, mapping->name, mapping->mapping);
            return pMappingString;
        }
        --mapping_index;
    }
    return NULL;
}

const char* SDL_GameControllerName

(

SDL_GameController *

gamecontroller

)

Return the name for this currently opened controller

Definition at line 1707 of file SDL_gamecontroller.c.

References NULL, SDL_GameControllerGetJoystick, SDL_JoystickName, and SDL_strcmp.

{
    if (!gamecontroller)
        return NULL;

    if (SDL_strcmp(gamecontroller->name, "*") == 0) {
        return SDL_JoystickName(SDL_GameControllerGetJoystick(gamecontroller));
    } else {
        return gamecontroller->name;
    }
}

const char* SDL_GameControllerNameForIndex

(

int

joystick_index

)

Get the implementation dependent name of a game controller. This can be called before any controllers are opened. If no name can be found, this function returns NULL.

Definition at line 1383 of file SDL_gamecontroller.c.

References ControllerMapping_t::name, NULL, SDL_JoystickNameForIndex, SDL_PrivateGetControllerMapping(), and SDL_strcmp.

{
    ControllerMapping_t *pSupportedController = SDL_PrivateGetControllerMapping(device_index);
    if (pSupportedController) {
        if (SDL_strcmp(pSupportedController->name, "*") == 0) {
            return SDL_JoystickNameForIndex(device_index);
        } else {
            return pSupportedController->name;
        }
    }
    return NULL;
}

int SDL_GameControllerNumMappings

(

void

)

Get the number of mappings installed

Returns

the number of mappings

Definition at line 1195 of file SDL_gamecontroller.c.

References ControllerMapping_t::guid, ControllerMapping_t::next, and SDL_memcmp.

{
    int num_mappings = 0;
    ControllerMapping_t *mapping;

    for (mapping = s_pSupportedControllers; mapping; mapping = mapping->next) {
        if (SDL_memcmp(&mapping->guid, &s_zeroGUID, sizeof(mapping->guid)) == 0) {
            continue;
        }
        ++num_mappings;
    }
    return num_mappings;
}

SDL_GameController* SDL_GameControllerOpen

(

int

joystick_index

)

Open a game controller for use. The index passed as an argument refers to the N'th game controller on the system. This index is not the value which will identify this controller in future controller events. The joystick's instance id (SDL_JoystickID) will be used there instead.

Returns

A controller identifier, or NULL if an error occurred.

Definition at line 1518 of file SDL_gamecontroller.c.

References ControllerMapping_t::mapping, ControllerMapping_t::name, NULL, SDL_calloc, SDL_free, SDL_gamecontrollers, SDL_JoystickClose, SDL_JoystickGetDeviceInstanceID, SDL_JoystickOpen, SDL_LockJoysticks, SDL_OutOfMemory, SDL_PrivateGetControllerMapping(), SDL_PrivateLoadButtonMapping(), SDL_SetError, and SDL_UnlockJoysticks.

{
    SDL_JoystickID instance_id;
    SDL_GameController *gamecontroller;
    SDL_GameController *gamecontrollerlist;
    ControllerMapping_t *pSupportedController = NULL;

    SDL_LockJoysticks();

    gamecontrollerlist = SDL_gamecontrollers;
    /* If the controller is already open, return it */
    instance_id = SDL_JoystickGetDeviceInstanceID(device_index);
    while (gamecontrollerlist) {
        if (instance_id == gamecontrollerlist->joystick->instance_id) {
                gamecontroller = gamecontrollerlist;
                ++gamecontroller->ref_count;
                SDL_UnlockJoysticks();
                return (gamecontroller);
        }
        gamecontrollerlist = gamecontrollerlist->next;
    }

    /* Find a controller mapping */
    pSupportedController =  SDL_PrivateGetControllerMapping(device_index);
    if (!pSupportedController) {
        SDL_SetError("Couldn't find mapping for device (%d)", device_index);
        SDL_UnlockJoysticks();
        return NULL;
    }

    /* Create and initialize the controller */
    gamecontroller = (SDL_GameController *) SDL_calloc(1, sizeof(*gamecontroller));
    if (gamecontroller == NULL) {
        SDL_OutOfMemory();
        SDL_UnlockJoysticks();
        return NULL;
    }

    gamecontroller->joystick = SDL_JoystickOpen(device_index);
    if (!gamecontroller->joystick) {
        SDL_free(gamecontroller);
        SDL_UnlockJoysticks();
        return NULL;
    }

    if (gamecontroller->joystick->naxes) {
        gamecontroller->last_match_axis = (SDL_ExtendedGameControllerBind **)SDL_calloc(gamecontroller->joystick->naxes, sizeof(*gamecontroller->last_match_axis));
        if (!gamecontroller->last_match_axis) {
            SDL_OutOfMemory();
            SDL_JoystickClose(gamecontroller->joystick);
            SDL_free(gamecontroller);
            SDL_UnlockJoysticks();
            return NULL;
        }
    }
    if (gamecontroller->joystick->nhats) {
        gamecontroller->last_hat_mask = (Uint8 *)SDL_calloc(gamecontroller->joystick->nhats, sizeof(*gamecontroller->last_hat_mask));
        if (!gamecontroller->last_hat_mask) {
            SDL_OutOfMemory();
            SDL_JoystickClose(gamecontroller->joystick);
            SDL_free(gamecontroller->last_match_axis);
            SDL_free(gamecontroller);
            SDL_UnlockJoysticks();
            return NULL;
        }
    }

    SDL_PrivateLoadButtonMapping(gamecontroller, pSupportedController->name, pSupportedController->mapping);

    /* Add the controller to list */
    ++gamecontroller->ref_count;
    /* Link the controller in the list */
    gamecontroller->next = SDL_gamecontrollers;
    SDL_gamecontrollers = gamecontroller;

    SDL_UnlockJoysticks();

    return (gamecontroller);
}

int SDL_GameControllerRumble	(	SDL_GameController *	gamecontroller,
		Uint16	low_frequency_rumble,
		Uint16	high_frequency_rumble,
		Uint32	duration_ms
	)

Trigger a rumble effect Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.

Parameters

gamecontroller	The controller to vibrate
low_frequency_rumble	The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
high_frequency_rumble	The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
duration_ms	The duration of the rumble effect, in milliseconds

Returns

0, or -1 if rumble isn't supported on this joystick

Definition at line 1854 of file SDL_gamecontroller.c.

References SDL_GameControllerGetJoystick, and SDL_JoystickRumble.

{
    return SDL_JoystickRumble(SDL_GameControllerGetJoystick(gamecontroller), low_frequency_rumble, high_frequency_rumble, duration_ms);
}

void SDL_GameControllerUpdate

(

void

)

Update the current state of the open game controllers.

This is called automatically by the event loop if any game controller events are enabled.

Definition at line 1602 of file SDL_gamecontroller.c.

References SDL_JoystickUpdate.

{
    /* Just for API completeness; the joystick API does all the work. */
    SDL_JoystickUpdate();
}

SDL_bool SDL_IsGameController

(

int

joystick_index

)

Is the joystick on this index supported by the game controller interface?

Definition at line 1448 of file SDL_gamecontroller.c.

References SDL_FALSE, SDL_PrivateGetControllerMapping(), and SDL_TRUE.

{
    ControllerMapping_t *pSupportedController = SDL_PrivateGetControllerMapping(device_index);
    if (pSupportedController) {
        return SDL_TRUE;
    }
    return SDL_FALSE;
}