AudioMixer Class Reference

#include <AudioMixer.hxx>

Inheritance diagram for AudioMixer:

Collaboration diagram for AudioMixer:

Public Types
enum	ORIENTATION_INDEX : int {   ORIENTATION_INDEX::FORWARD_X = 0, ORIENTATION_INDEX::FORWARD_Y = 1, ORIENTATION_INDEX::FORWARD_Z = 2, ORIENTATION_INDEX::UP_X = 3,   ORIENTATION_INDEX::UP_Y = 4, ORIENTATION_INDEX::UP_Z = 5 }
	orientation of listener More...
enum	POSITION_INDEX : int { POSITION_INDEX::X = 0, POSITION_INDEX::Y = 1, POSITION_INDEX::Z = 2 }
	position of listener More...
using	DEFAULT_CHANNELS = Constant< 4 >

Public Member Functions
void	setMusicVolume (float volume)
	sets the music volume More...
void	setSoundEffectVolume (float volume)
	sets the sound effects volume More...
void	play (const SoundtrackID &id, int effect=AL_EFFECT_NULL)
	Plays a Soundtrack given its ID and optionally applies an effect. More...
void	play (const AudioTrigger &trigger, int effect=AL_EFFECT_NULL)
	Plays a random Soundtrack from a trigger and optionally applies an effect. More...
void	play (const SoundtrackID &id, const Coordinate3D &position, int effect=AL_EFFECT_NULL)
	Plays a 3D Soundtrack given its ID and optionally applies an effect. More...
void	play (const AudioTrigger &trigger, const Coordinate3D &position, int effect=AL_EFFECT_NULL)
	Plays a 3D Soundtrack from a trigger and optionally applies an effect. More...
void	setMuted (bool isMuted)
	toggles the mute option for sounds More...
void	stopAll ()
	Stops all soundtracks. More...
void	prune ()
	Updates soundtracks that are no longer playing. More...
	AudioMixer ()
	~AudioMixer ()
	AudioMixer (const AudioMixer &)=delete
	AudioMixer (AudioMixer &&)=delete
AudioMixer &	operator= (const AudioMixer &)=delete
AudioMixer &	operator= (AudioMixer &&)=delete

Private Member Functions
const char *	get_al_error_msg (ALenum error)
	Get a descriptive error message from an error code. More...
void	playSoundtrack (SoundtrackUPtr &soundtrack)
	Plays the Soundtrack. More...
void	playSoundtrackWithEffect (SoundtrackUPtr &soundtrack, int ALEffect)
	Plays the Soundtrack with a certain effect applied. More...
void	onTrackFinished (int channelID)
	Called whenever a Channel has finished playing. More...
SoundtrackUPtr &	getTrack (const AudioTrigger &trigger)
SoundtrackUPtr &	getTrack (const SoundtrackID &id)

Static Private Member Functions
static void	onTrackFinishedFuncPtr (int channelID)

Private Attributes
Vector< SoundtrackUPtr >	m_Soundtracks
	All the available soundtracks. More...
Array< Vector< SoundtrackID >, AudioTrigger::_size()>	m_Triggers
	A Mapping between triggers and SoundtrackID. More...
Mapping< SoundtrackID, SoundtrackUPtr * >	m_GetSound
	A Mapping between SoundtrackID and Soundtrack. More...
List< SoundtrackUPtr * >	m_Playing
	All the currently playing Soundtracks. More...
ALCdevice *	gAudioDevice
	OpenAL Soft setup, audio device to be used. More...
ALCcontext *	alContext
	OpenAL Soft setup, context of where audio is played. More...

Static Private Attributes
static std::function< void(int)>	onTrackFinishedFunc

Friends
class	Game

Additional Inherited Members
Static Public Member Functions inherited from Singleton< AudioMixer >
static AudioMixer &	instance (void)
	Get an instance of the singleton. More...
Protected Member Functions inherited from Singleton< AudioMixer >
	Singleton () noexcept=default
	~Singleton () noexcept=default

Detailed Description

Definition at line 43 of file AudioMixer.hxx.

Member Typedef Documentation

DEFAULT_CHANNELS

using AudioMixer::DEFAULT_CHANNELS = Constant<4>

Definition at line 46 of file AudioMixer.hxx.

Member Enumeration Documentation

