The opaque handle that represents an audio stream. More...

Inheritance diagram for SDL::AudioStreamRef:

Public Member Functions
PropertiesRef	GetProperties () const
	Get the properties associated with an audio stream.

AudioSpec	GetInputFormat () const
	Query the current input format of an audio stream.

AudioSpec	GetOutputFormat () const
	Query the current output format of an audio stream.

void	GetFormat (AudioSpec src_spec, AudioSpec dst_spec) const
	Query the current format of an audio stream.

void	SetInputFormat (const AudioSpec &spec)
	Change the input format of an audio stream.

void	SetOutputFormat (const AudioSpec &spec)
	Change the output format of an audio stream.

void	SetFormat (OptionalRef< const AudioSpec > src_spec, OptionalRef< const AudioSpec > dst_spec)
	Change the input and output formats of an audio stream.

float	GetFrequencyRatio () const
	Get the frequency ratio of an audio stream.

void	SetFrequencyRatio (float ratio)
	Change the frequency ratio of an audio stream.

float	GetGain () const
	Get the gain of an audio stream.

void	SetGain (float gain)
	Change the gain of an audio stream.

OwnArray< int >	GetInputChannelMap () const
	Get the current input channel map of an audio stream.

OwnArray< int >	GetOutputChannelMap () const
	Get the current output channel map of an audio stream.

void	SetInputChannelMap (std::span< int > chmap)
	Set the current input channel map of an audio stream.

void	SetOutputChannelMap (std::span< int > chmap)
	Set the current output channel map of an audio stream.

void	PutData (SourceBytes buf)
	Add data to the stream.

int	GetData (TargetBytes buf)
	Get converted/resampled data from the stream.

int	GetAvailable () const
	Get the number of converted/resampled bytes available.

int	GetQueued () const
	Get the number of bytes currently queued.

void	Flush ()
	Tell the stream that you're done sending data, and anything being buffered should be converted/resampled and made available immediately.

void	Clear ()
	Clear any pending data in the stream.

void	PauseDevice ()
	Use this function to pause audio playback on the audio device associated with an audio stream.

void	ResumeDevice ()
	Use this function to unpause audio playback on the audio device associated with an audio stream.

bool	DevicePaused () const
	Use this function to query if an audio device associated with a stream is paused.

AudioStreamLock	Lock ()
	Lock an audio stream for serialized access.

void	SetGetCallback (AudioStreamCB callback)
	Set a callback that runs when data is requested from an audio stream.

void	SetGetCallback (AudioStreamCallback callback, void *userdata)
	Set a callback that runs when data is requested from an audio stream.

void	SetPutCallback (AudioStreamCB callback)
	Set a callback that runs when data is added to an audio stream.

void	SetPutCallback (AudioStreamCallback callback, void *userdata)
	Set a callback that runs when data is added to an audio stream.

void	Bind (AudioDeviceRef devid)
	Bind a single audio stream to an audio device.

void	Unbind ()
	Unbind a single audio stream from its audio device.

AudioDeviceRef	GetDevice () const
	Query an audio stream for its currently-bound device.

constexpr	Resource (T resource={})
	Constructs from the underlying resource.

constexpr	Resource (const ResourceHandle< Resource< T > > auto &resource)
	Constructs from pointer like.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

Public Member Functions inherited from SDL::Resource< SDL_AudioStream * >
constexpr	Resource (SDL_AudioStream * resource={})
	Constructs from the underlying resource.

constexpr	Resource (const ResourceHandle< Resource< SDL_AudioStream * > > auto &resource)
	Constructs from pointer like.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

constexpr	operator bool () const
	True if contains a valid resource.

constexpr	operator value_type () const
	Converts back to underlying type.

constexpr bool	operator== (const Resource &other) const=default
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

constexpr bool	operator== (std::nullptr_t) const
	Comparison.

constexpr SDL_AudioStream *	get () const
	Return contained resource;.

constexpr const SDL_AudioStream *	operator-> () const
	Access to fields.

constexpr SDL_AudioStream *	operator-> ()
	Access to fields.

Static Public Member Functions
static void	reset (SDL_AudioStream *resource)
	Free an audio stream.

Additional Inherited Members
Public Types inherited from SDL::Resource< SDL_AudioStream * >
using	value_type = SDL_AudioStream *
	The raw resource type.

