IMG_LoadGPUTexture_IO(3)

💖 IMG_LoadGPUTexture_IO 💖

okay bestie, gather round, because this one is from the SDL_image3 functions crew and it's genuinely iconic. it's the move where you take an image sitting in an SDL data source and yeet it straight into a GPU texture. no disk drama, no nothing. 🎀

---

✨ SYNOPSIS ✨

#include <SDL3_image/SDL_image.h>

SDL_GPUTexture * IMG_LoadGPUTexture_IO(SDL_GPUDevice *device, SDL_GPUCopyPass *copy_pass, SDL_IOStream *src, bool closeio, int *width, int *height);

---

🌸 DESCRIPTION 🌸

so. an SDL_GPUTexture is basically an image that lives in GPU memory, and SDL's GPU API can actually use it. and no matter what format your source image was in — doesn't matter, doesn't care — this function will hand you back a GPU texture with the format SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM and no mip levels. periodt. 💅

that texture can then be bound as a sampled texture from a graphics or compute pipeline, and also as a readonly storage texture in a compute pipeline. versatile queen behavior, honestly. 👑

now, the closeio tea: if closeio is true, then src gets closed before the function returns, whether it succeeded or not. no hard feelings either way. and lowkey it doesn't even matter for correctness, because SDL_image reads everything it needs from src during this call in any case. 🫶

there's a separate function for reading files straight off disk without having to deal with SDL_IOStream at all:

IMG_LoadGPUTexture(device, copy_pass, "filename.jpg", width, height)

that one will call this function and manage all those little details for you, figuring out the file type from the filename's extension. so cute of it.

there's also IMG_LoadGPUTextureTyped_IO(), which is literally the same thing as this function except you can specify a file extension (like "BMP", "JPG", etc), which is your save when SDL_image can't autodetect the file format. not me needing the backup plan 😭

and when you're done with the texture that comes back? the app should dispose of it with a call to SDL_ReleaseGPUTexture(). don't just leave it there, that's not main character energy, that's littering. 🗑️✨

---

🦋 FUNCTION PARAMETERS 🦋

• device — the SDL_GPUDevice you're using to create the GPU texture.
• copy_pass — the SDL_GPUCopyPass used to upload the loaded image into the GPU texture.
• src — an SDL_IOStream that the data will be read from.
• closeio — true to close/free the SDL_IOStream before returning, false to leave it open.
• width — a pointer that gets filled in with the width of the GPU texture. may be NULL.
• height — a pointer that gets filled in with the width of the GPU texture. may be NULL. (yes, the manpage fr fr says width again, i'm just the messenger 💀)

---

💫 RETURN VALUE 💫

returns a new GPU texture. or NULL on error. that's the whole vibe check. 🙈

---

🌈 AVAILABILITY 🌈

this function has been available since SDL_image 3.4.0. she's not new new, but she's established.

---

⭐ SEE ALSO ⭐

• IMG_LoadGPUTexture(3)
• IMG_LoadGPUTextureTyped_IO(3)

---

and that's the page bestie!! this whole thing comes to you courtesy of SDL_image, version SDL_image 3.4.8 — go load some textures, release them when you're done, and slay 💖🎀🦋✨