SDL_IOStreamInterface(3type)

💅 SDL_IOStreamInterface 💅 (from the SDL3 DATATYPES manual, bestie)

✨ NAME ✨

SDL_IOStreamInterface — the lil bundle of function pointers that literally drive an SDL_IOStream. it's giving "custom engine, your rules" 🏎️

---

🌸 SYNOPSIS 🌸

okay so first you gotta pull in the header:

#include <SDL3/SDL_iostream.h>

and then, boom, here's the whole struct in all its glory — every field, every callback, untouched, no cap:

typedef struct SDL_IOStreamInterface
{
    /* The version of this interface */
    Uint32 version;

    /**
     *  Return the number of bytes in this SDL_IOStream
     *
     *  \return the total size of the data stream, or -1 on error.
     */
    Sint64 (SDLCALL *size)(void *userdata);

    /**
     *  Seek to `offset` relative to `whence`, one of stdio's whence values:
     *  SDL_IO_SEEK_SET, SDL_IO_SEEK_CUR, SDL_IO_SEEK_END
     *
     *  \return the final offset in the data stream, or -1 on error.
     */
    Sint64 (SDLCALL *seek)(void *userdata, Sint64 offset, SDL_IOWhence whence);

    /**
     *  Read up to `size` bytes from the data stream to the area pointed
     *  at by `ptr`. `size` will always be > 0.
     *
     *  On an incomplete read, you should set `*status` to a value from the
     *  SDL_IOStatus enum. You do not have to explicitly set this on
     *  a complete, successful read.
     *
     *  \return the number of bytes read
     */
    size_t (SDLCALL *read)(void *userdata, void *ptr, size_t size, SDL_IOStatus *status);

    /**
     *  Write exactly `size` bytes from the area pointed at by `ptr`
     *  to data stream. `size` will always be > 0.
     *
     *  On an incomplete write, you should set `*status` to a value from the
     *  SDL_IOStatus enum. You do not have to explicitly set this on
     *  a complete, successful write.
     *
     *  \return the number of bytes written
     */
    size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status);

    /**
     *  If the stream is buffering, make sure the data is written out.
     *
     *  On failure, you should set `*status` to a value from the
     *  SDL_IOStatus enum. You do not have to explicitly set this on
     *  a successful flush.
     *
     *  \return true if successful or false on write error when flushing data.
     */
    bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status);

    /**
     *  Close and free any allocated resources.
     *
     *  This does not guarantee file writes will sync to physical media; they
     *  can be in the system's file cache, waiting to go to disk.
     *
     *  The SDL_IOStream is still destroyed even if this fails, so clean up anything
     *  even if flushing buffers, etc, returns an error.
     *
     *  \return true if successful or false on write error when flushing data.
     */
    bool (SDLCALL *close)(void *userdata);

} SDL_IOStreamInterface;

---

🎀 the members, one by one 🎀

• Uint32 version — the version of this interface, bestie. it's the little handshake that says "hey, we're on the same page". 🫶
• Sint64 (SDLCALL *size)(void *userdata) — hand back the number of bytes in this SDL_IOStream. you return the total size of the data stream, or -1 on error. 😭
• Sint64 (SDLCALL *seek)(void *userdata, Sint64 offset, SDL_IOWhence whence) — jump to offset relative to whence, which is one of stdio's whence values: SDL_IO_SEEK_SET, SDL_IO_SEEK_CUR, SDL_IO_SEEK_END. you return the final offset in the data stream, or -1 on error. periodt. 📍
• size_t (SDLCALL *read)(void *userdata, void *ptr, size_t size, SDL_IOStatus *status) — read up to size bytes from the data stream into the area ptr points at. size will always be > 0, no zero-byte shenanigans here. on an incomplete read you should set *status to a value from the SDL_IOStatus enum — but on a complete, successful read you do not have to set it explicitly, so chill. you return the number of bytes read. 📖
• size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status) — write exactly size bytes from the area ptr points at to the data stream. again, size will always be > 0. on an incomplete write you should set *status to a value from the SDL_IOStatus enum; on a complete, successful write you don't have to set it explicitly. you return the number of bytes written. ✍️
• bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status) — if the stream is buffering, make sure the data actually gets written out. on failure you should set *status to a value from the SDL_IOStatus enum; on a successful flush you don't have to set it. you return true if successful, or false on write error when flushing data. 🚰
• bool (SDLCALL *close)(void *userdata) — close and free any allocated resources, the final curtain call. ⚠️ heads up tho: this does not guarantee file writes will sync to physical media — they can be sitting in the system's file cache, waiting to go to disk. and listen: the SDL_IOStream is still destroyed even if this fails, so clean up everything even if flushing buffers, etc, returns an error. you return true if successful, or false on write error when flushing data. 👑

---

🌈 DESCRIPTION 🌈

so here's the tea: applications can hand this struct to SDL_OpenIO() to create their own implementation of SDL_IOStream. it's the DIY build-your-own-stream kit. 🛠️

but lowkey? it's not necessarily required, because SDL already offers several common types of I/O streams via functions like SDL_IOFromFile() and SDL_IOFromMem(). so if the stock ones hit, you don't gotta do a thing. 💖

⚠️ important: this structure should be initialized using SDL_INIT_INTERFACE(). do not skip this step, bestie, that's the whole vibe check. 🙈

---

🦋 AVAILABILITY 🦋

this struct is available since SDL 3.2.0. iconic behavior honestly. ✨

---

👀 SEE ALSO 👀

• SDL_INIT_INTERFACE(3)

---

and that's the whole page, bestie — brought to you by Simple Directmedia Layer, running SDL 3.4.18, and yes this is the SDL_IOStreamInterface(3type) page, slay, mwah 💅💖✨