Detailed Description

AudioStream is an audio conversion interface.

It can handle resampling data in chunks without generating artifacts, when it doesn't have the complete buffer available.
It can handle incoming data in any variable size.
It can handle input/output format changes on the fly.
It can remap audio channels between inputs and outputs.
You push data as you have it, and pull it when you need it
It can also function as a basic audio data queue even if you just have sound that needs to pass from one place to another.
You can hook callbacks up to them when more data is added or requested, to manage data on-the-fly.

Audio streams are the core of the SDL3 audio interface. You create one or more of them, bind them to an opened audio device, and feed data to them (or for recording, consume data from them).

Since: This struct is available since SDL 3.2.0.

Category:: Resource

See also: AudioStream.Create; AudioStream

Member Function Documentation

◆ Bind()

void SDL::AudioStreamRef::Bind ( AudioDeviceRef devid )

inline

This is a convenience function, equivalent to calling AudioDeviceBase.BindAudioStreams(devid, &stream, 1).

Parameters

devid the device to bind to.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioDeviceRef.BindAudioStreams; AudioDeviceRef.UnbindAudioStream; AudioStreamRef.GetDevice; AudioDeviceRef.BindAudioStream

◆ Clear()

void SDL::AudioStreamRef::Clear ( )

inline

This drops any queued data, so there will be nothing to read from the stream until more is added.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.GetAvailable; AudioStreamRef.GetData; AudioStreamRef.GetQueued; AudioStreamRef.PutData

◆ DevicePaused()

bool SDL::AudioStreamRef::DevicePaused ( ) const

inline

Unlike in SDL2, audio devices start in an unpaused state, since an app has to bind a stream before any audio will flow.

Returns: true if device is valid and paused, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.PauseDevice; AudioStreamRef.ResumeDevice

◆ Flush()

void SDL::AudioStreamRef::Flush ( )

inline

It is legal to add more data to a stream after flushing, but there may be audio gaps in the output. Generally this is intended to signal the end of input, so the complete output becomes available.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.PutData

◆ GetAvailable()

int SDL::AudioStreamRef::GetAvailable ( ) const

inline

The stream may be buffering data behind the scenes until it has enough to resample correctly, so this number might be lower than what you expect, or even be zero. Add more data or flush the stream if you need the data now.

If the stream has so much data that it would overflow an int, the return value is clamped to a maximum value, but no queued data is lost; if there are gigabytes of data queued, the app might need to read some of it with AudioStreamRef.GetData before this function's return value is no longer clamped.

Returns: the number of converted/resampled bytes available or -1 on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.GetData; AudioStreamRef.PutData

◆ GetData()

int SDL::AudioStreamRef::GetData ( TargetBytes buf )

inline

The input/output data format/channels/samplerate is specified when creating the stream, and can be changed after creation by calling AudioStreamRef.SetFormat.

Note that any conversion and resampling necessary is done during this call, and AudioStreamRef.PutData simply queues unconverted data for later. This is different than SDL2, where that work was done while inputting new data to the stream and requesting the output just copied the converted data.

Parameters

buf	a buffer to fill with audio data.

Returns: the number of bytes read from the stream or -1 on failure; call 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.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.Clear; AudioStreamRef.GetAvailable; AudioStreamRef.PutData

◆ GetDevice()

AudioDeviceRef SDL::AudioStreamRef::GetDevice ( ) const

inline

This reports the logical audio device that an audio stream is currently bound to.

If not bound, or invalid, this returns zero, which is not a valid device ID.

Returns: the bound audio device, or 0 if not bound or invalid.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioDeviceRef.BindAudioStream; AudioDeviceRef.BindAudioStreams

◆ GetFormat()

void SDL::AudioStreamRef::GetFormat	(	AudioSpec *	src_spec,
		AudioSpec *	dst_spec
	)		const

inline

Parameters

src_spec	where to store the input audio format; ignored if nullptr.
dst_spec	where to store the output audio format; ignored if nullptr.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetFormat

◆ GetFrequencyRatio()

float SDL::AudioStreamRef::GetFrequencyRatio ( ) const

inline

Returns: the frequency ratio of the stream or 0.0 on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetFrequencyRatio

◆ GetGain()

float SDL::AudioStreamRef::GetGain ( ) const

