Homepage Demos Overview Downloads Tutorials Reference
Credits
Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members | Related Pages | Search

SoundManager Class Reference

#include <SoundManager.h>

List of all members.


Detailed Description

Provides sound effects and caching services, as well as mixing buffers for the SoundPlay process.

Provides easy methods for playing back sounds, either from files on the memory stick, or from dynamically generated buffers. You can chain playback commands so that when one sound finishes, another picks up automatically. This might be handy if, say, someone wants to write an MP3 player ;) The sounds would be too large to load into memory all at once, but you could load a block at a time and chain them so it seamlessly moves from one to the other.

All functions will attempt to lock the SoundManager.

Todo:
Volume control, variable playback speed, support more wav file formats (all go together)

Add functions to hand out regions to be filled out to avoid copying into the buffer.

Definition at line 32 of file SoundManager.h.

Public Types

typedef SoundManagerMsg::Snd_ID Snd_ID
 This is used for referring to sound data so you can start playing it or release it.

typedef unsigned short Play_ID
 This is for referring to instances of the play command so you can stop, pause, or monitor progress (later versions will send events upon completion).

enum  MixMode_t { Fast, Quality }
 Used to set the mode for mixing multiple sound channels. More...

enum  QueueMode_t { Enqueue, Pause, Stop, Override }

Public Member Functions

 SoundManager ()
 constructor

void InitAccess (OSubject *subj)
 Needed to send sounds to the SoundPlay process.

