My Project
Public Types | Public Member Functions | Static Public Member Functions | List of all members
ParaEngine::CAudioEngine Class Reference

Class: CAudioEngine. More...

#include <AudioEngine.h>

Public Types

typedef map< string, ParaAudio_3DCUEPOOL_3DCUE_TYPE
 

Public Member Functions

HRESULT InitAudioEngine ()
 

Initialize the audio engine

This function ONLY does the following: More...
 
void CleanupAudioEngine ()
 Shutdown the audio engine Note that m_pEngine->ShutDown is synchronous and will take some time to complete if there are still playing cues. More...
 
bool IsValid ()
 Currently registered notifications: More...
 
bool IsValidAndEnabled ()
 return true if the audio is both valid and enabled. More...
 
void DoWork ()
 It is important to allow XACT to do periodic work by calling XACTDoWork(). More...
 
const char * GetRecordingDeviceEnum ()
 enumerate the available recording devices in this machine. More...
 
const char * GetRecordingFormatEnum ()
 enumerate the available recording formats on this machine. More...
 
bool SetRecordingOutput (const char *sOutputFile, int nDeviceIndex, int nWaveFormatIndex)
 set the recording output properties for recording with BeginRecording() and StopRecording() function. More...
 
bool BeginRecording ()
 start recording to the current recording output
 
bool IsRecording ()
 whether it is recording sound. More...
 
bool IsRecordingPaused ()
 whether it is recording is paused. More...
 
const char * GetLastRecordedData (int nTimeLength)
 try return a snapshot of the recorded wave data in the last nTimeLength time. More...
 
bool PauseOrResumeRecording (int nState)
 
bool StopRecording ()
 stop recording and save output to the current recording output
 
void SetVolume (float fVolume)
 Set the volume of all categories and all currently playing wave files. More...
 
float GetVolume ()
 Get the volume of average if all categories. More...
 
bool IsAudioEngineEnabled ()
 get is audio engine enabled
 
HRESULT EnableAudioEngine ()
 enable Audio Engine
 
HRESULT DisableAudioEngine ()
 disable Audio Engine
 
HRESULT PauseCategory (const char *strCategoryName)
 pause certain category in Audio Engine More...
 
HRESULT ResumeCategory (const char *strCategoryName)
 resume certain category in Audio Engine More...
 
HRESULT StopCategory (const char *strCategoryName)
 stop certain category in Audio Engine More...
 
HRESULT EnableAudioBank (const char *strBankName)
 initialize the audio banks needed in Audio Engine More...
 
HRESULT DisableAudioBank (const char *strBankName)
 clean up the audio banks needed in Audio Engine More...
 
string GetCurrentAudioBankName ()
 get the current audio bank name More...
 
HRESULT SetAudioStereo ()
 set listener's sound output format to stereo
 
HRESULT SetAudio5Point1 ()
 set listener's sound output format to 5.1 sound
 
int GetAudioFormat ()
 get listener's sound output format More...
 
HRESULT PlayBGMusic (const char *strBGMusicName)
 play background music More...
 
HRESULT PauseBGMusic ()
 pause background music More...
 
HRESULT ResumeBGMusic ()
 resume background music More...
 
HRESULT StopBGMusic ()
 stop background music More...
 
bool IsBGMusicEnabled ()
 get is background music enabled
 
HRESULT EnableBGMusic ()
 enable background music
 
HRESULT DisableBGMusic ()
 disable background music
 
float GetBGMusicVolume ()
 Get background music volume. More...
 
HRESULT SetBGMusicVolume (const float fVolume)
 set background music volume More...
 
HRESULT PlayDialog (const char *strDialogName, const char *strScript)
 play dialog music More...
 
HRESULT SkipDialog ()
 skip dialog music to the next marker
 
HRESULT PauseDialog ()
 pause dialog music More...
 
HRESULT ResumeDialog ()
 resume dialog music More...
 
HRESULT StopDialog ()
 stop dialog music More...
 
