#include <GameAudio.h>

Public Member Functions
	AudioManager ()

virtual	~AudioManager ()

virtual void	init ()

virtual void	postProcessLoad ()

virtual void	reset ()

virtual void	update ()

virtual void	stopAudio (AudioAffect which)=0

virtual void	pauseAudio (AudioAffect which)=0

virtual void	resumeAudio (AudioAffect which)=0

virtual void	pauseAmbient (Bool shouldPause)=0

virtual void	loseFocus (void)

virtual void	regainFocus (void)

virtual AudioHandle	addAudioEvent (const AudioEventRTS *eventToAdd)
	Add an audio event (event must be declared in an INI file)

virtual void	removeAudioEvent (AudioHandle audioEvent)
	Remove an audio event, stop for instance.

virtual void	killAudioEventImmediately (AudioHandle audioEvent)=0

virtual Bool	isValidAudioEvent (const AudioEventRTS *eventToCheck) const
	validate that this piece of audio exists

virtual Bool	isValidAudioEvent (AudioEventRTS *eventToCheck) const
	validate that this piece of audio exists

void	addTrackName (const AsciiString &trackName)

AsciiString	nextTrackName (const AsciiString &currentTrack)

AsciiString	prevTrackName (const AsciiString &currentTrack)

virtual void	nextMusicTrack (void)=0

virtual void	prevMusicTrack (void)=0

virtual Bool	isMusicPlaying (void) const =0

virtual Bool	hasMusicTrackCompleted (const AsciiString &trackName, Int numberOfTimes) const =0

virtual AsciiString	getMusicTrackName (void) const =0

virtual void	setAudioEventEnabled (AsciiString eventToAffect, Bool enable)

virtual void	setAudioEventVolumeOverride (AsciiString eventToAffect, Real newVolume)

virtual void	removeAudioEvent (AsciiString eventToRemove)

virtual void	removeDisabledEvents ()

virtual void	getInfoForAudioEvent (const AudioEventRTS *eventToFindAndFill) const

virtual Bool	isCurrentlyPlaying (AudioHandle handle)

virtual void	openDevice (void)=0

virtual void	closeDevice (void)=0

virtual void *	getDevice (void)=0

virtual void	notifyOfAudioCompletion (UnsignedInt audioCompleted, UnsignedInt flags)=0

virtual UnsignedInt	getProviderCount (void) const =0

virtual AsciiString	getProviderName (UnsignedInt providerNum) const =0

virtual UnsignedInt	getProviderIndex (AsciiString providerName) const =0

virtual void	selectProvider (UnsignedInt providerNdx)=0

virtual void	unselectProvider (void)=0

virtual UnsignedInt	getSelectedProvider (void) const =0

virtual void	setSpeakerType (UnsignedInt speakerType)=0

virtual UnsignedInt	getSpeakerType (void)=0

virtual UnsignedInt	translateSpeakerTypeToUnsignedInt (const AsciiString &speakerType)

virtual AsciiString	translateUnsignedIntToSpeakerType (UnsignedInt speakerType)

virtual UnsignedInt	getNum2DSamples (void) const =0

virtual UnsignedInt	getNum3DSamples (void) const =0

virtual UnsignedInt	getNumStreams (void) const =0

virtual Bool	doesViolateLimit (AudioEventRTS *event) const =0

virtual Bool	isPlayingLowerPriority (AudioEventRTS *event) const =0

virtual Bool	isPlayingAlready (AudioEventRTS *event) const =0

virtual Bool	isObjectPlayingVoice (UnsignedInt objID) const =0

virtual void	adjustVolumeOfPlayingAudio (AsciiString eventName, Real newVolume)=0

virtual void	removePlayingAudio (AsciiString eventName)=0

virtual void	removeAllDisabledAudio ()=0

virtual Bool	isOn (AudioAffect whichToGet) const

virtual void	setOn (Bool turnOn, AudioAffect whichToAffect)

virtual void	setVolume (Real volume, AudioAffect whichToAffect)

virtual Real	getVolume (AudioAffect whichToGet)

virtual void	set3DVolumeAdjustment (Real volumeAdjustment)

virtual Bool	has3DSensitiveStreamsPlaying (void) const =0

virtual void *	getHandleForBink (void)=0

virtual void	releaseHandleForBink (void)=0

virtual void	friend_forcePlayAudioEventRTS (const AudioEventRTS *eventToPlay)=0

virtual void	setListenerPosition (const Coord3D newListenerPos, const Coord3D newListenerOrientation)

virtual const Coord3D *	getListenerPosition (void) const

virtual AudioRequest *	allocateAudioRequest (Bool useAudioEvent)

virtual void	releaseAudioRequest (AudioRequest *requestToRelease)

virtual void	appendAudioRequest (AudioRequest *m_request)

virtual void	processRequestList (void)

virtual AudioEventInfo *	newAudioEventInfo (AsciiString newEventName)