Snd_ID LoadFile (const char *name)
 loads a wav file (if it matches Config::sound_config settings - can't do resampling yet)

Snd_ID LoadBuffer (const char buf[], unsigned int len)
 loads raw samples from a buffer (assumes matches Config::sound_config settings)

void ReleaseFile (const char *name)
 Marks the sound buffer to be released after the last play command completes (or right now if not being played).

void Release (Snd_ID id)
 Marks the sound buffer to be released after the last play command completes (or right now if not being played).

Play_ID PlayFile (const char *name)
 play a wav file (if it matches Config::sound_config settings - can't do resampling yet)

Play_ID PlayBuffer (const char buf[], unsigned int len)
 loads raw samples from a buffer (assumes buffer matches Config::sound_config settings)

Play_ID Play (Snd_ID id)
 plays a previously loaded buffer or file

Play_ID ChainFile (Play_ID base, const char *next)
 allows automatic queuing of sounds - good for dynamic sound sources!

Play_ID ChainBuffer (Play_ID base, const char buf[], unsigned int len)
 allows automatic queuing of sounds - good for dynamic sound sources!

Play_ID Chain (Play_ID base, Snd_ID next)
 allows automatic queuing of sounds - good for dynamic sound sources!

void StopPlay ()
 Lets you stop playback of all sounds.

void StopPlay (Play_ID id)
 Lets you stop playback of a sound.

void PausePlay (Play_ID id)
 Lets you pause playback.

void ResumePlay (Play_ID id)
 Lets you resume playback.

void SetMode (unsigned int max_channels, MixMode_t mixer_mode, QueueMode_t queuing_mode)
 Lets you control the maximum number of channels (currently playing sounds), method for mixing (applies when max_chan>1), and queuing method (for when overflow channels).

unsigned int GetRemainTime (Play_ID id) const
 Gives the time until the sound finishes, in milliseconds. Subtract 32 to get guarranteed valid time for this ID.

unsigned int CopyTo (OSoundVectorData *data)
 Copies the sound data to the OPENR buffer, ready to be passed to the system, only called by SoundPlay.

void ReceivedMsg (const ONotifyEvent &event)
 updates internal data structures on the SoundPlay side - you shouldn't be calling this

unsigned int GetNumPlaying ()
 
Returns:
number of sounds currently playing



Static Public Attributes

const Snd_ID invalid_Snd_ID = (Snd_ID)-1
 for reporting errors

const Snd_ID MAX_SND = 50
 the number of sounds that can be loaded at any given time

const Play_ID invalid_Play_ID = (Play_ID)-1
 for reporting errors

const Play_ID MAX_PLAY = 256
 the number of sounds that can be enqueued at the same time (see MixMode_t)

const unsigned int MAX_NAME_LEN = 64
 maximum length of a path


Protected Types

typedef ListMemBuf< SoundData,
MAX_SND, Snd_ID
sndlist_t
 For convenience.

typedef ListMemBuf< PlayState,
MAX_PLAY, Play_ID
playlist_t
 For convenience.

typedef ListMemBuf< Play_ID,
MAX_PLAY, Play_ID
chanlist_t
 For convenience.


Protected Member Functions

Snd_ID lookup (const char *name) const
 Looks to see if name matches any of the sounds in sndlist.

Snd_ID lookupPath (const char *path) const
 Looks to see if name matches any of the sounds in sndlist (assumes is absolute path).

void selectChannels (std::vector< Play_ID > &mix)
 selects which of the channels are actually to be mixed together, depending on queue_mode

void updateChannels (const std::vector< Play_ID > &mixs, size_t used)
 update the offsets of sounds which weren't mixed (when needed depending on queue_mode)

bool endPlay (Play_ID id)
 called when a buffer end is reached, may reset buffer to next in chain, or just StopPlay()

 SoundManager (const SoundManager &)
 don't call

SoundManager operator= (const SoundManager &)
 don't call


Static Protected Member Functions

RCRegion * initRegion (unsigned int size)
 Sets up a shared region to hold a sound - rounds to nearest page size.

const char * makePath (const char *name, char tmp[MAX_NAME_LEN])
 prepends config.sound.root to the name if necessary


Protected Attributes

sndlist_t sndlist
 Holds a list of all currently loaded sounds.

playlist_t playlist
 Holds a list of all sounds currently enqueued.

chanlist_t chanlist
 Holds a list of all currently playing sounds, ordered newest (front) to oldest(back).

MixMode_t mix_mode
 Current mixing mode, set by SetMode();.

QueueMode_t queue_mode
 Current queuing mode, set by SetMode();.

unsigned int max_chan
 Current maximum number of sounds to mix together.

MutexLock< ProcessID::NumProcesses > lock
 Prevents multiple processes from accessing at the same time.

OSubject * subjs [ProcessID::NumProcesses]
 For automatic transmission of shared regions to SoundPlay.


Member Typedef Documentation

typedef ListMemBuf<Play_ID,MAX_PLAY,Play_ID> SoundManager::chanlist_t [protected]
 

For convenience.

Definition at line 204 of file SoundManager.h.

typedef unsigned short SoundManager::Play_ID
 

This is for referring to instances of the play command so you can stop, pause, or monitor progress (later versions will send events upon completion).

Definition at line 43 of file SoundManager.h.

typedef ListMemBuf<PlayState,MAX_PLAY,Play_ID> SoundManager::playlist_t [protected]
 

For convenience.

Definition at line 200 of file SoundManager.h.

typedef SoundManagerMsg::Snd_ID SoundManager::Snd_ID
 

This is used for referring to sound data so you can start playing it or release it.

Definition at line 38 of file SoundManager.h.

typedef ListMemBuf<SoundData,MAX_SND,Snd_ID> SoundManager::sndlist_t [protected]
 

For convenience.

Definition at line 187 of file SoundManager.h.


Member Enumeration Documentation

enum SoundManager::MixMode_t
 

Used to set the mode for mixing multiple sound channels.

Feel free to add a higher quality mixer if you're an audiophile - I'm pretty new to sound processing

Enumeration values:
Fast  uses bit shifting trick, but can result in reduced volume with more active channels, best if you set max_channels to a power of 2
Quality  uses real division to maintain volume level, although still a rather naive (but relatively fast) algorithm

Definition at line 51 of file SoundManager.h.

enum SoundManager::QueueMode_t
 

Enumeration values:
Enqueue  newer sounds are played when a channel opens up (when old sound finishes)
Pause  newer sounds pause oldest sound, which continues when a channel opens
Stop  newer sounds stop oldest sound
Override  older sounds have play heads advanced, but don't get mixed until a channel opens

Definition at line 56 of file SoundManager.h.


Constructor & Destructor Documentation

SoundManager::SoundManager  ) 
 

constructor

Definition at line 19 of file SoundManager.cc.

SoundManager::SoundManager const SoundManager  )  [protected]
 

