#include <CUSoundEngine.h>

Classes
class	SoundPacket

Public Types
enum	SoundState { SoundState::INACTIVE, SoundState::LOADING, SoundState::PLAYING, SoundState::PAUSED }

Public Member Functions
void	playMusic (Sound *sound, bool loop=false, float volume=1.0)

const Sound *	currentMusic () const

SoundState	getMusicState () const

bool	isMusicLoop () const

void	setMusicLoop (bool loop)

bool	getMusicVolume () const

void	setMusicVolume (float volume)

float	getMusicDuration () const

float	getMusicElapsed () const

float	getMusicRemaining () const

void	setMusicElapsed (float time)

void	setMusicRemaining (float time)

void	stopMusic ()

void	pauseMusic ()

void	resumeMusic ()

void	restartMusic ()

void	queueMusic (Sound *sound, bool loop=false, float volume=1.0)

const std::vector< const Sound * >	getMusicQueue () const

size_t	getMusicQueueSize () const

void	skipMusicQueue (unsigned int steps=0)

void	playEffect (std::string key, Sound *sound, bool loop=false, float volume=1.0f, bool force=false)

int	getAvailableChannels ()

bool	isActiveEffect (std::string key) const

SoundState	getEffectState (std::string key) const

bool	isEffectLoop (std::string key) const

void	setEffectLoop (std::string key, bool loop)

float	getEffectVolume (std::string key) const

void	setEffectVolume (std::string key, float volume)

float	getEffectDuration (std::string key) const

float	getEffectElapsed (std::string key) const

float	getEffectRemaining (std::string key) const

void	setEffectElapsed (std::string key, float time)

void	setEffectRemaining (std::string key, float time)

void	stopEffect (std::string key)

void	pauseEffect (std::string key)

void	resumeEffect (std::string key)

void	restartEffect (std::string key)

void	stopAllEffects ()

void	pauseAllEffects ()

void	resumeAllEffects ()

void	stopAll ()

void	pauseAll ()

void	resumeAll ()

Static Public Member Functions
static SoundEngine *	getInstance ()

static void	start ()

static void	stop ()

Protected Member Functions
	SoundEngine ()

	~SoundEngine ()

bool	init ()

void	dispose ()

void	clearQueue ()

void	playMusic (SoundPacket *data)

void	playEffect (SoundPacket *data, bool force=false)

void	gcMusic (int id)

void	gcEffect (int id, const std::string key)

Static Protected Member Functions
static SoundState	convertAudioState (AENG::AudioState state)

Protected Attributes
experimental::AudioProfile *	_musicProfile

experimental::AudioProfile *	_effectProfile

SoundPacket *	_musicData

std::deque< SoundPacket * >	_mqueue

SoundPacket **	_effectData

std::unordered_map< std::string, int >	_effectIDs

std::deque< std::string >	_equeue

Static Protected Attributes
static SoundEngine *	_gEngine = nullptr

Detailed Description

Class provides a singleton sound manager

This class is a more robust sound manager on top of the new experimental AudioEngine. In particular, it allows the user to specify sound instances by predefined key. This cuts down on the overhead of managing the sound identifier. It also provides advanced support for stringing together music loops.

This class has all of the functionality of SimpleAudioEngine except for pan and pitch support. As there is no true cross platform support for either of these (they are usually ignored on non-Apple platforms) this should not be a problem.

You cannot create new instances of this class. Instead, you should access the singleton through the three static methods: start(), stop() and getInstance().

Member Enumeration Documentation

enum SoundEngine::SoundState

strong

This enumeration provides a public alternative to AudioState

We want to avoid any direct contact with the experimental AudioEngine.

Enumerator
INACTIVE	This sound channel is not actually active
LOADING	This sound is still being loaded
PLAYING	This sound is active and currently playing
PAUSED	This sound is active but is currently paused

Constructor & Destructor Documentation

SoundEngine::SoundEngine ( )

inlineprotected

Creates, but does not initialize the singleton sound engine

The engine must be initialized before is can be used.

SoundEngine::~SoundEngine ( )

inlineprotected

Disposes of the singleton sound engine.

This destructor releases all of the resources associated with this sound engine.

Member Function Documentation

void SoundEngine::clearQueue ( )

protected

Clears the music queue, but does not release any other resources.

SoundEngine::SoundState SoundEngine::convertAudioState ( AENG::AudioState state )

staticprotected

Returns the SoundState value equivalent to the AudioState value.