virtual void	addAudioEventInfo (AudioEventInfo *newEventInfo)

virtual AudioEventInfo *	findAudioEventInfo (AsciiString eventName) const

const AudioSettings *	getAudioSettings (void) const

const MiscAudio *	getMiscAudio (void) const

virtual void	releaseAudioEventRTS (AudioEventRTS *eventToRelease)

AudioSettings *	friend_getAudioSettings (void)

MiscAudio *	friend_getMiscAudio (void)

const FieldParse *	getFieldParseTable (void) const

const AudioEventRTS *	getValidSilentAudioEvent () const

virtual void	setHardwareAccelerated (Bool accel)

virtual Bool	getHardwareAccelerated ()

virtual void	setSpeakerSurround (Bool surround)

virtual Bool	getSpeakerSurround ()

virtual void	refreshCachedVariables ()

virtual void	setPreferredProvider (AsciiString providerNdx)=0

virtual void	setPreferredSpeaker (AsciiString speakerType)=0

virtual Real	getAudioLengthMS (const AudioEventRTS *event)

virtual Real	getFileLengthMS (AsciiString strToLoad) const =0

virtual void	closeAnySamplesUsingFile (const void *fileToClose)=0

virtual Bool	isMusicAlreadyLoaded (void) const

virtual Bool	isMusicPlayingFromCD (void) const

Bool	getDisallowSpeech (void) const

void	setDisallowSpeech (Bool disallowSpeech)

virtual void	findAllAudioEventsOfType (AudioType audioType, std::vector< AudioEventInfo * > &allEvents)

virtual const AudioEventInfoHash &	getAllAudioEvents () const

Real	getZoomVolume () const

Public Member Functions inherited from SubsystemInterface
	SubsystemInterface ()

virtual	~SubsystemInterface ()

virtual void	draw (void)

void	UPDATE (void)

void	DRAW (void)

AsciiString	getName (void)

void	setName (AsciiString name)

Protected Types
enum	{ NUM_VOLUME_TYPES = 4 }

Protected Member Functions
virtual Bool	isCurrentProviderHardwareAccelerated ()

virtual Bool	isCurrentSpeakerTypeSurroundSound ()

virtual Bool	shouldPlayLocally (const AudioEventRTS *audioEvent)

virtual void	setDeviceListenerPosition (void)=0

virtual AudioHandle	allocateNewHandle (void)

virtual void	removeLevelSpecificAudioEventInfos (void)

void	removeAllAudioRequests (void)

Protected Attributes
AudioSettings *	m_audioSettings

MiscAudio *	m_miscAudio

MusicManager *	m_music

SoundManager *	m_sound

Coord3D	m_listenerPosition

Coord3D	m_listenerOrientation

std::list< AudioRequest * >	m_audioRequests

std::vector< AsciiString >	m_musicTracks

AudioEventInfoHash	m_allAudioEventInfo

AudioHandle	theAudioHandlePool

std::list< std::pair< AsciiString, Real > >	m_adjustedVolumes

Real	m_musicVolume

Real	m_soundVolume

Real	m_sound3DVolume

Real	m_speechVolume

Real	m_scriptMusicVolume

Real	m_scriptSoundVolume

Real	m_scriptSound3DVolume

Real	m_scriptSpeechVolume

Real	m_systemMusicVolume

Real	m_systemSoundVolume

Real	m_systemSound3DVolume

Real	m_systemSpeechVolume

Real	m_zoomVolume

AudioEventRTS *	m_silentAudioEvent

Real *	m_savedValues

Bool	m_speechOn: 1

Bool	m_soundOn: 1

Bool	m_sound3DOn: 1

Bool	m_musicOn: 1

Bool	m_volumeHasChanged: 1

Bool	m_hardwareAccel: 1

Bool	m_surroundSpeakers: 1

Bool	m_musicPlayingFromCD: 1

Bool	m_disallowSpeech: 1

Protected Attributes inherited from SubsystemInterface
AsciiString	m_name

Detailed Description

The life of audio.

When audio is requested to play, it is done so in the following manner: 1) An AudioEventRTS is created on the stack. 2) Its guts are copied from elsewhere (for instance, a ThingTemplate, or MiscAudio). 3) It is added to TheAudio via TheAudio->addAudioEvent(...)

The return value from addAudioEvent can be saved in case the sound needs to loop and/or be terminated at some point.

To reomve a playing sound, the call TheAudio->removeAudioEvent(...) is used. This will search the list of currently playing audio for the specified handle, and kill the attached sound. It will play a decay sound, if one is specified.

The important functions of TheAudio, are therefore GameAudio::addAudioEvent() GameAudio::removeAudioEvent() All other functions exist to support these two basic requirements.

In addition to the fundamental requirements, the audio has a fairly complicated sound management scheme. If all units were always allowed to sound off, the sound engine would be overwhelmed and would sound awful. Therefore, when an audio event is requested, it goes through a series of checks to determine if it is near enough to the camera, if it should be heard based on shroud, local player affiliation, etc. (The entire list of checks is contained in shouldPlayLocally()).

