NAME¶

SDL_PutAudioStreamPlanarData - Add data to the stream with each channel in a separate array.

SYNOPSIS¶

#include <SDL3/SDL_audio.h>

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

DESCRIPTION¶

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.

FUNCTION PARAMETERS¶

stream

the stream the audio data is being added to.

channel_buffers

a pointer to an array of arrays, one array per channel.

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; call SDL_GetError() for more information.

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.

AVAILABILITY¶

This function is available since SDL 3.4.0.

SEE ALSO¶

SDL_ClearAudioStream(3), SDL_FlushAudioStream(3), SDL_GetAudioStreamData(3), SDL_GetAudioStreamQueued(3)