SFXSystem
This class provides access to the sound system.
Stats
Stats reported back to the console for tracking performance.
Device Management
bool
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
SFXSound *
createSourceFromStream(const ThreadSafeRef< SFXStream > & stream, SFXDescription * description)
Used to create a streaming sound source from a user supplied stream object.
stopAndDeleteSource(SFXSource * source)
Stop the source and delete it.
deleteWhenStopped(SFXSource * source)
Mark source for deletion when it is moving into stopped state.
Listeners
Return the number of listeners currently configured.
setNumListeners(U32 num)
Set the number of concurrent listeners.
getListener(U32 index)
Set the property of the given listener.
setListener(U32 index, const SFXListenerProperties & properties)
3D Sound Configuration
{
Return the curve model currently used distance attenuation of positional sounds.
setDistanceModel(SFXDistanceModel model)
setDopplerFactor(F32 factor)
setRolloffFactor(F32 factor)
setReverb(const SFXReverbProperties & reverb)
Public Types
Public Friends
Protected Static Attributes
The one and only instance of the SFXSystem.
Protected Attributes
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.
Vector< SFXSystemPlugin * >
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.
_assignVoice(SFXSound * sound)
This called to reprioritize and reassign voices to sources.
_createBuffer(const String & filename, SFXDescription * description)
Load file directly through SFXDevice.
_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.
_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)
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.
Returns the one an only instance of the SFXSystem unless it hasn't been initialized or its been disabled in your build.
Public Functions
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.
Return the SFX system event signal.
notifyDescriptionChanged(SFXDescription * description)
Notify the SFX system that the given description has changed.
notifyTrackChanged(SFXTrack * track)
removePlugin(SFXSystemPlugin * plugin)
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 |
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:Parameters: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.
| 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. |
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:Parameters: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.
| 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. |
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. |
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 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.
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.