don't call


Member Function Documentation

SoundManager::Play_ID SoundManager::Chain Play_ID  base,
Snd_ID  next
 

allows automatic queuing of sounds - good for dynamic sound sources!

if you chain more than once to the same base, the new buffers are appended to the end of the chain - the new buffer doesn't replace the current chain

Returns:
base - just for convenience of multiple calls

Definition at line 241 of file SoundManager.cc.

References invalid_Play_ID, invalid_Snd_ID, Play_ID, and playlist.

SoundManager::Play_ID SoundManager::ChainBuffer Play_ID  base,
const char  buf[],
unsigned int  len
 

allows automatic queuing of sounds - good for dynamic sound sources!

if you chain more than once to the same base, the new buffers are appended to the end of the chain - the new buffer doesn't replace the current chain

Returns:
base - just for convenience of multiple calls

Definition at line 221 of file SoundManager.cc.

References invalid_Play_ID, invalid_Snd_ID, LoadBuffer(), Play_ID, playlist, and Snd_ID.

SoundManager::Play_ID SoundManager::ChainFile Play_ID  base,
const char *  next
 

allows automatic queuing of sounds - good for dynamic sound sources!

if you chain more than once to the same base, the new buffers are appended to the end of the chain - the new buffer doesn't replace the current chain

Returns:
base - just for convenience of multiple calls

Definition at line 201 of file SoundManager.cc.

References invalid_Play_ID, invalid_Snd_ID, LoadFile(), Play_ID, playlist, and Snd_ID.

unsigned int SoundManager::CopyTo OSoundVectorData *  data  ) 
 

Copies the sound data to the OPENR buffer, ready to be passed to the system, only called by SoundPlay.

Returns:
the number of active sounds

Definition at line 325 of file SoundManager.cc.

References AutoLock, chanlist, config, endPlay(), Fast, ListMemBuf< PlayState, MAX_PLAY, Play_ID >::front(), ProcessID::getID(), lock, mix_mode, playlist, ListMemBuf< PlayState, MAX_PLAY, Play_ID >::pop_back(), ListMemBuf< PlayState, MAX_PLAY, Play_ID >::push_back(), Config::sound_config::sample_bits, selectChannels(), ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::size(), Snd_ID, sndlist, Config::sound, and updateChannels().

bool SoundManager::endPlay Play_ID  id  )  [protected]
 

called when a buffer end is reached, may reset buffer to next in chain, or just StopPlay()

Definition at line 655 of file SoundManager.cc.

References EventBase::audioEGID, config, erouter, invalid_Play_ID, Play_ID, playlist, EventRouter::postEvent(), Release(), Config::sound_config::sample_bits, Config::sound_config::sample_rate, Config::sound, EventBase::statusETID, and StopPlay().

unsigned int SoundManager::GetNumPlaying  )  [inline]
 

Returns:
number of sounds currently playing

Definition at line 151 of file SoundManager.h.

References chanlist, and ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::size().

unsigned int SoundManager::GetRemainTime Play_ID  id  )  const
 

Gives the time until the sound finishes, in milliseconds. Subtract 32 to get guarranteed valid time for this ID.

You should be passing the beginning of a chain to get proper results...
May be slightly conservative (will report too small a time) because this does not account for delay until SoundPlay picks up the message that a sound has been added.
However, it is slighly optimistic (will report too large a time) because it processes a buffer all at one go, so it could mark the sound as finished (and cause the ID to go invalid) up to RobotInfo::SoundBufferTime (32 ms) before the sound finishes. So subtract SoundBufferTime if you want to be absolutely sure the ID will still valid.

Definition at line 313 of file SoundManager.cc.

References AutoLock, config, ProcessID::getID(), invalid_Play_ID, lock, playlist, Config::sound_config::sample_bits, Config::sound_config::sample_rate, sndlist, and Config::sound.