inline

The gain of a stream is its volume; a larger gain means a louder output, with a gain of zero being silence.

Audio streams default to a gain of 1.0f (no change in output).

Returns: the gain of the stream or -1.0f on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetGain

◆ GetInputChannelMap()

OwnArray< int > SDL::AudioStreamRef::GetInputChannelMap ( ) const

inline

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

Audio streams default to no remapping applied. This is represented by returning nullptr, and does not signify an error.

Returns: an array of the current channel mapping, with as many elements as the current output spec's channels, or nullptr if default.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetInputChannelMap

◆ GetInputFormat()

AudioSpec SDL::AudioStreamRef::GetInputFormat ( ) const

inline

Returns: the input audio format.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetFormat

◆ GetOutputChannelMap()

OwnArray< int > SDL::AudioStreamRef::GetOutputChannelMap ( ) const

inline

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

Audio streams default to no remapping applied. This is represented by returning nullptr, and does not signify an error.

Returns: an array of the current channel mapping, with as many elements as the current output spec's channels, or nullptr if default.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetInputChannelMap

◆ GetOutputFormat()

AudioSpec SDL::AudioStreamRef::GetOutputFormat ( ) const

inline

Returns: the output audio format.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetFormat

◆ GetProperties()

PropertiesRef SDL::AudioStreamRef::GetProperties ( ) const

inline

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetQueued()

int SDL::AudioStreamRef::GetQueued ( ) const

inline

This is the number of bytes put into a stream as input, not the number that can be retrieved as output. Because of several details, it's not possible to calculate one number directly from the other. If you need to know how much usable data can be retrieved right now, you should use AudioStreamRef.GetAvailable() and not this function.

Note that audio streams can change their input format at any time, even if there is still data queued in a different format, so the returned byte count will not necessarily match the number of sample frames available. Users of this API should be aware of format changes they make when feeding a stream and plan accordingly.

Queued data is not converted until it is consumed by AudioStreamRef.GetData, so this value should be representative of the exact data that was put into the stream.

If the stream has so much data that it would overflow an int, the return value is clamped to a maximum value, but no queued data is lost; if there are gigabytes of data queued, the app might need to read some of it with AudioStreamRef.GetData before this function's return value is no longer clamped.

Returns: the number of bytes queued or -1 on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.PutData; AudioStreamRef.Clear

◆ PauseDevice()

void SDL::AudioStreamRef::PauseDevice ( )

inline

This function pauses audio processing for a given device. Any bound audio streams will not progress, and no audio will be generated. Pausing one device does not prevent other unpaused devices from running.

Pausing a device can be useful to halt all audio without unbinding all the audio streams. This might be useful while a game is paused, or a level is loading, etc.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.ResumeDevice

◆ PutData()

void SDL::AudioStreamRef::PutData ( SourceBytes buf )

inline

This data must match the format/channels/samplerate specified in the latest call to AudioStreamRef.SetFormat, or the format specified when creating the stream if it hasn't been changed.

Note that this call simply copies the unconverted data for later. This is different than SDL2, where data was converted during the Put call and the Get call would just dequeue the previously-converted data.

Parameters

buf	a pointer to the audio data to add.

Exceptions

Error on failure.

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.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.Clear; AudioStreamRef.Flush; AudioStreamRef.GetData; AudioStreamRef.GetQueued

◆ reset()

static void SDL::AudioStreamRef::reset ( SDL_AudioStream * resource )

inlinestatic

This will release all allocated data, including any audio that is still queued. You do not need to manually clear the stream first.

If this stream was bound to an audio device, it is unbound during this call. If this stream was created with AudioStream.OpenAudioDeviceStream, the audio device that was opened alongside this stream's creation will be closed, too.

Parameters

resource the audio stream to destroy.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStream.Create

◆ ResumeDevice()

void SDL::AudioStreamRef::ResumeDevice ( )

inline

This function unpauses audio processing for a given device that has previously been paused. Once unpaused, any bound audio streams will begin to progress again, and audio can be generated.

Remember, AudioStream.OpenAudioDeviceStream opens device in a paused state, so this function call is required for audio playback to begin on such device.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.PauseDevice

◆ SetFormat()

