SFXManager Class Reference

Manager of all sound effects. More...

#include <sfx_manager.hpp>

Inheritance diagram for SFXManager:

Classes
class	SFXCommand
	Data structure for the queue, which stores a sfx and the command to execute for it. More...

Public Types
enum	SFXCommands {   SFX_PLAY = 1 , SFX_PLAY_POSITION , SFX_STOP , SFX_PAUSE ,   SFX_PAUSE_ALL , SFX_RESUME , SFX_RESUME_ALL , SFX_DELETE ,   SFX_SPEED , SFX_POSITION , SFX_SPEED_POSITION , SFX_VOLUME ,   SFX_MASTER_VOLUME , SFX_LOOP , SFX_LISTENER , SFX_UPDATE ,   SFX_MUSIC_START , SFX_MUSIC_STOP , SFX_MUSIC_PAUSE , SFX_MUSIC_RESUME ,   SFX_MUSIC_SWITCH_FAST , SFX_MUSIC_SET_TMP_VOLUME , SFX_MUSIC_WAITING , SFX_MUSIC_DEFAULT_VOLUME ,   SFX_EXIT , SFX_CREATE_SOURCE }
	The various commands to be executed by the sfx manager thread for each sfx.
enum	CustomSFX : int {   CUSTOM_HORN , CUSTOM_CRASH , CUSTOM_WIN , CUSTOM_EXPLODE ,   CUSTOM_GOO , CUSTOM_PASS , CUSTOM_ZIPPER , CUSTOM_NAME ,   CUSTOM_ATTACH , CUSTOM_SHOOT , NUM_CUSTOMS }
	Entries for custom SFX sounds. More...

Public Member Functions
void	queue (SFXCommands command, SFXBase *sfx=NULL)
	Adds a sound effect command to the queue of the sfx manager.
void	queue (SFXCommands command, SFXBase *sfx, float f)
	Adds a sound effect command with a single floating point parameter to the queue of the sfx manager.
void	queue (SFXCommands command, SFXBase *sfx, const Vec3 &p)
	Adds a sound effect command with a Vec3 parameter to the queue of the sfx manager.
void	queue (SFXCommands command, SFXBase *sfx, float f, const Vec3 &p)
	Adds a sound effect command with a float and a Vec3 parameter to the queue of the sfx manager.
void	queue (SFXCommands command, MusicInformation *mi)
	Queues a command for the music manager.
