Saga::AudioEngine Namespace Reference

This contains a collection of methods that interfaces with the FMOD studio API to play audio. More...

Namespaces
namespace	anonymous_namespace{audioEngine.cpp}

Classes
struct	EventAttributes
	A collection of vectors that specify an object in 3D space. This allows the AudioEngine to determine where listeners as well as AudioEventInstance are situated in space. More...
struct	ParameterValue
	Value of a parameter in FMOD. Whenever a parameter is retrieved from an event (or globally), it will be in this form. More...

Functions
bool	init ()
	Initialize the Audio Engine. Must be called before any other audio operation.
void	update ()
	Update the Audio Engine. Needs to be run every frame for accurate result.
bool	release ()
	Release the Audio Engine. Must be called after init, and no audio operation should work after this call.
void	loadBank (const std::string &bankFileName, FMOD_STUDIO_LOAD_BANK_FLAGS flags=FMOD_STUDIO_LOAD_BANK_NORMAL)
	Load a bank of audio. By default, sample data will not be loaded. It is important that both the bank files and bank's strings file are loaded before events can be played.
void	unloadBank (const std::string &bankName)
	Unload bank.
void	loadEvent (const std::string &eventName, bool loadSampleData=false)
	Load an event from a loaded bank.
void	loadSampleData (const std::string &eventName)
	Load an event's sample data, allowing for event instances to be spawned and play instantaneously. For every call to load, you must call unload after. Loads and unloads are reference-counted, so the event's data won't completely unload until every load is followed by an unload.
void	unloadSampleData (const std::string &eventName)
	Unload an event's sample data.
AudioEventInstance	playEvent (const std::string &eventName)
	Play an event. If this event is not loaded, loadEvent will be called.
AudioEventInstance	createInstance (const std::string &eventName)
	Create an instance of a sound event. If this event has not been loaded, loadEvent will be called.
void	playEvent (AudioEventInstance event)
	Play an event.
void	stopEvent (AudioEventInstance event, bool immediate=false)
	Stop an event that's playing.
void	releaseEvent (AudioEventInstance event)
	Release an event instance. After this, the event instance is unusable.
void	releaseAllEventInstances (const std::string &eventName)
	Release all event instances associated with this event.
void	unloadEvent (const std::string &eventName, bool unloadSampleData=false)
	Unload an event. This effectively removes the ability to create instances of the event until it is loaded again.
void	setParameter (AudioEventInstance instance, const std::string &parameterName, float value)
	Set a parameter on an event instance.
ParameterValue	getParameter (AudioEventInstance instance, const std::string &parameterName)
	Get the value of an event.
void	setLabeledParameter (AudioEventInstance instance, const std::string &parameterName, std::string label)
	Set a parameter on an event instance to a labeled value.
std::string	getLabeledParameter (AudioEventInstance instance, const std::string &parameterName)
	Get the label-value of a parameter.
void	setGlobalParameter (const std::string &parameterName, float value)
	Set a global parameter.
ParameterValue	getGlobalParameter (const std::string &parameterName)
	Get the value of a global parameter.
void	setGlobalLabeledParameter (const std::string &parameterName, std::string label)
	Set the value of a global parameter by label.
std::string	getGlobalLabeledParameter (const std::string &parameterName)
	Get the label value of a global parameter.
void	setListenerData (const EventAttributes &attributes)
	Set the 3D position of the listener.
void	set3DAttributes (AudioEventInstance instance, const EventAttributes &attributes)
	Set the 3D attributes of an audio event instance.
FMOD_VECTOR	vectorToFmod (const glm::vec3 &vPosition)
	Convert a glm vector to an fmod vector.

Variables
AudioImplementation	implementation = AudioImplementation()
	Data used for operating the AudioEngine.
const int	maxChannels = 32
	Maximum channels we will use for FMOD. Usually you don't need that many (probably 4-5 would be ok).

Detailed Description

This contains a collection of methods that interfaces with the FMOD studio API to play audio.

Function Documentation

createInstance()

AudioEventInstance Saga::AudioEngine::createInstance