In addition, the world and unit audio are never allowed to exceed their footprint, as specified in the audio settings INI file. In order to accomodate this, the audio uses an audio cache. The audio cache will attempt to load a sample, assuming there is enough room. If there is not enough room, then it goes through and finds any samples that are lower priority, and kills them until enough room is present for the sample. If it cannot free enough room, nothing happens to the cache.

Although the audio is multithreaded, most of the operations are performed such that the worst case scenario for thread miscommunication is that the main thread misses an event for one frame. One specific case of this is the status of playing audio. Because audio is playing asynchronously, it can complete at any time. When most audio completes, it sets a flag on the event noting that it has completed. During the next update (from the main thread), anything with that flag set is moved to the stopped list, and then is cleaned up. (Basically, the audio uses a push model for its multithreadedness, which doesn't require thread safety such as mutexes or semaphores).

All in all, the best way to learn how the audio works is to track the lifetime of an event through the system. This will give a better understanding than all the documentation I could write.

-jkmcd -December 2002

Definition at line 134 of file GameAudio.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

protected

Enumerator
NUM_VOLUME_TYPES

Definition at line 358 of file GameAudio.h.

Constructor & Destructor Documentation

◆ AudioManager()

AudioManager::AudioManager ( )

Definition at line 147 of file GameAudio.cpp.

◆ ~AudioManager()

AudioManager::~AudioManager ( )

virtual

Definition at line 184 of file GameAudio.cpp.

Member Function Documentation

◆ addAudioEvent()

AudioHandle AudioManager::addAudioEvent ( const AudioEventRTS * eventToAdd )

virtual

Add an audio event (event must be declared in an INI file)

Definition at line 414 of file GameAudio.cpp.

◆ addAudioEventInfo()

void AudioManager::addAudioEventInfo ( AudioEventInfo * newEventInfo )

virtual

Definition at line 857 of file GameAudio.cpp.

◆ addTrackName()

void AudioManager::addTrackName ( const AsciiString & trackName )

Definition at line 527 of file GameAudio.cpp.

◆ adjustVolumeOfPlayingAudio()

virtual void AudioManager::adjustVolumeOfPlayingAudio	(	AsciiString	eventName,
		Real	newVolume )

pure virtual

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

Constructor & Destructor Documentation

◆ AudioManager()

◆ ~AudioManager()

Member Function Documentation

◆ addAudioEvent()

◆ addAudioEventInfo()

◆ addTrackName()

◆ adjustVolumeOfPlayingAudio()

◆ allocateAudioRequest()

◆ allocateNewHandle()

◆ appendAudioRequest()

◆ closeAnySamplesUsingFile()

◆ closeDevice()

◆ doesViolateLimit()

◆ findAllAudioEventsOfType()

◆ findAudioEventInfo()

◆ friend_forcePlayAudioEventRTS()

◆ friend_getAudioSettings()

◆ friend_getMiscAudio()

◆ getAllAudioEvents()

◆ getAudioLengthMS()

◆ getAudioSettings()

◆ getDevice()

◆ getDisallowSpeech()

◆ getFieldParseTable()

◆ getFileLengthMS()

◆ getHandleForBink()

◆ getHardwareAccelerated()

◆ getInfoForAudioEvent()

◆ getListenerPosition()

◆ getMiscAudio()

◆ getMusicTrackName()

◆ getNum2DSamples()

◆ getNum3DSamples()

◆ getNumStreams()

◆ getProviderCount()

◆ getProviderIndex()

◆ getProviderName()

◆ getSelectedProvider()

◆ getSpeakerSurround()

◆ getSpeakerType()

◆ getValidSilentAudioEvent()

◆ getVolume()

◆ getZoomVolume()

◆ has3DSensitiveStreamsPlaying()

◆ hasMusicTrackCompleted()

◆ init()

◆ isCurrentlyPlaying()

◆ isCurrentProviderHardwareAccelerated()

◆ isCurrentSpeakerTypeSurroundSound()

◆ isMusicAlreadyLoaded()

◆ isMusicPlaying()

◆ isMusicPlayingFromCD()

◆ isObjectPlayingVoice()

◆ isOn()

◆ isPlayingAlready()

◆ isPlayingLowerPriority()

◆ isValidAudioEvent() [1/2]

◆ isValidAudioEvent() [2/2]

◆ killAudioEventImmediately()

◆ loseFocus()

◆ newAudioEventInfo()

◆ nextMusicTrack()

◆ nextTrackName()

◆ notifyOfAudioCompletion()

◆ openDevice()

◆ pauseAmbient()

◆ pauseAudio()

◆ postProcessLoad()

◆ prevMusicTrack()

◆ prevTrackName()

◆ processRequestList()

◆ refreshCachedVariables()