ORIENTATION_INDEX

enum AudioMixer::ORIENTATION_INDEX : int

strong

orientation of listener

Enumerator
FORWARD_X
FORWARD_Y
FORWARD_Z
UP_X
UP_Y
UP_Z

Definition at line 124 of file AudioMixer.hxx.

                               : int
  {
    FORWARD_X = 0,
    FORWARD_Y = 1,
    FORWARD_Z = 2,
    UP_X = 3,
    UP_Y = 4,
    UP_Z = 5
  };

POSITION_INDEX

enum AudioMixer::POSITION_INDEX : int

strong

position of listener

Enumerator
X
Y
Z

Definition at line 135 of file AudioMixer.hxx.

                            : int
  {
    X = 0,
    Y = 1,
    Z = 2
  };

Constructor & Destructor Documentation

AudioMixer() [1/3]

AudioMixer::AudioMixer

(

)

Precondition

GameClock must be initialized

Exceptions

ConfigurationError	if there is a problem opening the audio config file
AudioError	if OpenAL context cannot be initialized or an OpenAL error occurs

Definition at line 21 of file AudioMixer.cxx.

{
  std::string jsonFileContent = fs::readFileAsString(Settings::instance().audioConfigJSONFile.get());
  json config_json = json::parse(jsonFileContent, nullptr, false);
 
  // check if json file can be parsed
  if (config_json.is_discarded())
    throw ConfigurationError(TRACE_INFO "Error parsing JSON File " + Settings::instance().audioConfigJSONFile.get());
 
  AudioConfig audioConfig = config_json;
  for (auto &item : audioConfig.Music)
    for (auto &trigger : item.second.triggers)
      m_Triggers[trigger].emplace_back(item.first);
  for (auto &item : audioConfig.Sound)
    for (auto &trigger : item.second.triggers)
      m_Triggers[trigger].emplace_back(item.first);
 
  /* use default audio device */
  gAudioDevice = alcOpenDevice(nullptr);
  if (!gAudioDevice)
  {
    const char *error_msg = get_al_error_msg(alGetError());
    LOG(LOG_WARNING) << "Unable to initialize default audio device! " << error_msg;
    return;
  }
 
  /* create context */
  alContext = alcCreateContext(gAudioDevice, nullptr);
  if (!alContext)
  {
    const char *error_msg = get_al_error_msg(alGetError());
    throw AudioError(TRACE_INFO "Unable to initialize OpenAL context! " + error_msg);
  }
  alcMakeContextCurrent(alContext);
 
  /* Check if an error occurred, and clean up if so. */
  ALenum err;
  err = alGetError();
  if (err != AL_NO_ERROR)
    throw AudioError(TRACE_INFO "OpenAL error occurred: " + get_al_error_msg(err));
 
  /* set listener position one space behind origin */
  Array<float, 3> listener_position_vector{0.0f, 0.0f, 1.0f};
 
  /* Initialize Listener speed */
  alListener3f(AL_VELOCITY, 0.0f, 0.0f, 0.0f); // is not moving in 3d space
 
  /* initialize listener position 1 space behind origin in openal
     * forward direction(-z direction in regular cartesian) */
  alListener3f(AL_POSITION, listener_position_vector[static_cast<int>(AudioMixer::POSITION_INDEX::X)],
               listener_position_vector[static_cast<int>(AudioMixer::POSITION_INDEX::Y)],
               listener_position_vector[static_cast<int>(AudioMixer::POSITION_INDEX::Z)]);
 
  /* Set Listener orientation
     * forward x, forward y, forward z, up x, up y, up z */
  Array<float, 6> listener_orientation_vector{0.0f, 0.0f, -1.0f, 0.0f, 1.0f, 0.0f};
  alListenerfv(AL_ORIENTATION, listener_orientation_vector.data());
 
  /* Set a pruning repeated task to get rid of soundtracks that have finished playing */
  GameClock::instance().addRealTimeClockTask(
      [&mixer = *this]
      {
        mixer.prune();
        return false;
      },
      0s, 5min);
 
  LOG(LOG_DEBUG) << "Created AudioMixer";
}

Here is the call graph for this function:

~AudioMixer()

AudioMixer::~AudioMixer

(

)

Definition at line 91 of file AudioMixer.cxx.