(

const std::string &

eventName

)

Create an instance of a sound event. If this event has not been loaded, loadEvent will be called.

Parameters

eventName

name of the event, typically in the form "event:/Folder/Name".

Returns

std::shared_ptr<AudioEventInstance> the instance.

Here is the call graph for this function:

getGlobalLabeledParameter()

std::string Saga::AudioEngine::getGlobalLabeledParameter

(

const std::string &

parameterName

)

Get the label value of a global parameter.

Parameters

parameterName

the name of the parameter.

Returns

std::string the label value of the parameter.

Here is the call graph for this function:

getGlobalParameter()

ParameterValue Saga::AudioEngine::getGlobalParameter

(

const std::string &

parameterName

)

Get the value of a global parameter.

Parameters

parameterName

the name of the parameter.

Returns

ParameterValue the value of the event in FMOD studio.

See also

ParameterValue

getLabeledParameter()

std::string Saga::AudioEngine::getLabeledParameter	(	AudioEventInstance	instance,
		const std::string &	parameterName
	)

Get the label-value of a parameter.

Parameters

instance	the event instance.
parameterName	the name of the parameter.

Returns

std::string the label value of a parameter.

Here is the call graph for this function:

getParameter()

ParameterValue Saga::AudioEngine::getParameter	(	AudioEventInstance	instance,
		const std::string &	parameterName
	)

Get the value of an event.

Parameters

instance	the event instance.
parameterName	the name of the parameter.

Returns

ParameterValue value of the event in FMOD studio.

init()

bool Saga::AudioEngine::init

(

)

Initialize the Audio Engine. Must be called before any other audio operation.

Returns

true if initilization is successful.

false if initialization fails. This can be either because the initialization itself fails, or the system has already been initialized.

loadBank()

void Saga::AudioEngine::loadBank	(	const std::string &	bankFileName,
		FMOD_STUDIO_LOAD_BANK_FLAGS	flags = FMOD_STUDIO_LOAD_BANK_NORMAL
	)

Load a bank of audio. By default, sample data will not be loaded. It is important that both the bank files and bank's strings file are loaded before events can be played.

Parameters

bankFileName	the filepath of the bank. This should be relative to your project source.
flags	flag for how the bank should load.

loadEvent()

void Saga::AudioEngine::loadEvent	(	const std::string &	eventName,
		bool	loadSampleData = false
	)

Load an event from a loaded bank.

Parameters

eventName	name of the event, typically in the form "event:/Folder/Name".
loadSampleData	whether or not to also load sample data.

Note

Loading sample data will preload the data for an event, allowing event instances to be created and immediately played without latency. Sample data loading happens asynchronously, so there is a possibility sound won't be played immediately if you load an event and immediately attempt to play it.

Here is the call graph for this function:

loadSampleData()

void Saga::AudioEngine::loadSampleData

(

const std::string &

eventName

)

Load an event's sample data, allowing for event instances to be spawned and play instantaneously. For every call to load, you must call unload after. Loads and unloads are reference-counted, so the event's data won't completely unload until every load is followed by an unload.

Parameters

eventName

name of the event, typically in the form "event:/Folder/Name".

Note

Loading sample data will preload the data for an event, allowing event instances to be created and immediately played without latency. Sample data loading happens asynchronously, so there is a possibility sound won't be played immediately if you load sample data for an event and immediately attempt to play it.

Here is the call graph for this function:

playEvent() [1/2]

void Saga::AudioEngine::playEvent

(

AudioEventInstance

event

)

Play an event.

Parameters

event

the event instance.

playEvent() [2/2]

AudioEventInstance Saga::AudioEngine::playEvent

(

const std::string &

eventName

)

Play an event. If this event is not loaded, loadEvent will be called.

Parameters

eventName

name of the event, typically in the form "event:/Folder/Name".

Returns

AudioEventInstance the correponding event instance.

Here is the call graph for this function:

release()

bool Saga::AudioEngine::release

(

)

Release the Audio Engine. Must be called after init, and no audio operation should work after this call.

Returns

true if release was sucessful.

