Main Page   Modules   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members  

snx::SoundImplementation Class Reference

#include <SoundImplementation.h>

Inheritance diagram for snx::SoundImplementation:

Inheritance graph
[legend]
Collaboration diagram for snx::SoundImplementation:

Collaboration graph
[legend]
List of all members.

Public Methods

 SoundImplementation ()
 @semantics default constructor. More...

virtual void clone (ISoundImplementation *&newCopy)=0
 every implementation can return a new copy of itself. More...

virtual ~SoundImplementation ()
 @semantics destructor. More...

void copy (const SoundImplementation &si)
 copies current state of the system from one API to another. More...

virtual void trigger (const std::string &alias, const int &repeat=1)
 trigger a sound. More...

virtual bool isPlaying (const std::string &alias)
 is the sound currently playing? More...

virtual void setRetriggerable (const std::string &alias, bool onOff)
 when sound is already playing then you call trigger, does the sound restart from beginning? (if a tree falls and no one is around to hear it, does it make sound?). More...

virtual bool isRetriggerable (const std::string &alias)
 is the sound retriggerable? More...

virtual void stop (const std::string &alias)
 @semantics stop the sound @input alias of the sound to be stopped. More...

virtual void pause (const std::string &alias)
 pause the sound, use unpause to return playback where you left off... More...

virtual void unpause (const std::string &alias)
 resume playback from a paused state. More...

virtual bool isPaused (const std::string &alias)
 if the sound is paused, then return true. More...

virtual void setAmbient (const std::string &alias, bool ambient=false)
 ambient or positional sound. More...

virtual bool isAmbient (const std::string &alias)
 is the sound ambient - attached to the listener, doesn't change volume when listener moves... More...

virtual void setPitchBend (const std::string &alias, float amount)
 bend the pitch of the sound. More...

virtual void setVolume (const std::string &alias, float amount)
 affect volume. More...

virtual void setCutoff (const std::string &alias, float amount)
 affect cutoff. More...

virtual void setPosition (const std::string &alias, float x, float y, float z)
 set sound's 3D position. More...

virtual void getPosition (const std::string &alias, float &x, float &y, float &z)
 get sound's 3D position @input alias is a name that has been associate()d with some sound data @output x,y,z are returned in OpenGL coordinates. More...

virtual void setListenerPosition (const gmtl::Matrix44f &mat)
 set the position of the listener. More...

virtual void getListenerPosition (gmtl::Matrix44f &mat)
 get the position of the listener. More...

virtual int startAPI ()=0
 start the sound API, creating any contexts or other configurations at startup. More...

virtual bool isStarted () const=0
 query whether the API has been started or not @semantics return true if api has been started, false otherwise. More...

virtual void shutdownAPI ()
 kill the sound API, deallocating any sounds, etc... More...

virtual void configure (const snx::SoundAPIInfo &sai)
virtual void configure (const std::string &alias, const snx::SoundInfo &description)
 configure/reconfigure a sound configure: associate a name (alias) to the description if not already done reconfigure: change properties of the sound to the descriptino provided. More...

virtual void remove (const std::string &alias)
 remove a configured sound, any future reference to the alias will not cause an error, but will not result in a rendered sound. More...

