SDL_AddSurfaceAlternateImage(3)

💖 SDL_AddSurfaceAlternateImage 💖

okay bestie, so this one lives in the SDL3 FUNCTIONS manual, and it's called SDL_AddSurfaceAlternateImage(3). let's get into it 🫶

---

✨ NAME ✨

SDL_AddSurfaceAlternateImage — add an alternate version of a surface. literally giving your surface a little backup twin 👯♀️

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_surface.h>

bool SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image);

---

🦋 DESCRIPTION 🦋

so what this does is it adds an alternate version of this surface. the usual reason you'd do this? content that has high DPI representations — think cursors or icons, the stuff that needs to look crisp on a fancy screen 💅

and here's the chill part: the size, format, and content of the alternate do not need to match the original surface. no matching outfit required, she can wear whatever 🎀

heads up tho — these alternate versions will not be updated when the original surface changes. they are NOT synced, they do not follow along, they are doing their own thing. periodt.

also important: this function adds a reference to the alternate version. so after you call this, you should call SDL_DestroySurface() on the image. don't skip that part bestie, that's the cleanup 😭

---

🌈 FUNCTION PARAMETERS 🌈

• surface — the SDL_Surface structure to update. this is the main character, the one getting the glow-up 👑
• image — a pointer to an alternate SDL_Surface to associate with this surface. this is the little alt twin 🧚

---

⭐ RETURN VALUE ⭐

returns true on success, or false on failure. if it fails, call SDL_GetError() for more info — she'll tell you what went wrong 🙈

---

💜 THREAD SAFETY 💜

this function can be called on different threads with different surfaces. so yes, you can parallelize — just keep it to different surfaces, iykyk ✨

---

🍓 AVAILABILITY 🍓

this function is available since SDL 3.2.0. not that old, she's fresh 🔥

---

👑 SEE ALSO 👑

• SDL_RemoveSurfaceAlternateImages(3)
• SDL_GetSurfaceImages(3)
• SDL_SurfaceHasAlternateImages(3)

---

and that's the whole vibe 💖 this came to you straight from Simple Directmedia Layer, SDL 3.4.18, and yes it's still the SDL_AddSurfaceAlternateImage(3) page. go forth and give your surfaces their alternate selves, bestie 🌸🦋🎀