SDL_UpdateTexture(3)

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

💖 SDL_UpdateTexture(3) — the glow-up your texture was waiting for 💖

okay bestie, welcome to the SDL3 FUNCTIONS section, and specifically to SDL_UpdateTexture(3), aka the girl who shows up with fresh pixel data and just... drops it in. no cap. ✨

✨ NAME ✨

SDL_UpdateTexture — update the given texture rectangle with new pixel data. that's it, that's the whole job description. 💅

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_render.h>

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

she takes four things and gives you back a bool. iconic honestly.

🦋 DESCRIPTION 🦋

okay so first thing, and this is NOT a vibe check you can skip: the pixel data you hand over must be in the pixel format of the texture. not a format like it. not a format that's basically the same. the actual one. you can find out which one that is by querying the SDL_PROP_TEXTURE_FORMAT_NUMBER property. iykyk. 🔍

second thing — and i'm gonna be real with you — this function is fairly slow. like, she's not the fast one in the group chat. she's intended for use with static textures that do not change often. set it once, admire it, move on. 🌈

so if your texture is the type that's gonna be updated often? bestie, please, it's preferred to create the texture as streaming and use the locking functions referenced down below in SEE ALSO. and here's the little gotcha that lives rent-free in my head: while this function will work with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward. so like... she'll take your pixels, but don't count on getting them returned to you later. 💀

not a bug, it's a documented optimization trade-off. still rude though. 🙈

🎀 FUNCTION PARAMETERS 🎀

  • texture — the texture to update. the main character of this whole operation. 👑
  • rect — an SDL_Rect structure representing the area to update, or NULL to update the entire texture. whole-texture glow-up? pass NULL and let her cook. 🍓
  • pixels — the raw pixel data, in the format of the texture. remember: the format. the matching one. ✨
  • pitch — the number of bytes in a row of pixel data, including padding between lines. yes, the padding counts. no, you can't skip it. 😭

⭐ RETURN VALUE ⭐

returns true on success or false on failure. and if you get a false? call SDL_GetError() for more information, because she's not gonna tell you what went wrong unprompted. 💅

🧚 THREAD SAFETY 🧚

this function should only be called on the main thread. periodt. no side quests, no background thread shenanigans. 🫶

💜 AVAILABILITY 💜

this function is available since SDL 3.2.0. so if you're on anything older, she simply does not exist yet. sorry babe. 🌸

🔥 SEE ALSO 🔥

go read those if your texture is the frequently-changing type, k? that's the streaming girlie pipeline. 💖

Simple Directmedia Layer wrote this, and we're all living in the SDL 3.4.18 era, so that's the version you're getting this wisdom from. mwah, take care of your textures, bestie 💅✨🎀

📦 where this page comes from