IMG_Load_IO(3)

🎀 IMG_Load_IO(3) — NAME 🎀

IMG_Load_IO — load an image from an SDL data source into a software surface. This page is serving SDL_image3 FUNCTIONS manual energy, bestie. 💅

✨ SYNOPSIS ✨

#include <SDL3_image/SDL_image.h>

SDL_Surface * IMG_Load_IO(SDL_IOStream *src, bool closeio);

🦋 DESCRIPTION 🦋

Okay so an SDL_Surface is a buffer of pixels in memory that the CPU can access. Use this when you plan to hand the data off to something else or keep manipulating it in code. Main character pixel-buffer energy. 💖

There are no guarantees about what format the new SDL_Surface data will be. In many cases, SDL_image will try to give you a surface that exactly matches the image you provided, but sometimes it 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 to multiple formats and SDL_image had to pick one. You can inspect an SDL_Surface for its specifics, then use SDL_ConvertSurface to migrate it to any supported format.

If the image format supports a transparent pixel, SDL will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling:

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

If closeio is true, src will be closed before returning, whether this function succeeds or not. SDL_image reads everything it needs from src during this call in any case. So yes, it's getting read either way — the close just decides whether the stream gets shut down too. 🫶

There's a separate function for reading files from disk without having to deal with SDL_IOStream: IMG_Load("filename.jpg") will call this function and manage those details for you, determining the file type from the filename's extension.

There's also IMG_LoadTyped_IO(), which is equivalent to this function except you can specify a file extension (like "BMP", "JPG", etc.) in case SDL_image cannot autodetect the file format.

If you're using SDL's 2D rendering API, there's an equivalent call to load images directly into an SDL_Texture for use by the GPU without using a software surface: call IMG_LoadTexture_IO() instead. No software middleman, just texture vibes. 🔥

When you're done with the returned surface, the app should dispose of it with a call to SDL_DestroySurface(). Clean up after yourself, icon behavior only. 👑

💖 FUNCTION PARAMETERS 💖

• src — an SDL_IOStream that data will be read from.
• closeio — true to close/free the SDL_IOStream before returning, false to leave it open.

🌈 RETURN VALUE 🌈

Returns a new SDL surface, or NULL on error. Simple as that, bestie. ✨

👑 AVAILABILITY 👑

This function is available since SDL_image 3.0.0.

🔥 SEE ALSO 🔥

• IMG_Load(3)
• IMG_LoadTyped_IO(3)

---

💌 xoxo, your Unix bestie — source/version is SDL_image, version 3.4.4, and the footer didn't give us a date, so we're not inventing one. Sending pixel-perfect love and absolutely no fake dates. 💅✨