Parameters

state the original AudioState value

Returns: the SoundState value equivalent to the AudioState value.

const Sound* SoundEngine::currentMusic ( ) const

inline

Returns a sound packet with the settings of the background music

If there is no active background music, this method returns null.

Returns: a sound packet with the settings of the background music

void SoundEngine::dispose ( )

protected

Releases all resources for this singleton sound engine.

If you need to use the engine again, you must call init().

void SoundEngine::gcEffect	(	int	id,
		const std::string	key
	)

protected

Callback function for when a sound effect channel finishes

This method is called when the active sound effect completes. It garbage collects the sound effect, allowing its key to be reused.

Parameters

id	the sound id for the completed sound
key	the reference key for the completed sound

void SoundEngine::gcMusic ( int id )

protected

Callback function for when a music channel finishes

This method is called when the active music completes. If there is any music waiting in the queue, it plays it immediately (using the second channel for a smooth transition). Otherwise, it sets _musicData to inactive.

Parameters

id	the sound id for the completed sound

int SoundEngine::getAvailableChannels ( )

inline

Returns the number of channels available for sound effects.

There are a limited number of channels available for sound effects. If you go over the number available, you cannot play another sound unless you force it. In that case, it will grab the channel from the longest playing sound effect.

Returns: the number of channels available for sound effects.

float SoundEngine::getEffectDuration ( std::string key ) const

Returns the duration of the sound effect

This method does not take into account whether the sound effect is on a loop.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect

Returns: the duration of the sound effect

float SoundEngine::getEffectElapsed ( std::string key ) const

Returns the elapsed time of the sound effect

The elapsed time is the current position of the sound from the beginning. It does not include any time spent on a continuous loop.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect

Returns: the elapsed time of the sound effect

float SoundEngine::getEffectRemaining ( std::string key ) const

Returns the time remaining for the sound effect.

The time remaining is just duration-elapsed. This method does not take into account whether the sound is on a loop.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect

Returns: the time remaining for the sound effect

SoundEngine::SoundState SoundEngine::getEffectState ( std::string key ) const

Returns the current state of the sound effect

If the key does not correspond to a channel, this method returns INACTIVE.

Parameters

key	the reference key for the sound effect

Returns: the current state of the sound effect

float SoundEngine::getEffectVolume ( std::string key ) const

Returns the current volume of the sound effect.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect

Returns: the current volume of the sound effect

static SoundEngine* SoundEngine::getInstance ( )

inlinestatic

Returns the singleton instance of the sound engine.

If the sound engine has not been started, then this method will return null.

Returns: the singleton instance of the sound engine.

float SoundEngine::getMusicDuration ( ) const

inline

Returns the duration of the background music

This method does not take into account whether the music is on a loop. It also does not include the duration of any music waiting in the queue. If there is no active background music, this method will return 0.

Returns: the duration of the background music

float SoundEngine::getMusicElapsed ( ) const

inline

Returns the elapsed time of the background music.

The elapsed time is the current position of the music from the beginning. It does not include any time spent on a continuous loop. If there is no active background music, this method will return 0.

Returns: the elapsed time of the background music

const std::vector< const Sound * > SoundEngine::getMusicQueue ( ) const

Returns the sound information for current the music queue

Returns: the sound information for current the music queue

size_t SoundEngine::getMusicQueueSize ( ) const

inline

Returns the size of the current the music queue

Returns: the size of the current the music queue

float SoundEngine::getMusicRemaining ( ) const

inline

Returns the time remaining for the background music.

The time remaining is just duration-elapsed. This method does not take into account whether the music is on a loop. It also does not include the duration of any music waiting in the queue. If there is no active background music, this method will return 0.

Returns: the time remaining for the background music

SoundEngine::SoundState SoundEngine::getMusicState ( ) const

Returns the current state of the background music

Returns: the current state of the background music

bool SoundEngine::getMusicVolume ( ) const

inline

Returns the volume of the background music

If there is no active background music, this method will return 0.

Returns: the volume of the background music

bool SoundEngine::init ( )

protected

Initializes the sound engine.

This method starts up the experimental AudioEngine and creates the custom profiles for this implementation.

Returns: true if the sound engine was successfully initialized.

bool SoundEngine::isActiveEffect ( std::string key ) const

inline

Returns true if the key is associated with an active channel.

Parameters

key	the reference key for the sound effect

Returns: true if the key is associated with an active channel.