void SDL::AudioStreamRef::SetFormat	(	OptionalRef< const AudioSpec >	src_spec,
		OptionalRef< const AudioSpec >	dst_spec
	)

inline

Future calls to and AudioStreamRef.GetAvailable and AudioStreamRef.GetData will reflect the new format, and future calls to AudioStreamRef.PutData must provide data in the new input formats.

Data that was previously queued in the stream will still be operated on in the format that was current when it was added, which is to say you can put the end of a sound file in one format to a stream, change formats for the next sound file, and start putting that new data while the previous sound file is still queued, and everything will still play back correctly.

If a stream is bound to a device, then the format of the side of the stream bound to a device cannot be changed (src_spec for recording devices, dst_spec for playback devices). Attempts to make a change to this side will be ignored, but this will not report an error. The other side's format can be changed.

Parameters

src_spec	the new format of the audio input; if std::nullopt, it is not changed.
dst_spec	the new format of the audio output; if std::nullopt, it is not changed.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.GetFormat; AudioStreamRef.SetFrequencyRatio

◆ SetFrequencyRatio()

void SDL::AudioStreamRef::SetFrequencyRatio ( float ratio )

inline

The frequency ratio is used to adjust the rate at which input data is consumed. Changing this effectively modifies the speed and pitch of the audio. A value greater than 1.0 will play the audio faster, and at a higher pitch. A value less than 1.0 will play the audio slower, and at a lower pitch.

This is applied during AudioStreamRef.GetData, and can be continuously changed to create various effects.

Parameters

ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01 and 100.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.GetFrequencyRatio; AudioStreamRef.SetFormat

◆ SetGain()

void SDL::AudioStreamRef::SetGain ( float gain )

inline

The gain of a stream is its volume; a larger gain means a louder output, with a gain of zero being silence.

Audio streams default to a gain of 1.0f (no change in output).

This is applied during AudioStreamRef.GetData, and can be continuously changed to create various effects.

Parameters

gain	the gain. 1.0f is no change, 0.0f is silence.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.GetGain

◆ SetGetCallback() [1/2]

void SDL::AudioStreamRef::SetGetCallback	(	AudioStreamCallback	callback,
		void *	userdata
	)

inline

This callback is called before data is obtained from the stream, giving the callback the chance to add more on-demand.

The callback can (optionally) call AudioStreamRef.PutData() to add more audio to the stream during this call; if needed, the request that triggered this callback will obtain the new data immediately.

The callback's additional_amount argument is roughly how many bytes of unconverted data (in the stream's input format) is needed by the caller, although this may overestimate a little for safety. This takes into account how much is already in the stream and only asks for any extra necessary to resolve the request, which means the callback may be asked for zero bytes, and a different amount on each call.

The callback is not required to supply exact amounts; it is allowed to supply too much or too little or none at all. The caller will get what's available, up to the amount they requested, regardless of this callback's outcome.

Clearing or flushing an audio stream does not call this callback.

This function obtains the stream's lock, which means any existing callback (get or put) in progress will finish running before setting the new callback.

Setting a nullptr function turns off the callback.

Parameters

callback	the new callback function to call when data is requested from the stream.
userdata	an opaque pointer provided to the callback for its own personal use.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetPutCallback

◆ SetGetCallback() [2/2]

void SDL::AudioStreamRef::SetGetCallback ( AudioStreamCB callback )

inline

This callback is called before data is obtained from the stream, giving the callback the chance to add more on-demand.

The callback can (optionally) call AudioStreamRef.PutData() to add more audio to the stream during this call; if needed, the request that triggered this callback will obtain the new data immediately.

The callback's additional_amount argument is roughly how many bytes of unconverted data (in the stream's input format) is needed by the caller, although this may overestimate a little for safety. This takes into account how much is already in the stream and only asks for any extra necessary to resolve the request, which means the callback may be asked for zero bytes, and a different amount on each call.

The callback is not required to supply exact amounts; it is allowed to supply too much or too little or none at all. The caller will get what's available, up to the amount they requested, regardless of this callback's outcome.

Clearing or flushing an audio stream does not call this callback.

This function obtains the stream's lock, which means any existing callback (get or put) in progress will finish running before setting the new callback.

Setting a nullptr function turns off the callback.

Parameters

callback the new callback function to call when data is requested from the stream.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetPutCallback

◆ SetInputChannelMap()