{
  if (!gAudioDevice)
  {
    return;
  }
 
  alcDestroyContext(alContext); //delete context
  alcCloseDevice(gAudioDevice); //close device
 
  LOG(LOG_DEBUG) << "Destroyed AudioMixer";
}

AudioMixer() [2/3]

AudioMixer::AudioMixer ( const AudioMixer &  )

delete

AudioMixer() [3/3]

AudioMixer::AudioMixer ( AudioMixer &&  )

delete

Member Function Documentation

get_al_error_msg()

const char * AudioMixer::get_al_error_msg ( ALenum  error )

private

Get a descriptive error message from an error code.

Definition at line 396 of file AudioMixer.cxx.

{
  switch (error)
  {
  case AL_INVALID_NAME:
    return "a bad name (ID) was passed to an OpenAL function";
  case AL_INVALID_ENUM:
    return "an invalid enum value was passed to an OpenAL function";
  case AL_INVALID_VALUE:
    return "an invalid value was passed to an OpenAL function";
  case AL_INVALID_OPERATION:
    return "the requested operation is not valid";
  case AL_OUT_OF_MEMORY:
    return "the requested operation resulted in OpenAL running out of memory";
  case AL_NO_ERROR:
    return "there is not currently an error";
  default:
    return "Unknown error";
  }
}

Here is the caller graph for this function:

getTrack() [1/2]

SoundtrackUPtr & AudioMixer::getTrack ( const AudioTrigger &  trigger )

private

Definition at line 106 of file AudioMixer.cxx.

{
  if (!gAudioDevice)
  {
    return noResoruce;
  }
 
  auto &possibilities = m_Triggers[trigger];
  if (possibilities.empty())
  {
    LOG(LOG_WARNING) << "No Soundtracks are triggered by " << trigger._to_string();
    return noResoruce;
  }
  const SoundtrackID &trackID = *Randomizer::instance().choose(possibilities.begin(), possibilities.end());
  return ResourceManager::instance().get(trackID);
}

Here is the call graph for this function:

Here is the caller graph for this function:

getTrack() [2/2]

SoundtrackUPtr & AudioMixer::getTrack ( const SoundtrackID &  id )

private

Definition at line 123 of file AudioMixer.cxx.

{
  if (!gAudioDevice)
  {
    return noResoruce;
  }
 
  return ResourceManager::instance().get(id);
}

Here is the call graph for this function:

onTrackFinished()

void AudioMixer::onTrackFinished ( int  channelID )

private

Called whenever a Channel has finished playing.

Parameters

channelID

the channel that has finished playing

Definition at line 378 of file AudioMixer.cxx.

{
  auto it = std::find_if(m_Playing.begin(), m_Playing.end(),
                         [channelID](const auto trackptr)
                         {
                           const auto &track = *trackptr;
                           return track && track->Channel.get() == channelID;
                         });
  auto &track = **it;
  if (track)
  {
    track->isPlaying = false;
    if (!track->isMusic)
      track->Channel = -1;
  }
  m_Playing.erase(it);
}

onTrackFinishedFuncPtr()

static void AudioMixer::onTrackFinishedFuncPtr ( int  channelID )

inlinestaticprivate

Because of SDL_Mixer's poor design, we are forced to use a function pointer. This means no lambda, no std::function, no std::bind. Our workaround involves creating the onTrackFinishedFunc global function object which captures the AudioMixer object

Definition at line 201 of file AudioMixer.hxx.

{ onTrackFinishedFunc(channelID); }

operator=() [1/2]

AudioMixer& AudioMixer::operator= ( AudioMixer &&  )

delete

operator=() [2/2]

AudioMixer& AudioMixer::operator= ( const AudioMixer &  )

delete

play() [1/4]

void AudioMixer::play	(	const AudioTrigger &	trigger,
		const Coordinate3D &	position,
		int	effect = AL_EFFECT_NULL
	)

Plays a 3D Soundtrack from a trigger and optionally applies an effect.

Parameters

trigger	the AudioTrigger
position	the Coordinate3D position of the sound
effect	the effect to apply. Should be in the form of an AL_EFFECT macro such as AL_EFFECT_REVERB or AL_EFFECT_ECHO.

Definition at line 196 of file AudioMixer.cxx.

