SDL_LockTexture(3)

💖 SDL_LockTexture(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS section of the manual, and today's main character is SDL_LockTexture 🎀

---

✨ NAME ✨

SDL_LockTexture — lock a portion of the texture for write-only pixel access. yes, write-only, we'll get to that, it matters, i promise 🫶

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_render.h>

bool SDL_LockTexture(SDL_Texture *texture,
                const SDL_Rect *rect,
                void **pixels, int *pitch);

that's the whole vibe right there, no cap ✨

---

🦋 DESCRIPTION 🦋

so here's the tea ☕ — as an optimization, the pixels you get handed to edit don't necessarily contain the old texture data. it's giving "surprise, it's empty in here". this is a write-only operation, and if you need to keep a copy of the texture data you should do that at the application level. so like, back it up yourself, bestie, don't come crying to SDL 😭

you must use SDL_UnlockTexture() to unlock the pixels and apply any changes. that's the whole point. lock, write, unlock, apply. periodt 💅

---

💜 FUNCTION PARAMETERS 💜

• texture — the texture to lock for access, which was created with SDL_TEXTUREACCESS_STREAMING. if it wasn't made with that flag, we are not doing this today 🙈
• rect — an SDL_Rect structure representing the area to lock for access; NULL to lock the entire texture. just the whole thing. go off 👑
• pixels — this is filled in with a pointer to the locked pixels, appropriately offset by the locked area. SDL hands you the pointer, you don't bring your own ✨
• pitch — this is filled in with the pitch of the locked pixels; the pitch is the length of one row in bytes. one row. in bytes. that's the definition, memorize it 🧚

---

⭐ RETURN VALUE ⭐

returns true on success 🌈 or false if the texture is not valid or was not created with SDL_TEXTUREACCESS_STREAMING 💀 — and if that happens, call SDL_GetError() for more information. she'll tell you what went wrong, she's very honest 🫶

---

🔥 THREAD SAFETY 🔥

this function should only be called on the main thread. do not be passing this to a worker thread, bestie, i'm begging 🙏

---

🌟 AVAILABILITY 🌟

this function is available since SDL 3.2.0 🎉

---

👑 SEE ALSO 👑

• SDL_LockTextureToSurface(3)
• SDL_UnlockTexture(3)

---

and that's the whole page, bestie. lock it, write it, unlock it, slay 💅✨

Simple Directmedia Layer • version SDL 3.4.18 • and yeah this page is literally titled SDL_LockTexture(3), we love a self-titled moment 💖 mwah, go forth and stream those textures 🦋🌸