IMG_LoadTexture(3)

🎀 IMG_LoadTexture(3) — SDL_image3 FUNCTIONS 🎀

okay bestie, welcome to the SDL_image3 FUNCTIONS chapter. this is the one about loading an image straight from a filesystem path into a texture. icon behavior. ✨

💖 NAME 💖

IMG_LoadTexture — load an image from a filesystem path into a texture. periodt. 💅

✨ SYNOPSIS ✨

#include <SDL3_image/SDL_image.h>

SDL_Texture * IMG_LoadTexture(SDL_Renderer *renderer, const char *file);

🦋 DESCRIPTION 🦋

So an SDL_Texture is literally an image living in GPU memory, and SDL's 2D Render API can use it. That's highkey more efficient than a CPU-bound SDL_Surface if you don't need to manipulate the image directly after loading it. no cap. 🫶

If the image you loaded has transparency or a colorkey, you get a texture with an alpha channel. otherwise, SDL_image will attempt to create an SDL_Texture in the most format that most reasonably represents the image data — and ngl, in many cases that just ends up being 32-bit RGB or 32-bit RGBA. slay. 🌈

There's a separate function for reading files from an SDL_IOStream when you need an i/o abstraction to provide data from anywhere instead of a simple filesystem read. that function is IMG_LoadTexture_IO(). iykyk. 💜

If you'd rather decode the image to an SDL_Surface (a buffer of pixels in CPU memory), call IMG_Load() instead. different vibe, different use case. 🎀

When you're done with the returned texture, the app should dispose of it with a call to SDL_DestroyTexture(). this is the cleanup check, don't skip it. 🫶

🌈 FUNCTION PARAMETERS 🌈

• renderer — the SDL_Renderer to use to create the texture. it's giving "the renderer that makes the texture happen". ✨
• file — a path on the filesystem to load an image from. yes, an actual path, bestie. 🍓

⭐ RETURN VALUE ⭐

Returns a new texture, or NULL on error. that's it. if you get NULL, something went sideways — check it, don't ignore it. 😭

👑 AVAILABILITY 👑

This function is available since SDL_image 3.0.0. iconic since day one, fr fr. 👑

🎀 SEE ALSO 🎀

• IMG_LoadTextureTyped_IO(3)
• IMG_LoadTexture_IO(3)

---

💌 cute sign-off: this page comes from SDL_image 3.4.4 — source/version is SDL_image 3.4.4, and the footer didn't list a date. love that for us. byeee bestie 💋✨