SDL_AddGamepadMapping(3)

💖 SDL_AddGamepadMapping(3) — SDL3 FUNCTIONS 💖

okay bestie, listen. we're in the SDL3 house tonight and today's main character is SDL_AddGamepadMapping — she lives in the SDL3 FUNCTIONS section and she is so much cooler than her name makes her sound. let's go 🫶

---

✨ NAME ✨

SDL_AddGamepadMapping — add support for gamepads that SDL is unaware of, or change the binding of an existing gamepad.

like. she's the girl who introduces your random third-party controller to the group chat. and she can also rearrange the buttons on a gamepad SDL already knows. iconic behaviour honestly 💅

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_gamepad.h>

int SDL_AddGamepadMapping(const char *mapping);

---

✨ DESCRIPTION ✨

so the mapping string is formatted like this:

"GUID,name,mapping"

break it down, bestie:

• GUID — this is the string value you get from SDL_GUIDToString()
• name — the human readable string for the device
• mapping — the actual gamepad mappings, mapping gamepad things onto joystick things

and under Windows there's a reserved GUID of "xinput" that covers all XInput devices. reserved. exclusive. she doesn't share. 💀

the mapping format for joystick goes like this:

• bX — a joystick button, index X
• hX.Y — hat X with value Y
• aX — axis X of the joystick

and the little plot twist: buttons can be used as gamepad axes and vice versa. no cap, they're interchangeable like that 🔥

if a device with this GUID is already plugged in, SDL will generate an SDL_EVENT_GAMEPAD_ADDED event. she just shows up and announces herself.

here's an example of a valid mapping for a gamepad, and yes it's long, it's giving ✨ full makeup routine ✨:

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

---

✨ FUNCTION PARAMETERS ✨

• mapping — the mapping string. that's it, that's the whole job 🎀

---

✨ RETURN VALUE ✨

• returns 1 if a new mapping is added 👑
• returns 0 if an existing mapping is updated 🦋
• returns -1 on failure 😭

and if you got that -1, call SDL_GetError() for more information. she'll tell you what went wrong, fr fr.

---

✨ THREAD SAFETY ✨

it is safe to call this function from any thread. multitasking queen, she contains multitudes 🌸

---

✨ AVAILABILITY ✨

this function is available since SDL 3.2.0. she's not new new, but she's not ancient either. a modern classic 💜

---

✨ SEE ALSO ✨

• SDL_AddGamepadMappingsFromFile(3)
• SDL_AddGamepadMappingsFromIO(3)
• SDL_GetGamepadMapping(3)
• SDL_GetGamepadMappingForGUID(3)
• SDL_HINT_GAMECONTROLLERCONFIG(3)
• SDL_HINT_GAMECONTROLLERCONFIG_FILE(3)
• SDL_EVENT_GAMEPAD_ADDED(3)

---

okay that's the whole page, bestie, you ate that 🍓 go forth and map your weird off-brand controller with confidence 💅

Simple Directmedia Layer • SDL 3.4.18 • SDL_AddGamepadMapping(3) — mwah, take care of her, she's doing her best 🧚💖