SDL_PutAudioStreamDataNoCopy(3)

✨ SDL_PutAudioStreamDataNoCopy ✨

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual 💖 this one's called SDL_PutAudioStreamDataNoCopy(3) and it's giving "zero-copy queen" energy, let's GO 🦋

---

🌸 NAME 🌸

SDL_PutAudioStreamDataNoCopy — add external data to an audio stream without copying it. no cap, it just... holds the pointer. iconic behavior fr fr 💅

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_audio.h>

bool SDL_PutAudioStreamDataNoCopy(SDL_AudioStream *stream, const void *buf, int len, SDL_AudioStreamDataCompleteCallback callback, void *userdata);

look at that signature. five whole parameters. she's thriving ✨

---

💜 DESCRIPTION 💜

so here's the tea ☕ unlike SDL_PutAudioStreamData(), this function does NOT make a copy of the provided data — instead it stores the provided pointer. that means the put operation doesn't have to allocate and copy the data (slay, efficiency), BUT 🔥 the original data has to remain available until the stream is done with it. "done with it" means either:

• it gets read from the stream in its entirety, or
• somebody calls SDL_ClearAudioStream(), or
• somebody calls SDL_DestroyAudioStream().

⚠️ bestie please internalize this: if your buffer gets freed or reused before the stream finishes with it, that's on you. the stream is holding a pointer, not a copy. no takesies backsies 🙈

the data must match the format / channels / samplerate specified in the latest call to SDL_SetAudioStreamFormat, or the format specified when creating the stream if it hasn't been changed. format mismatch = not the vibe 🌸

an optional callback may be provided, and it gets called when the stream no longer needs the data. once this callback fires, the stream will not access the data again. and it fires for any reason the data is no longer needed, including clearing or destroying the stream. so like, it's your lil notification bestie going "we're done here, you can let go now" 🫶

note that there is still an allocation to store tracking information, so this function is more efficient for larger blocks of data. if you're planning to put a few samples at a time, it will be more efficient to use SDL_PutAudioStreamData(), which allocates and buffers in blocks. small drips = use the other one, big chunks = use this one. periodt 💅

---

🧚 FUNCTION PARAMETERS 🧚

• stream — the stream the audio data is being added to. it's the main character here 👑
• buf — a pointer to the audio data to add. remember: the stream keeps this pointer, so don't go freeing it early 😭
• len — the number of bytes to add to the stream.
• callback — the callback function to call when the data is no longer needed by the stream. may be NULL. no callback? totally fine, you just won't get the lil heads-up ping 📞
• userdata — an opaque pointer provided to the callback for its own personal use. it's literally just vibes, the callback can do whatever it wants with it ✨

---

⭐ RETURN VALUE ⭐

returns true on success or false on failure; call SDL_GetError() for more information. if it returns false, go read the error, don't just sit there 🙈

---

🌈 THREAD SAFETY 🌈

it is safe to call this function from any thread, but if the stream has a callback set, the caller might need to manage extra locking. so like, multithreaded girlies, keep an eye on that 🔒

---

💖 AVAILABILITY 💖

this function is available since SDL 3.4.0. so if you're on an older version, she is simply not there yet, sorry bestie 😭

---

🦋 SEE ALSO 🦋

• SDL_ClearAudioStream(3)
• SDL_FlushAudioStream(3)
• SDL_GetAudioStreamData(3)
• SDL_GetAudioStreamQueued(3)

go read those too, they're all part of the same friend group 🫶

---

and that's the whole page, bestie!! 💅 this was SDL_PutAudioStreamDataNoCopy(3) from Simple Directmedia Layer, SDL 3.4.18, dated SDL 3.4.18 🎀 stay zero-copy, stay iconic, and don't let your buffers expire early 💖✨🦋