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

sonix Class Reference

#include <sonix.h>

Collaboration diagram for sonix:

Collaboration graph
[legend]
List of all members.

Public Methods

virtual void trigger (const std::string &alias, const int &repeat=1)
 @input alias of the sound to trigger, and number of times to play, -1 to repeat infinately, 1 (single shot) is default. More...

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

virtual void setRetriggerable (const std::string &alias, bool onOff)
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 setting=false)
 ambient or positional sound. More...

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

virtual void setPitchBend (const std::string &alias, float amount)
 alters the frequency of the sample. 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, const float &x, const float &y, const float &z)
 set sound's 3D position @input x,y,z are in OpenGL coordinates. 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 void changeAPI (const std::string &apiName)
 change the underlying sound API to something else. 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...


Protected Methods

 sonix ()
virtual ~sonix ()
snx::ISoundImplementation & impl ()

Constructor & Destructor Documentation

sonix::sonix (    )  [inline, protected]
 

Definition at line 62 of file sonix.h. 

00062            : mImplementation( NULL )
00063    {
00064    }

sonix::~sonix (    )  [protected, virtual]
 

Definition at line 61 of file sonix.cpp.

References snx::ISoundImplementation::shutdownAPI, and snx::ISoundImplementation::unbindAll. 

00062 {
00063    // release the implementation
00064    if (mImplementation != NULL)
00065    {
00066       // unload all sound data
00067       mImplementation->unbindAll();
00068       
00069       // shutdown old api if exists
00070       mImplementation->shutdownAPI();
00071       delete mImplementation;
00072       mImplementation = NULL;
00073    }
00074 }

Member Function Documentation

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

@input alias of the sound to trigger, and number of times to play, -1 to repeat infinately, 1 (single shot) is default.

@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

Definition at line 83 of file sonix.cpp.

References impl, and snx::ISoundImplementation::trigger. 

00084 {
00085    this->impl().trigger( alias, repeat );
00086 }

bool sonix::isPlaying (  const std::string &    alias )  [virtual]
 

is the sound currently playing?

Definition at line 91 of file sonix.cpp.

References impl, and snx::ISoundImplementation::isPlaying. 

00092 {
00093    return this->impl().isPlaying( alias );
00094 }

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

Definition at line 100 of file sonix.cpp.

References impl, and snx::ISoundImplementation::setRetriggerable. 

00101 {
00102    this->impl().setRetriggerable( alias, onOff );
00103 }

bool sonix::isRetriggerable (  const std::string &    alias )  [virtual]
 

is the sound retriggerable?

Definition at line 108 of file sonix.cpp.

References impl, and snx::ISoundImplementation::isRetriggerable. 

00109 {
00110    return this->impl().isRetriggerable( alias );
00111 }

void sonix::stop (  const std::string &    alias )  [virtual]
 

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

Definition at line 117 of file sonix.cpp.

References impl, and snx::ISoundImplementation::stop. 

00118 {
00119    this->impl().stop( alias );
00120 }

void sonix::pause (  const std::string &    alias )  [virtual]
 

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

Definition at line 125 of file sonix.cpp.

References impl, and snx::ISoundImplementation::pause. 

00126 {
00127    this->impl().pause( alias );
00128 }

void sonix::unpause (  const std::string &    alias )  [virtual]
 

resume playback from a paused state.

does nothing if sound was not paused.

Definition at line 133 of file sonix.cpp.

References impl, and snx::ISoundImplementation::unpause. 

00134 {
00135    this->impl().unpause( alias );
00136 }

bool sonix::isPaused (  const std::string &    alias )  [virtual]
 

if the sound is paused, then return true.

Definition at line 139 of file sonix.cpp.

References impl, and snx::ISoundImplementation::isPaused. 

00140 {
00141    return this->impl().isPaused( alias );
00142 }

