SDL_ConvertSurface(3)

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

✨ SDL_ConvertSurface ✨

okay bestie, gather round, because this one is literally the glow-up station for your surfaces 💅 it's from the SDL3 FUNCTIONS collection and it's called SDL_ConvertSurface — the icon, the moment, the main character of pixel format conversions 🎀

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_surface.h>

SDL_Surface * SDL_ConvertSurface(SDL_Surface *surface, SDL_PixelFormat format);

like, that's it. two little args, one big slay 🦋

💖 DESCRIPTION 💖

so the whole point of this function? it's for optimizing images so your repeat blits go zoom ⚡ you convert the original, and the result gets stored as a brand new surface. then that new optimized surface can be the source for all your future blits, and those blits are just faster. it's giving ✨performance✨ and honestly we're obsessed.

quick side quest: if you're converting to an indexed surface and you wanna map colors to a palette, you should hit up SDL_ConvertSurfaceAndColorspace() instead, bestie. this one is not that one. no cap 🙈

and one more lil thing that's lowkey important — if the original surface has alternate images, the new surface will have a reference to them as well 🫶 so nothing gets lost in the conversion, we love a faithful copy.

🎀 FUNCTION PARAMETERS 🎀

  • surface — the existing SDL_Surface structure you wanna convert, i.e. the one getting the makeover 💅
  • format — the new pixel format. this is the vibe you're converting into ✨

⭐ RETURN VALUE ⭐

it returns the new SDL_Surface structure it just created 🥳 or NULL if it failed, and in that case please call SDL_GetError() for the deets — she will tell you what went wrong, fr fr 😭

🌈 THREAD SAFETY 🌈

this one is actually flexible, periodt. you can call it on different threads, as long as you're using different surfaces. so like, don't be chaotic and share one surface across threads, but different surfaces on different threads? go off 👑

🦋 AVAILABILITY 🦋

available since SDL 3.2.0 — so if you're on anything older, this function is not gonna manifest for you, sorry bestie 💀

💜 SEE ALSO 💜

iykyk, go read those next 📚

that's the whole page, and no detail got left on read 🫶 brought to you by the fine folks at Simple Directmedia Layer, running SDL 3.4.18 — mwah, slay, bye 💅✨

📦 where this page comes from