virtual void step (const float &timeElapsed)
 @semantics call once per sound frame (doesn't have to be same as your graphics frame) @input time elapsed since last frame. More...

virtual void clear ()
 clear all associate()tions. More...

virtual void bindAll ()
 bind: load (or reload) all associate()d sounds. More...

virtual void unbindAll ()
 unbind: unload/deallocate all associate()d sounds. More...

virtual void bind (const std::string &alias)=0
 load/allocate the sound data this alias refers to the sound API. More...

virtual void unbind (const std::string &alias)=0
 unload/deallocate the sound data this alias refers from the sound API. More...

snx::SoundInfo & lookup (const std::string &alias)
void setName (const std::string &name)
std::string & name ()

Protected Attributes

std::string mName
snx::SoundAPIInfo mSoundAPIInfo
std::map< std::string, snx::SoundInfo > mSounds
gmtl::Matrix44f mListenerPos

Constructor & Destructor Documentation

snx::SoundImplementation::SoundImplementation (    )  [inline]
 

@semantics default constructor.

Definition at line 68 of file SoundImplementation.h.

Referenced by snx::StubSoundImplementation::StubSoundImplementation. 

00068                          : ISoundImplementation(), 
00069                            mName( "unknown" ),
00070                            mSoundAPIInfo(),
00071                            mSounds(),
00072                            mListenerPos()
00073    {
00074    }

virtual snx::SoundImplementation::~SoundImplementation (    )  [inline, virtual]
 

@semantics destructor.

Definition at line 84 of file SoundImplementation.h. 

00085    {
00086       // make sure the API has gracefully exited.
00087       this->shutdownAPI();
00088    }

Member Function Documentation

virtual void snx::SoundImplementation::clone (  ISoundImplementation *&    newCopy )  [pure virtual]
 

every implementation can return a new copy of itself.

Implements snx::ISoundImplementation.

Implemented in snx::StubSoundImplementation.

void snx::SoundImplementation::copy (  const SoundImplementation &    si ) 
 

copies current state of the system from one API to another.

@semantics copies sound state. doesn't do binding here, you must do that separately

Definition at line 54 of file SoundImplementation.cpp.

References mListenerPos, mName, mSoundAPIInfo, and mSounds.

Referenced by sonix::changeAPI. 

00055 {
00056    // copy over the current state
00057    mName = si.mName;
00058    mSounds = si.mSounds;
00059    mListenerPos = si.mListenerPos;
00060    mSoundAPIInfo = si.mSoundAPIInfo;
00061 }

virtual void snx::SoundImplementation::trigger (  const std::string &    alias,
const int &    repeat = 1
)  [inline, virtual]
 

trigger a sound.

@input alias of the sound to trigger, and number of times to play, -1 is repeat infinately @preconditions alias does not have to be associated with a loaded sound. @postconditions if it is, then the loaded sound is triggered. if it isn't then nothing happens. @semantics Triggers a sound

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 104 of file SoundImplementation.h.

Referenced by snx::StubSoundImplementation::trigger. 

00105    {
00106       assert( this->isStarted() == true && "must call startAPI prior to this function" );
00107       
00108       this->lookup( alias ).repeat = repeat;
00109       this->lookup( alias ).repeatCountdown = repeat;
00110    }

virtual bool snx::SoundImplementation::isPlaying (  const std::string &    alias )  [inline, virtual]
 

is the sound currently playing?

Implements snx::ISoundImplementation.

Definition at line 115 of file SoundImplementation.h. 

00116    {
00117       boost::ignore_unused_variable_warning(alias);
00118       return false;
00119    }

virtual void snx::SoundImplementation::setRetriggerable (  const std::string &    alias,
bool    onOff
)  [inline, virtual]
 

when sound is already playing then you call trigger, does the sound restart from beginning? (if a tree falls and no one is around to hear it, does it make sound?).

Implements snx::ISoundImplementation.

Definition at line 126 of file SoundImplementation.h. 

00127    {
00128       this->lookup( alias ).retriggerable = onOff;
00129    }

virtual bool snx::SoundImplementation::isRetriggerable (  const std::string &    alias )  [inline, virtual]
 

is the sound retriggerable?

Implements snx::ISoundImplementation.

Definition at line 134 of file SoundImplementation.h. 

00135    {
00136       return bool( this->lookup( alias ).retriggerable == true );
00137    }

virtual void snx::SoundImplementation::stop (  const std::string &    alias )  [inline, virtual]
 

@semantics stop the sound @input alias of the sound to be stopped.

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 143 of file SoundImplementation.h.

Referenced by snx::StubSoundImplementation::stop. 

00144    {
00145       assert( this->isStarted() == true && "must call startAPI prior to this function" );
00146       this->lookup( alias ).repeatCountdown = 0;
00147    }

virtual void snx::SoundImplementation::pause (  const std::string &    alias )  [inline, virtual]
 

pause the sound, use unpause to return playback where you left off...

Implements snx::ISoundImplementation.

Definition at line 152 of file SoundImplementation.h. 

00153    {
00154       this->stop( alias );
00155    }

virtual void snx::SoundImplementation::unpause (  const std::string &    alias )  [inline, virtual]
 

resume playback from a paused state.

does nothing if sound was not paused.

Implements snx::ISoundImplementation.

Definition at line 160 of file SoundImplementation.h. 

00161    {
00162       this->trigger( alias, this->lookup( alias ).repeat );
00163    }

virtual bool snx::SoundImplementation::isPaused (  const std::string &    alias )  [inline, virtual]
 

if the sound is paused, then return true.

Implements snx::ISoundImplementation.

Definition at line 166 of file SoundImplementation.h. 

00167    {
00168       boost::ignore_unused_variable_warning(alias);
00169       return false;
00170    }

virtual void snx::SoundImplementation::setAmbient (  const std::string &    alias,
bool    ambient = false
)  [inline, virtual]
 

ambient or positional sound.

is the sound ambient - attached to the listener, doesn't change volume when listener moves... or is the sound positional - changes volume as listener nears or retreats..

Implements snx::ISoundImplementation.

Definition at line 178 of file SoundImplementation.h. 

00179    {
00180       this->lookup( alias ).ambient = ambient;
00181    }

virtual bool snx::SoundImplementation::isAmbient (  const std::string &    alias )  [inline, virtual]
 

is the sound ambient - attached to the listener, doesn't change volume when listener moves...

Implements snx::ISoundImplementation.

Definition at line 187 of file SoundImplementation.h. 

00188    {
00189       return this->lookup( alias ).ambient;
00190    }

virtual void snx::SoundImplementation::setPitchBend (  const std::string &    alias,
float    amount
)  [inline, virtual]
 

bend the pitch of the sound.

Implements snx::ISoundImplementation.

Definition at line 193 of file SoundImplementation.h. 

00194    {
00195       this->lookup( alias ).pitchbend = amount;
00196    }

virtual void snx::SoundImplementation::setVolume (  const std::string &    alias,
float    amount
)  [inline, virtual]
 

affect volume.

set to a value between [0..1].

Implements snx::ISoundImplementation.

Definition at line 199 of file SoundImplementation.h. 

00200    {
00201       this->lookup( alias ).volume = amount;
00202    }

virtual void snx::SoundImplementation::setCutoff (  const std::string &    alias,
float    amount
)  [inline, virtual]
 

affect cutoff.

set to a value between [0..1]... 1 is no change. 0 is total cutoff.

Implements snx::ISoundImplementation.

Definition at line 207 of file SoundImplementation.h. 

00208    {
00209       this->lookup( alias ).cutoff = amount;
00210    }

virtual void snx::SoundImplementation::setPosition (  const std::string &    alias,
float    x,
float    y,
float    z
)  [inline, virtual]
 

set sound's 3D position.

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 215 of file SoundImplementation.h.

Referenced by snx::StubSoundImplementation::setPosition. 

00216    {
00217       assert( this->isStarted() == true && "must call startAPI prior to this function" );
00218       this->lookup( alias ).position[0] = x;
00219       this->lookup( alias ).position[1] = y;
00220       this->lookup( alias ).position[2] = z;
00221    }

virtual void snx::SoundImplementation::getPosition (  const std::string &    alias,
float &    x,
float &    y,
float &    z
)  [inline, virtual]
 

get sound's 3D position @input alias is a name that has been associate()d with some sound data @output x,y,z are returned in OpenGL coordinates.

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 228 of file SoundImplementation.h.

Referenced by snx::StubSoundImplementation::getPosition. 

00229    {
00230       assert( this->isStarted() == true && "must call startAPI prior to this function" );
00231       
00232       x = this->lookup( alias ).position[0];
00233       y = this->lookup( alias ).position[1];
00234       z = this->lookup( alias ).position[2];
00235    }

virtual void snx::SoundImplementation::setListenerPosition (  const gmtl::Matrix44f &    mat )  [inline, virtual]
 

set the position of the listener.

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 240 of file SoundImplementation.h.

Referenced by snx::StubSoundImplementation::setListenerPosition. 

00241    {
00242       assert( this->isStarted() == true && "must call startAPI prior to this function" );
00243       mListenerPos = mat;
00244    }

virtual void snx::SoundImplementation::getListenerPosition (  gmtl::Matrix44f &    mat )  [inline, virtual]
 

get the position of the listener.

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 249 of file SoundImplementation.h.

Referenced by snx::StubSoundImplementation::getListenerPosition. 

00250    {
00251       assert( this->isStarted() == true && "must call startAPI prior to this function" );
00252       mat = mListenerPos;
00253    }

virtual int snx::SoundImplementation::startAPI (    )  [pure virtual]
 

start the sound API, creating any contexts or other configurations at startup.

@postconditions sound API is ready to go.

Returns:
1 if success return 0 otherwise @semantics this function should be called before using the other functions in the class.

Implements snx::ISoundImplementation.

Implemented in snx::StubSoundImplementation.

virtual bool snx::SoundImplementation::isStarted (    )  const [pure virtual]
 

query whether the API has been started or not @semantics return true if api has been started, false otherwise.

Implements snx::ISoundImplementation.

Implemented in snx::StubSoundImplementation.

Referenced by configure, and remove.

virtual void snx::SoundImplementation::shutdownAPI (    )  [inline, virtual]
 

kill the sound API, deallocating any sounds, etc...

@postconditions sound API is ready to go. @semantics this function could be called any time, the function could be called multiple times, so it should be smart.

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 274 of file SoundImplementation.h. 

00274 {}

virtual void snx::SoundImplementation::configure (  const snx::SoundAPIInfo &    sai )  [inline, virtual]
 

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 279 of file SoundImplementation.h.

Referenced by snx::StubSoundImplementation::configure. 

00280    {
00281       mSoundAPIInfo = sai;
00282    }

void snx::SoundImplementation::configure (  const std::string &    alias,
const snx::SoundInfo &    description
)  [virtual]
 

configure/reconfigure a sound configure: associate a name (alias) to the description if not already done reconfigure: change properties of the sound to the descriptino provided.

@preconditions provide an alias and a SoundInfo which describes the sound @postconditions alias will point to loaded sound data @semantics associate an alias to sound data. later this alias can be used to operate on this sound data.

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 63 of file SoundImplementation.cpp.

References bind, isStarted, mSounds, snx::SoundInfo::triggerOnNextBind, and unbind. 

00064 {
00065    this->unbind( alias );
00066    snx::SoundInfo temp = mSounds[alias];
00067    mSounds[alias] = description; // TODO: put is_playing within the SoundInfo.
00068 
00069    // restore fields that should be preserved on a reconfigure...
00070    mSounds[alias].triggerOnNextBind = temp.triggerOnNextBind;
00071    //std::cout<<"DEBUG: triggerOnNextBind = "<<mSounds[alias].triggerOnNextBind<<"\n"<<std::flush;
00072 
00073    if (this->isStarted())
00074    {
00075       this->bind( alias );
00076    }
00077 }

void snx::SoundImplementation::remove (  const std::string &    alias )  [virtual]
 

remove a configured sound, any future reference to the alias will not cause an error, but will not result in a rendered sound.

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 79 of file SoundImplementation.cpp.

References isStarted, mSounds, and unbind.

Referenced by snx::StubSoundImplementation::remove. 

00080 {
00081    if (this->isStarted())
00082    {
00083       this->unbind( alias );
00084    }
00085    mSounds.erase( alias );
00086 }

virtual void snx::SoundImplementation::step (  const float &    timeElapsed )  [inline, virtual]
 

@semantics call once per sound frame (doesn't have to be same as your graphics frame) @input time elapsed since last frame.

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 304 of file SoundImplementation.h.

Referenced by snx::StubSoundImplementation::step. 

00305    {
00306       boost::ignore_unused_variable_warning(timeElapsed);
00307    }

virtual void snx::SoundImplementation::clear (    )  [inline, virtual]
 

clear all associate()tions.

@semantics any existing aliases will be stubbed. sounds will be unbound

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 313 of file SoundImplementation.h. 

00314    {
00315       this->unbindAll();
00316    }

void snx::SoundImplementation::bindAll (    )  [virtual]
 

bind: load (or reload) all associate()d sounds.

@postconditions all sound associations are buffered by the sound API

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 88 of file SoundImplementation.cpp.

References bind, and mSounds. 

00089 {
00090    std::map< std::string, snx::SoundInfo >::iterator it;
00091    for( it = mSounds.begin(); it != mSounds.end(); ++it)
00092    {
00093       //std::cout<<"DEBUG: loading alias: "<<(*it).first<<"\n"<<std::flush;
00094       this->bind( (*it).first );
00095    }
00096 }

void snx::SoundImplementation::unbindAll (    )  [virtual]
 

unbind: unload/deallocate all associate()d sounds.

@postconditions all sound associations are unbuffered by the sound API

Implements snx::ISoundImplementation.

Reimplemented in snx::StubSoundImplementation.

Definition at line 98 of file SoundImplementation.cpp.

References mSounds, and unbind. 

00099 {
00100    std::map< std::string, snx::SoundInfo >::iterator it;
00101    for( it = mSounds.begin(); it != mSounds.end(); ++it)
00102    {
00103       //std::cout<<"DEBUG: loading alias: "<<(*it).first<<"\n"<<std::flush;
00104       this->unbind( (*it).first );
00105    }
00106    /*
00107    std::map< std::string, AlSoundInfo >::iterator it;
00108    for( it = mBindLookup.begin(); it != mBindLookup.end(); ++it)
00109    {
00110       this->unbind( (*it).first );
00111    }
00112 
00113    assert( mBindLookup.size() == 0 && "unbindAll failed" );
00114    */
00115 }

virtual void snx::SoundImplementation::bind (  const std::string &    alias )  [pure virtual]
 

load/allocate the sound data this alias refers to the sound API.

@postconditions the sound API has the sound buffered.

Implements snx::ISoundImplementation.

Implemented in snx::StubSoundImplementation.

Referenced by bindAll, and configure.

virtual void snx::SoundImplementation::unbind (  const std::string &    alias )  [pure virtual]
 

unload/deallocate the sound data this alias refers from the sound API.

@postconditions the sound API no longer has the sound buffered.

Implements snx::ISoundImplementation.

Implemented in snx::StubSoundImplementation.

Referenced by configure, remove, and unbindAll.

snx::SoundInfo& snx::SoundImplementation::lookup (  const std::string &    alias )  [inline, virtual]
 

Implements snx::ISoundImplementation.

Definition at line 342 of file SoundImplementation.h.

Referenced by snx::StubSoundImplementation::stop, and snx::StubSoundImplementation::trigger. 

00343    {
00344       return mSounds[alias];
00345    }

void snx::SoundImplementation::setName (  const std::string &    name )  [inline, virtual]
 

Implements snx::ISoundImplementation.

Definition at line 347 of file SoundImplementation.h.

Referenced by snx::StubSoundImplementation::StubSoundImplementation. 

00348    {
00349       mName = name;
00350    }

std::string& snx::SoundImplementation::name (    )  [inline, virtual]
 

Implements snx::ISoundImplementation.

Definition at line 352 of file SoundImplementation.h. 

00353    {
00354       return mName;
00355    }

Member Data Documentation

std::string snx::SoundImplementation::mName [protected]
 

Definition at line 362 of file SoundImplementation.h.

Referenced by copy.

snx::SoundAPIInfo snx::SoundImplementation::mSoundAPIInfo [protected]
 

Definition at line 364 of file SoundImplementation.h.

Referenced by copy.

std::map<std::string, snx::SoundInfo> snx::SoundImplementation::mSounds [protected]
 

Definition at line 365 of file SoundImplementation.h.

Referenced by bindAll, configure, copy, remove, and unbindAll.

gmtl::Matrix44f snx::SoundImplementation::mListenerPos [protected]
 

Definition at line 369 of file SoundImplementation.h.

Referenced by copy.

The documentation for this class was generated from the following files:
Generated on Sun May 2 14:39:33 2004 for Juggler Sonix by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002