false otherwise. This can fail because either the studio system is not initialized, or some failure in the fmod system.

releaseAllEventInstances()

void Saga::AudioEngine::releaseAllEventInstances

(

const std::string &

eventName

)

Release all event instances associated with this event.

Parameters

eventName

name of the event, typically in the form "event:/Folder/Name".

releaseEvent()

void Saga::AudioEngine::releaseEvent

(

AudioEventInstance

event

)

Release an event instance. After this, the event instance is unusable.

Parameters

event

the event instance.

set3DAttributes()

void Saga::AudioEngine::set3DAttributes	(	AudioEventInstance	instance,
		const EventAttributes &	attributes
	)

Set the 3D attributes of an audio event instance.

Parameters

instance	the event instance.
attributes	the 3D attributes of the listener.

Here is the call graph for this function:

setGlobalLabeledParameter()

void Saga::AudioEngine::setGlobalLabeledParameter	(	const std::string &	parameterName,
		std::string	label
	)

Set the value of a global parameter by label.

Parameters

parameterName	the name of the parameter.
label	the label value to set the parameter to.

setGlobalParameter()

void Saga::AudioEngine::setGlobalParameter	(	const std::string &	parameterName,
		float	value
	)

Set a global parameter.

Parameters

parameterName	the name of the parameter.
value	the value to set the parameter to.

setLabeledParameter()

void Saga::AudioEngine::setLabeledParameter	(	AudioEventInstance	instance,
		const std::string &	parameterName,
		std::string	label
	)

Set a parameter on an event instance to a labeled value.

Parameters

instance	the event instance.
parameterName	the name of the parameter.
label	the label of the value to set the parameter to.

setListenerData()

void Saga::AudioEngine::setListenerData

(

const EventAttributes &

attributes

)

Set the 3D position of the listener.

Parameters

attributes

the 3D attributes of the listener.

Here is the call graph for this function:

setParameter()

void Saga::AudioEngine::setParameter	(	AudioEventInstance	instance,
		const std::string &	parameterName,
		float	value
	)

Set a parameter on an event instance.

Parameters

instance	the event instance.
parameterName	the name of the parameter.
value	the value to set it to.

stopEvent()

void Saga::AudioEngine::stopEvent	(	AudioEventInstance	event,
		bool	immediate = false
	)

Stop an event that's playing.

Parameters

event	the event instance.
immediate	whether or not the event stops immediately, or with a falloff.

unloadBank()

void Saga::AudioEngine::unloadBank

(

const std::string &

bankName

)

Unload bank.

Parameters

bankName

the filepath of the bank. This should be relative to your project's source.

unloadEvent()

void Saga::AudioEngine::unloadEvent	(	const std::string &	eventName,
		bool	unloadSampleData = false
	)

Unload an event. This effectively removes the ability to create instances of the event until it is loaded again.

Parameters

eventName	name of the event, typically in the form "event:/Folder/Name".
unloadSampleData	whether or not to unload any sample data.

Note

the unload happens asynchronously and only when all event instances are released.

unloadSampleData()

void Saga::AudioEngine::unloadSampleData

(

const std::string &

eventName

)

Unload an event's sample data.

Parameters

eventName

name of the event, typically in the form "event:/Folder/Name".

Note

Unloading takes place only after all events are released.

update()

void Saga::AudioEngine::update

(

)

Update the Audio Engine. Needs to be run every frame for accurate result.

Note

For accurate positioning of sounds, update both the listener's 3D position and event instance positions before calling this update.

vectorToFmod()

FMOD_VECTOR Saga::AudioEngine::vectorToFmod

(

const glm::vec3 &

vPosition

)

Convert a glm vector to an fmod vector.

Parameters

vPosition

the vector.

Returns

FMOD_VECTOR the vector converted to fmod acceptable format.

Variable Documentation

implementation

AudioImplementation Saga::AudioEngine::implementation = AudioImplementation()

Data used for operating the AudioEngine.

maxChannels

const int Saga::AudioEngine::maxChannels = 32

Maximum channels we will use for FMOD. Usually you don't need that many (probably 4-5 would be ok).