SDL_PutAudioStreamPlanarData(3)

💖 SDL_PutAudioStreamPlanarData(3) 💖

okay bestie, so this one lives in the SDL3 FUNCTIONS section of the manual, and it's genuinely one of my faves. like, it's the "i have my channels all separated and i need them together" function. let's go 🎀

---

✨ NAME ✨

SDL_PutAudioStreamPlanarData — shove data into the stream, except each channel gets its own separate array. planar girlies rise 🦋

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_audio.h>

bool SDL_PutAudioStreamPlanarData(SDL_AudioStream *stream, const void * const *channel_buffers, int num_channels, int num_samples);

---

💅 DESCRIPTION 💅

So. The data you're handing over must match the format / channels / samplerate from the latest call to SDL_SetAudioStreamFormat, or — if nobody's changed anything — whatever format the stream was born with. no cap, mismatched formats are not it 😭

Your data gets interleaved and queued. and here's the tea: SDL_AudioStream only deals in interleaved data. so this is literally just a convenience function for when your source hands you separate arrays per channel and you don't wanna do the interleaving dance yourself. also — important — there is no equivalent function to retrieve planar data. it's a one-way street, bestie, we do not get planar back out 🫶

The arrays inside channel_buffers are ordered exactly as they'll be interleaved: the first array becomes the first sample in the interleaved data. and any individual array may be NULL — in that case, silence gets interleaved for that channel. iconic behavior honestly.

num_channels tells the function how many arrays live in channel_buffers. you can use it as a lil safety net to prevent overflow in case the stream format changed somewhere else behind your back 👀 If you specify more channels than the current input spec, the extras are just ignored. If you specify fewer, the missing arrays get treated as if they were NULL (so silence gets written to those channels). And if the count is -1, SDL assumes the array count matches the current input spec. so many options, all valid ✨

⚠️ heads up, this trips people up: num_samples is the number of samples per array. you can also think of it as the number of sample frames being queued. a value of 1 with stereo arrays queues two samples to the stream. this is different from SDL_PutAudioStreamData, which wants the size of a single array in bytes. don't mix those up, i'm begging 🙈

---

🎀 FUNCTION PARAMETERS 🎀

• stream — the stream the audio data is being added to. the main character, obviously.
• channel_buffers — a pointer to an array of arrays, one array per channel. arrays all the way down, slay.
• num_channels — the number of arrays in channel_buffers, or -1.
• num_samples — the number of samples per array to write to the stream.

---

⭐ RETURN VALUE ⭐

Returns true on success or false on failure. and if it fails? call SDL_GetError() for more info, bestie, it'll tell you what went wrong 💀

---

🌈 THREAD SAFETY 🌈

It's safe to call this function from any thread 🧚 but — and this is the but — if the stream has a callback set, the caller might need to manage extra locking. so like, be aware. don't be messy.

---

👑 AVAILABILITY 👑

This function is available since SDL 3.4.0. so if you're on anything older, this is not your moment 😭

---

🍓 SEE ALSO 🍓

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

---

and that's the whole vibe, bestie 💜 this page came to you from Simple Directmedia Layer, version SDL 3.4.18 — go interleave something beautiful with it. mwah 💋✨🎀