IMG_LoadGPUTexture(3)

💖 IMG_LoadGPUTexture(3) — the SDL_image3 glow-up 💖

okay so bestie, welcome to the SDL_image3 functions era ✨ this one lives in section 3 of the manual, and it is literally the "put my picture on the GPU" button. no cap.

---

🌸 NAME 🌸

IMG_LoadGPUTexture — load an image from a filesystem path straight into a GPU texture. it's giving "file goes in, texture comes out" 💅

---

🎀 SYNOPSIS 🎀

#include <SDL3_image/SDL_image.h>

SDL_GPUTexture * IMG_LoadGPUTexture(SDL_GPUDevice *device, SDL_GPUCopyPass *copy_pass, const char *file, int *width, int *height);

---

🦋 DESCRIPTION 🦋

so an SDL_GPUTexture is an image that lives in GPU memory, and SDL's GPU API can actually use it. iconic. 🫶

and here's the thing that makes this function so slay: no matter what format your source image is in, this function is gonna create a GPU texture with the format SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, with no mip levels. that's just the deal, fr fr. it can be bound as a sampled texture from a graphics or compute pipeline, and also as a read-only storage texture in a compute pipeline. versatility queen 👑

now, if you need an i/o abstraction so you can feed data from anywhere instead of a plain old filesystem read, there's a whole separate function for reading from an SDL_IOStream. that one is IMG_LoadGPUTexture_IO(). iykyk 💜

and when you're done with the texture it hands you? the app should dispose of it by calling SDL_ReleaseGPUTexture(). clean up after yourself bestie, the GPU is not your personal landfill 💀

---

✨ FUNCTION PARAMETERS ✨

• device — the SDL_GPUDevice you're using to create the GPU texture. this is the main character here.
• copy_pass — the SDL_GPUCopyPass used to upload the loaded image onto the GPU texture.
• file — a path on the filesystem to load an image from. yes, an actual path, on an actual filesystem 🌈
• width — a pointer that gets filled in with the width of the GPU texture. it may be NULL, so if you don't care, don't stress 🍓
• height — a pointer that gets filled in with the height of the GPU texture. it may be NULL too 🧚

---

🔥 RETURN VALUE 🔥

returns a new GPU texture, or NULL on error. so if you get NULL, that's your vibe check failing — go check for an error, bestie 😭

---

⭐ AVAILABILITY ⭐

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

---

👑 SEE ALSO 👑

• IMG_LoadGPUTextureTyped_IO(3)
• IMG_LoadGPUTexture_IO(3)

---

and that's the whole page, bestie 🎀 go forth and texture the GPU, periodt. 🌸💖✨

this page came to you from the SDL_image docs, version SDL_image 3.4.8 — mwah, take care of her 🫶