CAudioEngine2 is based on the cAudioEngine plugin dll. More...

#include <AudioEngine2.h>

Public Types
typedef std::map< std::string, CAudioSource2_ptr >	AudioFileMap_type

Public Member Functions
IParaAudioEngine *	GetInterface ()
	get the audio interface

HRESULT	InitAudioEngine (IParaAudioEngine *pInteface=NULL)
	check load the plugin dll if any

void	CleanupAudioEngine ()
	shutdown and clean up audio engine. More...

bool	IsValid ()
	if the audio engine valid

bool	IsValidAndEnabled ()
	return true if the audio is both valid and enabled. More...

bool	IsAudioEngineEnabled ()
	get is audio engine enabled

void	EnableAudioEngine (bool bEnable)
	enable Audio Engine

float	GetGlobalVolume ()
	Returns the global volume modifier for all sources.

void	SetGlobalVolume (const float &volume)
	Sets the global volume modifier (will effect all sources) param volume: Volume to scale all sources by. More...

void	OnSwitch (bool bOn)
	switch on/off the audio engine. More...

CAudioSource2_ptr	Create (const char sName, const char sWavePath=NULL, bool bStream=false)
	create a given audio source by name. More...

CAudioSource2_ptr	Get (const char *sName)
	get audio source by name. More...

CAudioSource2_ptr	CreateGet (const char sName, const char sWavePath=NULL, bool bStream=false)
	get a given audio source by name. More...

void	release (CAudioSource2_ptr &audio_src)
	release audio source. More...

void	Update ()
	Frame move the audio engine. More...

void	SetAutoMoveListener (bool bAuto)
	whether to automatically move the listener according to current camera position. More...

bool	GetAutoMoveListener ()
	whether to automatically move the listener according to current camera position. More...

HRESULT	PlayWaveFile (const char *sWavePath, bool bLoop=false, bool bStream=false, int dwPlayOffset=0)
	Prepare and play a wave object from a standard audio file (WAV, OGG, mp3). More...

HRESULT	PrepareWaveFile (CAudioSource2_ptr &pWave, const char *sWavePath, bool bStream=false)
	call this function to prepare a given wave file from disk. More...

HRESULT	StopWaveFile (const char *sWavePath, ParaAudioFlagsEnum dwFlags)
	stop a wave file More...

HRESULT	ReleaseWaveFile (const std::string &szWavePath)
	release a wave file More...

bool	IsWaveFileInQueue (const std::string &filename)
	whether a given wave file is still in the code driven queue. More...

bool	IsWaveFileLoopPlaying (const std::string &filename)
	whether a given wave file is still in the code driven queue, and is being loop played

void	SetDistanceModel (ParaAudioDistanceModelEnum eDistModel)
	set the audio distance model. More...

void	setPosition (const PARAVECTOR3 &pos)
	Sets the position of the listener. More...

void	setDirection (const PARAVECTOR3 &dir)
	Sets the direction the listener is facing. More...

void	setUpVector (const PARAVECTOR3 &up)
	Sets the up vector to use for the listener Default up vector is Y+, same as OpenGL. More...

void	setVelocity (const PARAVECTOR3 &vel)
	Sets the current velocity of the listener for doppler effects. More...

void	move (const PARAVECTOR3 &pos)
	Convenience function to automatically set the velocity and position for you in a single call Velocity will be set to new position - last position. More...

PARAVECTOR3	getPosition () const
	Returns the current position of the listener.

PARAVECTOR3	getDirection () const
	Returns the current direction of the listener.

PARAVECTOR3	getUpVector () const
	Returns the current up vector of the listener.

PARAVECTOR3	getVelocity () const
	Returns the current velocity of the listener.

void	PauseAll ()

void	ResumeAll ()

Static Public Member Functions
static CAudioEngine2 *	GetInstance ()
	get the singleton interface

Detailed Description

CAudioEngine2 is based on the cAudioEngine plugin dll.

And it adds async sound asset downloading support to the original interface. It also implement some handy functions to play 2d and 3d sound.

Member Function Documentation