bool IsDialogEnabled ()
 get is dialog music enabled
 
HRESULT EnableDialog ()
 enable dialog music
 
HRESULT DisableDialog ()
 disable dialog music
 
float GetDialogVolume ()
 get dialog volume More...
 
HRESULT SetDialogVolume (const float fVolume)
 set dialog volume More...
 
HRESULT PlayAmbientSound (const char *strAmbientSoundName)
 play ambient sound More...
 
HRESULT PauseAmbientSound (const char *strAmbientSoundName)
 pause ambient sound More...
 
HRESULT ResumeAmbientSound (const char *strAmbientSoundName)
 resume ambient sound More...
 
HRESULT StopAmbientSound (const char *strAmbientSoundName)
 stop ambient sound More...
 
bool IsAmbientSoundEnabled ()
 get is ambient sound enabled
 
HRESULT EnableAmbientSound ()
 enable ambient sound music
 
HRESULT DisableAmbientSound ()
 disable ambient sound music
 
float GetAmbientSoundVolume ()
 get ambient sound volume More...
 
HRESULT SetAmbientSoundVolume (const float fVolume)
 set ambient sound volume More...
 
HRESULT PlayUISound (const char *strUISoundName)
 play UI sound More...
 
float GetUISoundVolume ()
 get UI sound volume More...
 
HRESULT SetUISoundVolume (const float fVolume)
 set UI sound volume More...
 
HRESULT PlayStatic3DSound (const char *str3DSoundName, const char *assetName, float x, float y, float z)
 play 3D sound in static position. More...
 
HRESULT PauseStatic3DSound (const char *assetName)
 pause 3D sound in static position More...
 
HRESULT ResumeStatic3DSound (const char *assetName)
 Resume 3D sound in static position. More...
 
HRESULT StopStatic3DSound (const char *assetName)
 stop 3D sound in static position More...
 
HRESULT PlayDynamic3DSound (const char *str3DSoundName, const char *objectName)
 play 3D sound to dynamic object More...
 
float Get3DSoundVolume ()
 get 3D sound volume More...
 
HRESULT Set3DSoundVolume (const float fVolume)
 set 3D sound volume More...
 
HRESULT PlayInteractiveSound (const char *strInteractiveSoundName)
 play Interactive sound More...
 
float GetInteractiveSoundVolume ()
 get interactive sound volume More...
 
HRESULT SetInteractiveSoundVolume (const float fVolume)
 set interactive sound volume More...
 
HRESULT LoadSoundBank (const char *filename)
 Load a sound bank. More...
 
HRESULT UnLoadSoundBank (const char *filename=NULL)
 unload a sound bank
 
HRESULT LoadInMemoryWaveBank (const char *filename)
 Load an in memory wave bank. More...
 
HRESULT UnLoadInMemoryWaveBank (const char *filename=NULL)
 unload a wave bank
 
HRESULT LoadStreamWaveBank (const char *filename)
 Load an stream wave bank. More...
 
HRESULT UnLoadStreamWaveBank (const char *filename=NULL)
 unload a wave bank
 
IXACTWaveBank * GetWaveBankStream ()
 
IXACTCue * GetCurrentDialog ()
 
IXACTCue * GetCurrentBGMusic ()
 
void SetHandleStreamingWaveBankPrepared (bool bHandle)
 
void SetHandleDialogCuePrepared (bool bHandle)
 
void SetHandleDialogCueStop (bool bHandle)
 
void SetHandleBGCuePrepared (bool bHandle)
 
void SetHandleBGCueStop (bool bHandle)
 
HRESULT PlayWaveFile (PCSTR szWavePath, XACTLOOPCOUNT nLoopCount, WORD wStreamingPacketSize=0, DWORD dwPlayOffset=0, DWORD dwAlignment=2048)
 Prepare and play a wave object from a standard PCM, XMA (Xbox 360) file. More...
 
HRESULT StopWaveFile (PCSTR szWavePath, DWORD dwFlags)
 stop a wave file More...
 
