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

snx::SoundHandle Class Reference
[The Sonix API.]

A handle to a sonix sound. More...

#include <SoundHandle.h>

List of all members.

Public Methods

 SoundHandle ()
 default constructor @semantics you should call init to name this handle... More...

 SoundHandle (const std::string &myUniqueName)
 name constructor. More...

void init (const std::string &myUniqueName)
 initialize the name of this sound. More...

std::string getName () const
 get the handle name. More...

virtual ~SoundHandle ()
virtual void trigger (const int &repeat=1)
 trigger a sound. More...

virtual bool isPlaying ()
 is the sound currently playing? More...

virtual void setRetriggerable (bool onOff)
virtual bool isRetriggerable ()
 is the sound retriggerable? More...

virtual void stop ()
 stop the sound. More...

virtual void pause ()
 pause the sound, use unpause to return playback where you left off... More...

virtual void unpause ()
 resume playback from a paused state. More...

virtual bool isPaused ()
 if the sound is paused, then return true. More...

virtual void setAmbient (bool setting=false)
 ambient or positional sound. More...

virtual bool isAmbient ()
 is the sound ambient? More...

virtual void setPitchBend (float amount)
 alters the frequency of the sample. More...

virtual void setVolume (float amount)
 affect volume. More...

virtual void setCutoff (float amount)
 affect cutoff. More...

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

virtual void getPosition (float &x, float &y, float &z)
 get sound's 3D position. 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 configure (const snx::SoundInfo &description)
 configure/reconfigure this sound. More...

virtual void remove ()
 remove a configured sound. More...

Detailed Description

A handle to a sonix sound.

This is a convenient handle to your sound and is your interface to using individual sounds in sonix use configure, and remove as you would new and delete... i.e. you could leak, if you don't call remove - this is because there may be more than one handle to a sound... NOTE: you may have to sonix::instance()->changeAPI() to the api you want to use (usually OpenAL, or AudioWorks)

Definition at line 73 of file SoundHandle.h.

Constructor & Destructor Documentation

snx::SoundHandle::SoundHandle (    )  [inline]
 

default constructor @semantics you should call init to name this handle...

See also:
init

Definition at line 81 of file SoundHandle.h. 

00081                     : mDefaultName( "unnamed_sound_handle" ), mAlias( mDefaultName )
00082       {
00083       }

snx::SoundHandle::SoundHandle (  const std::string &    myUniqueName )  [inline]
 

name constructor.

@semantics gives the handle your chosen name. this name is what is used in all sonix:: class calls (SoundHandle is a wrapper for sonix::)

Postcondition:
you do not need to call init if you use the name constructor.
See also:
init

Definition at line 91 of file SoundHandle.h. 

00091                                                    : mAlias( myUniqueName )
00092       {
00093       }

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

Definition at line 117 of file SoundHandle.h. 

00118       {
00119          mAlias = "deleted";
00120       }

Member Function Documentation

void snx::SoundHandle::init (  const std::string &    myUniqueName )  [inline]
 

initialize the name of this sound.

@semantics initialize the handle your chosen name. important: you must configure() your sound after calling init(), if this name hasn't been configured before...

"Example:" 

    snx::SoundHandle click_sound;
    click_sound.init( "click" );
    click_sound.configure( sound_info );

See also:
snx::SoundHandle::configure

Definition at line 108 of file SoundHandle.h. 

00109       {
00110          mAlias = myUniqueName;
00111       }

std::string snx::SoundHandle::getName (    )  const [inline]
 

get the handle name.

Definition at line 114 of file SoundHandle.h. 

00114 { return mAlias; }

virtual void snx::SoundHandle::trigger (  const int &    repeat = 1 )  [inline, virtual]
 

trigger a sound.

@input number of times to play, -1 to repeat infinately, 1 (single shot) is default. @preconditions object does not have to be a valid sound (but it helps :). @postconditions if it is, then the loaded sound is triggered. if it isn't then nothing happens. @semantics Triggers a sound.

Definition at line 130 of file SoundHandle.h. 

00131       {
00132          sonix::instance()->trigger( mAlias, repeat );
00133       }

virtual bool snx::SoundHandle::isPlaying (    )  [inline, virtual]
 

is the sound currently playing?

Definition at line 138 of file SoundHandle.h. 

00139       {
00140          return sonix::instance()->isPlaying( mAlias );
00141       }

virtual void snx::SoundHandle::setRetriggerable (  bool    onOff )  [inline, virtual]
 

Definition at line 147 of file SoundHandle.h. 

