SDL_AddGamepadMappingsFromIO(3)

💖 SDL_AddGamepadMappingsFromIO 💖

okay so bestie, welcome to the SDL3 FUNCTIONS corner of the manual, and today's main character is SDL_AddGamepadMappingsFromIO(3). she loads gamepad mappings. she's giving ✨database goblin✨. let's get into it 🎀

---

🌸 NAME 🌸

SDL_AddGamepadMappingsFromIO — load a whole set of gamepad mappings from an SDL_IOStream. yes, the whole vibe, straight off a stream 💅

---

🦋 SYNOPSIS 🦋

#include <SDL3/SDL_gamepad.h>

int SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, bool closeio);

look at her. two args. immaculate. no cap 🫶

---

⭐ DESCRIPTION ⭐

so here's the tea, fr fr:

• You can call this function several times if you need to — no judgement — to load different database files. she's flexible like that 💁♀️
• If a new mapping gets loaded for a gamepad GUID that's already known, the later version overwrites the one currently loaded. out with the old, in with the new, periodt.
• Any new mappings for controllers that are already plugged in will generate SDL_EVENT_GAMEPAD_ADDED events. so like, your controller gets a little "hey girl hey" notification 👑
• Mappings that don't belong to the current platform, or that have no platform field specified, get ignored. (i.e. mappings for Linux will be ignored in Windows, etc.) soz babes, wrong party 🌈
• This function loads the text database entirely in memory before processing it, so keep that in mind if you're in a memory constrained environment. she's hungry. she eats RAM. 🍓

not me warning you about memory but like... she does load the whole thing first. just so you know 🫶

---

💜 FUNCTION PARAMETERS 💜

• src — the data stream for the mappings to be added. your source of truth, your little stream of destiny 🦋
• closeio — if true, calls SDL_CloseIO() on src before returning, even in the case of an error. she cleans up after herself no matter what. iconic behaviour honestly 💅

---

🎀 RETURN VALUE 🎀

Returns the number of mappings added, or -1 on failure. if it flops, call SDL_GetError() for more info — she'll tell you what went wrong, she's not mysterious like that 😭

---

✨ THREAD SAFETY ✨

It is safe to call this function from any thread. go off, multitask, live your life 🧚

---

🌈 AVAILABILITY 🌈

This function is available since SDL 3.2.0. vintage but fresh 💖

---

👑 SEE ALSO 👑

the girlies she runs with:

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

---

Simple Directmedia Layer • SDL 3.4.18 • SDL_AddGamepadMappingsFromIO(3)

and that's the whole page bestie, mwah 💋 thanks for reading, go load some mappings, you ate 🫶✨🎀