SDL_SetSurfaceColorKey(3)

📦
version 3.4.18 · 9 versions
, in fedora 43, fedora 44

💖 SDL_SetSurfaceColorKey 💖

okay so bestie, we're in the SDL3 FUNCTIONS section of the manual, and today's main character is SDL_SetSurfaceColorKey(3). she's the one who decides which pixel gets to be invisible. let's go 🫶

✨ NAME ✨

SDL_SetSurfaceColorKey</purl> — set the color key (transparent pixel) in a surface. yes, the whole point is making one specific pixel value ✨not exist✨ during a blit. iconic behaviour, honestly 💅

✨ SYNOPSIS ✨

#include <SDL3/SDL_surface.h>

bool SDL_SetSurfaceColorKey(SDL_Surface *surface, bool enabled, Uint32 key);

✨ DESCRIPTION ✨

so the color key is literally a pixel value that gets treated as transparent in a blit. like, ghosted. not rendered. gone. 🦋

for example, you can use this to say that cyan pixels should be considered transparent, and therefore not rendered at all. poof. bye. 😭

and it's a pixel of the format used by the surface, as generated by SDL_MapRGB(). so don't just make up a number, bestie, run it through SDL_MapRGB() first or it's giving chaos. 🎀

✨ FUNCTION PARAMETERS ✨

  • surface — the SDL_Surface structure to update. this is the one getting the glow-up ✨
  • enabled — true to enable color key, false to disable color key. flip the switch, queen 👑
  • key — the transparent pixel. the one we're sending to the shadow realm 💀

✨ RETURN VALUE ✨

returns true on success or false on failure 🥲 and if it fails? call SDL_GetError() for more information. she will tell you what went wrong, fr fr.

✨ THREAD SAFETY ✨

this function can be called on different threads with different surfaces. so like, multi-threaded girlies, you're safe — as long as the surfaces are different ones. no sharing, no drama 🙈

✨ AVAILABILITY ✨

this function is available since SDL 3.2.0. so if you're on something older, that's a no from her 🌸

✨ SEE ALSO ✨

and that's the whole page, bestie!! this beauty comes to you from Simple Directmedia Layer, version SDL 3.4.18 🎀 go forth and make pixels invisible, you absolute icon ⭐👑💖

📦 where this page comes from