void SoundManager::InitAccess OSubject *  subj  ) 
 

Needed to send sounds to the SoundPlay process.

Definition at line 24 of file SoundManager.cc.

References ProcessID::getID(), and subjs.

RCRegion * SoundManager::initRegion unsigned int  size  )  [static, protected]
 

Sets up a shared region to hold a sound - rounds to nearest page size.

Definition at line 539 of file SoundManager.cc.

References ASSERT.

SoundManager::Snd_ID SoundManager::LoadBuffer const char  buf[],
unsigned int  len
 

loads raw samples from a buffer (assumes matches Config::sound_config settings)

The sound data will be cached until Release() is called a matching number of times.
This function is useful for dynamic sound sources. A copy will be made.

Definition at line 68 of file SoundManager.cc.

References AutoLock, config, SoundManagerMsg::getID(), ProcessID::getID(), initRegion(), invalid_Snd_ID, lock, SoundManagerMsg::MSG_SIZE, ListMemBuf< SoundData, MAX_SND, Snd_ID >::new_front(), region, Config::sound_config::sample_bits, SoundManagerMsg::setAdd(), sndlist, Config::sound, ProcessID::SoundProcess, and subjs.

SoundManager::Snd_ID SoundManager::LoadFile const char *  name  ) 
 

loads a wav file (if it matches Config::sound_config settings - can't do resampling yet)

Since the SoundManager does the loading, if the same file is being played more than once, only once copy is stored in memory

Parameters:
name can be either a full path, or a partial path relative to Config::sound_config::root
Returns:
ID number for future references (can also use name) The sound data will be cached until ReleaseFile() or Release() is called a matching number of times

Definition at line 30 of file SoundManager.cc.

References AutoLock, config, WAV::GetBitsPerSample(), WAV::GetDataEnd(), WAV::GetDataStart(), ProcessID::getID(), WAV::GetSamplingRate(), invalid_Snd_ID, LoadBuffer(), lock, lookupPath(), makePath(), MAX_NAME_LEN, Config::sound_config::sample_bits, Config::sound_config::sample_rate, WAV::Set(), Snd_ID, sndlist, Config::sound, WAV_SUCCESS, and WAVError.

SoundManager::Snd_ID SoundManager::lookup const char *  name  )  const [protected]
 

Looks to see if name matches any of the sounds in sndlist.

Definition at line 548 of file SoundManager.cc.

References lookupPath(), makePath(), and MAX_NAME_LEN.

SoundManager::Snd_ID SoundManager::lookupPath const char *  path  )  const [protected]
 

Looks to see if name matches any of the sounds in sndlist (assumes is absolute path).

Definition at line 553 of file SoundManager.cc.

References ListMemBuf< SoundData, MAX_SND, Snd_ID >::begin(), ListMemBuf< SoundData, MAX_SND, Snd_ID >::end(), invalid_Snd_ID, MAX_NAME_LEN, ListMemBuf< SoundData, MAX_SND, Snd_ID >::next(), and sndlist.

const char * SoundManager::makePath const char *  name,
char  tmp[MAX_NAME_LEN]
[static, protected]
 

prepends config.sound.root to the name if necessary

Definition at line 561 of file SoundManager.cc.

References config, Config::sound_config::root, and Config::sound.

SoundManager SoundManager::operator= const SoundManager  )  [protected]
 

don't call

void SoundManager::PausePlay Play_ID  id  ) 
 

Lets you pause playback.

Definition at line 282 of file SoundManager.cc.

References AutoLock, ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::begin(), chanlist, ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::end(), ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::erase(), ProcessID::getID(), invalid_Play_ID, lock, and ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::next().

SoundManager::Play_ID SoundManager::Play Snd_ID  id  ) 
 

plays a previously loaded buffer or file

Definition at line 167 of file SoundManager.cc.