bool SoundEngine::isEffectLoop ( std::string key ) const

Returns true if the sound effect is in a continuous loop.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect

Returns: true if the sound effect is in a continuous loop.

bool SoundEngine::isMusicLoop ( ) const

inline

Returns true if the background music is in a continuous loop.

If there is no active background music, this method will return false.

Returns: true if the background music is in a continuous loop.

void SoundEngine::pauseAll ( )

Pauses all sounds, both music and sound effects, allowing them to be resumed later.

void SoundEngine::pauseAllEffects ( )

Pauses all sound effects, allowing them to be resumed later.

void SoundEngine::pauseEffect ( std::string key )

Pauses the sound effect for the given key.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect

void SoundEngine::pauseMusic ( )

Pauses the background music, allowing it to be resumed later.

This method has no effect on the music queue.

void SoundEngine::playEffect	(	SoundPacket *	data,
		bool	force = `false`
	)

protected

Plays the sound effect for the associated sound packet

This does not change the _effectData attribute. It simply plays the sound and attaches the callback function.

There are a limited number of channels available for sound effects. If you go over the number available, the sound will not play unless force is true. In that case, it will grab the channel from the longest playing sound effect.

Parameters

data	the settings for the sound effect to play
force	whether to force another sound to stop.

void SoundEngine::playEffect	(	std::string	key,
		Sound *	sound,
		bool	loop = `false`,
		float	volume = `1.0f`,
		bool	force = `false`
	)

Plays given sound effect, and associates it with the specified key.

Sound effects are associated with a reference key. This allows the application to easily reference the sound state without having to internally manage pointers to the AudioEngine.

If the key is already associated with an active sound channel, this method will stop the existing sound and replace it with this one. It is the responsibility of the application layer to manage key usage.

There are a limited number of channels available for sound effects. If you go over the number available, the sound will not play unless force is true. In that case, it will grab the channel from the longest playing sound effect.

Parameters

key	the reference key for the sound effect
filename	the sound effect file to play
loop	whether to loop the sound effect continuously
volume	the sound effect volume
force	whether to force another sound to stop.

the sound asset (until completion)

void SoundEngine::playMusic ( SoundPacket * data )

protected

Plays the music for the associated sound packet

This does not change the _musicData attribute. It simply plays the sound and attaches the callback function.

Parameters

data	the settings for the sound effect to play

void SoundEngine::playMusic	(	Sound *	sound,
		bool	loop = `false`,
		float	volume = `1.0`
	)

Plays given sound file as background music.

Music is handled differently from sound effects. Only one sound effect can be treated as music at a time. However, it is possible to queue music files for immediate playback once the active sound is finished.

This method immediately plays the provided sound. Hence it overrides and clears the music queue. To safely play a sound without affecting the music queue, use the method queueMusic instead.

Parameters

filename	the sound file to play as music
loop	whether to loop the music continuously
volume	the music volume

the sound asset (until completion)

void SoundEngine::queueMusic	(	Sound *	sound,
		bool	loop = `false`,
		float	volume = `1.0`
	)

Adds the given sound file the background music queue

Music is handled differently from sound effects. Only one sound effect can be treated as music at a time. However, it is possible to queue music files for immediate playback once the active sound is finished.

If the queue is empty and there is no active music, this method will play the music immediately. Otherwise, it will add the music to the queue, and it will play as soon as it is removed from the queue. Only the last element of the queue can be in a loop (otherwise the queue will experience starvation). Therefore, this method will disable the loop option of the active music and any music in the queue.

Parameters

filename	the sound file to play as music
loop	whether to loop the music continuously
volume	the music volume

the sound asset (until completion)

void SoundEngine::restartEffect ( std::string key )

Restarts the sound effect from the beginning

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect

void SoundEngine::restartMusic ( )

Restarts the current background music from the beginning

This method has no effect on the music queue.

void SoundEngine::resumeAll ( )

Resumes all paused sounds, both music and sound effects.

void SoundEngine::resumeAllEffects ( )

Resumes all paused sound effects.

void SoundEngine::resumeEffect ( std::string key )

Resumes the sound effect for the given key.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect

void SoundEngine::resumeMusic ( )

Resumes the background music assuming that it was paused previously.

void SoundEngine::setEffectElapsed	(	std::string	key,
		float	time
	)

Sets the elapsed time of the sound effect

The elapsed time is the current position of the sound from the beginning. It does not include any time spent on a continuous loop.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect
time	the new position of the sound effect