void SDL::AudioStreamRef::SetInputChannelMap ( std::span< int > chmap )

inline

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

The input channel map reorders data that is added to a stream via AudioStreamRef.PutData. Future calls to AudioStreamRef.PutData must provide data in the new channel order.

Each item in the array represents an input channel, and its value is the channel that it should be remapped to. To reverse a stereo signal's left and right values, you'd have an array of { 1, 0 }. It is legal to remap multiple channels to the same thing, so { 1, 1 } would duplicate the right channel to both channels of a stereo signal. An element in the channel map set to -1 instead of a valid channel will mute that channel, setting it to a silence value.

You cannot change the number of channels through a channel map, just reorder/mute them.

Data that was previously queued in the stream will still be operated on in the order that was current when it was added, which is to say you can put the end of a sound file in one order to a stream, change orders for the next sound file, and start putting that new data while the previous sound file is still queued, and everything will still play back correctly.

Audio streams default to no remapping applied. Passing a nullptr channel map is legal, and turns off remapping.

SDL will copy the channel map; the caller does not have to save this array after this call.

If count is not equal to the current number of channels in the audio stream's format, this will fail. This is a safety measure to make sure a race condition hasn't changed the format while this call is setting the channel map.

Unlike attempting to change the stream's format, the input channel map on a stream bound to a recording device is permitted to change at any time; any data added to the stream from the device after this call will have the new mapping, but previously-added data will still have the prior mapping.

Parameters

chmap the new channel map, nullptr to reset to default.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running. Don't change the stream's format to have a different number of channels from a a different thread at the same time, though!

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetInputChannelMap

◆ SetInputFormat()

void SDL::AudioStreamRef::SetInputFormat ( const AudioSpec & spec )

inline

Future calls to and AudioStreamRef.GetAvailable and AudioStreamRef.GetData will reflect the new format, and future calls to AudioStreamRef.PutData must provide data in the new input formats.

Data that was previously queued in the stream will still be operated on in the format that was current when it was added, which is to say you can put the end of a sound file in one format to a stream, change formats for the next sound file, and start putting that new data while the previous sound file is still queued, and everything will still play back correctly.

If a stream is bound to a device, then the format of the side of the stream bound to a device cannot be changed (src_spec for recording devices, dst_spec for playback devices). Attempts to make a change to this side will be ignored, but this will not report an error. The other side's format can be changed.

Parameters

spec	the new format of the audio input.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.GetFormat; AudioStreamRef.SetFrequencyRatio

◆ SetOutputChannelMap()

void SDL::AudioStreamRef::SetOutputChannelMap ( std::span< int > chmap )

inline

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

The output channel map reorders data that leaving a stream via AudioStreamRef.GetData.

Each item in the array represents an input channel, and its value is the channel that it should be remapped to. To reverse a stereo signal's left and right values, you'd have an array of { 1, 0 }. It is legal to remap multiple channels to the same thing, so { 1, 1 } would duplicate the right channel to both channels of a stereo signal. An element in the channel map set to -1 instead of a valid channel will mute that channel, setting it to a silence value.

You cannot change the number of channels through a channel map, just reorder/mute them.

The output channel map can be changed at any time, as output remapping is applied during AudioStreamRef.GetData.

Audio streams default to no remapping applied. Passing a nullptr channel map is legal, and turns off remapping.

SDL will copy the channel map; the caller does not have to save this array after this call.

If count is not equal to the current number of channels in the audio stream's format, this will fail. This is a safety measure to make sure a race condition hasn't changed the format while this call is setting the channel map.

Unlike attempting to change the stream's format, the output channel map on a stream bound to a recording device is permitted to change at any time; any data added to the stream after this call will have the new mapping, but previously-added data will still have the prior mapping. When the channel map doesn't match the hardware's channel layout, SDL will convert the data before feeding it to the device for playback.

Parameters

chmap the new channel map, nullptr to reset to default.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running. Don't change the stream's format to have a different number of channels from a a different thread at the same time, though!

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetInputChannelMap

◆ SetOutputFormat()

void SDL::AudioStreamRef::SetOutputFormat ( const AudioSpec & spec )

inline

Future calls to and AudioStreamRef.GetAvailable and AudioStreamRef.GetData will reflect the new format, and future calls to AudioStreamRef.PutData must provide data in the new input formats.

