SDL_LockSurface(3)

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

💖 SDL_LockSurface(3) 💖

okay bestie, so we're in the SDL3 FUNCTIONS corner of the manual, and today's main character is SDL_LockSurface — it's giving "let me at those pixels" energy. no cap.

✨ NAME ✨

SDL_LockSurface — set up a surface so you can go straight in and touch the pixels yourself. direct access, hand on the glass, no middleman. 🫶

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_surface.h>

bool SDL_LockSurface(SDL_Surface *surface);

🦋 DESCRIPTION 🦋

okay so picture this: between your calls to SDL_LockSurface() and SDL_UnlockSurface(), you can write to and read from surface->pixels, using whatever pixel format is chillin' in surface->format. it's literally right there for you. 💅

and the moment you're done messing with the surface? you should hit SDL_UnlockSurface() to release it. don't be the person who locks and never unlocks, that's not the vibe. 😭

here's the tea though — not all surfaces require locking. if SDL_MUSTLOCK(surface) evaluates to 0, then you can read and write to the surface any time you want, and the pixel format of the surface will not change. so chill, it's fine. ✨

🎀 FUNCTION PARAMETERS 🎀

  • surface — the SDL_Surface structure that's getting locked. that's the one. that's her. 👑

⭐ RETURN VALUE ⭐

returns true on success or false on failure. if it flops, call SDL_GetError() for more info — she'll tell you what went wrong. 💀

🔥 THREAD SAFETY 🔥

you can call this function on different threads, as long as it's with different surfaces. multiple surfaces, multiple threads, everyone thriving. 🌈

but lowkey important: the "locking" this function is talking about is making the pixels available for direct access — it is not thread-safe locking. those are two different things, bestie, don't mix them up. 🙈

💜 AVAILABILITY 💜

this function has been available since SDL 3.2.0. she's been here, she's iconic. ✨

🌸 SEE ALSO 🌸

okay that's the whole page, you ate it fr fr 🍓 this was brought to you by Simple Directmedia Layer, running SDL 3.4.18 — go lock a surface, bestie, and remember to unlock it. mwah 💖🧚

📦 where this page comes from