{
  if (getTrack(trigger))
  {
    auto &track = getTrack(trigger);
    /* set position of sources in track
   * converted to regular Cartesian coordinate system */
    alSource3f(track->source[0], AL_POSITION, static_cast<ALfloat>(position.x), static_cast<ALfloat>(position.y),
               static_cast<ALfloat>(position.z));
    alSource3f(track->source[1], AL_POSITION, static_cast<ALfloat>(position.x), static_cast<ALfloat>(position.y),
               static_cast<ALfloat>(position.z));
    play(trigger, effect);
  }
}

Here is the call graph for this function:

play() [2/4]

void AudioMixer::play	(	const AudioTrigger &	trigger,
		int	effect = AL_EFFECT_NULL
	)

Plays a random Soundtrack from a trigger and optionally applies an effect.

Parameters

trigger	the AudioTrigger
effect	the effect to apply. Should be in the form of an AL_EFFECT macro such as AL_EFFECT_REVERB or AL_EFFECT_ECHO.

Definition at line 170 of file AudioMixer.cxx.

{
  auto &track = getTrack(trigger);
  if (track)
  {
    if (effect == AL_EFFECT_NULL)
      playSoundtrack(track);
    else
      playSoundtrackWithEffect(track, effect);
  }
}

Here is the call graph for this function:

play() [3/4]

void AudioMixer::play	(	const SoundtrackID &	id,
		const Coordinate3D &	position,
		int	effect = AL_EFFECT_NULL
	)

Plays a 3D Soundtrack given its ID and optionally applies an effect.

Parameters

id	the SoundtrackID
position	the Coordinate3D position of the sound
effect	the effect to apply. Should be in the form of an AL_EFFECT macro such as AL_EFFECT_REVERB or AL_EFFECT_ECHO.

Definition at line 182 of file AudioMixer.cxx.

{
  if (getTrack(id))
  {
    auto &track = getTrack(id);
    /* set position of sources in track */
    alSource3f(track->source[0], AL_POSITION, static_cast<ALfloat>(position.x), static_cast<ALfloat>(position.y),
               static_cast<ALfloat>(position.z));
    alSource3f(track->source[1], AL_POSITION, static_cast<ALfloat>(position.x), static_cast<ALfloat>(position.y),
               static_cast<ALfloat>(position.z));
    play(id, effect);
  }
}

Here is the call graph for this function:

play() [4/4]

void AudioMixer::play	(	const SoundtrackID &	id,
		int	effect = AL_EFFECT_NULL
	)

Plays a Soundtrack given its ID and optionally applies an effect.

Parameters

id	the SoundtrackID
effect	the effect to apply. Should be in the form of an AL_EFFECT macro such as AL_EFFECT_REVERB or AL_EFFECT_ECHO.

Definition at line 158 of file AudioMixer.cxx.

