SDL Audio Device instance IDs. More...

Inheritance diagram for SDL::AudioDevice:

Public Member Functions
constexpr	AudioDevice ()=default
	Default ctor.

constexpr	AudioDevice (const AudioDeviceID resource)
	Constructs from AudioDeviceParam. More...

constexpr	AudioDevice (const AudioDevice &other)=delete
	Copy constructor.

constexpr	AudioDevice (AudioDevice &&other)
	Move constructor.

constexpr	AudioDevice (const AudioDeviceRef &other)=delete

constexpr	AudioDevice (AudioDeviceRef &&other)=delete

	AudioDevice (AudioDeviceParam devid, OptionalRef< const AudioSpec > spec)
	Open a specific audio device. More...

	~AudioDevice ()
	Destructor.

AudioDevice &	operator= (AudioDevice other)
	Assignment operator.

constexpr AudioDeviceID	get () const
	Retrieves underlying AudioDeviceID.

constexpr AudioDeviceID	release ()
	Retrieves underlying AudioDeviceID and clear this.

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

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

constexpr	operator bool () const
	Converts to bool.

constexpr	operator AudioDeviceParam () const
	Converts to AudioDeviceParam.

void	Close ()
	Close a previously-opened audio device. More...

const char *	GetName () const
	Get the human-readable name of a specific audio device. More...

AudioSpec	GetFormat (int *sample_frames=nullptr) const
	Get the current audio format of a specific audio device. More...

OwnArray< int >	GetChannelMap () const
	Get the current channel map of an audio device. More...

bool	IsPhysical () const
	Determine if an audio device is physical (instead of logical). More...

bool	IsPlayback () const
	Determine if an audio device is a playback device (instead of recording). More...

void	Pause ()
	Use this function to pause audio playback on a specified device. More...

void	Resume ()
	Use this function to unpause audio playback on a specified device. More...

bool	Paused () const
	Use this function to query if an audio device is paused. More...

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

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

void	BindAudioStreams (std::span< AudioStreamRef > streams)
	Bind a list of audio streams to an audio device. More...

void	BindAudioStream (AudioStreamParam stream)
	Bind a single audio stream to an audio device. More...

void	SetPostmixCallback (AudioPostmixCB callback)
	Set a callback that fires when data is about to be fed to an audio device. More...

void	SetPostmixCallback (AudioPostmixCallback callback, void *userdata)
	Set a callback that fires when data is about to be fed to an audio device. More...

AudioStream	OpenStream (OptionalRef< const AudioSpec > spec, AudioStreamCallback callback, void *userdata)
	Convenience function for straightforward audio init for the common case. More...

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

Detailed Description

Zero is used to signify an invalid/null device.

Since: This datatype is available since SDL 3.2.0.

Category:: Resource

Constructor & Destructor Documentation

◆ AudioDevice() [1/2]

constexpr SDL::AudioDevice::AudioDevice ( const AudioDeviceID resource )

inlineexplicitconstexpr

Parameters

resource a AudioDeviceID to be wrapped.

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

◆ AudioDevice() [2/2]

SDL::AudioDevice::AudioDevice	(	AudioDeviceParam	devid,
		OptionalRef< const AudioSpec >	spec
	)

inline

You can open both playback and recording devices through this function. Playback devices will take data from bound audio streams, mix it, and send it to the hardware. Recording devices will feed any bound audio streams with a copy of any incoming data.

An opened audio device starts out with no audio streams bound. To start audio playing, bind a stream and supply audio data to it. Unlike SDL2, there is no audio callback; you only bind audio streams and make sure they have data flowing into them (however, you can simulate SDL2's semantics fairly closely by using AudioStream.AudioStream instead of this function).

If you don't care about opening a specific device, pass a devid of either AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING. In this case, SDL will try to pick the most reasonable default, and may also switch between physical devices seamlessly later, if the most reasonable default changes during the lifetime of this opened device (user changed the default in the OS's system preferences, the default got unplugged so the system jumped to a new default, the user plugged in headphones on a mobile device, etc). Unless you have a good reason to choose a specific device, this is probably what you want.

You may request a specific format for the audio device, but there is no promise the device will honor that request for several reasons. As such, it's only meant to be a hint as to what data your app will provide. Audio streams will accept data in whatever format you specify and manage conversion for you as appropriate. AudioDevice.GetFormat can tell you the preferred format for the device before opening and the actual format the device is using after opening.

It's legal to open the same device ID more than once; each successful open will generate a new logical AudioDevice that is managed separately from others on the same physical device. This allows libraries to open a device separately from the main app and bind its own streams without conflicting.

It is also legal to open a device ID returned by a previous call to this function; doing so just creates another logical device on the same physical device. This may be useful for making logical groupings of audio streams.

This function returns the opened device ID on success. This is a new, unique AudioDevice that represents a logical device.

Some backends might offer arbitrary devices (for example, a networked audio protocol that can connect to an arbitrary server). For these, as a change from SDL2, you should open a default device ID and use an SDL hint to specify the target if you care, or otherwise let the backend figure out a reasonable default. Most backends don't offer anything like this, and often this would be an end user setting an environment variable for their custom need, and not something an application should specifically manage.

When done with an audio device, possibly at the end of the app's life, one should call AudioDevice.Close() on the returned device id.

Parameters

devid	the device instance id to open, or AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING for the most reasonable default device.
spec	the requested device configuration. Can be nullptr to use reasonable defaults.

Postcondition: the device 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.

See also: AudioDevice.Close; AudioDevice.GetFormat

Member Function Documentation

◆ SetPostmixCallback()

void SDL::AudioDevice::SetPostmixCallback ( AudioPostmixCB callback )

This is useful for accessing the final mix, perhaps for writing a visualizer or applying a final effect to the audio data before playback.

The buffer is the final mix of all bound audio streams on an opened device; this callback will fire regularly for any device that is both opened and unpaused. If there is no new data to mix, either because no streams are bound to the device or all the streams are empty, this callback will still fire with the entire buffer set to silence.

This callback is allowed to make changes to the data; the contents of the buffer after this call is what is ultimately passed along to the hardware.

The callback is always provided the data in float format (values from -1.0f to 1.0f), but the number of channels or sample rate may be different than the format the app requested when opening the device; SDL might have had to manage a conversion behind the scenes, or the playback might have jumped to new physical hardware when a system default changed, etc. These details may change between calls. Accordingly, the size of the buffer might change between calls as well.

This callback can run at any time, and from any thread; if you need to serialize access to your app's data, you should provide and use a mutex or other synchronization device.

All of this to say: there are specific needs this callback can fulfill, but it is not the simplest interface. Apps should generally provide audio in their preferred format through an AudioStream and let SDL handle the difference.

This function is extremely time-sensitive; the callback should do the least amount of work possible and return as quickly as it can. The longer the callback runs, the higher the risk of audio dropouts or other problems.

This function will block until the audio device is in between iterations, so any existing callback that might be running will finish before this function sets the new callback and returns.

Setting a nullptr callback function disables any previously-set callback.

Parameters

callback a callback function to be called. Can be nullptr.

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.

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

SDL3pp/SDL3pp_audio.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ AudioDevice() [1/2]

◆ AudioDevice() [2/2]

Member Function Documentation

◆ SetPostmixCallback()