void SoundEngine::setEffectLoop	(	std::string	key,
		bool	loop
	)

Sets whether the sound effect is in a continuous loop.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect
loop	whether the sound effect is in a continuous loop

void SoundEngine::setEffectRemaining	(	std::string	key,
		float	time
	)

Sets the time remaining for the sound effect.

The time remaining is just duration-elapsed. This method does not take into account whether the sound is on a loop.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect
time	the new time remaining for the sound effect

void SoundEngine::setEffectVolume	(	std::string	key,
		float	volume
	)

Sets the current volume of the sound effect.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect
volume	the current volume of the sound effect

void SoundEngine::setMusicElapsed ( float time )

Sets the elapsed time of the background music.

The elapsed time is the current position of the music from the beginning. It does not include any time spent on a continuous loop.

If there is no active background music, this method will raise an error.

Parameters

time	the new position of the background music

void SoundEngine::setMusicLoop ( bool loop )

Sets whether the background music is on a continuous loop.

If loop is true, this will clear the active music queue (as a continuous loop cannot be followed by later music).

If there is no active background music, this method will raise an error.

Parameters

loop	whether the background music should be on a continuous loop

void SoundEngine::setMusicRemaining ( float time )

Sets the time remaining for the background music.

The time remaining is just duration-elapsed. It does not take into account whether the music is on a loop. is the current position of the music from the beginning. It does not include any time spent on a continuous loop. It does not include the duration of any music waiting in the queue.

If there is no active background music, this method will raise an error.

Parameters

time	the new time remaining of the background music

void SoundEngine::setMusicVolume ( float volume )

Sets the volume of the background music

If there is no active background music, this method will raise an error.

Parameters

volume the volume of the background music

void SoundEngine::skipMusicQueue ( unsigned int steps = 0 )

Skips ahead in the music queue.

The value skip is the number of songs to skip over. A value of 0 will simply skip over the active music to the next element of the queue. Each value above 0 will skip over one more element in the queue. If this skipping empties the queue, then no music will play.

Parameters

steps number of elements to skip in the queue

Skips ahead in the music queue.

The value skip is the number of songs to skip over. A value of 0 will simply skip over the active music to the next element of the queue. Each value above 0 will skip over one more element in the queue. If this skipping empties the queue, then no music will play.

Parameters

steps number of elements to skip in the queue

a music assets stopped or skipped

void SoundEngine::start ( )

static

Starts the singleton sound engine.

Once this method is called, the method getInstance() will no longer return null. Calling the method multiple times (without calling stop) will have no effect.

void SoundEngine::stop ( )

static

Starts the singleton sound, releasing all resources.

Once this method is called, the method getInstance() will return null. Calling the method multiple times (without calling stop) will have no effect.

void SoundEngine::stopAll ( )

Stops all sounds, both music and sound effects.

This effectively clears the sound engine.

all active sounds assets

void SoundEngine::stopAllEffects ( )

Stops all sound effects, removing them from the engine.

all active sounds assets

void SoundEngine::stopEffect ( std::string key )

Stops the sound effect for the given key, removing it.

If the key does not correspond to a channel, this method raises an error.

Parameters

key	the reference key for the sound effect

the stopped sound asset

void SoundEngine::stopMusic ( )

Stops the background music

This method clears the queue of any further music.

all queued music assets

Member Data Documentation

SoundPacket** SoundEngine::_effectData

protected

The sound packets for all active effects

std::unordered_map<std::string,int> SoundEngine::_effectIDs

protected

Map keys to identifiers

experimental::AudioProfile* SoundEngine::_effectProfile

protected

The sound profile for sound effect channels (uses the leftover channels)

std::deque<std::string> SoundEngine::_equeue

protected

The queue for subsequent sound loops

SoundEngine * SoundEngine::_gEngine = nullptr

staticprotected

Reference to the sound engine singleton

std::deque<SoundPacket*> SoundEngine::_mqueue

protected

The queue for subsequent sound loops

SoundPacket* SoundEngine::_musicData

protected

The sound packet for the active music channel

experimental::AudioProfile* SoundEngine::_musicProfile

protected

The sound profile for music channels (we reserve 2 for smooth loop transitions)

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

/Users/wmwhite/Developer/cocos2d-cornell/cocos/cornell/CUSoundEngine.h
/Users/wmwhite/Developer/cocos2d-cornell/cocos/cornell/CUSoundEngine.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation