Persistent system for playing sound in a simulated 3D arena to the default audio device. More...

#include <donut/audio/SoundStage.hpp>

Public Types
using	SoundInstanceId = unsigned
	Opaque handle to a specific instance of a sound in the sound stage. More...

Public Member Functions
	SoundStage (const SoundStageOptions &options={})
	Construct a sound stage. More...

void	update (Time< float > deltaTime, const Listener &listener)
	Update the 3D parameters of the sound stage and advance the current time. More...

SoundInstanceId	playSound (const Sound &sound, float volume=-1.0f, vec3 position={0.0f, 0.0f, 0.0f}, vec3 velocity={0.0f, 0.0f, 0.0f})
	Create a new 3D sound instance and start playing it. More...

SoundInstanceId	playSoundInBackground (const Sound &sound, float volume=-1.0f)
	Create a new sound instance without any panning and start playing it. More...

SoundInstanceId	createPausedSoundInBackground (const Sound &sound, float volume=-1.0f)
	Create a new sound instance without any panning, but don't start playing it yet. More...

bool	isSoundPaused (SoundInstanceId id) const noexcept
	Check if a specific sound instance is currently paused. More...

bool	isSoundStopped (SoundInstanceId id) const noexcept
	Check if a specific sound instance has finished playing. More...

void	stopSound (SoundInstanceId id)
	Stop a specific sound instance and remove it. More...

void	pauseSound (SoundInstanceId id)
	Pause a specific sound instance. More...

void	resumeSound (SoundInstanceId id)
	Unpause and resume a specific sound instance. More...

void	scheduleSoundStop (SoundInstanceId id, Time< float > timePointInSound)
	Schedule for a specific sound instance to stop playing and remove itself when the playback reaches a specific time point. More...

void	scheduleSoundPause (SoundInstanceId id, Time< float > timePointInSound)
	Schedule for a specific sound instance to pause itself when the playback reaches a specific time point. More...

void	seekToSoundTime (SoundInstanceId id, Time< float > timePointInSound)
	Set the current playback time point for a specific sound instance. More...

void	setSoundPosition (SoundInstanceId id, vec3 newPosition)
	Set the current 3D position of a specific sound instance. More...

void	setSoundVelocity (SoundInstanceId id, vec3 newVelocity)
	Set the current 3D velocity of a specific sound instance. More...

void	setSoundPositionAndVelocity (SoundInstanceId id, vec3 newPosition, vec3 newVelocity)
	Set both the 3D position and 3D velocity of a specific sound instance at the same time. More...

void	setSoundVolume (SoundInstanceId id, float volume)
	Set the volume of a specific sound instance. More...

void	fadeSoundVolume (SoundInstanceId id, float targetVolume, float fadeDuration)
	Fade the volume of a specific sound instance towards a target volume over a given duration. More...

void	setSoundPlaybackSpeed (SoundInstanceId id, float playbackSpeed)
	Set the relative playback speed of a specific sound instance. More...

void	fadeSoundPlaybackSpeed (SoundInstanceId id, float targetPlaybackSpeed, float fadeDuration)
	Fade the relative playback speed of a specific sound instance towards a target relative playback speed over a given duration. More...

void	setVolume (float volume)
	Set the global master volume of the sound stage. More...

void	fadeVolume (float targetVolume, float fadeDuration)
	Fade the global master volume of the sound stage towards a target volume over a given duration. More...

void	setSpeedOfSound (float speedOfSound)
	Set the speed of sound in the sound stage. More...

void	setMaxSimultaneousSounds (unsigned maxSimultaneousSounds)
	Set the maximum total number of sound instances that can play simultaneously. More...

Detailed Description

Persistent system for playing sound in a simulated 3D arena to the default audio device.

The sound stage uses a right-handed coordinate system for 3D calculations, and any coordinates are assumed to be in meters by default. Applications that use a different unit of length should adjust the SoundStageOptions::speedOfSound in the sound stage configuration as well as the SoundOptions::rolloffFactor of each Sound accordingly.

