SDL_GetWindowSurface(3)

📦
version 3.4.18 · 9 versions
, in fedora 43, fedora 44

💖 SDL_GetWindowSurface(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS section of the manual, we're gonna talk about surfaces, windows, and the sacred art of not freeing things you don't own 🫶

✨ NAME ✨

SDL_GetWindowSurface — grab the SDL_Surface that's chillin' with your window 💅

✨ SYNOPSIS ✨

#include <SDL3/SDL_video.h>

SDL_Surface * SDL_GetWindowSurface(SDL_Window *window);

✨ DESCRIPTION ✨

so basically? if it needs to, this function makes you a brand new surface in the optimal format for the window. that's the whole point. no cap.

and here's the part everyone gets wrong on the first try: this surface gets freed when the window is destroyed. do NOT free this surface. like. it's not yours. it's the window's. hands off. 🙈

also, the moment you resize the window, this surface gets invalidated. poof. gone. so after a resize you have to call this function again to get a valid surface back. it's giving "the vibe check resets every time you change the layout," iykyk.

and you may not combine this with 3D or the rendering API on this window. pick a lane. pick one. it's not both. 💀

oh and also — this function is affected by SDL_HINT_FRAMEBUFFER_ACCELERATION. just so you know. the hint has opinions and they matter here.

✨ FUNCTION PARAMETERS ✨

  • window — the window you're querying, bestie. that's the one. 👑

✨ RETURN VALUE ✨

returns the surface associated with the window 💖 …or NULL if it failed 😭. and if you get NULL, go call SDL_GetError() for more info, because it will tell you what went wrong. it's not gonna gatekeep.

✨ THREAD SAFETY ✨

main thread only, periodt. 🚫🧵 this function should only be called on the main thread.

✨ AVAILABILITY ✨

this function has been available since SDL 3.2.0. she's not new new but she's not ancient either. ✨

✨ SEE ALSO ✨

and that's the whole page, bestie!! 🌸 go forth, get your surface, and do not free it 💅 this was brought to you by the lovely folks at Simple Directmedia Layer, straight outta SDL 3.4.18, and yes, the manual page was literally called SDL_GetWindowSurface(3) the whole time — iconic of her, honestly. mwah 🎀🦋

📦 where this page comes from