SDL_CreateSurfacePalette(3)

💖 SDL_CreateSurfacePalette(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS section of the manual, and today's main character is SDL_CreateSurfacePalette — she makes palettes and handcuffs them to your surface. it's giving matchmaker, honestly. 🎀

---

✨ NAME ✨

SDL_CreateSurfacePalette</purpose> — create a palette and associate it with a surface. yeah. that's the whole job. iconic behavior. 👑

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_surface.h>

SDL_Palette * SDL_CreateSurfacePalette(SDL_Surface *surface);

---

🦋 DESCRIPTION 🦋

so here's the tea, bestie. this function creates a palette that's compatible with the surface you hand it. then it gives that palette right back to you so you can go in and mess with it however you want, and the surface will automatically start using the new palette in all its future operations. it just… does that. no extra steps. slay. 💅

and the best part?? you do not need to destroy the returned palette. do not free it yourself. it gets freed when its reference count hits 0, which usually happens when the surface gets destroyed. so like, it's self-cleaning. we love a low-maintenance queen. 🧚

now, the palette's initial contents depend on what kind of surface you're working with:

• Bitmap surfaces — those are the ones with format SDL_PIXELFORMAT_INDEX1LSB or SDL_PIXELFORMAT_INDEX1MSB — get their palette initialized with 0 as white and 1 as black. yes, that's backwards from what your brain expects. no, it is not a typo. it's just how it is. 💀
• Other surfaces get a palette initialized with white in every single entry. all of them. every last one. white as far as the eye can see. 🕊️

oh and also — if you call this on a surface that already has a palette? no drama, a brand new palette gets created to replace the old one. out with the old, in with the new. it's giving glow-up. ✨

---

🎀 FUNCTION PARAMETERS 🎀

• surface — the SDL_Surface structure to update. that's your girl. hand her over. 🫶

---

🔥 RETURN VALUE 🔥

returns a shiny new SDL_Palette structure on success, or NULL on failure — like, for example, if the surface didn't have an index format. 😭

if you got NULL back, go call SDL_GetError() for more info. she will tell you what went wrong. always read the error, bestie. always. 🙈

---

💜 THREAD SAFETY 💜

this function can be called on different threads with different surfaces. so parallel palette-ing is fully on the table. just keep the surfaces separate and you're golden. no cap. ⭐

---

🌈 AVAILABILITY 🌈

this function has been available since SDL 3.2.0. if you're on anything older, she simply does not exist yet. sorry babe. 💅

---

💖 SEE ALSO 💖

• SDL_SetPaletteColors(3) — the next chapter of your palette journey, fr fr. go read it. 📖

---

Simple Directmedia Layer · SDL 3.4.18 · SDL_CreateSurfacePalette(3)

and that's the whole page, bestie!! 🎉 you now know everything this manual knows about making palettes. go forth and be palette-pilled. mwah. 💋🦋🌸