References EventBase::activateETID, ASSERT, EventBase::audioEGID, AutoLock, chanlist, erouter, ProcessID::getID(), initRegion(), invalid_Play_ID, invalid_Snd_ID, lock, SoundManagerMsg::MSG_SIZE, ListMemBuf< PlayState, MAX_PLAY, Play_ID >::new_front(), Play_ID, playlist, EventRouter::postEvent(), ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::push_front(), region, SoundManagerMsg::setWakeup(), sndlist, ProcessID::SoundProcess, and subjs.

SoundManager::Play_ID SoundManager::PlayBuffer const char  buf[],
unsigned int  len
 

loads raw samples from a buffer (assumes buffer matches Config::sound_config settings)

The sound data will be released after done playing

Definition at line 155 of file SoundManager.cc.

References AutoLock, ProcessID::getID(), invalid_Play_ID, invalid_Snd_ID, LoadBuffer(), lock, Play(), playlist, ListMemBuf< PlayState, MAX_PLAY, Play_ID >::size(), Snd_ID, and sndlist.

SoundManager::Play_ID SoundManager::PlayFile const char *  name  ) 
 

play a wav file (if it matches Config::sound_config settings - can't do resampling yet)

Will do a call to LoadFile() first, and then automatically release the sound again when complete.

Parameters:
name can be either a full path, or a partial path relative to Config::sound_config::root
Returns:
ID number for future references The sound data will not be cached after done playing unless a call to LoadFile is made

Definition at line 143 of file SoundManager.cc.

References AutoLock, ProcessID::getID(), invalid_Play_ID, invalid_Snd_ID, LoadFile(), lock, Play(), playlist, ListMemBuf< PlayState, MAX_PLAY, Play_ID >::size(), Snd_ID, and sndlist.

void SoundManager::ReceivedMsg const ONotifyEvent &  event  ) 
 

updates internal data structures on the SoundPlay side - you shouldn't be calling this

Definition at line 509 of file SoundManager.cc.

References EventBase::activateETID, SoundManagerMsg::add, EventBase::audioEGID, ListMemBuf< PlayState, MAX_PLAY, Play_ID >::begin(), SoundManagerMsg::del, ListMemBuf< PlayState, MAX_PLAY, Play_ID >::end(), erouter, SoundManagerMsg::id, SoundManagerMsg::MSG_SIZE, ListMemBuf< PlayState, MAX_PLAY, Play_ID >::next(), playlist, EventRouter::postEvent(), SoundManagerMsg::region, sndlist, SoundManagerMsg::type, and SoundManagerMsg::wakeup.

void SoundManager::Release Snd_ID  id  ) 
 

Marks the sound buffer to be released after the last play command completes (or right now if not being played).

Definition at line 114 of file SoundManager.cc.

References AutoLock, ListMemBuf< SoundData, MAX_SND, Snd_ID >::erase(), ProcessID::getID(), initRegion(), invalid_Snd_ID, lock, SoundManagerMsg::MSG_SIZE, SoundManagerMsg::region, region, SoundManagerMsg::setDelete(), sndlist, ProcessID::SoundProcess, and subjs.

void SoundManager::ReleaseFile const char *  name  ) 
 

Marks the sound buffer to be released after the last play command completes (or right now if not being played).

Definition at line 106 of file SoundManager.cc.

References AutoLock, ProcessID::getID(), lock, lookup(), and Release().

void SoundManager::ResumePlay Play_ID  id  ) 
 

Lets you resume playback.

Definition at line 294 of file SoundManager.cc.

References AutoLock, ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::begin(), chanlist, ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::end(), ProcessID::getID(), invalid_Play_ID, lock, ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::next(), and ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::push_front().

void SoundManager::selectChannels std::vector< Play_ID > &  mix  )  [protected]
 

selects which of the channels are actually to be mixed together, depending on queue_mode

Definition at line 574 of file SoundManager.cc.

References ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::begin(), chanlist, ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::end(), endPlay(), Enqueue, max_chan, ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::next(), Override, Pause, playlist, ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::prev(), queue_mode, sndlist, and Stop.

void SoundManager::SetMode unsigned int  max_channels,
MixMode_t  mixer_mode,
QueueMode_t  queuing_mode
 