HRESULT ReleaseWaveFile (PCSTR szWavePath)
 release a wave file More...
 
bool IsWaveFileInQueue (const string &filename)
 whether a given wave file is still in the code driven queue. More...
 

Static Public Member Functions

static CAudioEngineGetInstance ()
 CAudioEngine is a singleton class.
 

Detailed Description

Class: CAudioEngine.

The purpose of the audio in ParaEngine is to serve as a lightweight container built upon Microsoft Cross-Platform Audio Creation Tool (XACT) engine. The main design goal is to provide a framework that allows easy access of sound and music without concerning the management and organization of linear and 3D audio resources.

Member Function Documentation

§ CleanupAudioEngine()

void ParaEngine::CAudioEngine::CleanupAudioEngine ( )

Shutdown the audio engine Note that m_pEngine->ShutDown is synchronous and will take some time to complete if there are still playing cues.

Also m_pEngine->ShutDown() is generally only called when a game exits and is not the preferred method of changing audio resources.

§ DisableAudioBank()

HRESULT ParaEngine::CAudioEngine::DisableAudioBank ( const char *  strBankName)

clean up the audio banks needed in Audio Engine

Parameters
strBankNamesound and wave bank name

§ DoWork()

void ParaEngine::CAudioEngine::DoWork ( )

It is important to allow XACT to do periodic work by calling XACTDoWork().

DoWork internally call the UpdateAudio() function. And called by the audio engine to join the game main loop.

§ EnableAudioBank()

HRESULT ParaEngine::CAudioEngine::EnableAudioBank ( const char *  strBankName)

initialize the audio banks needed in Audio Engine

Parameters
strBankNamesound and wave bank name

§ Get3DSoundVolume()

float ParaEngine::CAudioEngine::Get3DSoundVolume ( )

get 3D sound volume

Parameters
fVolume3D sound volume

§ GetAmbientSoundVolume()

float ParaEngine::CAudioEngine::GetAmbientSoundVolume ( )

get ambient sound volume

Parameters
fVolumeambient sound volume

§ GetAudioFormat()

int ParaEngine::CAudioEngine::GetAudioFormat ( )

get listener's sound output format

Returns
: 2:Stereo 6:5Point1

§ GetBGMusicVolume()

float ParaEngine::CAudioEngine::GetBGMusicVolume ( )

Get background music volume.

Parameters
fVolumebackground music volume

§ GetCurrentAudioBankName()

string ParaEngine::CAudioEngine::GetCurrentAudioBankName ( )

get the current audio bank name

Returns
: current audio bank name

§ GetDialogVolume()

float ParaEngine::CAudioEngine::GetDialogVolume ( )

get dialog volume

Parameters
fVolumedialog volume

§ GetInteractiveSoundVolume()

float ParaEngine::CAudioEngine::GetInteractiveSoundVolume ( )

get interactive sound volume

Parameters
fVolumeinteractive sound volume

§ GetLastRecordedData()

const char* ParaEngine::CAudioEngine::GetLastRecordedData ( int  nTimeLength)

try return a snapshot of the recorded wave data in the last nTimeLength time.

just turn the music to strings to be displayed by the GUI.

§ GetRecordingDeviceEnum()

const char* ParaEngine::CAudioEngine::GetRecordingDeviceEnum ( )

enumerate the available recording devices in this machine.

returned as strings separated by ';' this function is not thread safe

§ GetRecordingFormatEnum()

const char* ParaEngine::CAudioEngine::GetRecordingFormatEnum ( )

enumerate the available recording formats on this machine.

returned as strings separated by ';' this function is not thread safe

§ GetUISoundVolume()

float ParaEngine::CAudioEngine::GetUISoundVolume ( )

get UI sound volume

Parameters
fVolumeUI sound volume

§ GetVolume()

float ParaEngine::CAudioEngine::GetVolume ( )

Get the volume of average if all categories.