Member Typedef Documentation

◆ SoundInstanceId

using donut::audio::SoundStage::SoundInstanceId = unsigned

Opaque handle to a specific instance of a sound in the sound stage.

Examples: example_game.cpp.

Constructor & Destructor Documentation

◆ SoundStage()

donut::audio::SoundStage::SoundStage ( const SoundStageOptions & options = {} )

explicit

Construct a sound stage.

Parameters

options initial configuration of the sound stage, see SoundStageOptions.

Exceptions

audio::Error	on failure to initialize the underlying audio engine.
std::bad_alloc	on allocation failure.

Warning: Due to having global access to the default audio device, only a single SoundManager instance may exist in the program at any given time.

Member Function Documentation

◆ update()

void donut::audio::SoundStage::update	(	Time< float >	deltaTime,
		const Listener &	listener
	)

Update the 3D parameters of the sound stage and advance the current time.

Parameters

deltaTime	time delta to advance the time by, in seconds, typically received from the current application::FrameInfo in application::Application::update().
listener	current parameters to use for the sound listener on this frame.

Note: This function should typically be called once every frame during the application::Application::update() callback.

◆ playSound()

SoundInstanceId donut::audio::SoundStage::playSound	(	const Sound &	sound,
		float	volume = `-1.0f`,
		vec3	position = `{0.0f, 0.0f, 0.0f}`,
		vec3	velocity = `{0.0f, 0.0f, 0.0f}`
	)

Create a new 3D sound instance and start playing it.

Parameters

sound	the sound data to use for this instance.
volume	gain to multiply the amplitude of the sound by when playing. If negative, the default volume set in the SoundOptions is used instead.
position	the position to play the sound at, in sound stage coordinates. Used for distance attenuation/falloff according to the SoundAttenuationModel set in the sound's SoundOptions.
velocity	initial linear velocity of the sound. Relevant for simulating the doppler effect.

Returns: a handle to the new sound instance that can be used to refer back to it later in order to query its state or make changes to it.

See also: playSoundInBackground(); createPausedSoundInBackground()

◆ playSoundInBackground()

SoundInstanceId donut::audio::SoundStage::playSoundInBackground	(	const Sound &	sound,
		float	volume = `-1.0f`
	)

Create a new sound instance without any panning and start playing it.

Parameters

sound	the sound data to use for this instance.
volume	gain to multiply the amplitude of the sound by when playing. If negative, the default volume set in the SoundOptions is used instead.

Returns: a handle to the new sound instance that can be used to refer back to it later in order to query its state or make changes to it.

See also: playSound(); createPausedSoundInBackground()

◆ createPausedSoundInBackground()

SoundInstanceId donut::audio::SoundStage::createPausedSoundInBackground	(	const Sound &	sound,
		float	volume = `-1.0f`
	)

Create a new sound instance without any panning, but don't start playing it yet.

Parameters

sound	the sound data to use for this instance.
volume	gain to multiply the amplitude of the sound by when playing. If negative, the default volume set in the SoundOptions is used instead.

Returns: a handle to the new sound instance that can be used to refer back to it later in order to query its state or make changes to it.

See also: playSound(); playSoundInBackground()

◆ isSoundPaused()

bool donut::audio::SoundStage::isSoundPaused ( SoundInstanceId id ) const

noexcept

Check if a specific sound instance is currently paused.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.

Returns: true if the sound instance still exists and is currently paused, false otherwise.

See also: isSoundStopped(); pauseSound(); resumeSound()

◆ isSoundStopped()

bool donut::audio::SoundStage::isSoundStopped ( SoundInstanceId id ) const

noexcept

Check if a specific sound instance has finished playing.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.

Returns: true if the sound instance has been stopped or finished playing and no longer exists, false otherwise.

See also: isSoundPaused(); stopSound()

