SDL_LockTextureToSurface(3)

💖 SDL_LockTextureToSurface(3) 💖

okay bestie so this is a page from the SDL3 FUNCTIONS collection, and it's genuinely one of the cutest little render tricks in the whole library. let's get into it 🫶

---

✨ NAME ✨

SDL_LockTextureToSurface — lock a portion of the texture for write-only pixel access, and expose it as a SDL_Surface. yes queen, you get a whole surface out of it 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_render.h>

bool SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface);

---

🦋 DESCRIPTION 🦋

so like. this does basically the same thing as SDL_LockTexture, except instead of handing you raw pixel data, it hands you an SDL_Surface. same energy, different outfit 💖

and here's the optimization tea: the pixels you get to edit don't necessarily contain the old texture data. ngl this is a write-only operation. so if you need to keep a copy of the texture data, you gotta do that yourself at the application level. no cap. 🙈

you must use SDL_UnlockTexture() to unlock the pixels and apply any changes. that's the whole deal, you can't skip it.

the returned surface gets freed internally after you call SDL_UnlockTexture() or SDL_DestroyTexture(). so the caller should not free it. not even a little bit. do not touch. it's giving hands off my surface 😭

---

🎀 FUNCTION PARAMETERS 🎀

• texture — the texture to lock for access. and listen, it must be created with SDL_TEXTUREACCESS_STREAMING. no other access mode is invited to this party, periodt.
• rect — a pointer to the rectangle to lock for access. if the rect is NULL, the entire texture will be locked. full send, iconic. ✨
• surface — a pointer to an SDL surface of size rect. don't assume any specific pixel content. seriously. don't assume. it's mysterious on purpose 💀

---

👑 RETURN VALUE 👑

returns true on success or false on failure. if it flops, call SDL_GetError() for more information and it'll tell you what went wrong bestie 🥺

---

🌈 THREAD SAFETY 🌈

this function should only be called on the main thread. main character energy only, no side quests on other threads 🔥

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0. so if you're on anything older, that's a no from her 💜

---

💜 SEE ALSO 💜

• SDL_LockTexture(3)
• SDL_UnlockTexture(3)

---

🫶 reminder: write-only, unlock or destroy to free, don't you dare free() that surface yourself. iykyk 💅

okay that's the whole page, mwah. this lil manual page came to you courtesy of Simple Directmedia Layer, version SDL 3.4.18 — go slay some streaming textures bestie 🌸💖✨