void	queue (SFXCommands command, MusicInformation *mi, float f)
	Queues a command for the music manager that takes a floating point value (e.g.
void	queue (SFXCommands command, SFXBase *sfx, const Vec3 &p, SFXBuffer *buffer)
void	stopThread ()
	Puts a NULL request into the queue, which will trigger the thread to exit.
bool	sfxAllowed ()
	Returns if sfx can be played.
SFXBuffer *	loadSingleSfx (const XMLNode *node, const std::string &path=std::string(""), const bool load=true)
	Loads a single sfx from the XML specification.
SFXBuffer *	addSingleSfx (const std::string &sfx_name, const std::string &filename, bool positional, float rolloff, float max_dist, float gain, const bool load=true)
	Introduces a mechanism by which one can load sound effects beyond the basic enumerated types.
SFXBase *	createSoundSource (SFXBuffer *info, const bool add_to_SFX_list=true, const bool owns_buffer=false)
	Creates a new SFX object.
SFXBase *	createSoundSource (const std::string &name, const bool addToSFXList=true)
void	deleteSFXMapping (const std::string &name)
	This function removes a sfx buffer info entry from the mapping, and frees the openal buffer.
void	pauseAll ()
	Pauses all looping SFXs.
void	reallyPauseAllNow ()
	Pauses all looping SFXs.
void	resumeAll ()
	Resumes all paused SFXs.
void	reallyResumeAllNow ()
	Resumes all paused SFXs.
void	update ()
	Make sure that the sfx thread is started at least once per frame.
void	reallyUpdateNow (SFXCommand *current)
	Updates the status of all playing sfx (to test if they are finished).
bool	soundExist (const std::string &name)
	Returns true if a sfx with the given name exists.
void	setMasterSFXVolume (float gain)
	Sets the master volume for all sound effects.
float	getMasterSFXVolume () const
void	positionListener (const Vec3 &position, const Vec3 &front, const Vec3 &up)
	Sets the position and orientation of the listener.
SFXBase *	quickSound (const std::string &soundName)
	Positional sound is cool, but creating a new object just to play a simple menu sound is not.
void	toggleSound (const bool newValue)
	Called when sound was muted/unmuted.
void	dump ()
	Prints the list of currently loaded sounds to stdout.
Vec3	getListenerPos () const
	Returns the current position of the listener.
SFXBuffer *	getBuffer (const std::string &name)
Public Member Functions inherited from CanBeDeleted
	CanBeDeleted ()
	Set this instance to be not ready to be deleted.
void	setCanBeDeleted ()
	Sets this instance to be ready to be deleted.
void	resetCanBeDeleted ()
bool	canBeDeletedNow ()
bool	waitForReadyToDeleted (float waiting_time)
	Waits at most t seconds for this class to be ready to be deleted.

Static Public Member Functions
static void	create ()
	Static function to create the singleton sfx manager.
static void	destroy ()
	Static function to delete the singleton sfx manager.
static SFXManager *	get ()
	Static function to get the singleton sfx manager.
static bool	checkError (const std::string &context)
	Returns whether or not an openal error has occurred.
static const std::string	getErrorString (int err)

Private Member Functions
void	loadSfx ()
	Loads all sounds specified in the sound config file.
	SFXManager ()
	Initialises the SFX manager and loads the sfx from a config file.
virtual	~SFXManager ()
	Destructor, frees all sound effects.
void	deleteSFX (SFXBase *sfx)
	Delete a sound effect object, and removes it from the internal list of all SFXs.
void	queueCommand (SFXCommand *command)
	Enqueues a command to the sfx queue threadsafe.
void	reallyPositionListenerNow ()
	Sets the position and orientation of the listener.

Static Private Member Functions
static void	mainLoop (void *obj)
	This loops runs in a different threads, and starts sfx to be played.

Private Attributes
Synchronised< Vec3 >	m_listener_position
	The position of the listener.
Vec3	m_listener_front
	The direction the listener is facing.
Vec3	m_listener_up
	Up vector of the listener.
std::map< std::string, SFXBuffer * >	m_all_sfx_types
	The buffers and info for all sound effects.
Synchronised< std::vector< SFXBase * > >	m_all_sfx
	The actual instances (sound sources)
Synchronised< std::vector< SFXCommand * > >	m_sfx_commands
	The list of sound effects to be played in the next update.
Synchronised< std::map< std::string, SFXBase * > >	m_quick_sounds
	To play non-positional sounds without having to create a new object for each.
bool	m_initialized
	If the sfx manager has been initialised.
float	m_master_gain
	Master gain value, taken from the user config value.
std::thread	m_thread
	Thread id of the thread running in this object.
uint64_t	m_last_update_time
std::condition_variable	m_condition_variable
	A conditional variable to wake up the main loop.

Static Private Attributes
static SFXManager *	m_sfx_manager
	Singleton pointer.

Detailed Description

Manager of all sound effects.

The manager reads all sound effects and maintains the corresponding buffers. Each sound effect objects uses on of the (shared) buffers from the sound manager.

Member Enumeration Documentation

CustomSFX

enum SFXManager::CustomSFX : int

Entries for custom SFX sounds.

These are unique for each kart. eg. kart->playCustomSFX(SFX_MANAGER::CUSTOM_HORN)

Enumerator
CUSTOM_HORN	Replaces default horn.
CUSTOM_CRASH	Played when colliding with another kart.
CUSTOM_WIN	Played when racer wins.
CUSTOM_EXPLODE	Played when struck by bowling ball or dynamite.
CUSTOM_GOO	Played when driving through goo.
CUSTOM_PASS	Played when passing another kart.
CUSTOM_ZIPPER	Played when kart hits zipper.
CUSTOM_NAME	Introduction (e.g. "I'm Tux!")
CUSTOM_ATTACH	Played when something is attached to kart (Uh-Oh)
CUSTOM_SHOOT	Played when weapon is used.

Member Function Documentation

addSingleSfx()

SFXBuffer * SFXManager::addSingleSfx	(	const std::string &	sfx_name,
		const std::string &	sfx_file,
		bool	positional,
		float	rolloff,
		float	max_dist,
		float	gain,
		const bool	load = true
	)

Introduces a mechanism by which one can load sound effects beyond the basic enumerated types.

This will be used when loading custom sound effects for individual karts (character voices) so that we can avoid creating an enumeration for each effect, for each kart.

Parameters

sfx_name
sfxFile	must be an absolute pathname

Returns

whether loading this sound effect was successful

checkError()

bool SFXManager::checkError ( const std::string &  context )

static

Returns whether or not an openal error has occurred.

If so, an error message is printed containing the given context.

Parameters

context

Context to specify in the error message.

Returns

True if no error happened.

createSoundSource()

SFXBase * SFXManager::createSoundSource	(	SFXBuffer *	buffer,
		const bool	add_to_SFX_list = true,
		const bool	owns_buffer = false
	)

Creates a new SFX object.

The memory for this object is managed completely by the SFXManager. This makes it easy to use different implementations of SFX - since createSoundSource can return whatever type is used. To free the memory, call deleteSFX().

Parameters

id	Identifier of the sound effect to create.

deleteSFX()

void SFXManager::deleteSFX ( SFXBase *  sfx )

private

Delete a sound effect object, and removes it from the internal list of all SFXs.

This call deletes the object, and removes it from the list of all SFXs.

Parameters

sfx	SFX object to delete.

deleteSFXMapping()

void SFXManager::deleteSFXMapping

(

const std::string &

name

)

This function removes a sfx buffer info entry from the mapping, and frees the openal buffer.

Parameters

name	The name of the mapping entry to remove.

dump()

void SFXManager::dump

(

)

Prints the list of currently loaded sounds to stdout.

Useful to debug audio leaks

loadSingleSfx()

SFXBuffer * SFXManager::loadSingleSfx	(	const XMLNode *	node,
		const std::string &	path = std::string(""),
		const bool	load = true
	)

Loads a single sfx from the XML specification.

Parameters

node	The XML node with the data for this sfx.

mainLoop()

void SFXManager::mainLoop ( void *  obj )

staticprivate

This loops runs in a different threads, and starts sfx to be played.

This can sometimes take up to 5 ms, so it needs to be handled in a thread in order to avoid rendering delays.

Parameters

obj	A pointer to the SFX singleton.

pauseAll()

void SFXManager::pauseAll

(

)

Pauses all looping SFXs.

Non-looping SFX will be finished, since it's otherwise not possible to determine which SFX must be resumed (i.e. were actually playing at the time pause was called).

positionListener()

void SFXManager::positionListener	(	const Vec3 &	position,
		const Vec3 &	front,
		const Vec3 &	up
	)

Sets the position and orientation of the listener.

Parameters

position	Position of the listener.
front	Which way the listener is facing.
up	The up direction of the listener.

queue() [1/6]

void SFXManager::queue	(	SFXCommands	command,
		MusicInformation *	mi
	)

Queues a command for the music manager.

Parameters

mi	The music for which the command is.

queue() [2/6]

void SFXManager::queue	(	SFXCommands	command,
		MusicInformation *	mi,
		float	f
	)

Queues a command for the music manager that takes a floating point value (e.g.

setTemporaryVolume).

Parameters

mi	The music for which the command is.
f	The floating point parameter.

queue() [3/6]

void SFXManager::queue	(	SFXCommands	command,
		SFXBase *	sfx,
		const Vec3 &	p
	)

Adds a sound effect command with a Vec3 parameter to the queue of the sfx manager.

Openal commands can sometimes cause a 5ms delay, so it is done in a separate thread.

Parameters

command	The command to execute.
sfx	The sound effect to be started.
p	A Vec3 parameter for the command.

queue() [4/6]

void SFXManager::queue	(	SFXCommands	command,
		SFXBase *	sfx,
		float	f
	)

Adds a sound effect command with a single floating point parameter to the queue of the sfx manager.

Openal commands can sometimes cause a 5ms delay, so it is done in a separate thread.

Parameters

command	The command to execute.
sfx	The sound effect to be started.
f	Floating point parameter for the command.

queue() [5/6]

void SFXManager::queue	(	SFXCommands	command,
		SFXBase *	sfx,
		float	f,
		const Vec3 &	p
	)

Adds a sound effect command with a float and a Vec3 parameter to the queue of the sfx manager.

Openal commands can sometimes cause a 5ms delay, so it is done in a separate thread.

Parameters

command	The command to execute.
sfx	The sound effect to be started.
f	A float parameter for the command.
p	A Vec3 parameter for the command.

queue() [6/6]

void SFXManager::queue	(	SFXCommands	command,
		SFXBase *	sfx = NULL
	)

Adds a sound effect command to the queue of the sfx manager.

Openal commands can sometimes cause a 5ms delay, so it is done in a separate thread.

Parameters

command	The command to execute.
sfx	The sound effect to be started.

queueCommand()

void SFXManager::queueCommand ( SFXCommand *  command )

private

Enqueues a command to the sfx queue threadsafe.

Then signal the sfx manager to wake up.

Parameters

command

Pointer to the command to queue up.

quickSound()

SFXBase * SFXManager::quickSound

(

const std::string &

sound_type

)

Positional sound is cool, but creating a new object just to play a simple menu sound is not.

This function allows for 'quick sounds' in a single call.

Parameters

sound_type

Internal name of the sfx to play.

Returns

a pointer to the sound, for instance to check when the sound finished. don't delete the returned pointer.

reallyPauseAllNow()

void SFXManager::reallyPauseAllNow

(

)

Pauses all looping SFXs.

Non-looping SFX will be finished, since it's otherwise not possible to determine which SFX must be resumed (i.e. were actually playing at the time pause was called.

reallyPositionListenerNow()

void SFXManager::reallyPositionListenerNow ( )

private

Sets the position and orientation of the listener.

Parameters

position	Position of the listener.
front	Which way the listener is facing.

reallyResumeAllNow()

void SFXManager::reallyResumeAllNow

(

)

Resumes all paused SFXs.

If sound is disabled, does nothing.

reallyUpdateNow()

void SFXManager::reallyUpdateNow

(

SFXCommand *

current

)

Updates the status of all playing sfx (to test if they are finished).

This function is executed once per frame (triggered by the audio thread).

Parameters

current

The sfx command - used to get timestep information.

resumeAll()

void SFXManager::resumeAll

(

)

Resumes all paused SFXs.

If sound is disabled, does nothing.

setMasterSFXVolume()

void SFXManager::setMasterSFXVolume

(

float

gain

)

Sets the master volume for all sound effects.

Parameters

gain	The volume to set.

sfxAllowed()

bool SFXManager::sfxAllowed

(

)

Returns if sfx can be played.

This means sfx are enabled and the manager is correctly initialised.

soundExist()

bool SFXManager::soundExist

(

const std::string &

name

)

Returns true if a sfx with the given name exists.

Parameters

name	The internal name of the sfx (not the name of the ogg file)

toggleSound()

void SFXManager::toggleSound

(

const bool

on

)

Called when sound was muted/unmuted.

Called when sound is globally switched on or off.

It either pauses or resumes all sound effects.

Parameters

on	If sound is switched on or off.

update()

void SFXManager::update

(

)

Make sure that the sfx thread is started at least once per frame.

It also adds an update command for the music manager.

Parameters

dt	Time step size.

Member Data Documentation

m_all_sfx_types

std::map<std::string, SFXBuffer*> SFXManager::m_all_sfx_types

private

The buffers and info for all sound effects.

These are shared among all instances of SFXOpenal.

m_listener_position

Synchronised<Vec3> SFXManager::m_listener_position

private

The position of the listener.

Its lock will be used to access m_listener_{position,front, up}.

---

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

• audio/sfx_manager.hpp
• audio/sfx_manager.cpp