Lets you control the maximum number of channels (currently playing sounds), method for mixing (applies when max_chan>1), and queuing method (for when overflow channels).

Definition at line 305 of file SoundManager.cc.

References AutoLock, ProcessID::getID(), lock, max_chan, mix_mode, and queue_mode.

void SoundManager::StopPlay Play_ID  id  ) 
 

Lets you stop playback of a sound.

Definition at line 262 of file SoundManager.cc.

References EventBase::audioEGID, AutoLock, chanlist, config, EventBase::deactivateETID, ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::end(), ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::erase(), ListMemBuf< PlayState, MAX_PLAY, Play_ID >::erase(), erouter, ProcessID::getID(), invalid_Play_ID, lock, playlist, EventRouter::postEvent(), ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::prev(), Release(), Config::sound_config::sample_bits, Config::sound_config::sample_rate, and Config::sound.

void SoundManager::StopPlay  ) 
 

Lets you stop playback of all sounds.

Definition at line 256 of file SoundManager.cc.

References ListMemBuf< PlayState, MAX_PLAY, Play_ID >::begin(), ListMemBuf< PlayState, MAX_PLAY, Play_ID >::empty(), and playlist.

void SoundManager::updateChannels const std::vector< Play_ID > &  mixs,
size_t  used
[protected]
 

update the offsets of sounds which weren't mixed (when needed depending on queue_mode)

Definition at line 619 of file SoundManager.cc.

References ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::begin(), chanlist, ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::end(), endPlay(), Enqueue, ListMemBuf< Play_ID, MAX_PLAY, Play_ID >::next(), Override, Pause, playlist, queue_mode, Snd_ID, sndlist, and Stop.


Member Data Documentation

chanlist_t SoundManager::chanlist [protected]
 

Holds a list of all currently playing sounds, ordered newest (front) to oldest(back).

Definition at line 206 of file SoundManager.h.

const Play_ID SoundManager::invalid_Play_ID = (Play_ID)-1 [static]
 

for reporting errors

Definition at line 44 of file SoundManager.h.

const Snd_ID SoundManager::invalid_Snd_ID = (Snd_ID)-1 [static]
 

for reporting errors

Definition at line 39 of file SoundManager.h.

MutexLock<ProcessID::NumProcesses> SoundManager::lock [mutable, protected]
 

Prevents multiple processes from accessing at the same time.

Definition at line 218 of file SoundManager.h.

unsigned int SoundManager::max_chan [protected]
 

Current maximum number of sounds to mix together.

Definition at line 215 of file SoundManager.h.

const unsigned int SoundManager::MAX_NAME_LEN = 64 [static]
 

maximum length of a path

Definition at line 47 of file SoundManager.h.

const Play_ID SoundManager::MAX_PLAY = 256 [static]
 

the number of sounds that can be enqueued at the same time (see MixMode_t)

Definition at line 45 of file SoundManager.h.

const Snd_ID SoundManager::MAX_SND = 50 [static]
 

the number of sounds that can be loaded at any given time

Definition at line 40 of file SoundManager.h.

MixMode_t SoundManager::mix_mode [protected]
 

Current mixing mode, set by SetMode();.

Definition at line 209 of file SoundManager.h.

playlist_t SoundManager::playlist [protected]
 

Holds a list of all sounds currently enqueued.

Definition at line 202 of file SoundManager.h.

QueueMode_t SoundManager::queue_mode [protected]
 

Current queuing mode, set by SetMode();.

Definition at line 212 of file SoundManager.h.

sndlist_t SoundManager::sndlist [protected]
 

Holds a list of all currently loaded sounds.

Definition at line 189 of file SoundManager.h.

OSubject* SoundManager::subjs[ProcessID::NumProcesses] [protected]
 

For automatic transmission of shared regions to SoundPlay.

Definition at line 221 of file SoundManager.h.


The documentation for this class was generated from the following files:
Tekkotsu v1.4
Generated Sat Jul 19 00:09:10 2003 by Doxygen 1.3.2