00148       {
00149          sonix::instance()->setRetriggerable( mAlias, onOff );
00150       }

virtual bool snx::SoundHandle::isRetriggerable (    )  [inline, virtual]
 

is the sound retriggerable?

Definition at line 155 of file SoundHandle.h. 

00156       {
00157          return sonix::instance()->isRetriggerable( mAlias );
00158       }

virtual void snx::SoundHandle::stop (    )  [inline, virtual]
 

stop the sound.

@semantics stop the sound @input

Definition at line 165 of file SoundHandle.h. 

00166       {
00167          sonix::instance()->stop( mAlias );
00168       }

virtual void snx::SoundHandle::pause (    )  [inline, virtual]
 

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

Definition at line 173 of file SoundHandle.h. 

00174       {
00175          sonix::instance()->pause( mAlias );
00176       }

virtual void snx::SoundHandle::unpause (    )  [inline, virtual]
 

resume playback from a paused state.

does nothing if sound was not paused.

Definition at line 181 of file SoundHandle.h. 

00182       {
00183          sonix::instance()->unpause( mAlias );
00184       }

virtual bool snx::SoundHandle::isPaused (    )  [inline, virtual]
 

if the sound is paused, then return true.

Definition at line 187 of file SoundHandle.h. 

00188       {
00189          return sonix::instance()->isPaused( mAlias );
00190       }

virtual void snx::SoundHandle::setAmbient (  bool    setting = 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..

Definition at line 197 of file SoundHandle.h. 

00198       {
00199          sonix::instance()->setAmbient( mAlias, setting );
00200       }

virtual bool snx::SoundHandle::isAmbient (    )  [inline, virtual]
 

is the sound ambient?

Definition at line 203 of file SoundHandle.h. 

00204       {
00205          return sonix::instance()->isAmbient( mAlias );
00206       }

virtual void snx::SoundHandle::setPitchBend (  float    amount )  [inline, virtual]
 

alters the frequency of the sample.

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

Definition at line 213 of file SoundHandle.h. 

00214       {
00215          sonix::instance()->setPitchBend( mAlias, amount );
00216       }

virtual void snx::SoundHandle::setVolume (  float    amount )  [inline, virtual]
 

affect volume.

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

Definition at line 219 of file SoundHandle.h. 

00220       {
00221          sonix::instance()->setVolume( mAlias, amount );
00222       }

virtual void snx::SoundHandle::setCutoff (  float    amount )  [inline, virtual]
 

affect cutoff.

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

Definition at line 227 of file SoundHandle.h. 

00228       {
00229          sonix::instance()->setCutoff( mAlias, amount );
00230       }

virtual void snx::SoundHandle::setPosition (  const float &    x,
const float &    y,
const float &    z
)  [inline, virtual]
 

set sound's 3D position .

@input x,y,z are in OpenGL coordinates (right handed sys, x right, y up, z towards you)

Definition at line 236 of file SoundHandle.h. 

00237       {
00238          sonix::instance()->setPosition( mAlias, x, y, z );
00239       }

virtual void snx::SoundHandle::getPosition (  float &    x,
float &    y,
float &    z
)  [inline, virtual]
 

get sound's 3D position.

@output x,y,z are returned in OpenGL coordinates.

Definition at line 245 of file SoundHandle.h. 

00246       {
00247          sonix::instance()->getPosition( mAlias, x, y, z );
00248       }

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

set the position of the listener.

Definition at line 253 of file SoundHandle.h. 

00254       {
00255          sonix::instance()->setListenerPosition( mat );
00256       }

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

get the position of the listener.

Definition at line 261 of file SoundHandle.h. 

00262       {
00263          sonix::instance()->getListenerPosition( mat );
00264       }

virtual void snx::SoundHandle::configure (  const snx::SoundInfo &    description )  [inline, virtual]
 

configure/reconfigure this 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 a SoundInfo which describes the sound @postconditions this handle will point to loaded sound data @semantics associate sound data to this handle. afterwards, this SoundHandle can be used to operate on this sound data.

Definition at line 274 of file SoundHandle.h. 

00275       {
00276          assert( mAlias != mDefaultName && "you must call init to set your sound's name" );
00277          sonix::instance()->configure( mAlias, description );
00278       }

virtual void snx::SoundHandle::remove (    )  [inline, virtual]
 

remove a configured sound.

any future reference to the mAlias will not cause an error, but will not result in a rendered sound

Definition at line 284 of file SoundHandle.h. 

00285       {
00286          sonix::instance()->remove( mAlias );
00287       }

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