◆ stopSound()

void donut::audio::SoundStage::stopSound ( SoundInstanceId id )

Stop a specific sound instance and remove it.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.

Note: If the given sound instance doesn't exist, this function has no effect.

See also: isSoundStopped(); scheduleSoundStop()

◆ pauseSound()

void donut::audio::SoundStage::pauseSound ( SoundInstanceId id )

Pause a specific sound instance.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.

Note: If the given sound instance doesn't exist, or if it is already paused, this function has no effect.

See also: isSoundPaused(); resumeSound(); scheduleSoundPause()

◆ resumeSound()

void donut::audio::SoundStage::resumeSound ( SoundInstanceId id )

Unpause and resume a specific sound instance.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.

Note: If the given sound instance doesn't exist, or if it is not paused, this function has no effect.

See also: isSoundPaused(); pauseSound()

◆ scheduleSoundStop()

void donut::audio::SoundStage::scheduleSoundStop	(	SoundInstanceId	id,
		Time< float >	timePointInSound
	)

Schedule for a specific sound instance to stop playing and remove itself when the playback reaches a specific time point.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.
timePointInSound	the time point, measured in seconds from the beginning of the sound, where the sound instance will stop itself.

Note: If the given sound instance doesn't exist, this function has no effect.

See also: isSoundStopped(); stopSound()

◆ scheduleSoundPause()

void donut::audio::SoundStage::scheduleSoundPause	(	SoundInstanceId	id,
		Time< float >	timePointInSound
	)

Schedule for a specific sound instance to pause itself when the playback reaches a specific time point.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.
timePointInSound	the time point, measured in seconds from the beginning of the sound, where the sound instance will pause itself.

Note: If the given sound instance doesn't exist, this function has no effect.

See also: isSoundPaused(); pauseSound()

◆ seekToSoundTime()

void donut::audio::SoundStage::seekToSoundTime	(	SoundInstanceId	id,
		Time< float >	timePointInSound
	)

Set the current playback time point for a specific sound instance.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.
timePointInSound	the time point, measured in seconds from the beginning of the sound, to seek to.

Note: If the given sound instance exists, it will continue playing after seeking unless it was paused.; If the given sound instance doesn't exist, this function has no effect.

◆ setSoundPosition()

void donut::audio::SoundStage::setSoundPosition	(	SoundInstanceId	id,
		vec3	newPosition
	)

Set the current 3D position of a specific sound instance.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.
newPosition	new position of the sound instance, in sound stage coordinates.

Note: The effect of this function will only apply after the next call to update().; If the given sound instance doesn't exist, this function has no effect.

See also: setSoundVelocity(); setSoundPositionAndVelocity()

◆ setSoundVelocity()

void donut::audio::SoundStage::setSoundVelocity	(	SoundInstanceId	id,
		vec3	newVelocity
	)

Set the current 3D velocity of a specific sound instance.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.
newVelocity	new linear velocity of the sound instance.

Note: The effect of this function will only apply after the next call to update().; If the given sound instance doesn't exist, this function has no effect.

See also: setSoundPosition(); setSoundPositionAndVelocity()

◆ setSoundPositionAndVelocity()

void donut::audio::SoundStage::setSoundPositionAndVelocity	(	SoundInstanceId	id,
		vec3	newPosition,
		vec3	newVelocity
	)

Set both the 3D position and 3D velocity of a specific sound instance at the same time.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.
newPosition	new position of the sound instance, in sound stage coordinates.
newVelocity	new linear velocity of the sound instance.

Note: The effect of this function will only apply after the next call to update().; If the given sound instance doesn't exist, this function has no effect.

See also: setSoundPosition(); setSoundVelocity()

◆ setSoundVolume()

void donut::audio::SoundStage::setSoundVolume	(	SoundInstanceId	id,
		float	volume
	)

Set the volume of a specific sound instance.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.
volume	new volume, see SoundOptions::volume.

