Delta3D: dtAudio::Sound Class Reference

List of all members.


Public Types
enum	Command { NONE = 0L, LOAD, UNLOAD, PLAY, PAUSE, STOP, REWIND, LOOP, UNLOOP, QUEUE, GAIN, PITCH, POSITION, DIRECTION, VELOCITY, ABS, REL, MIN_DIST, MAX_DIST, ROL_FACT, MIN_GAIN, MAX_GAIN, kNumCommands }
typedef void(*	CallBack )(Sound sound, void param)
Public Member Functions
virtual void	LoadFile (const char *file)
	Loads the specified sound file.
virtual void	UnloadFile (void)
	Unloads the specified sound file.
virtual const char *	GetFilename (void)
	Returns the name of the loaded sound file.
virtual void	SetPlayCallback (CallBack cb, void *param)
	Set callback for when sound starts playing.
virtual void	SetStopCallback (CallBack cb, void *param)
	Set callback for when sound stops playing.
virtual void	Play (void)
	Starts playing this sound.
virtual void	Pause (void)
	Pauses playing this sound.
virtual void	Stop (void)
	Stops playing this sound.
virtual void	Rewind (void)
	Rewinds to the beginning of this sound.
virtual bool	IsPlaying (void) const
	Is sound playing.
virtual bool	IsPaused (void) const
	Is sound paused.
virtual bool	IsStopped (void) const
	Is sound stopped.
virtual void	SetLooping (bool loop=true)
	Sets whether or not to play the sound in a continuous loop.
virtual bool	IsLooping (void) const
	Checks whether or not the sound plays in a continuous loop.
virtual void	SetGain (float gain)
	Sets the gain of the sound source.
virtual float	GetGain (void) const
	Returns the gain of the sound source.
virtual void	SetPitch (float pitch)
	Sets the pitch multiplier of the sound source.
virtual float	GetPitch (void) const
	Returns the pitch multipier of the sound source.
virtual void	ListenerRelative (bool relative)
	Flags sound to be relative to listener position.
virtual bool	IsListenerRelative (void) const
	Get relative to listener position flag.
virtual void	SetTransform (const dtCore::Transform &xform, dtCore::Transformable::CoordSysEnum cs=dtCore::Transformable::ABS_CS)
	Set the transform position of sound.
virtual void	SetPosition (const osg::Vec3 &position)
	Set the position of sound.
virtual void	GetPosition (osg::Vec3 &position) const
	Get the position of sound.
virtual void	SetDirection (const osg::Vec3 &direction)
	Set the direction of sound.
virtual void	GetDirection (osg::Vec3 &direction) const
	Get the direction of sound.
virtual void	SetVelocity (const osg::Vec3 &velocity)
	Set the velocity of sound.
virtual void	GetVelocity (osg::Vec3 &velocity) const
	Get the velocity of sound.
virtual void	SetMinDistance (float dist)
	Set the minimum distance that sound plays at max_gain.
virtual float	GetMinDistance (void) const
	Get the minimum distance that sound plays at max_gain.
virtual void	SetMaxDistance (float dist)
	Sets the distance where there will no longer be any attenuation of the source.
virtual float	GetMaxDistance (void) const
	Get the maximum distance that sound plays at min_gain.
virtual void	SetRolloffFactor (float rolloff)
	Set the rolloff factor describing attenuation curve.
virtual float	GetRolloffFactor (void) const
	Get the rolloff factor describing attenuation curve.
virtual void	SetMinGain (float gain)
	Set the minimum gain that sound plays at.
virtual float	GetMinGain (void) const
	Get the minimum gain that sound plays at.
virtual void	SetMaxGain (float gain)
	Set the maximum gain that sound plays at.
virtual float	GetMaxGain (void) const
	Get the maximum gain that sound plays at.
FrameData *	CreateFrameData () const
	Generates and returns a key frame that represents the complete recordable state of this object.
void	UseFrameData (const FrameData *data)
	Used by dtCore::Recorder in playback.