Returns
usually between [0,1], where 0 is silent and 1 is full. value larger than 1 is also possible.

§ InitAudioEngine()

HRESULT ParaEngine::CAudioEngine::InitAudioEngine ( )

Initialize the audio engine

This function ONLY does the following:

  1. Load global setting stored in Audio\Global.xgs
  2. Set the callback function: AudioEngineNotificationCallback
  3. Initialize XACT by calling m_pEngine->Initialize
  4. Register notification
  5. Setup 3D audio struct to Stereo

This function DOESN'T do the following:

  1. Create the XACT wave bank(s)
  2. Create the XACT sound bank(s)

    3. Store indices to the XACT cue(s)

§ IsRecording()

bool ParaEngine::CAudioEngine::IsRecording ( )

whether it is recording sound.

§ IsRecordingPaused()

bool ParaEngine::CAudioEngine::IsRecordingPaused ( )

whether it is recording is paused.

§ IsValid()

bool ParaEngine::CAudioEngine::IsValid ( )

Currently registered notifications:

  1. Wave bank prepared
  2. Background cue prepared
  3. Background cue stopped
  4. Dialog cue prepared
  5. Dialog cue stopped if the audio engine valid

§ IsValidAndEnabled()

bool ParaEngine::CAudioEngine::IsValidAndEnabled ( )
inline

return true if the audio is both valid and enabled.

§ IsWaveFileInQueue()

