SDL_SetColorKey(3)

📦 version 1.2.15, in debian bookworm, nixos 26.05, nixpkgs unstable, ubuntu jammy

💖 SDL_SetColorKey 💖

okay bestie, gather round, because this one is literally the transparent pixel icon of the SDL API. this is SDL_SetColorKey from the SDL API Reference, and she is that girl 🎀

✨ NAME ✨

SDL_SetColorKey — sets the color key (transparent pixel) in a blittable surface, and does the RLE acceleration thing too. no cap 🦋

✨ SYNOPSIS ✨

#include "SDL.h"

int SDL_SetColorKey(SDL_Surface *surface, Uint32 flag, Uint32 key);

✨ DESCRIPTION ✨

so basically, this function sets the color key — that's the transparent pixel — in a blittable surface, and it also turns RLE blit acceleration on or off. two jobs, one function, she's working overtime 💅

RLE acceleration can substantially speed up blitting of images that have big horizontal runs of transparent pixels — iykyk, those are the pixels that match the key value. 🏃‍♀️💨

the key has to be the same pixel format as the surface, okay? and SDL_MapRGB is often useful for getting a value that actually works. don't skip that part bestie 😭

here's the flag tea, sip slowly 🍓

  • if flag is SDL_SRCCOLORKEY, then key is the transparent pixel value in the source image of a blit.
  • if flag is OR'd with SDL_RLEACCEL, then the surface will be drawn using RLE acceleration whenever it's drawn with SDL_BlitSurface. and here's the lowkey sneaky bit: the surface doesn't get actually encoded for RLE acceleration until the first time SDL_BlitSurface or SDL_DisplayFormat is called on it. it's giving "I'll do it later" energy, but fr fr it does happen 👑
  • if flag is 0, this function clears any current color key. gone. bye. periodt 💀

✨ RETURN VALUE ✨

this function returns 0, or -1 if there was an error. so if you see that -1... it's not a vibe, something went wrong 🙈

✨ SEE ALSO ✨

  • SDL_BlitSurface
  • SDL_DisplayFormat
  • SDL_MapRGB
  • SDL_SetAlpha

go read those too, you're already here, might as well slay the whole set 💜

and that's the whole page, bestie!! this was SDL, part of the SDL API Reference, and it was last touched up on Tue 11 Sep 2001, 23:01. iconic date, iconic function. mwah 🫶✨🌸

📦 where this page comes from