FrameData	Deserialize (const FrameData *data)
	Deserializes an XML element representing a state frame, turning it into a new StateFrame instance.
XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *	Serialize (const FrameData d, XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument doc) const
	turns the FrameData into its XML representation.
Static Public Attributes
static const char *	kCommand [kNumCommands]
Protected Member Functions
	Sound ()
	Constructor, user does not create directly instead requests a sound from AudioManager.
virtual	~Sound ()
	Destructor, user does not delete directly instead frees sound to the AudioManager.
virtual void	OnMessage (MessageData *data)
	Message handler.
Protected Attributes
std::string	mFilename
CallBack	mPlayCB
void *	mPlayCBData
CallBack	mStopCB
void *	mStopCBData
float	mGain
float	mPitch
osg::Vec3	mPos
osg::Vec3	mDir
osg::Vec3	mVelo
float	mMinDist
float	mMaxDist
float	mRolloff
float	mMinGain
float	mMaxGain
Classes
class	FrameData
	callback function type More...

Detailed Description

Sound objects are not created directly by the user (new/delete). Instead the user requests a new sound from the AudioManager:

The user can then call any of the Sound interface functions. After the user is finished with Sound, it should be returned to the AudioManager for recycling:

Sounds do not directly call the underlying sound-engine functions, but rather send commands through the sig-slot messaging system to the AudioManager for processing. The AudioManager will queue up the commands for processing at the appropriate times.

Since the Sound commands (play, stop, pitch, etc.) may not happen immediately, Sound has two callback functions which, if set by the user, will get fired off when the Sound actually starts playing and when it actually stops playing.

Sound is a transformable, so it can be a child of other transformables. When a Sound is child of another object, it automatically gets positioned in scene-space relative to the parent object every frame, so there is no need to update the Sound's position. The Sound position can be set manually in scene-space without having to make it a child of another object, but any position updates must then be made manually.

WARNING ******************** JPJ (Sept. 23 2004) ******************** The ListenerRelative( bool ) is not working properly. The underlying sound engine (OpenAL) claims setting the AL_SOURCE_RELATIVE flag to AL_TRUE will attenuate the sources with respect to the gloabal listener's position, and resetting the flag to AL_FALSE will not do any distance calculations. This does not appear to be correct. It appears that resetting the flag to AL_FALSE does the distance calculations with respect to the listener's position, and setting to AL_TRUE still does the distance calculations with respect to the origin. For now, we are always resseting the flag to AL_FALSE.

WARNING ******************** The serialization member functions have not been tested. They may work well. Also, the functions require for playback, CreateFrameData and UseFrameData have not been tested. They may be working. An application was not developed to explicitly test these functions due to lack of time.

Member Typedef Documentation

typedef void(* dtAudio::Sound::CallBack)(Sound *sound, void *param)

Member Enumeration Documentation

enum dtAudio::Sound::Command

Enumerator:

NONE
LOAD
UNLOAD
PLAY
PAUSE
STOP
REWIND
LOOP
UNLOOP
QUEUE
GAIN
PITCH
POSITION
DIRECTION
VELOCITY
ABS
REL
MIN_DIST
MAX_DIST
ROL_FACT
MIN_GAIN
MAX_GAIN
kNumCommands

Constructor & Destructor Documentation

Sound::Sound ( ) [protected]

Constructor, user does not create directly instead requests a sound from AudioManager.

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

Destructor, user does not delete directly instead frees sound to the AudioManager.

Member Function Documentation

void Sound::OnMessage ( MessageData * data ) [protected, virtual]

Message handler.

Parameters:

data

the received message

Reimplemented from dtCore::Base.

void Sound::LoadFile ( const char * file ) [virtual]

Loads the specified sound file.

Parameters:

	file	the name of the file to load
	filename	the name of the file to load

void Sound::UnloadFile ( void ) [virtual]

Unloads the specified sound file.

virtual const char* dtAudio::Sound::GetFilename ( void ) [inline, virtual]

