Semi-safe reference for AudioStream.

Inheritance diagram for SDL::AudioStreamRef:

Collaboration diagram for SDL::AudioStreamRef:

Public Member Functions
	AudioStreamRef (AudioStreamParam resource) noexcept
	Constructs from AudioStreamParam. More...

	AudioStreamRef (AudioStreamRaw resource) noexcept
	Constructs from AudioStreamParam. More...

	AudioStreamRef (const AudioStreamRef &other) noexcept
	Copy constructor.

	~AudioStreamRef ()
	Destructor.

constexpr	AudioStream (std::nullptr_t=nullptr) noexcept
	Default ctor.

constexpr	AudioStream (const AudioStreamRaw resource) noexcept
	Constructs from AudioStreamParam. More...

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. More...

	AudioStream (AudioDeviceParam devid, OptionalRef< const AudioSpec > spec=std::nullopt, AudioStreamCallback callback=nullptr, void *userdata=nullptr)
	Convenience function for straightforward audio init for the common case. More...

	AudioStream (AudioDeviceParam devid, OptionalRef< const AudioSpec > spec, AudioStreamCB callback)
	Convenience function for straightforward audio init for the common case. More...

Public Member Functions inherited from SDL::AudioStream
constexpr	AudioStream (std::nullptr_t=nullptr) noexcept
	Default ctor.

constexpr	AudioStream (const AudioStreamRaw resource) noexcept
	Constructs from AudioStreamParam. More...

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. More...

	AudioStream (AudioDeviceParam devid, OptionalRef< const AudioSpec > spec=std::nullopt, AudioStreamCallback callback=nullptr, void *userdata=nullptr)
	Convenience function for straightforward audio init for the common case. More...

	AudioStream (AudioDeviceParam devid, OptionalRef< const AudioSpec > spec, AudioStreamCB callback)
	Convenience function for straightforward audio init for the common case. More...

	~AudioStream ()
	Destructor.

constexpr AudioStream &	operator= (AudioStream &&other) noexcept
	Assignment operator.

constexpr AudioStreamRaw	get () const noexcept
	Retrieves underlying AudioStreamRaw.

constexpr AudioStreamRaw	release () noexcept
	Retrieves underlying AudioStreamRaw and clear this.

constexpr auto	operator<=> (const AudioStream &other) const noexcept=default
	Comparison.

constexpr	operator bool () const noexcept
	Converts to bool.

constexpr	operator AudioStreamParam () const noexcept
	Converts to AudioStreamParam.

void	Destroy ()
	Free an audio stream. More...

PropertiesRef	GetProperties () const
	Get the properties associated with an audio stream. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void	Lock ()
	Lock an audio stream for serialized access. More...

void	Unlock ()
	Unlock an audio stream for serialized access. More...

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

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

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

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

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

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

Additional Inherited Members
Protected Member Functions inherited from SDL::AudioStream
constexpr AudioStream &	operator= (const AudioStream &other) noexcept=default
	Assignment operator.

Constructor & Destructor Documentation

◆ AudioStreamRef() [1/2]

SDL::AudioStreamRef::AudioStreamRef ( AudioStreamParam resource )

inlinenoexcept

Parameters

resource a AudioStreamRaw or AudioStream.

This does not takes ownership!

◆ AudioStreamRef() [2/2]

SDL::AudioStreamRef::AudioStreamRef ( AudioStreamRaw resource )

inlinenoexcept

Parameters

resource a AudioStreamRaw or AudioStream.

This does not takes ownership!

Member Function Documentation

◆ AudioStream() [1/4]

SDL::AudioStream::AudioStream	(	AudioDeviceParam	devid,
		OptionalRef< const AudioSpec >	spec,
		AudioStreamCB	callback
	)

inline

If all your app intends to do is provide a single source of PCM audio, this function allows you to do all your audio setup in a single call.

This is also intended to be a clean means to migrate apps from SDL2.

This function will open an audio device, create a stream and bind it. Unlike other methods of setup, the audio device will be closed when this stream is destroyed, so the app can treat the returned AudioStream as the only object needed to manage audio playback.

Also unlike other functions, the audio device begins paused. This is to map more closely to SDL2-style behavior, since there is no extra step here to bind a stream to begin audio flowing. The audio device should be resumed with AudioStream.ResumeDevice(stream);

This function works with both playback and recording devices.

The spec parameter represents the app's side of the audio stream. That is, for recording audio, this will be the output format, and for playing audio, this will be the input format. If spec is nullptr, the system will choose the format, and the app can use AudioStream.GetFormat() to obtain this information later.

If you don't care about opening a specific audio device, you can (and probably should), use AUDIO_DEVICE_DEFAULT_PLAYBACK for playback and AUDIO_DEVICE_DEFAULT_RECORDING for recording.

One can optionally provide a callback function; if nullptr, the app is expected to queue audio data for playback (or unqueue audio data if capturing). Otherwise, the callback will begin to fire once the device is unpaused.

Destroying the returned stream with AudioStream.Destroy will also close the audio device associated with this stream.

Parameters

devid	an audio device to open, or AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING.
spec	the audio stream's data format. Can be nullptr.
callback	a callback where the app will provide new data for playback, or receive new data for recording.

Postcondition: an audio stream 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.

See also: AudioStream.GetDevice; AudioStream.ResumeDevice

◆ AudioStream() [2/4]

SDL::AudioStream::AudioStream	(	AudioDeviceParam	devid,
		OptionalRef< const AudioSpec >	spec = `std::nullopt`,
		AudioStreamCallback	callback = `nullptr`,
		void *	userdata = `nullptr`
	)