SDL_ReadSurfacePixel(3)

✨ SDL_ReadSurfacePixel(3) ✨

okay so bestie, welcome to the SDL3 FUNCTIONS section of the manual 💖 this one's called SDL_ReadSurfacePixel and it is exactly what it sounds like — we're grabbing one single pixel. one. singular. pixel. it's giving surgical precision 🎀

---

🌸 NAME 🌸

SDL_ReadSurfacePixel — Retrieves a single pixel from a surface. yes queen, one pixel, that's the whole job 💅

---

🦋 SYNOPSIS 🦋

#include <SDL3/SDL_surface.h>

bool SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);

look at her. seven whole arguments. she's thriving 😭💖

---

👑 DESCRIPTION 👑

so here's the tea, and it's important tea 🫖: this function prioritizes correctness over speed. like, it is not trying to be fast, it is trying to be right. that means it's literally perfect for unit tests, but it is not intended for use in a game engine. nope. do not put this in your render loop. i'm serious. it's the friend who double-checks the receipt at the restaurant — beloved, correct, not fast 🐢✨

and ooh, second thing: like SDL_GetRGBA, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component. so a lil 5-bit channel still gets stretched all the way out to the full 0-255 glow-up 💅🔥 no wasted range, no crumbs.

---

🎀 FUNCTION PARAMETERS 🎀

• surface — the surface to read. that's our girl. the thing we're peeking at 👀
• x — the horizontal coordinate, 0 <= x < width. stay in bounds bestie, we do not wander off the edge 💀
• y — the vertical coordinate, 0 <= y < height. same energy, but vertical 🌈
• r — a pointer filled in with the red channel, 0-255, or NULL to ignore this channel. don't care about red? pass NULL, live your truth 🍓
• g — a pointer filled in with the green channel, 0-255, or NULL to ignore this channel. same deal, green edition 🌿
• b — a pointer filled in with the blue channel, 0-255, or NULL to ignore this channel. blue bestie, also optional 💙
• a — a pointer filled in with the alpha channel, 0-255, or NULL to ignore this channel. alpha! the transparency of it all 🫶

ngl the NULL thing is lowkey iconic — you can literally ask for just the channels you want and ghost the rest. obsessed.

---

⭐ RETURN VALUE ⭐

Returns true on success or false on failure 🥲 and if it fails, call SDL_GetError() for more information. like, she will tell you what went wrong, you just have to ask 💖

---

🧚 THREAD SAFETY 🧚

This function can be called on different threads with different surfaces. 🎉

so like — multiple threads, multiple surfaces, absolutely no drama. note the vibe check though: different surfaces. don't be messy about it 😌

---

💜 AVAILABILITY 💜

This function is available since SDL 3.2.0. she's new-ish and she knows it ✨

---

and that's the whole page, bestie — go read a pixel, you've earned it 💅🦋

with love from the Simple Directmedia Layer girlies, SDL 3.4.18 era 🎀 (the date line was giving mysterious, so we're just gonna say hi and go) 💖✨