IMG_LoadTyped_IO(3)

📦

version 3.4.4 · 8 versions

NAME 💖

IMG_LoadTyped_IO — load an image from an SDL data source into a software surface, bestie 💅

This page is from the SDL_image3 FUNCTIONS manual, and it's giving "typed IO loader with main character energy" ✨

SYNOPSIS 🎀

#include <SDL3_image/SDL_image.h>

SDL_Surface * IMG_LoadTyped_IO(SDL_IOStream *src, bool closeio, const char *type);

DESCRIPTION 🦋

Okay so first thing: an SDL_Surface is a buffer of pixels in memory that the CPU can access 👑. Use this function if you're planning to hand that data off to something else or keep manipulating it further in code. Very "I have pixels and I'm not afraid to use them" energy 💖.

There are no guarantees about what format the new SDL_Surface data will be 😭. In many cases, SDL_image will attempt to supply a surface that exactly matches the provided image, but in others it might have to convert — either because the image is in a format that SDL doesn't directly support, or because it's compressed data that could reasonably uncompress to various formats and SDL_image had to pick one. You can inspect an SDL_Surface for its specifics, and use SDL_ConvertSurface to then migrate to any supported format. Slay 💅.

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. No cap.

Even though this function accepts a file type, SDL_image may still try other decoders that are capable of detecting file type from the contents of the image data, but may rely on the caller-provided type string for formats that it cannot autodetect 👀. If type is NULL, SDL_image will rely solely on its ability to guess the format. iykyk.

There is a separate function to read 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 is also IMG_Load_IO(), which is equivalent to this function except that it will rely on SDL_image to determine what type of data it is loading, much like passing a NULL for type 💜.

If you are using SDL's 2D rendering API, there is an equivalent call to load images directly into an SDL_Texture for use by the GPU without using a software surface: call IMG_LoadTextureTyped_IO() instead 🔥.

When done with the returned surface, the app should dispose of it with a call to SDL_DestroySurface(). Clean up your room, bestie 🧚.

FUNCTION PARAMETERS 🌈

src — an SDL_IOStream that data will be read from. That's the source, periodt 🍓.
closeio — true to close/free the SDL_IOStream before returning, false to leave it open. Choose wisely 💀.
type — a filename extension that represent this data ("BMP", "GIF", "PNG", etc). Yes, literally a little string like that 💅.

RETURN VALUE 🎀

Returns a new SDL surface, or NULL on error 😭. That's the whole vibe check.

AVAILABILITY ⭐

This function is available since SDL_image 3.0.0. Iconic behavior since day one 👑.