SDL_RenderReadPixels(3)

💖 SDL_RenderReadPixels(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, where we're talking about SDL_RenderReadPixels — the little function that literally screenshots your renderer. no cap. let's get into it 🫶

---

✨ NAME ✨

SDL_RenderReadPixels — read pixels from the current rendering target. it's giving "grab the pixels off the screen and hand them to you in a surface." iconic behavior honestly 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_render.h>

SDL_Surface * SDL_RenderReadPixels(SDL_Renderer *renderer, const SDL_Rect *rect);

look at her. two params. no drama. 🎀

---

🦋 DESCRIPTION 🦋

so the surface you get back? it contains the pixels inside the area you asked for, clipped to the current viewport. and bestie, when you're done with it you HAVE to free it with SDL_DestroySurface(). it's a whole new surface, she's not gonna clean up after herself. 🙈

highkey important: this returns the actual pixels on the screen. so if you're out here using logical presentation, you should use SDL_GetRenderLogicalPresentationRect() to get the area that actually contains your content. otherwise you're gonna be reading the wrong region and be like "why is my screenshot cursed 😭". iykyk.

⚠️ WARNING: this is a very slow operation, and you should not use it frequently. like, not every frame, bestie, please. and if you're using this on the main rendering target, it should be called after rendering and before SDL_RenderPresent(). that's the window. that's the vibe check. don't miss it.

---

✨ FUNCTION PARAMETERS ✨

• renderer — the rendering context. your main character. the renderer in question. 👑
• rect — an SDL_Rect structure representing the area to read, which will be clipped to the current viewport. or NULL if you want the entire viewport. your choice, gorgeous. 🌈

---

💜 RETURN VALUE 💜

returns a new SDL_Surface on success, or NULL on failure. and if you got NULL? call SDL_GetError() for more info, she'll tell you what went wrong fr fr. 💀

---

🧚 THREAD SAFETY 🧚

this function should only be called on the main thread. periodt. don't try to be cute and call it from a worker thread, that's not the move. 🚫

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0. so if you're on something older, no pixels for you, sorry bestie. 🍓

---

🎀 SEE ALSO 🎀

• SDL_DestroySurface()
• SDL_GetRenderLogicalPresentationRect()
• SDL_RenderPresent()
• SDL_GetError()

---

SDL_RenderReadPixels — go forth and screenshot responsibly, my love. don't spam it, free your surfaces, and stay on the main thread. that's the whole entire assignment. 💖✨🦋

~ brought to you by Simple Directmedia Layer, SDL 3.4.18, dated SDL_RenderReadPixels(3) ~ 🌸💅🎀