SDL_AudioS...eteCallback(3type)

📦
version 3.4.18 · 5 versions
, in fedora 43, fedora 44

💖 SDL_AudioS...eteCallback — a datatype from the SDL3 DATATYPES crew 🎀

okay bestie, sit down, hydrate, and let me tell you about the single most underrated little callback in the whole audio section. it's giving "I'll tell you the exact moment your buffer is free" energy and honestly? iconic.

✨ NAME ✨

SDL_AudioStreamDataCompleteCallback — a callback that fires when the data you handed over with SDL_PutAudioStreamDataNoCopy() is finally, officially, completely done. 💅

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_audio.h>

typedef void (SDLCALL *SDL_AudioStreamDataCompleteCallback)(void *userdata, const void *buf, int buflen);

look at her. gorgeous. no notes. 🦋

🫶 DESCRIPTION 🫶

so here's the situation, bestie. when you use SDL_PutAudioStreamDataNoCopy() to feed data into an SDL_AudioStream, you're basically saying "hey, use this buffer, I'm not making you a copy, we're being efficient." which slays, truly. but — and this is the important part — it is NOT safe to dispose of that data until the stream has completely consumed it. no cap.

and the annoying part? often times it's difficult to know exactly when this has happened. like, the stream just... has your pointer... and you're sitting there like 🙈 "is it done? can I free it? hello?"

this callback is the answer. it fires once when the stream no longer needs the buffer, which lets the app easily free or reuse it. that's it. that's the whole vibe. closure, literally. 😭✨

🎀 FUNCTION PARAMETERS 🎀

  • userdata — an opaque pointer that you the app provided, for your own personal use. no questions asked, no interpretation made. it's yours. 💜
  • buf — the pointer that was provided to SDL_PutAudioStreamDataNoCopy(). yes, that exact one. 🍓
  • buflen — the size of buffer, in bytes, that was provided to SDL_PutAudioStreamDataNoCopy(). 💫

🧚 THREAD SAFETY 🧚

okay this part matters so listen up. this callback may run from any thread. so if you need to protect shared data, you should use SDL_LockAudioStream to serialize access.

but here's the cute part: this lock will be held before your callback is called, so your callback does not need to manage the lock explicitly. she already did that for you. main character behavior, honestly. 👑

⭐ AVAILABILITY ⭐

this datatype has been available since SDL 3.4.0. so if you're on 3.4.0 or later, you're good. 🎉

🌈 SEE ALSO 🌈

go read those too bestie, they're all in the same friend group. 🫶

💀 tiny reminder before you go: the whole reason this callback exists is that SDL_PutAudioStreamDataNoCopy() means no copy, which means you keep ownership of that memory, which means freeing it too early is a you problem that this callback is here to prevent. free it when she tells you to. periodt.

okay that's the whole page, you ate it, I'm obsessed with you, bye bestie 💖🌸🦋 — brought to you by Simple Directmedia Layer, running SDL 3.4.18 (that's the source + version babe, that's the date vibe, that's the footer energy), mwah 💅✨

📦 where this page comes from