SDL_SetColors(3)

💖 SDL_SetColors — bestie edition 💖

okay so you're in the SDL API Reference and you found SDL_SetColors(3)?? slay, come sit with me, this one's actually so fun once it clicks 🫶

---

✨ NAME ✨

SDL_SetColors — sets a portion of the colormap for the given 8-bit surface. that's it, that's the whole job, and it eats every time 💅

---

🌸 SYNOPSIS 🌸

#include "SDL.h"

int SDL_SetColors(SDL_Surface *surface, SDL_Color *colors, int
firstcolor, int ncolors);

yes bestie, four args, don't panic, we're going through every single one 🎀

---

🦋 DESCRIPTION 🦋

So. SDL_SetColors sets a portion of the colormap for the given 8-bit surface. a portion, bestie, not the whole thing — you get to pick where it starts and how far it goes, main character energy fr fr ✨

When surface is the surface associated with the current display, the display colormap will be updated with the colors you requested. and if SDL_HWPALETTE was set in the SDL_SetVideoMode flags?? then SDL_SetColors will always return 1, and the palette is guaranteed to be set the way you desire — even if the window colormap has to be warped or run under emulation. no cap. it's giving "your palette, your rules" 👑

The color components of a SDL_Color structure are 8-bits in size, which gives you a total of 256^3 = 16777216 colors. seventeen million bestie!! that's so many fits to choose from 🌈

Now here's the part that lowkey changes your whole life. Palettized (8-bit) screen surfaces with the SDL_HWPALETTE flag have two palettes:

• a logical palette — used for mapping blits to/from the surface
• a physical palette — determines how the hardware will map the colors to the display

SDL_SetColors modifies both palettes (if present). it is equivalent to calling SDL_SetPalette with the flags set to (SDL_LOGPAL | SDL_PHYSPAL). so like, you could do it the long way, but why would you 🙈

---

💀 RETURN VALUE 💀

okay bestie this part matters, pay attention:

• If surface is not a palettized surface, this function does nothing, returning 0. it's giving "read the room, wrong surface" 😭
• If all of the colors were set as passed to SDL_SetColors, it will return 1. slay!! ✅
• If not all the color entries were set exactly as given, it will return 0 — and you should look at the surface palette to determine the actual color palette. i.e. go check what actually happened, don't just assume 🫠

not me getting a 0 back and being like "but I asked nicely" — bestie, the hardware said no. check the surface palette. periodt.

---

🎀 EXAMPLE 🎀

here's a whole grayscale palette setup, iconic behavior:

/* Create a display surface with a grayscale palette */
SDL_Surface *screen;
SDL_Color colors[256];
int i;
.
.
.
/* Fill colors with color information */
for(i=0;i<256;i++){
  colors[i].r=i;
  colors[i].g=i;
  colors[i].b=i;
}

/* Create display */
screen=SDL_SetVideoMode(640, 480, 8, SDL_HWPALETTE);
if(!screen){
  printf("Couldn't set video mode: %s
", SDL_GetError());
  exit(-1);
}

/* Set palette */
SDL_SetColors(screen, colors, 0, 256);
.
.
.
.

look at her go 🧚 all 256 entries, r, g, b all marching in lockstep — that's a grayscale gradient and she's serving 🍓

---

🔥 SEE ALSO 🔥

• SDL_Color
• SDL_Surface
• SDL_SetPalette
• SDL_SetVideoMode

go read these next, iykyk 💜

---

okay that's the whole page!! this was written for the SDL manual, dated Tue 11 Sep 2001, 23:01 — yes bestie, 2001, she's vintage and she still hits 💖 stay palettized, love u, bye!! 🎀✨🦋