Our (very simple) sound system. More...

#include <SoundDevice.h>

Public Member Functions
AngelSampleHandle	LoadSample (const char *filename, bool isStream)
AngelSoundHandle	PlaySound (AngelSampleHandle sample, float volume=1.0f, bool looping=false, int flags=0)
void	StopSound (AngelSoundHandle sound)
void	PauseSound (AngelSoundHandle sound, bool paused)
bool	IsPlaying (AngelSoundHandle sound)
bool	IsPaused (AngelSoundHandle sound)
void	SetPan (AngelSoundHandle sound, float newPan)
void	SetVolume (AngelSoundHandle sound, float newVolume)
void	SetSoundCallback (GameManager instance, void(GameManager::function)(AngelSoundHandle param))
void	Update ()
void	Shutdown ()
Static Public Member Functions
static SoundDevice &	GetInstance ()

Detailed Description

Our sound system is pretty much just a light wrapper around FMOD. We don't expose all of FMOD's functionality, but if you're interested in more advanced usage, it shouldn't be hard to expand this class.

For more information on FMOD: http://www.fmod.org/

Note that FMOD requires licensing fees if you want to distribute your game for money. Because we're focused on prototyping, and FMOD supports a wide array of sound formats while producing very high quality audio, it's the default sound system in Angel. If it doesn't fit your needs for some reason, though, no worries. This same interface can play sound through OpenAL, but only in the Ogg Vorbis format.

To switch to OpenAL, set the ANGEL_DISABLE_FMOD flag in AngelConfig.h to 1.

This class uses the singleton pattern; you can't actually declare a new instance of a SoundDevice. To access sound in your world, use "theSound" to retrieve the singleton object. "theSound" is defined in both C++ and Lua.

If you're not familiar with the singleton pattern, this paper is a good starting point. (Don't be afraid that it's written by Microsoft.)

http://msdn.microsoft.com/en-us/library/ms954629.aspx

Definition at line 95 of file SoundDevice.h.

Member Function Documentation

SoundDevice & SoundDevice::GetInstance ( ) [static]

Used to access the singleton instance of this class. As a shortcut, you can just use "theSound".

Returns:: The singleton

Definition at line 114 of file SoundDevice.cpp.

AngelSampleHandle SoundDevice::LoadSample	(	const char *	filename,
		bool	isStream
	)

Loads a sound file from disk and gets it ready to be played by the system. Depending on how many sounds you're loading at once and/or how large they are, this could cause a hiccup. It's best to call this in advance of when you actually want to play the sound.

Parameters:

filename	The path to the file you want to load
isStream	Whether or not the sound should stream or get loaded all at once

Returns:: The AngelSampleHandle that you should hold on to for when you actually want to play the sound. You'll pass this to SoundDevice::PlaySound.

Definition at line 290 of file SoundDevice.cpp.

AngelSoundHandle SoundDevice::PlaySound	(	AngelSampleHandle	sample,
		float	volume = `1.0f`,
		bool	looping = `false`,
		int	flags = `0`
	)

Plays a sound that has been previously loaded.

Parameters:

sample	The AngelSampleHandle that you got from the SoundDevice::LoadSample function
volume	The desired loudness of the sound, as a multiplier of its normal volume. (1.0 is maximum volume.)
looping	Whether you want the sound to repeat when it's done
flags	Currently unused; this will eventually let you pass in flags to the underlying sound system (only supported with FMOD)

Returns:: The AngelSoundHandle that you can use to monitor or affect playback

Definition at line 439 of file SoundDevice.cpp.

void SoundDevice::StopSound ( AngelSoundHandle sound )

Stops a sound that is currently playing.

Parameters:

sound The handle to the playing sound, gotten from SoundDevice::PlaySound

Definition at line 585 of file SoundDevice.cpp.

void SoundDevice::PauseSound	(	AngelSoundHandle	sound,
		bool	paused
	)

Pauses a sound that is currently playing. Its playback can be resumed from the same point later.

Parameters:

sound	The handle to the playing sound, gotten from SoundDevice::PlaySound
paused	If true, the sound will be paused. If false, it will be unpaused.

Definition at line 598 of file SoundDevice.cpp.

bool SoundDevice::IsPlaying ( AngelSoundHandle sound )

Find out whether or not a sound is still playing

Parameters:

sound The handle to the playing sound, gotten from SoundDevice::PlaySound

Returns:: True if the sound is still playing, false if it's not

Definition at line 617 of file SoundDevice.cpp.

bool SoundDevice::IsPaused ( AngelSoundHandle sound )

Find out whether a sound is paused

Parameters:

sound The handle to the playing sound, gotten from SoundDevice::PlaySound

Returns:: True if the sound is paused, false if it's playing or stopped

Definition at line 634 of file SoundDevice.cpp.

void SoundDevice::SetPan	(	AngelSoundHandle	sound,
		float	newPan
	)

Change the stereo positioning of a sound while it's playing.

NB: If you've disabled FMOD (and are thus using the OpenAL backend), only mono sounds will pan properly.

Parameters:

sound	The handle to the playing sound, gotten from SoundDevice::PlaySound
newPan	The new pan value. Should range from -1.0 (full left) to 1.0 (full right)

Definition at line 651 of file SoundDevice.cpp.

void SoundDevice::SetVolume	(	AngelSoundHandle	sound,
		float	newVolume
	)

Change the volume of a sound while it's playing

Parameters:

sound	The handle to the playing sound, gotten from SoundDevice::PlaySound
newVolume	The new volume level. Should range from 0.0 (silent) to 1.0 (full volume)

Definition at line 664 of file SoundDevice.cpp.

void SoundDevice::SetSoundCallback	(	GameManager *	instance,
		void(GameManager::*)(AngelSoundHandle param)	function
	)		`[inline]`

If you set a callback here, it will be executed whenever a sound finishes playing. If you're doing a music-or-sound-intensive game, this can be very important to you.

Note that the callback you're passing must be a member function of a GameManager.

Parameters:

instance	The GameManager instance on which to execute the function
void	The function to execute, which will be passed the AngelSoundHandle

Definition at line 199 of file SoundDevice.h.

void SoundDevice::Update ( )

Calls the underlying FMOD update function to keep the sound thread chugging along appropriately.

NB: Must be called once (and only once) per frame. The World already calls this function appropriately, so you should only be calling it if you really know what you're doing.

Definition at line 517 of file SoundDevice.cpp.

void SoundDevice::Shutdown ( )

Releases all sounds (invalidating your leftover AngelSoundHandle and AngelSampleHandle pointers) and shuts down FMOD if necessary. Should really only be called at the end of the game, which the World handles for you by default.

Definition at line 234 of file SoundDevice.cpp.

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

Infrastructure/SoundDevice.h
Infrastructure/SoundDevice.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation