SDL::AudioStream Struct Reference

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

Inheritance diagram for SDL::AudioStream:

Public Member Functions
constexpr	AudioStream (AudioStreamRaw resource) noexcept
	Constructs from raw AudioStream.
constexpr	AudioStream (const AudioStream &other)=delete
	Copy constructor.
constexpr	AudioStream (AudioStream &&other) noexcept
	Move constructor.
constexpr	AudioStream (const AudioStreamRef &other)=delete
constexpr	AudioStream (AudioStreamRef &&other)=delete
	AudioStream (OptionalRef< const AudioSpec > src_spec, OptionalRef< const AudioSpec > dst_spec)
	Create a new audio stream.
	AudioStream (AudioDeviceRef devid, OptionalRef< const AudioSpec > spec=std::nullopt, AudioStreamCallback callback=nullptr, void *userdata=nullptr)
	Convenience function for straightforward audio init for the common case.
	AudioStream (AudioDeviceRef devid, OptionalRef< const AudioSpec > spec, AudioStreamCB callback)
	Convenience function for straightforward audio init for the common case.
	~AudioStream ()
	Destructor.
constexpr AudioStream &	operator= (AudioStream &&other) noexcept
	Assignment operator.
AudioStream &	operator= (const AudioStream &other)=delete
	Assignment operator.
void	Destroy ()
	Free an audio stream.
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.
void	PutDataNoCopy (SourceBytes buf, AudioStreamDataCompleteCallback callback, void *userdata)
	Add external data to an audio stream without copying it.
void	PutDataNoCopy (SourceBytes buf, AudioStreamDataCompleteCB callback)
	Add external data to an audio stream without copying it.
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	Unlock (AudioStreamLock &&lock)
	Unlock an audio stream for serialized access.
void	SetGetCallback (AudioStreamCallback callback, void *userdata)
	Set a callback that runs when data is requested from an audio stream.
void	SetGetCallback (AudioStreamCB callback)
	Set a callback that runs when data is requested from an audio stream.
void	SetPutCallback (AudioStreamCallback callback, void *userdata)
	Set a callback that runs when data is added to an audio stream.
void	SetPutCallback (AudioStreamCB callback)
	Set a callback that runs when data is added to an audio stream.
void	Unbind ()
	Unbind a single audio stream from its audio device.
AudioDeviceRef	GetDevice () const
	Query an audio stream for its currently-bound device.
void	PutPlanarData (const void *const *channel_buffers, int num_channels, int num_samples)
	Add data to the stream with each channel in a separate array.
constexpr	ResourceBase (RawPointer resource)
	Constructs from resource pointer.
constexpr	ResourceBase (std::nullptr_t=nullptr)
	Constructs null/invalid.
Public Member Functions inherited from SDL::ResourceBase< AudioStreamRaw >
constexpr	ResourceBase (RawPointer resource)
	Constructs from resource pointer.
constexpr	operator bool () const
	Converts to bool.
constexpr auto	operator<=> (const ResourceBase &other) const=default
	Comparison.
constexpr RawConstPointer	operator-> () const noexcept
	member access to underlying resource pointer.
constexpr RawPointer	get () const noexcept
	Retrieves underlying resource pointer.
constexpr RawPointer	release () noexcept
	Retrieves underlying resource pointer and clear this.

Additional Inherited Members
Public Types inherited from SDL::ResourceBase< AudioStreamRaw >
using	RawPointer
	The underlying raw pointer type.
using	RawConstPointer
	The underlying const raw pointer type.

Detailed Description

The opaque handle that represents an audio stream.

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.

See also

CreateAudioStream

Category:

Resource

Constructor & Destructor Documentation

AudioStream()

SDL::AudioStream::AudioStream ( AudioStreamRaw resource )

inlineexplicitconstexprnoexcept

Constructs from raw AudioStream.

Parameters

resource

a AudioStreamRaw to be wrapped.

This assumes the ownership, call release() if you need to take back.

Member Function Documentation

GetInputFormat()

AudioSpec SDL::AudioStream::GetInputFormat ( ) const

inline

Query the current input format of an audio stream.

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

AudioStream.SetFormat

GetOutputFormat()

AudioSpec SDL::AudioStream::GetOutputFormat ( ) const

inline

Query the current output format of an audio stream.

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

AudioStream.SetFormat

SetInputFormat()

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

inline

Change the input format of an audio stream.

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

AudioStream.GetFormat

AudioStream.SetFrequencyRatio

SetOutputFormat()

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

inline

Change the output format of an audio stream.

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

AudioStream.GetFormat

AudioStream.SetFrequencyRatio

---

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

• SDL3pp/SDL3pp_audio.h