void sonix::setAmbient (  const std::string &    alias,
bool    setting = false
)  [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..

Definition at line 150 of file sonix.cpp.

References impl, and snx::ISoundImplementation::setAmbient. 

00151 {
00152    this->impl().setAmbient( alias, setting );
00153 }

bool sonix::isAmbient (  const std::string &    alias )  [virtual]
 

is the sound ambient?

Definition at line 156 of file sonix.cpp.

References impl, and snx::ISoundImplementation::isAmbient. 

00157 {
00158    return this->impl().isAmbient( alias );
00159 }

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

alters the frequency of the sample.

1 is no change < 1 is low > 1 is high.

Definition at line 166 of file sonix.cpp.

References impl, and snx::ISoundImplementation::setPitchBend. 

00167 {
00168    this->impl().setPitchBend( alias, amount );
00169 }

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

affect volume.

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

Definition at line 172 of file sonix.cpp.

References impl, and snx::ISoundImplementation::setVolume. 

00173 {
00174    this->impl().setVolume( alias, amount );
00175 }

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

affect cutoff.

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

Definition at line 180 of file sonix.cpp.

References impl, and snx::ISoundImplementation::setCutoff. 

00181 {
00182    this->impl().setCutoff( alias, amount );
00183 }

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

set sound's 3D position @input x,y,z are in OpenGL coordinates.

alias is a name that has been associate()d with some sound data

Definition at line 189 of file sonix.cpp.

References impl, and snx::ISoundImplementation::setPosition. 

00190 {
00191    this->impl().setPosition( alias, x, y, z );
00192 }

void sonix::getPosition (  const std::string &    alias,
float &    x,
float &    y,
float &    z
)  [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.

Definition at line 199 of file sonix.cpp.

References snx::ISoundImplementation::getPosition, and impl. 

00200 {
00201    this->impl().getPosition( alias, x, y, z );
00202 }

void sonix::setListenerPosition (  const gmtl::Matrix44f &    mat )  [virtual]
 

set the position of the listener.

Definition at line 207 of file sonix.cpp.

References impl, and snx::ISoundImplementation::setListenerPosition. 

00208 {
00209    this->impl().setListenerPosition( mat );
00210 }

void sonix::getListenerPosition (  gmtl::Matrix44f &    mat )  [virtual]
 

get the position of the listener.

Definition at line 215 of file sonix.cpp.

References snx::ISoundImplementation::getListenerPosition, and impl. 

00216 {
00217    this->impl().getListenerPosition( mat );
00218 }

void sonix::changeAPI (  const std::string &    apiName )  [virtual]
 

change the underlying sound API to something else.

@input usually a name of a valid registered sound API implementation @preconditions sound implementation should be registered @postconditions underlying API is changed to the requested API name. if apiName's implementation is not registered, then underlying API is changed to the stub version. @semantics function is safe: always returns a valid implementation. @time O(1) @output a valid sound API. if apiName is invalid, then a stub implementation is returned.

Definition at line 230 of file sonix.cpp.

References snx::ISoundImplementation::bindAll, snx::SoundImplementation::copy, impl, snx::ISoundImplementation::name, snx::ISoundImplementation::shutdownAPI, snxDBG, snx::ISoundImplementation::startAPI, and snx::ISoundImplementation::unbindAll. 

00231 {
00232    snx::ISoundImplementation& oldImpl = this->impl();
00233    vprASSERT( &oldImpl != NULL && "this->impl() should ensure that oldImpl is non-NULL" );
00234    
00235    // change the current api to the newly requested one.
00236    snx::SoundFactory::instance()->createImplementation( apiName, mImplementation );
00237 
00238    vprDEBUG(snxDBG, vprDBG_CRITICAL_LVL) << "Changing sound API from '"
00239                                          << oldImpl.name() << "' to '"
00240                                          << mImplementation->name() << "'\n"
00241                                          << vprDEBUG_FLUSH;
00242    
00243    // copy sound state from old to current (doesn't do binding yet)
00244    snx::SoundImplementation* si = dynamic_cast<snx::SoundImplementation*>( mImplementation );
00245    vprASSERT( NULL != si && "implementation is not of type SoundImplementation, cast fails" );
00246    snx::SoundImplementation& old_si = dynamic_cast<snx::SoundImplementation&>( oldImpl );
00247    vprASSERT( NULL != &old_si && "implementation is not of type SoundImplementation, cast fails" );
00248    si->copy( old_si );
00249 
00250       // unload all sound data
00251       oldImpl.unbindAll();
00252 
00253       // shutdown old api if exists
00254       oldImpl.shutdownAPI();
00255 
00256       // delete old api, we're done with it...
00257       delete &oldImpl;
00258 
00259    // startup the new API
00260    if(!mImplementation->startAPI()) // if it fails to start then we revert back to stub
00261    {
00262       vprDEBUG(snxDBG, vprDBG_CRITICAL_LVL)
00263          << clrOutBOLD(clrRED, "ERROR:") << " Failed to start new API--"
00264          << "changing back to Stub\n" << vprDEBUG_FLUSH;
00265       changeAPI("stub");
00266    }
00267 
00268    // load all sound data
00269    mImplementation->bindAll();
00270 }

void sonix::configure (  const snx::SoundAPIInfo &    sai )  [virtual]
 

Definition at line 275 of file sonix.cpp.

References snx::ISoundImplementation::configure, and impl. 

00276 {
00277    this->impl().configure( sai );
00278 }

void sonix::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.

Definition at line 288 of file sonix.cpp.

References snx::ISoundImplementation::configure, and impl. 

00289 {
00290    this->impl().configure( alias, description );
00291 }

void sonix::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.

Definition at line 297 of file sonix.cpp.

References impl, and snx::ISoundImplementation::remove. 

00298 {
00299    this->impl().remove( alias );
00300 }

void sonix::step (  const float &    timeElapsed )  [virtual]
 

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

Definition at line 306 of file sonix.cpp.

References impl, and snx::ISoundImplementation::step. 

00307 {
00308    this->impl().step( timeElapsed );
00309 }

snx::ISoundImplementation & sonix::impl (    )  [protected]
 

Definition at line 311 of file sonix.cpp.

References snx::ISoundImplementation::bindAll, and snx::ISoundImplementation::startAPI.

Referenced by changeAPI, configure, getListenerPosition, getPosition, isAmbient, isPaused, isPlaying, isRetriggerable, pause, remove, setAmbient, setCutoff, setListenerPosition, setPitchBend, setPosition, setRetriggerable, setVolume, step, stop, trigger, and unpause. 

00312 {
00313    if (mImplementation == NULL)
00314    {
00315       snx::SoundFactory::instance()->createImplementation( "stub", mImplementation );
00316       mImplementation->startAPI();
00317       mImplementation->bindAll();
00318    }
00319    return *mImplementation;
00320 }

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