SDL_AudioStreamCallback(3type)

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

💖 SDL_AudioStreamCallback — a 3type from the SDL3 DATATYPES squad 💖

okay bestie, sit down, hydrate, and let me tell you about SDL_AudioStreamCallback ✨ this is a 3type, which is the manual-section way of saying "it's a typedef, not a function you call yourself" — she lives in the SDL3 DATATYPES crew 🎀

🌸 NAME 🌸

SDL_AudioStreamCallback — a callback that fires when data passes through an SDL_AudioStream. it's giving "hey, something's moving through the pipe, you wanna handle it?" 💅

✨ SYNOPSIS ✨

#include <SDL3/SDL_audio.h>

typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount);

like… that's the whole shape of her. no cap 🫶

🦋 DESCRIPTION 🦋

so here's the tea, bestie ☕ apps can optionally register a callback with an audio stream, and that callback gets called when data is added with SDL_PutAudioStreamData, or requested with SDL_GetAudioStreamData. optionally! as in, you don't have to. she's not needy 💜

Two values are offered here, and the way they work is kinda the whole point:

  • one is the amount of additional data needed to satisfy the immediate request — and lowkey this might be zero if the stream already has enough data queued up 💀
  • the other is the total amount being requested

and the way these two interact depends on the direction, so listen up:

  • In a Get call triggering a Put callback, these values can be different 🙈
  • In a Put call triggering a Get callback, these values are always the same ✅

Byte counts might be slightly overestimated due to buffering or resampling, and may change from call to call. so don't get attached to your numbers, they're fluid, they're main characters, they do what they want 🌈

This callback is not required to do anything. genuinely! Generally this is useful for adding/reading data on demand, and the app will often put/get data as appropriate, but the system goes on with the data currently available to it if this callback does nothing. she's chill like that 😌

⚠️ DO NOT call SDL_DestroyAudioStream() on stream during this callback. fr fr. do not. not the vibe. absolutely not the move 💀🚫

🎀 FUNCTION PARAMETERS 🎀

  • stream — the SDL audio stream associated with this callback. your girl, the stream in question 🦋
  • additional_amount — the amount of data, in bytes, that is needed right now ⏰
  • total_amount — the total amount of data requested, in bytes, that is requested or available 📊
  • userdata — an opaque pointer provided by the app for their personal use 🙈 it's yours, do what you want with it

🔥 THREAD SAFETY 🔥

okay this part matters, bestie. These callbacks may run from any thread 😭 so if you need to protect shared data, you should use SDL_LockAudioStream to serialize access. and here's the slay part: this lock will be held before your callback is called, so your callback does not need to manage the lock explicitly. the system already did it for you. she's got you 🫶

⭐ AVAILABILITY ⭐

This datatype is available since SDL 3.2.0. she's not new new, but she's not ancient either. iconic behavior 👑

💜 SEE ALSO 💜

go read those next, iykyk 📚✨

k bye ily, this page came to you from Simple Directmedia Layer, running version SDL 3.4.18 🎀 that's the source and the version, right there, in the sign-off like a little wax seal 💌 mwah, go make some audio 💅

📦 where this page comes from