§ CleanupAudioEngine()

void ParaEngine::CAudioEngine2::CleanupAudioEngine ( )

shutdown and clean up audio engine.

§ Create()

CAudioSource2_ptr ParaEngine::CAudioEngine2::Create	(	const char *	sName,
		const char *	sWavePath = `NULL`,
		bool	bStream = `false`
	)

create a given audio source by name.

If no audio source with the name is loaded before, we will create one new; otherwise we will overwrite the previous one.

Parameters

sName	the audio source name. Usually same as the audio file path, however it can be any string.
sWavePath	if NULL, it will defaults to sName. Please note, in order to play the same music at the same time, they must be created with different names.
bStream	whether to stream the music once created.

Returns: CAudioSource2_ptr object returned. It may be null if failed.

§ CreateGet()

CAudioSource2_ptr ParaEngine::CAudioEngine2::CreateGet	(	const char *	sName,
		const char *	sWavePath = `NULL`,
		bool	bStream = `false`
	)

get a given audio source by name.

If no audio source with the name is loaded before, we will create one.

Parameters

sName	the audio source name. Usually same as the audio file path, however it can be any string.
sWavePath	if NULL, it will defaults to sName. Please note, in order to play the same music at the same time, they must be created with different names.
bStream	whether to stream the music once created.

Returns: CAudioSource2_ptr object returned. It may be null if failed.

§ Get()

CAudioSource2_ptr ParaEngine::CAudioEngine2::Get ( const char * sName )

get audio source by name.

The source should be created by Create() function.

§ GetAutoMoveListener()

bool ParaEngine::CAudioEngine2::GetAutoMoveListener ( )

inline

whether to automatically move the listener according to current camera position.

§ IsValidAndEnabled()

bool ParaEngine::CAudioEngine2::IsValidAndEnabled ( )

inline

return true if the audio is both valid and enabled.

§ IsWaveFileInQueue()

bool ParaEngine::CAudioEngine2::IsWaveFileInQueue ( const std::string & filename )

whether a given wave file is still in the code driven queue.

We will enqueue a wave file, when it is played and deque it when it is stopped. if the wave file is not downloaded from the remote server, it will also be enqueued.

§ move()

void ParaEngine::CAudioEngine2::move ( const PARAVECTOR3 & pos )

Convenience function to automatically set the velocity and position for you in a single call Velocity will be set to new position - last position.

Parameters

pos	New position to move the listener to.

§ OnSwitch()

void ParaEngine::CAudioEngine2::OnSwitch ( bool bOn )

switch on/off the audio engine.

This is usually due to window lose/get focus.

§ PlayWaveFile()

HRESULT ParaEngine::CAudioEngine2::PlayWaveFile	(	const char *	sWavePath,
		bool	bLoop = `false`,
		bool	bStream = `false`,
		int	dwPlayOffset = `0`
	)

Prepare and play a wave object from a standard audio file (WAV, OGG, mp3).

If a wave file is already prepared before. It will be reused.

Parameters

sWavePath	Path to the wave file.
bLoop	true for looping sound
dwPlayOffset	Play offset to use as the start of the wave. The offset can be described in milliseconds or in samples. The dwFlags argument determines the offset units.

Returns: Returns S_OK if successful. Otherwise, an error code.

§ PrepareWaveFile()

HRESULT ParaEngine::CAudioEngine2::PrepareWaveFile	(	CAudioSource2_ptr &	pWave,
		const char *	sWavePath,
		bool	bStream = `false`
	)

call this function to prepare a given wave file from disk.

if the wave file does not exist on disk, this function does nothing. this function is usually called after a wave file has been just downloaded from the web.

Parameters

pWave	the input wave file to prepare.
sWavePath	the wave path on disk or asset manifest key.

§ release()

void ParaEngine::CAudioEngine2::release ( CAudioSource2_ptr & audio_src )

release audio source.

It will stop the audio and unload it from memory.

§ ReleaseWaveFile()

HRESULT ParaEngine::CAudioEngine2::ReleaseWaveFile ( const std::string & szWavePath )

release a wave file

Parameters