Data that was previously queued in the stream will still be operated on in the format that was current when it was added, which is to say you can put the end of a sound file in one format to a stream, change formats for the next sound file, and start putting that new data while the previous sound file is still queued, and everything will still play back correctly.

If a stream is bound to a device, then the format of the side of the stream bound to a device cannot be changed (src_spec for recording devices, dst_spec for playback devices). Attempts to make a change to this side will be ignored, but this will not report an error. The other side's format can be changed.

Parameters

spec	the new format of the audio output.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.GetFormat; AudioStreamRef.SetFrequencyRatio

◆ SetPutCallback() [1/2]

void SDL::AudioStreamRef::SetPutCallback	(	AudioStreamCallback	callback,
		void *	userdata
	)

inline

This callback is called after the data is added to the stream, giving the callback the chance to obtain it immediately.

The callback can (optionally) call AudioStreamRef.GetData() to obtain audio from the stream during this call.

The callback's additional_amount argument is how many bytes of converted data (in the stream's output format) was provided by the caller, although this may underestimate a little for safety. This value might be less than what is currently available in the stream, if data was already there, and might be less than the caller provided if the stream needs to keep a buffer to aid in resampling. Which means the callback may be provided with zero bytes, and a different amount on each call.

The callback may call AudioStreamRef.GetAvailable to see the total amount currently available to read from the stream, instead of the total provided by the current call.

The callback is not required to obtain all data. It is allowed to read less or none at all. Anything not read now simply remains in the stream for later access.

Clearing or flushing an audio stream does not call this callback.

This function obtains the stream's lock, which means any existing callback (get or put) in progress will finish running before setting the new callback.

Setting a nullptr function turns off the callback.

Parameters

callback	the new callback function to call when data is added to the stream.
userdata	an opaque pointer provided to the callback for its own personal use.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetGetCallback

◆ SetPutCallback() [2/2]

void SDL::AudioStreamRef::SetPutCallback ( AudioStreamCB callback )

inline

This callback is called after the data is added to the stream, giving the callback the chance to obtain it immediately.

The callback can (optionally) call AudioStreamRef.GetData() to obtain audio from the stream during this call.

The callback's additional_amount argument is how many bytes of converted data (in the stream's output format) was provided by the caller, although this may underestimate a little for safety. This value might be less than what is currently available in the stream, if data was already there, and might be less than the caller provided if the stream needs to keep a buffer to aid in resampling. Which means the callback may be provided with zero bytes, and a different amount on each call.

The callback may call AudioStreamRef.GetAvailable to see the total amount currently available to read from the stream, instead of the total provided by the current call.

The callback is not required to obtain all data. It is allowed to read less or none at all. Anything not read now simply remains in the stream for later access.

Clearing or flushing an audio stream does not call this callback.

This function obtains the stream's lock, which means any existing callback (get or put) in progress will finish running before setting the new callback.

Setting a nullptr function turns off the callback.

Parameters

callback the new callback function to call when data is added to the stream.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetGetCallback

◆ Unbind()

void SDL::AudioStreamRef::Unbind ( )

inline

This is a convenience function, equivalent to calling UnbindAudioStreams(&stream, 1).

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioDeviceRef.BindAudioStream

The documentation for this struct was generated from the following file:

SDL3pp/SDL3pp_audio.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ Bind()

◆ Clear()

◆ DevicePaused()

◆ Flush()

◆ GetAvailable()

◆ GetData()

◆ GetDevice()

◆ GetFormat()

◆ GetFrequencyRatio()

◆ GetGain()

◆ GetInputChannelMap()

◆ GetInputFormat()

◆ GetOutputChannelMap()

◆ GetOutputFormat()

◆ GetProperties()

◆ GetQueued()

◆ PauseDevice()

◆ PutData()

◆ reset()

◆ ResumeDevice()

◆ SetFormat()

◆ SetFrequencyRatio()

◆ SetGain()

◆ SetGetCallback() [1/2]

◆ SetGetCallback() [2/2]

◆ SetInputChannelMap()

◆ SetInputFormat()

◆ SetOutputChannelMap()

◆ SetOutputFormat()

◆ SetPutCallback() [1/2]

◆ SetPutCallback() [2/2]

◆ Unbind()