Returns the name of the loaded sound file.

Returns:: the name of the loaded file

void Sound::SetPlayCallback	(	CallBack	cb,
		void *	param
	)			`[virtual]`

Set callback for when sound starts playing.

Parameters:

	cb	callback function pointer
	param	any supplied user data
	callback	function pointer
	user	data

void Sound::SetStopCallback	(	CallBack	cb,
		void *	param
	)			`[virtual]`

Set callback for when sound stops playing.

Parameters:

	cb	callback function pointer
	param	any supplied user data
	callback	function pointer
	user	data

void Sound::Play ( void ) [virtual]

Starts playing this sound.

Tell audio manager to play this sound.

void Sound::Pause ( void ) [virtual]

Pauses playing this sound.

Tell audio manager to pause this sound.

void Sound::Stop ( void ) [virtual]

Stops playing this sound.

Tell audio manager to stop this sound.

void Sound::Rewind ( void ) [virtual]

Rewinds to the beginning of this sound.

Tell audio manager to rewind this sound.

virtual bool dtAudio::Sound::IsPlaying ( void ) const [inline, virtual]

Is sound playing.

(overloaded function)

Returns:: true if playing

virtual bool dtAudio::Sound::IsPaused ( void ) const [inline, virtual]

Is sound paused.

(overloaded function)

Returns:: true if playing

virtual bool dtAudio::Sound::IsStopped ( void ) const [inline, virtual]

Is sound stopped.

(overloaded function)

Returns:: true if playing

void Sound::SetLooping ( bool loop = true ) [virtual]

Sets whether or not to play the sound in a continuous loop.

Parameters:

	loop	true to play the sound in a loop, false otherwise
	looping	true to play the sound in a loop, false otherwise

virtual bool dtAudio::Sound::IsLooping ( void ) const [inline, virtual]

Checks whether or not the sound plays in a continuous loop.

(overloaded function)

Returns:: true if the sound plays in a loop, false otherwise

void Sound::SetGain ( float gain ) [virtual]

Sets the gain of the sound source.

Parameters:

gain

the new gain

virtual float dtAudio::Sound::GetGain ( void ) const [inline, virtual]

Returns the gain of the sound source.

Returns:: the current gain

void Sound::SetPitch ( float pitch ) [virtual]

Sets the pitch multiplier of the sound source.

Parameters:

pitch

the new pitch

virtual float dtAudio::Sound::GetPitch ( void ) const [inline, virtual]

Returns the pitch multipier of the sound source.

Returns:: the current pitch

void Sound::ListenerRelative ( bool relative ) [virtual]

Flags sound to be relative to listener position.

Parameters:

relative

true uses distance modeling

virtual bool dtAudio::Sound::IsListenerRelative ( void ) const [inline, virtual]

Get relative to listener position flag.

(overloaded function)

Returns:: relative true uses distance modeling

void Sound::SetTransform	(	const dtCore::Transform &	xform,
		dtCore::Transformable::CoordSysEnum	cs = `dtCore::Transformable::ABS_CS`
	)			`[virtual]`

Set the transform position of sound.

Parameters:

	*xform	: The new Transform to position this instance
	cs	: Optional parameter describing the coordinate system of xform Defaults to ABS_CS.

Reimplemented from dtCore::Transformable.

void Sound::SetPosition ( const osg::Vec3 & position ) [virtual]

Set the position of sound.

Parameters:

position

to set

void Sound::GetPosition ( osg::Vec3 & position ) const [virtual]

Get the position of sound.

Parameters:

position

to get

void Sound::SetDirection ( const osg::Vec3 & direction ) [virtual]

Set the direction of sound.

Parameters:

direction

to set

void Sound::GetDirection ( osg::Vec3 & direction ) const [virtual]

Get the direction of sound.

Parameters:

direction

to get

void Sound::SetVelocity ( const osg::Vec3 & velocity ) [virtual]

Set the velocity of sound.

Parameters:

velocity

to set

