SDL Wiki
(This is the documentation for SDL3, which is under heavy development and the API is changing! SDL2 is the current stable version!)


Add support for gamepads that SDL is unaware of or change the binding of an existing gamepad.

Header File

Defined in <SDL3/SDL_gamepad.h>


int SDL_AddGamepadMapping(const char *mapping);

Function Parameters

const char * mapping the mapping string.

Return Value

(int) Returns 1 if a new mapping is added, 0 if an existing mapping is updated, -1 on error; call SDL_GetError() for more information.


The mapping string has the format "GUID,name,mapping", where GUID is the string value from SDL_GetJoystickGUIDString(), name is the human readable string for the device and mappings are gamepad mappings to joystick ones. Under Windows there is a reserved GUID of "xinput" that covers all XInput devices. The mapping format for joystick is:

Buttons can be used as a gamepad axes and vice versa.

This string shows an example of a valid mapping for a gamepad:

"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"

Thread Safety

It is safe to call this function from any thread.


This function is available since SDL 3.0.0.

See Also

CategoryAPI, CategoryAPIFunction, CategoryGamepad

[ edit | delete | history | feedback | raw ]

[ front page | index | search | recent changes | git repo | offline html ]

All wiki content is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
Wiki powered by ghwikipp.