szWavePath Path to the wave file.

Returns: Returns S_OK if successful. Otherwise, an error code.

§ SetAutoMoveListener()

void ParaEngine::CAudioEngine2::SetAutoMoveListener ( bool bAuto )

inline

whether to automatically move the listener according to current camera position.

default to true.

§ setDirection()

void ParaEngine::CAudioEngine2::setDirection ( const PARAVECTOR3 & dir )

Sets the direction the listener is facing.

Parameters

dir	New direction vector for the listener.

§ SetDistanceModel()

void ParaEngine::CAudioEngine2::SetDistanceModel ( ParaAudioDistanceModelEnum eDistModel )

set the audio distance model.

see: http://connect.creativelabs.com/openal/Documentation/OpenAL%201.1%20Specification.htm

Parameters

eDistModel int of following. enum ParaAudioDistanceModelEnum { Audio_DistModel_NONE = 0, Audio_DistModel_INVERSE_DISTANCE, Audio_DistModel_INVERSE_DISTANCE_CLAMPED, Audio_DistModel_LINEAR_DISTANCE, Audio_DistModel_LINEAR_DISTANCE_CLAMPED, Audio_DistModel_EXPONENT_DISTANCE, Audio_DistModel_EXPONENT_DISTANCE_CLAMPED, };

§ SetGlobalVolume()

void ParaEngine::CAudioEngine2::SetGlobalVolume ( const float & volume )

Sets the global volume modifier (will effect all sources) param volume: Volume to scale all sources by.

Range: 0.0 to +inf.

§ setPosition()

void ParaEngine::CAudioEngine2::setPosition ( const PARAVECTOR3 & pos )

Sets the position of the listener.

Note that you will still have to set velocity after this call for proper doppler effects. Use move() if you'd like to have cAudio automatically handle velocity for you.

Parameters

pos	New position for the listener.

§ setUpVector()

void ParaEngine::CAudioEngine2::setUpVector ( const PARAVECTOR3 & up )

Sets the up vector to use for the listener Default up vector is Y+, same as OpenGL.

Parameters

up	New up vector for the listener.

§ setVelocity()

void ParaEngine::CAudioEngine2::setVelocity ( const PARAVECTOR3 & vel )

Sets the current velocity of the listener for doppler effects.

Parameters

vel	New velocity for the listener.

§ StopWaveFile()

HRESULT ParaEngine::CAudioEngine2::StopWaveFile	(	const char *	sWavePath,
		ParaAudioFlagsEnum	dwFlags
	)

stop a wave file

Parameters

szWavePath Path to the wave file.

dwFlags

Flags that affect how the wave is stopped:

AUDIO_FLAG_STOP_RELEASE Plays the wave to completion, then stops. For looping waves, this flag plays the current iteration to completion, then stops (ignoring any subsequent iterations). In either case, any release (or tail) is played. To stop the wave immediately, use the XACT_FLAG_STOP_IMMEDIATE flag.
AUDIO_FLAG_STOP_IMMEDIATE Stops the playback immediately.

Returns: Returns S_OK if successful. Otherwise, an error code.

§ Update()

void ParaEngine::CAudioEngine2::Update ( )

Frame move the audio engine.

since we use an internal thread for sound updating. this function simply updates the listener's position, orientation, upvector and velocity according to the current camera.

The documentation for this class was generated from the following files:

Client/trunk/ParaEngineClient/3dengine/AudioEngine2.h
Client/trunk/ParaEngineClient/3dengine/AudioEngine2.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

§ CleanupAudioEngine()

§ Create()

§ CreateGet()

§ Get()

§ GetAutoMoveListener()

§ IsValidAndEnabled()

§ IsWaveFileInQueue()

§ move()

§ OnSwitch()

§ PlayWaveFile()

§ PrepareWaveFile()

§ release()

§ ReleaseWaveFile()

§ SetAutoMoveListener()

§ setDirection()

§ SetDistanceModel()

§ SetGlobalVolume()

§ setPosition()

§ setUpVector()

§ setVelocity()

§ StopWaveFile()

§ Update()