void Sound::GetVelocity ( osg::Vec3 & velocity ) const [virtual]

Get the velocity of sound.

Parameters:

velocity

to get

void Sound::SetMinDistance ( float dist ) [virtual]

Set the minimum distance that sound plays at max_gain.

Attenuation is not calculated below this distance

Parameters:

dist

set to minimum

Attenuation is not calculated below this distance

Parameters:

distance

set to minimum

virtual float dtAudio::Sound::GetMinDistance ( void ) const [inline, virtual]

Get the minimum distance that sound plays at max_gain.

Returns:: distance minimum

void Sound::SetMaxDistance ( float dist ) [virtual]

Sets the distance where there will no longer be any attenuation of the source.

Set the maximum distance that sound plays at min_gain.

Used with the Inverse Clamped Distance model.

See also:: dmINVCLAMP

Parameters:

dist

the maximum distance

Attenuation is not calculated above this distance

Parameters:

distance

set to maximum

virtual float dtAudio::Sound::GetMaxDistance ( void ) const [inline, virtual]

Get the maximum distance that sound plays at min_gain.

Returns:: distance maximum

void Sound::SetRolloffFactor ( float rolloff ) [virtual]

Set the rolloff factor describing attenuation curve.

Parameters:

	rolloff	factor to set
	rollff	factor to set

virtual float dtAudio::Sound::GetRolloffFactor ( void ) const [inline, virtual]

Get the rolloff factor describing attenuation curve.

Returns:: rolloff factor

void Sound::SetMinGain ( float gain ) [virtual]

Set the minimum gain that sound plays at.

Attenuation is clamped to this gain

Parameters:

gain

set to minimum

virtual float dtAudio::Sound::GetMinGain ( void ) const [inline, virtual]

Get the minimum gain that sound plays at.

Returns:: gain minimum

void Sound::SetMaxGain ( float gain ) [virtual]

Set the maximum gain that sound plays at.

Attenuation is clamped to this gain

Parameters:

gain

set to maximum

virtual float dtAudio::Sound::GetMaxGain ( void ) const [inline, virtual]

Get the maximum gain that sound plays at.

Returns:: gain maximum

Sound::FrameData * Sound::CreateFrameData ( ) const

Generates and returns a key frame that represents the complete recordable state of this object.

Returns:: a new key frame

void Sound::UseFrameData ( const FrameData * data )

Used by dtCore::Recorder in playback.

Parameters:

data

The Sound::FrameData containing the Sound's state information.

FrameData dtAudio::Sound::Deserialize ( const FrameData * data )

Deserializes an XML element representing a state frame, turning it into a new StateFrame instance.

Parameters:

data

the element that represents the frame

Returns:: a newly generated state frame corresponding to the element

DOMElement * Sound::Serialize	(	const FrameData *	d,
		XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument *	doc
	)			const

turns the FrameData into its XML representation.

Member Data Documentation

XERCES_CPP_NAMESPACE_USE const char * Sound::kCommand [static]

Initial value:

            {
               "",            "load",        "unload",
               "play",        "pause",       "stop",
               "rewind",      "loop",        "unloop",
               "queue",       "gain",        "pitch",
               "position",    "direction",   "velocity",
               "absolute",    "relative",    "mindist",
               "maxdist",     "rolloff",     "mingain",
               "maxgain"
            }

std::string dtAudio::Sound::mFilename [protected]

CallBack dtAudio::Sound::mPlayCB [protected]

void* dtAudio::Sound::mPlayCBData [protected]

CallBack dtAudio::Sound::mStopCB [protected]

void* dtAudio::Sound::mStopCBData [protected]

float dtAudio::Sound::mGain [protected]

float dtAudio::Sound::mPitch [protected]

osg::Vec3 dtAudio::Sound::mPos [protected]

osg::Vec3 dtAudio::Sound::mDir [protected]

osg::Vec3 dtAudio::Sound::mVelo [protected]

dtAudio::Sound Class Reference

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Classes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation