Add data to the stream with each channel in a separate array.
Defined in <SDL3/SDL_audio.h>
bool SDL_PutAudioStreamPlanarData(SDL_AudioStream *stream, const void * const *channel_buffers, int num_channels, int num_samples);| SDL_AudioStream * | stream | the stream the audio data is being added to. |
| const void * const * | channel_buffers | a pointer to an array of arrays, one array per channel. |
| int | num_channels | the number of arrays in channel_buffers or -1. |
| int | num_samples | the number of samples per array to write to the stream. |
(bool) Returns true on success or false on failure; call SDL_GetError() for more information.
This 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.
The data will be interleaved and queued. Note that SDL_AudioStream only operates on interleaved data, so this is simply a convenience function for easily queueing data from sources that provide separate arrays. There is no equivalent function to retrieve planar data.
The arrays in channel_buffers are ordered as they are to be interleaved; the first array will be the first sample in the interleaved data. Any individual array may be NULL; in this case, silence will be interleaved for that channel.
num_channels specifies how many arrays are in channel_buffers. This can be used as a safety to prevent overflow, in case the stream format has changed elsewhere. If more channels are specified than the current input spec, they are ignored. If less channels are specified, the missing arrays are treated as if they are NULL (silence is written to those channels). If the count is -1, SDL will assume the array count matches the current input spec.
Note that num_samples is the number of samples per array. This can also be thought of as the number of sample frames to be queued. A value of 1 with stereo arrays will queue two samples to the stream. This is different than SDL_PutAudioStreamData, which wants the size of a single array in bytes.
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.
This function is available since SDL 3.4.0.