Note: If the given sound instance doesn't exist, this function has no effect.

See also: setVolume(); fadeSoundVolume()

◆ fadeSoundVolume()

void donut::audio::SoundStage::fadeSoundVolume	(	SoundInstanceId	id,
		float	targetVolume,
		float	fadeDuration
	)

Fade the volume of a specific sound instance towards a target volume over a given duration.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.
targetVolume	new volume to fade towards, see SoundOptions::volume.
fadeDuration	duration of time, in seconds, to fade over.

Note: If the given sound instance doesn't exist, this function has no effect.

See also: setSoundVolume()

◆ setSoundPlaybackSpeed()

void donut::audio::SoundStage::setSoundPlaybackSpeed	(	SoundInstanceId	id,
		float	playbackSpeed
	)

Set the relative playback speed of a specific sound instance.

The effective sample rate of the playing sound is adjusted by this factor, meaning that a value of 1 represents no change, i.e. 100% of the original playback speed of the loaded sound file.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.
playbackSpeed	new relative playback speed. Must be greater than 0.

Note: If the given sound instance doesn't exist, this function has no effect.

See also: fadeSoundPlaybackSpeed()

◆ fadeSoundPlaybackSpeed()

void donut::audio::SoundStage::fadeSoundPlaybackSpeed	(	SoundInstanceId	id,
		float	targetPlaybackSpeed,
		float	fadeDuration
	)

Fade the relative playback speed of a specific sound instance towards a target relative playback speed over a given duration.

Parameters

id	handle to the sound instance, acquired from when the sound instance was created.
targetPlaybackSpeed	new relative playback speed to fade towards. Must be greater than 0.
fadeDuration	duration of time, in seconds, to fade over.

Note: If the given sound instance doesn't exist, this function has no effect.

See also: setSoundPlaybackSpeed()

◆ setVolume()

void donut::audio::SoundStage::setVolume ( float volume )

Set the global master volume of the sound stage.

Parameters

volume new volume, see SoundStageOptions::volume.

See also: setSoundVolume(); fadeVolume()

◆ fadeVolume()

void donut::audio::SoundStage::fadeVolume	(	float	targetVolume,
		float	fadeDuration
	)

Fade the global master volume of the sound stage towards a target volume over a given duration.

Parameters

targetVolume	new volume to fade towards, see SoundStageOptions::volume.
fadeDuration	duration of time, in seconds, to fade over.

See also: setVolume()

◆ setSpeedOfSound()

void donut::audio::SoundStage::setSpeedOfSound ( float speedOfSound )

Set the speed of sound in the sound stage.

Parameters

speedOfSound new speed of sound, see SoundStageOptions::speedOfSound.

◆ setMaxSimultaneousSounds()

void donut::audio::SoundStage::setMaxSimultaneousSounds ( unsigned maxSimultaneousSounds )

Set the maximum total number of sound instances that can play simultaneously.

Parameters

maxSimultaneousSounds new number of sound instances, see SoundStageOptions::maxSimultaneousSounds.

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

include/donut/audio/SoundStage.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ SoundInstanceId

Constructor & Destructor Documentation

◆ SoundStage()

Member Function Documentation

◆ update()

◆ playSound()

◆ playSoundInBackground()

◆ createPausedSoundInBackground()

◆ isSoundPaused()

◆ isSoundStopped()

◆ stopSound()

◆ pauseSound()

◆ resumeSound()

◆ scheduleSoundStop()

◆ scheduleSoundPause()

◆ seekToSoundTime()

◆ setSoundPosition()

◆ setSoundVelocity()

◆ setSoundPositionAndVelocity()

◆ setSoundVolume()

◆ fadeSoundVolume()

◆ setSoundPlaybackSpeed()

◆ fadeSoundPlaybackSpeed()

◆ setVolume()

◆ fadeVolume()

◆ setSpeedOfSound()

◆ setMaxSimultaneousSounds()