Delta3D: dtAudio::AudioManager Class Reference

List of all members.


Public Member Functions
virtual void	Config (const AudioConfigData &data=_DefCfg)
	initialize AudioManager
bool	IsInitialized () const
	Returns true if initialized.
virtual void	OnMessage (MessageData *data)
	receive messages handles the timeing messages (pre-post-frame) from the system pushes sounds onto the command queue for later processing
Sound *	NewSound (void)
	create or recycle a new sound for the user
void	FreeSound (Sound *&sound)
	free a sound (recycle it) that the user is finish with
bool	LoadFile (const std::string &file)
	Pre-load a sound file into a buffer.
bool	UnloadFile (const std::string &file)
	un-load a sound file from a buffer (if use-count is zero)
Static Public Member Functions
static bool	CheckForError (const std::string &userMessage, const std::string &msgFunction, int lineNumber)
	This was added to help check for error messages all the time, and have them feed through here.
static void	Instantiate (void)
	create the singleton and initialize OpenAL
static void	Destroy (void)
	destroy the singleton and shutdown OpenAL
static AudioManager &	GetInstance (void)
	access the AudioManager
static Listener *	GetListener (void)
	access the global Listener
Static Public Attributes
static const std::string	ERROR_CLEARING_STRING
Classes
struct	BufferData
	BufferData is an internal structure used to identify an OpenAL buffer and hold reference data associated with it.
class	ListenerObj
	ListenerObj is the concrete object associated with Listener interface that users manipulate.
class	SoundObj
	SoundObj is the concrete object associated with Sound interface that users manipulate.

Detailed Description

Optionally the user can create an AudioConfigData structure to pass to the AudioManager when configuring set some of the base functionalit of the manager. Currently only the number of sources is set this way. It is encouraged, but not required, that the user know how many channels their audio hardware uses and set the number of sources = the number of channels.

FOR THE USER: Sounds are not created by the user, but they are requested from the AudioManager. After getting a sound from the AudioManager the user then calls the sound's functions. When the user is finished with the sound, the sound should be passed back to the AudioManager for free the resource.

There is one global listener which the user also requests from the AudioManager. After getting the listener from the AudioManager the usere then calls the listener's functions. When finished with the listener, the user does NOT free it. The listener is just an interface to AudioManager's protected object and the AudioManager will handle it's resources.

In many cases it's more efficeint to preload the sounds into the AudioManager before loading them into the individual sounds.

FOR THE DEVELOPER: The AudioManager is a repository for all sounds objects, buffers, sources (sound channels), listeners, etc. The AudioManager hands out interfaces to the various objects for users to manipulate but it holds all the resources for those objects.

When a sound command is requested (play, stop, pitch, etc.) the AudioManager receives the sound through the sig-slot messaging system and pushes the sound onto a queue of sounds requesting command processing. At pre-frame, the AudioManager process all the sounds waiting for command processing in the ordered they were queued. State commands are commnads to change the state of the sound (play, stop, pause, etc.), but not the value of any of the sounds attributes (gain, pitch, etc.). Value commands change the value of a sound's attributes. If the sound is currently active (has a source) the value commands are processed immediately, else the value is saved for when the sound becomes active. State commands push the sound onto a queue for further processing at the appropriate time. For instance, a play command will bind a sound's source to the sound's buffer and then will push the source onto the play queue awaiting to start playing.

At frame time, AudioManager process all sources waiting for a state change. All sources waiting a stop command get stopped, waiting a pause command get paused, waiting a rewind command get rewound, and waiting a play command get played. Then the AudioManager runs through all sources in it's active list and removes sources that have finished playing then puts them in a cleanup list for later cleanup.

At post-frame, the AudioManager takes all sources waiting for cleanup and unbinds the source from it's associated buffer. The source is then put in a recycle queue for later use by new sounds.

WARNING ******************** JPJ (Sept. 23 2004) ******************** The SetRelative() and SetAbsolute() functions are 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.

Member Function Documentation

bool AudioManager::CheckForError	(	const std::string &	userMessage,
		const std::string &	msgFunction,
		int	lineNumber
	)			`[static]`

This was added to help check for error messages all the time, and have them feed through here.

Returns true on error, false if no error

void AudioManager::Instantiate ( void ) [static]

create the singleton and initialize OpenAL

void AudioManager::Destroy ( void ) [static]

destroy the singleton and shutdown OpenAL

AudioManager & AudioManager::GetInstance ( void ) [static]

access the AudioManager

Listener * AudioManager::GetListener ( void ) [static]

access the global Listener

void AudioManager::Config ( const AudioConfigData & data = _DefCfg ) [virtual]

initialize AudioManager

bool dtAudio::AudioManager::IsInitialized ( ) const [inline]

Returns true if initialized.

void AudioManager::OnMessage ( MessageData * data ) [virtual]

receive messages handles the timeing messages (pre-post-frame) from the system pushes sounds onto the command queue for later processing

Reimplemented from dtCore::Base.

Sound * AudioManager::NewSound ( void )

create or recycle a new sound for the user

void AudioManager::FreeSound ( Sound *& sound )

free a sound (recycle it) that the user is finish with

bool AudioManager::LoadFile ( const std::string & file )

Pre-load a sound file into a buffer.

We still only support .wav's but .ogg support is coming soon!

bool AudioManager::UnloadFile ( const std::string & file )

un-load a sound file from a buffer (if use-count is zero)

Member Data Documentation

const std::string AudioManager::ERROR_CLEARING_STRING [static]

Initial value:

 "Clearing Error code "
"system at start of method, if this appears then an error occurred before this "
"method was called."

dtAudio::AudioManager Class Reference

Public Member Functions

Static Public Member Functions

Static Public Attributes

Classes

Detailed Description

Member Function Documentation

Member Data Documentation