{
  auto &track = getTrack(id);
  if (track)
  {
    if (effect == AL_EFFECT_NULL)
      playSoundtrack(track);
    else
      playSoundtrackWithEffect(track, effect);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

playSoundtrack()

void AudioMixer::playSoundtrack ( SoundtrackUPtr &  soundtrack )

private

Plays the Soundtrack.

Parameters

soundtrack

the Soundtrack

Exceptions

AudioError

if track is invalid or its source is uninitialized

Definition at line 259 of file AudioMixer.cxx.

{
  if (!track)
    throw AudioError(TRACE_INFO "Received an invalid soundtrack");
 
  if (!track->source)
    throw AudioError{TRACE_INFO "Unable to play track because its source is uninitialized"};
 
  alSourcePlay(track->source[track->isMusic]);
 
  m_Playing.push_front(&track);
  track->isPlaying = true;
}

Here is the caller graph for this function:

playSoundtrackWithEffect()

void AudioMixer::playSoundtrackWithEffect ( SoundtrackUPtr &  soundtrack, int  ALEffect  )

private

Plays the Soundtrack with a certain effect applied.

Given the soundtrack, this function will apply the given AL effect to the audio with the default settings.

Parameters

soundtrack	the Soundtrack
ALEffect	the effect to apply. Should be in the form of an AL_EFFECT macro such as AL_EFFECT_REVERB or AL_EFFECT_ECHO.

Exceptions

AudioError

if track is invalid, its source is uninitialized, or reverb effect could not be applied

Definition at line 299 of file AudioMixer.cxx.

{
  if (!track)
    throw AudioError(TRACE_INFO "Received an invalid soundtrack");
 
  if (!track->source)
    throw AudioError{TRACE_INFO "Unable to play track because its source is uninitialized"};
 
    //set up effect
#define LOAD_PROC(T, x) ((x) = (T)alGetProcAddress(#x))
  LOAD_PROC(LPALGENEFFECTS, alGenEffects);
  LOAD_PROC(LPALDELETEEFFECTS, alDeleteEffects);
  LOAD_PROC(LPALISEFFECT, alIsEffect);
  LOAD_PROC(LPALEFFECTI, alEffecti);
  LOAD_PROC(LPALEFFECTIV, alEffectiv);
  LOAD_PROC(LPALEFFECTF, alEffectf);
  LOAD_PROC(LPALEFFECTFV, alEffectfv);
  LOAD_PROC(LPALGETEFFECTI, alGetEffecti);
  LOAD_PROC(LPALGETEFFECTIV, alGetEffectiv);
  LOAD_PROC(LPALGETEFFECTF, alGetEffectf);
  LOAD_PROC(LPALGETEFFECTFV, alGetEffectfv);
 
  LOAD_PROC(LPALGENAUXILIARYEFFECTSLOTS, alGenAuxiliaryEffectSlots);
  LOAD_PROC(LPALDELETEAUXILIARYEFFECTSLOTS, alDeleteAuxiliaryEffectSlots);
  LOAD_PROC(LPALISAUXILIARYEFFECTSLOT, alIsAuxiliaryEffectSlot);
  LOAD_PROC(LPALAUXILIARYEFFECTSLOTI, alAuxiliaryEffectSloti);
  LOAD_PROC(LPALAUXILIARYEFFECTSLOTIV, alAuxiliaryEffectSlotiv);
  LOAD_PROC(LPALAUXILIARYEFFECTSLOTF, alAuxiliaryEffectSlotf);
  LOAD_PROC(LPALAUXILIARYEFFECTSLOTFV, alAuxiliaryEffectSlotfv);
  LOAD_PROC(LPALGETAUXILIARYEFFECTSLOTI, alGetAuxiliaryEffectSloti);
  LOAD_PROC(LPALGETAUXILIARYEFFECTSLOTIV, alGetAuxiliaryEffectSlotiv);
  LOAD_PROC(LPALGETAUXILIARYEFFECTSLOTF, alGetAuxiliaryEffectSlotf);
  LOAD_PROC(LPALGETAUXILIARYEFFECTSLOTFV, alGetAuxiliaryEffectSlotfv);
#undef LOAD_PROC
 
  //load effect
  ALuint effect = 0;
 
  // Create the effect object
  alGenEffects(1, &effect);
 
  alEffecti(effect, AL_EFFECT_TYPE, ALEffect);
 
  // this is where we would put code to customize the properties of the effect
 
  // Check if an error occured, and clean up if so.
  ALenum err = alGetError();
  if (err != AL_NO_ERROR)
  {
    if (alIsEffect(effect))
      alDeleteEffects(1, &effect);
 
    throw AudioError{TRACE_INFO "Unable to add effect to track."};
    fprintf(stderr, "OpenAL error: %s\n", alGetString(err));
  }
 
  /* Create the effect slot object. This is what "plays" an effect on sources
   * that connect to it. */
  alGenAuxiliaryEffectSlots(1, &track->effect_slot);
 
  /* Tell the effect slot to use the loaded effect object. Note that this
   * effectively copies the effect properties. You can modify or delete the
   * effect object afterward without affecting the effect slot.
   */
  alAuxiliaryEffectSloti(track->effect_slot, AL_EFFECTSLOT_EFFECT, (ALint)effect);
  assert(alGetError() == AL_NO_ERROR && "Failed to set effect slot");
 
  alDeleteEffects(1, &effect);
 
  //apply effect to source
  alSource3i(track->source[track->isMusic], AL_AUXILIARY_SEND_FILTER, (ALint)(track->effect_slot), 0, AL_FILTER_NULL);
  assert(alGetError() == AL_NO_ERROR && "Failed to setup reverb for sound source send 0.");
 
  //play sound
  alSourcePlay(track->source[track->isMusic]);
  m_Playing.push_front(&track);
  track->isPlaying = true;
}

Here is the caller graph for this function:

prune()

void AudioMixer::prune

(

)

Updates soundtracks that are no longer playing.

Definition at line 230 of file AudioMixer.cxx.

{
  if (!gAudioDevice)
  {
    return;
  }
 
  for (auto it = m_Playing.begin(); it != m_Playing.end();)
  {
    int state = 0;
    alGetSourcei((**it)->source[(**it)->isMusic], AL_SOURCE_STATE, &state);
    if (state != AL_PLAYING)
    {
      (**it)->isPlaying = false;
      it = m_Playing.erase(it);
    }
    else
    {
      ++it;
    }
  }
}

setMusicVolume()

void AudioMixer::setMusicVolume

(

float

volume

)

sets the music volume

Parameters

volume

Precondition

volume must be a float within [0, 1]

Postcondition

Settings::MusicVolume is changed

Definition at line 139 of file AudioMixer.cxx.

{
  for (auto it : m_Playing)
  {
    alSourcef((**it).source[1], AL_GAIN, volume);
  }
  // update the settings accordingly
  Settings::instance().musicVolume = volume;
}

Here is the call graph for this function:

Here is the caller graph for this function:

setMuted()

void AudioMixer::setMuted

(

bool

isMuted

)

toggles the mute option for sounds

Parameters

isMuted

true to mute all sounds, false to unmute

Exceptions

UnimplementedError

Currently throws UnimplementedError on function call

Definition at line 211 of file AudioMixer.cxx.

{ throw UnimplementedError(TRACE_INFO "Unimplemented Error"); }

setSoundEffectVolume()

void AudioMixer::setSoundEffectVolume

(

float

volume

)

sets the sound effects volume

Parameters

volume

Precondition

volume must be a float within [0, 1]

Postcondition

Settings::SoundEffectsVolume is changed

Definition at line 149 of file AudioMixer.cxx.

{
  for (auto it : m_Playing)
  {
    alSourcef((**it).source[0], AL_GAIN, volume);
  }
  Settings::instance().soundEffectsVolume = volume;
}

Here is the call graph for this function:

Here is the caller graph for this function:

stopAll()

void AudioMixer::stopAll

(

)

Stops all soundtracks.

Definition at line 213 of file AudioMixer.cxx.

{
  if (!gAudioDevice)
  {
    return;
  }
 
  while (!m_Playing.empty())
  {
    auto it = m_Playing.begin();
    alSourceStop((**it)->source[0]);
    alSourceStop((**it)->source[1]);
    (**it)->isPlaying = false;
    m_Playing.erase(it);
  }
}

Friends And Related Function Documentation

Game

friend class Game

friend

Definition at line 206 of file AudioMixer.hxx.

Member Data Documentation

alContext

ALCcontext* AudioMixer::alContext

private

OpenAL Soft setup, context of where audio is played.

Definition at line 217 of file AudioMixer.hxx.

gAudioDevice

ALCdevice* AudioMixer::gAudioDevice

private

OpenAL Soft setup, audio device to be used.

Definition at line 212 of file AudioMixer.hxx.

m_GetSound

Mapping<SoundtrackID, SoundtrackUPtr *> AudioMixer::m_GetSound

private

A Mapping between SoundtrackID and Soundtrack.

Definition at line 156 of file AudioMixer.hxx.

m_Playing

List<SoundtrackUPtr *> AudioMixer::m_Playing

private

All the currently playing Soundtracks.

Definition at line 161 of file AudioMixer.hxx.

m_Soundtracks

Vector<SoundtrackUPtr> AudioMixer::m_Soundtracks

private

All the available soundtracks.

Definition at line 146 of file AudioMixer.hxx.

m_Triggers

Array<Vector<SoundtrackID>, AudioTrigger::_size()> AudioMixer::m_Triggers

private

A Mapping between triggers and SoundtrackID.

Definition at line 151 of file AudioMixer.hxx.

onTrackFinishedFunc

std::function< void(int)> AudioMixer::onTrackFinishedFunc

staticprivate

A global closure to capture an AudioMixer object

Definition at line 194 of file AudioMixer.hxx.

---

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

• src/services/AudioMixer.hxx
• src/services/AudioMixer.cxx