IMG_Load(3)

💖 IMG_Load(3) — like, the SDL_image3 functions era 💖

okay bestie, pull up a chair, because this one is a classic. This is IMG_Load from the SDL_image3 manual (the SDL_image one, yeah), and honestly? She's iconic. Let's get into it. 🎀

---

✨ NAME ✨

IMG_Load — load an image from a filesystem path into a software surface. that's it. that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

#include <SDL3_image/SDL_image.h>

SDL_Surface * IMG_Load(const char *file);

literally just point her at a file and she gives you pixels. slay. 💅

---

👑 DESCRIPTION 👑

okay so first things first: an SDL_Surface is a buffer of pixels in memory that the CPU can actually reach. use this one when you're planning to hand that data off to something else, or keep messing with it in your own code. it's the "I want to touch the pixels myself" option, and honestly? relatable. 🫶

now, no cap on this part: there are no guarantees about what format the new SDL_Surface data is gonna be in. in many cases, SDL_image will try to give you a surface that matches the provided image exactly, but in other cases she might have to convert — either because the image is in a format SDL doesn't directly support, or because it's compressed data that could reasonably uncompress into a bunch of different formats and SDL_image just had to pick one. 😭 she did her best!

the good news? you can inspect an SDL_Surface for its specifics, and then use SDL_ConvertSurface to migrate to any supported format. so like, you're never stuck. 💜

oh and — if the image format supports a transparent pixel, SDL will set the colorkey for the surface. and if you wanna enable RLE acceleration on the surface afterwards, you just call:

SDL_SetSurfaceColorKey(image, SDL_RLEACCEL, image->format->colorkey);

that's the whole thing. no notes. 🔥

also, quick FYI bestie: there's a separate function for reading files from an SDL_IOStream, in case you need an i/o abstraction to feed data in from literally anywhere instead of a plain old filesystem read. that function is IMG_Load_IO(). iykyk. ✨

and if you're using SDL's 2D rendering API? there's an equivalent call that loads images directly into an SDL_Texture for the GPU to use, no software surface middleman needed — call IMG_LoadTexture() instead. main character energy, honestly. 👑

when you're done with the returned surface, the app should dispose of it with a call to SDL_DestroySurface(). don't just ghost her, okay? 😭 the docs link, verbatim, because the manpage renders it in a whole state:

https:// wiki.www:lenstrwww:splitstr:nwww:splitstr:r[char46]libsdl.www:lenstrwww:splitstr:nwww:splitstr:r[char46]org/
SDL3/SDL_DestroySurface

🚨 friendly reminder: that surface is yours to clean up. SDL_DestroySurface() or it's a leak, and leaks are not the vibe. 💀

---

🍓 FUNCTION PARAMETERS 🍓

• file — a path on the filesystem to load an image from. give her a path, she gives you pixels. simple as that. 💖

---

🌈 RETURN VALUE 🌈

returns a new SDL surface, or NULL on error. so like — always check for NULL, bestie. always. 🙈

---

⭐ AVAILABILITY ⭐

this function is available since SDL_image 3.0.0. she's been here a minute. 👑

---

🦋 SEE ALSO 🦋

• IMG_LoadTyped_IO(3)
• IMG_Load_IO(3)

---

and that's the whole page, bestie!! go forth and load some images 🧚

mwah 💋 — this has been SDL_image, version SDL_image 3.4.4, saying goodnight from the IMG_Load(3) corner of the manual. take care of your surfaces and they'll take care of you. 🎀✨