SDL Audio Device instance IDs. More...

Inheritance diagram for SDL::AudioDeviceRef:

Public Member Functions
constexpr auto	operator<=> (AudioDeviceRef other) const
	Comparison.

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

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

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

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

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

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

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

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

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

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

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

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

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

void	SetPostmixCallback (AudioPostmixCallback callback, void *userdata)
	Set a callback that fires when data is about to be fed to an audio 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_AudioDeviceID >
constexpr	Resource (SDL_AudioDeviceID resource={})
	Constructs from the underlying resource.

constexpr	Resource (const ResourceHandle< Resource< SDL_AudioDeviceID > > 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_AudioDeviceID	get () const
	Return contained resource;.

constexpr const SDL_AudioDeviceID	operator-> () const
	Access to fields.

constexpr SDL_AudioDeviceID	operator-> ()
	Access to fields.

Static Public Member Functions
static void	reset (SDL_AudioDeviceID resource)
	Close a previously-opened audio device.

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

Detailed Description

Zero is used to signify an invalid/null device.

Since: This datatype is available since SDL 3.2.0.

Category:: Resource

See also: AudioDevice

Member Function Documentation

◆ GetChannelMap()

OwnArray< int > SDL::AudioDeviceRef::GetChannelMap ( ) const

inline

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

Audio devices usually have 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.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.SetInputChannelMap

◆ GetFormat()

AudioSpec SDL::AudioDeviceRef::GetFormat ( int * sample_frames = nullptr ) const

inline

For an opened device, this will report the format the device is currently using. If the device isn't yet opened, this will report the device's preferred format (or a reasonable default if this can't be determined).

You may also specify AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING here, which is useful for getting a reasonable recommendation before opening the system-recommended default device.

You can also use this to request the current device buffer size. This is specified in sample frames and represents the amount of data SDL will feed to the physical hardware in each chunk. This can be converted to milliseconds of audio with the following equation:

ms = (int) ((((Sint64) frames) * 1000) / spec.freq);

Buffer size is only important if you need low-level control over the audio playback timing. Most apps do not need this.

Parameters

sample_frames pointer to store device buffer size, in sample frames. Can be nullptr.

Returns: the device format details 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.

◆ GetGain()

float SDL::AudioDeviceRef::GetGain ( ) const

inline

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

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

Physical devices may not have their gain changed, only logical devices, and this function will always return -1.0f when used on physical devices.

Returns: the gain of the device or -1.0f 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: AudioDeviceRef.SetGain

◆ GetName()

const char * SDL::AudioDeviceRef::GetName ( ) const

inline

Returns: the name of the audio device, or nullptr 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: GetAudioPlaybackDevices; GetAudioRecordingDevices

◆ IsPhysical()

bool SDL::AudioDeviceRef::IsPhysical ( ) const

inline

An AudioDevice that represents physical hardware is a physical device; there is one for each piece of hardware that SDL can see. Logical devices are created by calling AudioDevice.Open or AudioStream.OpenAudioDeviceStream, and while each is associated with a physical device, there can be any number of logical devices on one physical device.

For the most part, logical and physical IDs are interchangeable–if you try to open a logical device, SDL understands to assign that effort to the underlying physical device, etc. However, it might be useful to know if an arbitrary device ID is physical or logical. This function reports which.

This function may return either true or false for invalid device IDs.

Returns: true if devid is a physical device, false if it is logical.

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

Since: This function is available since SDL 3.2.0.

◆ IsPlayback()

bool SDL::AudioDeviceRef::IsPlayback ( ) const

inline

This function may return either true or false for invalid device IDs.

Returns: true if devid is a playback device, false if it is recording.

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

Since: This function is available since SDL 3.2.0.

◆ Pause()

void SDL::AudioDeviceRef::Pause ( )

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.

Unlike in SDL2, audio devices start in an unpaused state, since an app has to bind a stream before any audio will flow. Pausing a paused device is a legal no-op.

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.

Physical devices can not be paused or unpaused, only logical devices created through AudioDevice.Open() can be.

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.Resume; AudioDeviceRef.Paused

◆ Paused()

bool SDL::AudioDeviceRef::Paused ( ) 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.

Physical devices can not be paused or unpaused, only logical devices created through AudioDevice.Open() can be. Physical and invalid device IDs will report themselves as unpaused here.

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: AudioDeviceRef.Pause; AudioDeviceRef.Resume

◆ reset()

static void SDL::AudioDeviceRef::reset ( SDL_AudioDeviceID resource )

inlinestatic

The application should close open audio devices once they are no longer needed.

This function may block briefly while pending audio data is played by the hardware, so that applications don't drop the last buffer of data they supplied if terminating immediately afterwards.

Parameters

resource an audio device id previously returned by AudioDevice.Open().

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

◆ Resume()

void SDL::AudioDeviceRef::Resume ( )

inline

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

Unlike in SDL2, audio devices start in an unpaused state, since an app has to bind a stream before any audio will flow. Unpausing an unpaused device is a legal no-op.

Physical devices can not be paused or unpaused, only logical devices created through AudioDevice.Open() can be.

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.Paused; AudioDeviceRef.Pause

◆ SetGain()

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

inline

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

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

Physical devices may not have their gain changed, only logical devices, and this function will always return false when used on physical devices. While it might seem attractive to adjust several logical devices at once in this way, it would allow an app or library to interfere with another portion of the program's otherwise-isolated devices.

This is applied, along with any per-audiostream gain, during playback to the hardware, and can be continuously changed to create various effects. On recording devices, this will adjust the gain before passing the data into an audiostream; that recording audiostream can then adjust its gain further when outputting the data elsewhere, if it likes, but that second gain is not applied until the data leaves the audiostream again.

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: AudioDeviceRef.GetGain

◆ SetPostmixCallback() [1/2]

void SDL::AudioDeviceRef::SetPostmixCallback	(	AudioPostmixCallback	callback,
		void *	userdata
	)

inline

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.
userdata	app-controlled pointer passed to callback. 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.

◆ SetPostmixCallback() [2/2]

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

inline

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 AudioStreamRef 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 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

◆ GetChannelMap()

◆ GetFormat()

◆ GetGain()

◆ GetName()

◆ IsPhysical()

◆ IsPlayback()

◆ Pause()

◆ Paused()

◆ reset()

◆ Resume()

◆ SetGain()

◆ SetPostmixCallback() [1/2]

◆ SetPostmixCallback() [2/2]