SFXSystem

Engine/source/sfx/sfxSystem.h

This class provides access to the sound system.

More...

Device Management

bool
createDevice(const String & providerName, const String & deviceName, bool useHardware, S32 maxBuffers, bool changeDevice)

This initializes a new device.

Returns the current device information or NULL if no device is present.

This destroys the current device.

bool

Returns true if a device is allocated.

Source Creation

createSource(SFXTrack * track, const MatrixF * transform, const VectorF * velocity)

Used to create new sound sources from a sound profile.

Used to create a streaming sound source from a user supplied stream object.

playOnce(SFXTrack * track, const MatrixF * transform, const VectorF * velocity, F32 fadeInTime)

Creates a source which when it finishes playing will auto delete itself.

playOnce(SFXProfile * profile, const MatrixF * transform, const VectorF * velocity, F32 fadeInTime)

Stop the source and delete it.

Mark source for deletion when it is moving into stopped state.

Listeners

Return the number of listeners currently configured.

Set the number of concurrent listeners.

Set the property of the given listener.

setListener(U32 index, const MatrixF & transform, const Point3F & velocity)

Set the 3D attributes of the given listener.

3D Sound Configuration

{

Public Types

EventSignalType 
SFXSoundVector 
SFXSourceVector 

Public Friends

class
class
class

Protected Static Attributes

The one and only instance of the SFXSystem.

Protected Attributes

The current output sound device initialized and ready to play back.

The distance model used for rolloff curve computation on 3D sounds.

The current doppler scale factor.

SFX system event signal.

The last time the sources got an update.

The current position and orientation of all listeners.

This is used to keep track of play once sources that must be released when they stop playing.

List of plugins currently linked to the SFX system.

Current global reverb properties.

The current curve rolloff factor.

Ambient soundscape manager.

Protected Functions

The protected constructor.

The non-virtual destructor.

This called to reprioritize and reassign voices to sources.

_createBuffer(const String & filename, SFXDescription * description)

Load file directly through SFXDevice.

Called from SFXProfile to create a device specific sound buffer used in conjunction with a voice in playback.

Called from SFXSource::onAdd to register the source.

Called from SFXSource::onRemove to unregister the source.

Called to reprioritize and reassign buffers as sources change state, volumes are adjusted, and the listener moves around.

Public Static Functions

This is called after Sim::shutdown() in shutdownLibraries() to free the sound system singlton.

Returns the one an only instance of the SFXSystem unless it hasn't been initialized or its been disabled in your build.

init()

This is called from initialization to prepare the sound system singleton.

Public Functions

This is only public so that it can be called by the game update loop.

Register the given plugin with the system.

dumpSources(StringBuilder * toString, bool excludeGroups)

Dump information about all current SFXSources to the console or to the given StringBuilder.

Return the SFX system event signal.

Notify the SFX system that the given description has changed.

Unregister the given plugin with the system.

Detailed Description

This class provides access to the sound system.

There are a few script preferences that are used by the sound providers.

$pref::SFX::frequency - This is the playback frequency for the primary sound buffer used for mixing. Although most providers will reformat on the fly, for best quality and performance match your sound files to this setting.

$pref::SFX::bitrate - This is the playback bitrate for the primary sound buffer used for mixing. Although most providers will reformat on the fly, for best quality and performance match your sound files to this setting.

Stats

Stats reported back to the console for tracking performance.

S32 mStatNumSources 
S32 mStatNumSounds 
S32 mStatNumPlaying 
S32 mStatNumCulled 
S32 mStatNumVoices 
S32 mStatSourceUpdateTime 
S32 mStatParameterUpdateTime 
S32 mStatAmbientUpdateTime 

Device Management

createDevice(const String & providerName, const String & deviceName, bool useHardware, S32 maxBuffers, bool changeDevice)

This initializes a new device.

Parameters:

providerName

The name of the provider.

deviceName

The name of the provider device.

useHardware

Toggles the use of hardware processing when available.

maxBuffers

The maximum buffers for this device to use or -1 for the device to pick its own reasonable default.

changeDevice

Allows this to change the current device to a new one

return:

Returns true if the device was created.

getDeviceInfoString()

Returns the current device information or NULL if no device is present.

The information string is in the following format:

Provider Name\tDevice Name\tUse Hardware\tMax Buffers

deleteDevice()

This destroys the current device.

All sources loose their playback buffers, but otherwise continue to function.

hasDevice()

Returns true if a device is allocated.

Source Creation

createSource(SFXTrack * track, const MatrixF * transform, const VectorF * velocity)

Used to create new sound sources from a sound profile.

The returned source is in a stopped state and ready for playback. Use the SFX_DELETE macro to free the source when your done.

note:

The track must have at least the same lifetime as the source. If the description disappears while the source is still there, the source will go with it.

Parameters:
profile

The sound profile for the created source.

transform

The optional transform if creating a 3D source.

velocity

The optional doppler velocity if creating a 3D source.

return:

The sound source or NULL if an error occured.

createSourceFromStream(const ThreadSafeRef< SFXStream > & stream, SFXDescription * description)

Used to create a streaming sound source from a user supplied stream object.


It is only intended for memory based streams. For sound file streaming use createSource() with a streaming SFXProfile.

Use the SFX_DELETE macro to free the source when your done.

note:

The description must have at least the same lifetime as the sound. If the description disappears while the source is still there, the sound will go with it.

Parameters:
stream

The stream used to create the sound buffer. It must exist for the lifetime of the source and will have its reference count decremented when the source is destroyed.

description

The sound description to apply to the source.

return:

The sound source or NULL if an error occured.

playOnce(SFXTrack * track, const MatrixF * transform, const VectorF * velocity, F32 fadeInTime)

Creates a source which when it finishes playing will auto delete itself.

Be aware that the returned SFXSource pointer should only be used for error checking or immediate setting changes. It may be deleted as soon as the next system tick.

Parameters:

profile

The sound profile for the created source.

transform

The optional transform if creating a 3D source.

velocity

The optional doppler velocity if creating a 3D source.

return:

The sound source or NULL if an error occured.

playOnce(SFXProfile * profile, const MatrixF * transform, const VectorF * velocity, F32 fadeInTime)

stopAndDeleteSource(SFXSource * source)

Stop the source and delete it.

This method will take care of the fade-out time that the source may need before it will actually stop and may be deleted.

deleteWhenStopped(SFXSource * source)

Mark source for deletion when it is moving into stopped state.

This method is useful to basically make a source a play-once source after the fact.

Listeners

getNumListeners()

Return the number of listeners currently configured.

setNumListeners(U32 num)

Set the number of concurrent listeners.

note:

It depends on the selected device if more than one listener is actually supported.

getListener(U32 index)

Set the property of the given listener.

setListener(U32 index, const MatrixF & transform, const Point3F & velocity)

Set the 3D attributes of the given listener.

setListener(U32 index, const SFXListenerProperties & properties)

3D Sound Configuration

{

getDistanceModel()

Return the curve model currently used distance attenuation of positional sounds.

setDistanceModel(SFXDistanceModel model)

getDopplerFactor()

setDopplerFactor(F32 factor)

getRolloffFactor()

setRolloffFactor(F32 factor)

getReverb()

setReverb(const SFXReverbProperties & reverb)

Public Types

typedef Signal< void(SFXSystemEventType event) > EventSignalType 
typedef Vector< SFXSound * > SFXSoundVector 
typedef Vector< SFXSource * > SFXSourceVector 

Public Friends

Protected Static Attributes

SFXSystem * smSingleton 

The one and only instance of the SFXSystem.

Protected Attributes

SFXDevice * mDevice 

The current output sound device initialized and ready to play back.

SFXDistanceModel mDistanceModel 

The distance model used for rolloff curve computation on 3D sounds.

F32 mDopplerFactor 

The current doppler scale factor.

EventSignalType mEventSignal 

SFX system event signal.

U32 mLastAmbientUpdateTime 
U32 mLastParameterUpdateTime 
U32 mLastSourceUpdateTime 

The last time the sources got an update.

Vector< SFXListenerProperties > mListeners 

The current position and orientation of all listeners.

SFXSourceVector mPlayOnceSources 

This is used to keep track of play once sources that must be released when they stop playing.

Vector< SFXSystemPlugin * > mPlugins 

List of plugins currently linked to the SFX system.

SFXReverbProperties mReverb 

Current global reverb properties.

F32 mRolloffFactor 

The current curve rolloff factor.

SFXSoundVector mSounds 
SFXSoundscapeManager * mSoundscapeMgr 

Ambient soundscape manager.

Protected Functions

SFXSystem()

The protected constructor.

~SFXSystem()

The non-virtual destructor.

You shouldn't ever need to overload this class.

_assignVoice(SFXSound * sound)

_assignVoices()

This called to reprioritize and reassign voices to sources.

_createBuffer(const String & filename, SFXDescription * description)

Load file directly through SFXDevice.

Depends on availability with selected SFXDevice.

return:

Return new buffer or NULL.

_createBuffer(const ThreadSafeRef< SFXStream > & stream, SFXDescription * description)

Called from SFXProfile to create a device specific sound buffer used in conjunction with a voice in playback.

_getDevice()

_onAddSource(SFXSource * source)

Called from SFXSource::onAdd to register the source.

_onRemoveSource(SFXSource * source)

Called from SFXSource::onRemove to unregister the source.

_sortSounds(const SFXListenerProperties & listener)

_updateSources()

Called to reprioritize and reassign buffers as sources change state, volumes are adjusted, and the listener moves around.

Public Static Functions

destroy()

This is called after Sim::shutdown() in shutdownLibraries() to free the sound system singlton.

After this the SFX singleton is null and any call to it will crash.

getSingleton()

Returns the one an only instance of the SFXSystem unless it hasn't been initialized or its been disabled in your build.

For convienence you can use the SFX-> macro as well.

see:

init()

This is called from initialization to prepare the sound system singleton.

This also includes registering common resource types and initializing available sound providers.

Public Functions

_update()

This is only public so that it can be called by the game update loop.

It updates the current device and all sources.

addPlugin(SFXSystemPlugin * plugin)

Register the given plugin with the system.

dumpSources(StringBuilder * toString, bool excludeGroups)

Dump information about all current SFXSources to the console or to the given StringBuilder.

getEventSignal()

Return the SFX system event signal.

getSoundscapeManager()

notifyDescriptionChanged(SFXDescription * description)

Notify the SFX system that the given description has changed.

All sources currently using the description will be updated.

notifyTrackChanged(SFXTrack * track)

removePlugin(SFXSystemPlugin * plugin)

Unregister the given plugin with the system.