bool ParaEngine::CAudioEngine::IsWaveFileInQueue ( const 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.

§ LoadInMemoryWaveBank()

HRESULT ParaEngine::CAudioEngine::LoadInMemoryWaveBank ( const char *  filename)

Load an in memory wave bank.

note: Currently only one can be loaded at a time, future version may support many.

Parameters
filenamethe logical "*-InMemory.xwb". It can be an asset file. such as "audio/name/name-InMemory.xwb"
Returns
: S_OK if loaded. E_PENDING if we are downloading. E_FAIL if cannot load.

§ LoadSoundBank()

HRESULT ParaEngine::CAudioEngine::LoadSoundBank ( const char *  filename)

Load a sound bank.

note: Currently only one can be loaded at a time, future version may support many.

Parameters
filenamethe logical *.xsb sound bank file path. It can be an asset file. such as "audio/name/name.xsb"
Returns
: S_OK if loaded. E_PENDING if we are downloading. E_FAIL if cannot load.

§ LoadStreamWaveBank()

HRESULT ParaEngine::CAudioEngine::LoadStreamWaveBank ( const char *  filename)

Load an stream wave bank.

note: Currently only one can be loaded at a time, future version may support many.

Parameters
filenamethe logical "*-Stream.xwb". It can be an asset file. such as "audio/name/name-Stream.xwb"
Returns
: S_OK if loaded. E_PENDING if we are downloading. E_FAIL if cannot load.

§ PauseAmbientSound()

HRESULT ParaEngine::CAudioEngine::PauseAmbientSound ( const char *  strAmbientSoundName)

pause ambient sound

Parameters
strAmbientSoundNameambient sound name

§ PauseBGMusic()

HRESULT ParaEngine::CAudioEngine::PauseBGMusic ( )

pause background music

Parameters
strBGMusicNamebackground music name

§ PauseCategory()

HRESULT ParaEngine::CAudioEngine::PauseCategory ( const char *  strCategoryName)

pause certain category in Audio Engine

Parameters
strCategoryNamecategory name

§ PauseDialog()

HRESULT ParaEngine::CAudioEngine::PauseDialog ( )

pause dialog music

Parameters
strDialogNamedialog music name

§ PauseOrResumeRecording()

bool ParaEngine::CAudioEngine::PauseOrResumeRecording ( int  nState)
Parameters
nState0 for toggle pause and resume. -1 for pause, 1 for resume.

§ PauseStatic3DSound()

HRESULT ParaEngine::CAudioEngine::PauseStatic3DSound ( const char *  assetName)

pause 3D sound in static position

Parameters
assetName3D sound asset name, this is the KEY to the 3D Sound

§ PlayAmbientSound()

HRESULT ParaEngine::CAudioEngine::PlayAmbientSound ( const char *  strAmbientSoundName)

play ambient sound

Parameters
strAmbientSoundNameambient sound name

§ PlayBGMusic()

HRESULT ParaEngine::CAudioEngine::PlayBGMusic ( const char *  strBGMusicName)

play background music

Parameters
strBGMusicNamebackground music name

§ PlayDialog()

HRESULT ParaEngine::CAudioEngine::PlayDialog ( const char *  strDialogName,
const char *  strScript 
)

play dialog music

Parameters
strDialogNamedialog music name

§ PlayDynamic3DSound()

HRESULT ParaEngine::CAudioEngine::PlayDynamic3DSound ( const char *  str3DSoundName,
const char *  objectName 
)

play 3D sound to dynamic object

Parameters
str3DSoundName3D sound name
objectName3D sound object name, this is the KEY to the 3D Sound

§ PlayInteractiveSound()

HRESULT ParaEngine::CAudioEngine::PlayInteractiveSound ( const char *  strInteractiveSoundName)

play Interactive sound

Parameters
strInteractiveSoundNameinteractive sound name NOTE: Interactive sound is now behave like UI sound, and it don't promise Zero-Latency

§ PlayStatic3DSound()

HRESULT ParaEngine::CAudioEngine::PlayStatic3DSound ( const char *  str3DSoundName,
const char *  assetName,
float  x,
float  y,
float  z 
)

play 3D sound in static position.

3d sound whose position does not change in the world once created.

Parameters
str3DSoundName3D sound name
assetName3D sound asset name, this is the KEY to the 3D Sound
x,y,z3D sound position

§ PlayUISound()

HRESULT ParaEngine::CAudioEngine::PlayUISound ( const char *  strUISoundName)

play UI sound

Parameters
strUISoundNameUI sound name

§ PlayWaveFile()

HRESULT ParaEngine::CAudioEngine::PlayWaveFile ( PCSTR  szWavePath,
XACTLOOPCOUNT  nLoopCount,
WORD  wStreamingPacketSize = 0,
DWORD  dwPlayOffset = 0,
DWORD  dwAlignment = 2048 
)

Prepare and play a wave object from a standard PCM, XMA (Xbox 360) file.

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

Parameters
szWavePathPath to the wave file.
nLoopCountNumber of times to loop this file. If there is no loop region, but the loop count is nonzero, the entire wave is looped.
wStreamingPacketSizeDefault it 0, Packet Size, in 2 KB increments. If wStreamingPacketSize is 0, the file is an in-memory wave. A fully prepared wave is returned. For streaming waves, the client needs to call IXACTWave::GetState to ensure that the wave is prepared before playback. Loop region information is read from the wave file.
dwPlayOffsetPlay 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.
dwAlignmentAlignment of wave data on the media from which it is streamed. This must be at least 2048. Otherwise, it must be a multiple of 2048.
Returns
Returns S_OK if successful. Otherwise, an error code.

§ ReleaseWaveFile()

HRESULT ParaEngine::CAudioEngine::ReleaseWaveFile ( PCSTR  szWavePath)

release a wave file

Parameters
szWavePathPath to the wave file.
Returns
Returns S_OK if successful. Otherwise, an error code.

§ ResumeAmbientSound()

HRESULT ParaEngine::CAudioEngine::ResumeAmbientSound ( const char *  strAmbientSoundName)

resume ambient sound

Parameters
strAmbientSoundNameambient sound name

§ ResumeBGMusic()

HRESULT ParaEngine::CAudioEngine::ResumeBGMusic ( )

resume background music

Parameters
strBGMusicNamebackground music name

§ ResumeCategory()

HRESULT ParaEngine::CAudioEngine::ResumeCategory ( const char *  strCategoryName)

resume certain category in Audio Engine

Parameters
strCategoryNamecategory name

§ ResumeDialog()

HRESULT ParaEngine::CAudioEngine::ResumeDialog ( )

resume dialog music

Parameters
strDialogNamedialog music name

§ ResumeStatic3DSound()

HRESULT ParaEngine::CAudioEngine::ResumeStatic3DSound ( const char *  assetName)

Resume 3D sound in static position.

Parameters
assetName3D sound asset name, this is the KEY to the 3D Sound

§ Set3DSoundVolume()

HRESULT ParaEngine::CAudioEngine::Set3DSoundVolume ( const float  fVolume)

set 3D sound volume

Parameters
fVolume3D sound volume

§ SetAmbientSoundVolume()

HRESULT ParaEngine::CAudioEngine::SetAmbientSoundVolume ( const float  fVolume)

set ambient sound volume

Parameters
fVolumeambient sound volume

§ SetBGMusicVolume()

HRESULT ParaEngine::CAudioEngine::SetBGMusicVolume ( const float  fVolume)

set background music volume

Parameters
fVolumebackground music volume

§ SetDialogVolume()

HRESULT ParaEngine::CAudioEngine::SetDialogVolume ( const float  fVolume)

set dialog volume

Parameters
fVolumedialog volume

§ SetInteractiveSoundVolume()

HRESULT ParaEngine::CAudioEngine::SetInteractiveSoundVolume ( const float  fVolume)

set interactive sound volume

Parameters
fVolumeinteractive sound volume

§ SetRecordingOutput()

bool ParaEngine::CAudioEngine::SetRecordingOutput ( const char *  sOutputFile,
int  nDeviceIndex,
int  nWaveFormatIndex 
)

set the recording output properties for recording with BeginRecording() and StopRecording() function.

Parameters
sOutputFilethe output file. it can be nil. Default is "temp/soundcapture.wav",
nDeviceIndex-1 to use the current one. or it should be a valid index as in GetRecordingDeviceEnum();
nWaveFormatIndex-1 to use the current one. or it should be a valid index as in GetRecordingFormatEnum();

§ SetUISoundVolume()

HRESULT ParaEngine::CAudioEngine::SetUISoundVolume ( const float  fVolume)

set UI sound volume

Parameters
fVolumeUI sound volume

§ SetVolume()

void ParaEngine::CAudioEngine::SetVolume ( float  fVolume)

Set the volume of all categories and all currently playing wave files.

Parameters
fVolumeusually between [0,1], where 0 is silent and 1 is full. value larger than 1 is also possible.

§ StopAmbientSound()

HRESULT ParaEngine::CAudioEngine::StopAmbientSound ( const char *  strAmbientSoundName)

stop ambient sound

Parameters
strAmbientSoundNameambient sound name

§ StopBGMusic()

HRESULT ParaEngine::CAudioEngine::StopBGMusic ( )

stop background music

Parameters
strBGMusicNamebackground music name

§ StopCategory()

HRESULT ParaEngine::CAudioEngine::StopCategory ( const char *  strCategoryName)

stop certain category in Audio Engine

Parameters
strCategoryNamecategory name

§ StopDialog()

HRESULT ParaEngine::CAudioEngine::StopDialog ( )

stop dialog music

Parameters
strDialogNamedialog music name

§ StopStatic3DSound()

HRESULT ParaEngine::CAudioEngine::StopStatic3DSound ( const char *  assetName)

stop 3D sound in static position

Parameters
assetName3D sound asset name, this is the KEY to the 3D Sound

§ StopWaveFile()

HRESULT ParaEngine::CAudioEngine::StopWaveFile ( PCSTR  szWavePath,
DWORD  dwFlags 
)

stop a wave file

Parameters
szWavePathPath to the wave file.
dwFlagsFlags that affect how the wave is stopped:
  • XACT_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.
  • XACT_FLAG_STOP_IMMEDIATE Stops the playback immediately.
Returns
Returns S_OK if successful. Otherwise, an error code.

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