TorqueGameEngines/Torque3D
1
0
Fork 0
mirror of https://github.com/TorqueGameEngines/Torque3D.git synced 2026-06-15 09:54:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

SFX API Changes

Browse source 
DSound has since been deprecated and xaudio2 would require us to write our own 3d spatialization and mixer
Load devices the same way we load in the gfx end
setup sfx provider
run sfx devices on startup
various fixes around sfx null device
added the bitrate and samplerate globals
added the hrtf global code is in to use this but not setup yet
Adds speed of sound to the sound system
SFXAmbience now has a property for speed of sound for different mediums, can also be set directly
This commit is contained in:
marauder2k7 2026-03-13 08:05:42 +00:00
parent 1c6409a485
commit 974f217b96
53 changed files with 1885 additions and 6409 deletions
Download patch file Download diff file Expand all files Collapse all files

560
Engine/source/sfx/sfxSystem.h
View file

@ -23,9 +23,10 @@
#ifndef _SFXSYSTEM_H_
#define _SFXSYSTEM_H_
#ifndef _SFXCOMMON_H_
#include "sfx/sfxCommon.h"
#endif
#ifndef _SFXPROVIDER_H_
#include "sfx/sfxProvider.h"
#endif // !_SFXPROVIDER_H_
#ifndef _TSIGNAL_H_
#include "core/util/tSignal.h"
#endif
@ -98,343 +99,358 @@ class SFXSystemPlugin
///
class SFXSystem
{
friend class SFXSound; // _assignVoices
friend class SFXSource; // _onAddSource, _onRemoveSource.
friend class SFXProfile; // _createBuffer.
friend class SFXSound; // _assignVoices
friend class SFXSource; // _onAddSource, _onRemoveSource.
friend class SFXProfile; // _createBuffer.
public:
/// Allows device to register themselves as available
typedef Signal<void(Vector<SFXProvider*>&)> RegisterProviderSignal;
static RegisterProviderSignal& getRegisterProviderSignal();
/// Get the number of available providers.
static S32 getProviderCount();
/// Enumerate all the sound providers on the system
static void enumerateProviders();
static void getProviders(Vector<SFXProvider*>* providers);
static const char* getProviderNameFromType(SFXProviderType type);
static SFXProvider* getBestProviderChoice();
static SFXProvider* getProvider(U32 index);
typedef Signal< void( SFXSystemEventType event ) > EventSignalType;
typedef Vector< SFXSource* > SFXSourceVector;
typedef Vector< SFXSound* > SFXSoundVector;
private:
/// List of known adapters.
static Vector<SFXProvider*> smProviders;
static RegisterProviderSignal* smRegisterProviderSignal;
protected:
/// The one and only instance of the SFXSystem.
static SFXSystem* smSingleton;
/// The protected constructor.
///
/// @see SFXSystem::init()
///
SFXSystem();
/// The non-virtual destructor. You shouldn't
/// ever need to overload this class.
~SFXSystem();
public:
typedef Signal< void( SFXSystemEventType event ) > EventSignalType;
typedef Vector< SFXSource* > SFXSourceVector;
typedef Vector< SFXSound* > SFXSoundVector;
/// The current output sound device initialized
/// and ready to play back.
SFXDevice* mDevice;
protected:
///
SFXSoundVector mSounds;
/// The one and only instance of the SFXSystem.
static SFXSystem* smSingleton;
/// The protected constructor.
///
/// @see SFXSystem::init()
///
SFXSystem();
/// The non-virtual destructor. You shouldn't
/// ever need to overload this class.
~SFXSystem();
/// The current output sound device initialized
/// and ready to play back.
SFXDevice* mDevice;
///
SFXSoundVector mSounds;
/// This is used to keep track of play once sources
/// that must be released when they stop playing.
SFXSourceVector mPlayOnceSources;
/// This is used to keep track of play once sources
/// that must be released when they stop playing.
SFXSourceVector mPlayOnceSources;
/// The last time the sources got an update.
U32 mLastSourceUpdateTime;
/// The last time the sources got an update.
U32 mLastSourceUpdateTime;
///
U32 mLastAmbientUpdateTime;
///
U32 mLastAmbientUpdateTime;
///
U32 mLastParameterUpdateTime;
///
U32 mLastParameterUpdateTime;
/// The distance model used for rolloff curve computation on 3D sounds.
SFXDistanceModel mDistanceModel;
/// The distance model used for rolloff curve computation on 3D sounds.
SFXDistanceModel mDistanceModel;
/// The current doppler scale factor.
F32 mDopplerFactor;
/// The current doppler scale factor.
F32 mDopplerFactor;
/// The current speed of sound.
F32 mSpeedOfSound;
/// The current curve rolloff factor.
F32 mRolloffFactor;
/// The current curve rolloff factor.
F32 mRolloffFactor;
/// The current position and orientation of all listeners.
Vector< SFXListenerProperties > mListeners;
/// The current position and orientation of all listeners.
Vector< SFXListenerProperties > mListeners;
/// Current global reverb properties.
SFXReverbProperties mReverb;
/// Current global reverb properties.
SFXReverbProperties mReverb;
/// SFX system event signal.
EventSignalType mEventSignal;
/// SFX system event signal.
EventSignalType mEventSignal;
/// Ambient soundscape manager.
SFXSoundscapeManager* mSoundscapeMgr;
/// Ambient soundscape manager.
SFXSoundscapeManager* mSoundscapeMgr;
/// List of plugins currently linked to the SFX system.
Vector< SFXSystemPlugin* > mPlugins;
/// List of plugins currently linked to the SFX system.
Vector< SFXSystemPlugin* > mPlugins;
/// @name Stats
///
/// Stats reported back to the console for tracking performance.
///
/// @{
/// @name 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;
S32 mStatNumSources;
S32 mStatNumSounds;
S32 mStatNumPlaying;
S32 mStatNumCulled;
S32 mStatNumVoices;
S32 mStatSourceUpdateTime;
S32 mStatParameterUpdateTime;
S32 mStatAmbientUpdateTime;
/// @}
/// @}
/// Called to reprioritize and reassign buffers as
/// sources change state, volumes are adjusted, and
/// the listener moves around.
///
/// @see SFXSource::_update()
///
void _updateSources();
/// Called to reprioritize and reassign buffers as
/// sources change state, volumes are adjusted, and
/// the listener moves around.
///
/// @see SFXSource::_update()
///
void _updateSources();
/// This called to reprioritize and reassign
/// voices to sources.
void _assignVoices();
/// This called to reprioritize and reassign
/// voices to sources.
void _assignVoices();
///
void _assignVoice( SFXSound* sound );
///
void _assignVoice( SFXSound* sound );
///
void _sortSounds( const SFXListenerProperties& listener );
///
void _sortSounds( const SFXListenerProperties& listener );
/// Called from SFXSource::onAdd to register the source.
void _onAddSource( SFXSource* source );
/// Called from SFXSource::onAdd to register the source.
void _onAddSource( SFXSource* source );
/// Called from SFXSource::onRemove to unregister the source.
void _onRemoveSource( SFXSource* source );
/// Called from SFXSource::onRemove to unregister the source.
void _onRemoveSource( SFXSource* source );
/// Called from SFXProfile to create a device specific
/// sound buffer used in conjunction with a voice in playback.
SFXBuffer* _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.
SFXBuffer* _createBuffer( const ThreadSafeRef< SFXStream >& stream, SFXDescription* description );
/// Load file directly through SFXDevice. Depends on
/// availability with selected SFXDevice.
///
/// @return Return new buffer or NULL.
SFXBuffer* _createBuffer( const String& filename, SFXDescription* description );
/// Load file directly through SFXDevice. Depends on
/// availability with selected SFXDevice.
///
/// @return Return new buffer or NULL.
SFXBuffer* _createBuffer( const String& filename, SFXDescription* description );
///
SFXDevice* _getDevice() const { return mDevice; }
///
SFXDevice* _getDevice() const { return mDevice; }
public:
public:
/// 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 SFXSystem::init()
/// @see SFX
static SFXSystem* getSingleton() { return smSingleton; }
/// 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 SFXSystem::init()
/// @see SFX
static SFXSystem* getSingleton() { return smSingleton; }
/// This is called from initialization to prepare the
/// sound system singleton. This also includes registering
/// common resource types and initializing available sound
/// providers.
static void init();
/// This is called from initialization to prepare the
/// sound system singleton. This also includes registering
/// common resource types and initializing available sound
/// providers.
static void init();
/// 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.
static void 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.
static void destroy();
/// This is only public so that it can be called by
/// the game update loop. It updates the current
/// device and all sources.
void _update();
/// This is only public so that it can be called by
/// the game update loop. It updates the current
/// device and all sources.
void _update();
/// Register the given plugin with the system.
void addPlugin( SFXSystemPlugin* plugin );
/// Register the given plugin with the system.
void addPlugin( SFXSystemPlugin* plugin );
/// Unregister the given plugin with the system.
void removePlugin( SFXSystemPlugin* plugin );
/// Unregister the given plugin with the system.
void removePlugin( SFXSystemPlugin* plugin );
/// @name Device Management
/// @{
/// @name Device Management
/// @{
/// This initializes a new device.
///
/// @param providerName The name of the provider.
/// @param deviceName The name of the provider device.
/// @param useHardware Toggles the use of hardware processing when available.
/// @param maxBuffers The maximum buffers for this device to use or -1
/// for the device to pick its own reasonable default.
/// @param changeDevice Allows this to change the current device to a new one
/// @return Returns true if the device was created.
bool createDevice( const String& providerName,
const String& deviceName,
bool useHardware,
S32 maxBuffers,
bool changeDevice = false);
/// This initializes a new device.
///
/// @return Returns true if the device was created.
bool createDevice( SFXProvider* provider);
/// 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
String 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
String getDeviceInfoString();
/// This destroys the current device. All sources loose their
/// playback buffers, but otherwise continue to function.
void deleteDevice();
/// This destroys the current device. All sources loose their
/// playback buffers, but otherwise continue to function.
void deleteDevice();
/// Returns true if a device is allocated.
bool hasDevice() const { return mDevice != NULL; }
/// Returns true if a device is allocated.
bool hasDevice() const { return mDevice != NULL; }
/// @}
/// @}
/// @name Source Creation
/// @{
/// @name Source Creation
/// @{
/// 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.
///
/// @param profile The sound profile for the created source.
/// @param transform The optional transform if creating a 3D source.
/// @param velocity The optional doppler velocity if creating a 3D source.
///
/// @return The sound source or NULL if an error occured.
SFXSource* createSource( SFXTrack* track,
const MatrixF* transform = NULL,
const VectorF* velocity = NULL );
/// 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.
///
/// @param profile The sound profile for the created source.
/// @param transform The optional transform if creating a 3D source.
/// @param velocity The optional doppler velocity if creating a 3D source.
///
/// @return The sound source or NULL if an error occured.
SFXSource* createSource( SFXTrack* track,
const MatrixF* transform = NULL,
const VectorF* velocity = NULL );
/// 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.
///
/// @param 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.
///
/// @param description The sound description to apply to the source.
///
/// @return The sound source or NULL if an error occured.
SFXSound* 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.
///
/// @param 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.
///
/// @param description The sound description to apply to the source.
///
/// @return The sound source or NULL if an error occured.
SFXSound* createSourceFromStream( const ThreadSafeRef< SFXStream >& stream,
SFXDescription* description );
/// 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.
///
/// @param profile The sound profile for the created source.
/// @param transform The optional transform if creating a 3D source.
/// @param velocity The optional doppler velocity if creating a 3D source.
///
/// @return The sound source or NULL if an error occured.
SFXSource* playOnce( SFXTrack* track,
const MatrixF* transform = NULL,
const VectorF* velocity = NULL,
F32 fadeInTime = -1.f );
SFXSource* playOnce( SFXProfile* profile,
const MatrixF* transform = NULL,
const VectorF* velocity = NULL,
F32 fadeInTime = -1.f )
{ // Avoids having to require inclusion of sfxProfile.h
return playOnce( ( SFXTrack* ) profile, transform, velocity, 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.
///
/// @param profile The sound profile for the created source.
/// @param transform The optional transform if creating a 3D source.
/// @param velocity The optional doppler velocity if creating a 3D source.
///
/// @return The sound source or NULL if an error occured.
SFXSource* playOnce( SFXTrack* track,
const MatrixF* transform = NULL,
const VectorF* velocity = NULL,
F32 fadeInTime = -1.f );
SFXSource* playOnce( SFXProfile* profile,
const MatrixF* transform = NULL,
const VectorF* velocity = NULL,
F32 fadeInTime = -1.f )
{ // Avoids having to require inclusion of sfxProfile.h
return playOnce( ( SFXTrack* ) profile, transform, velocity, fadeInTime );
}
/// 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.
void 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.
void stopAndDeleteSource( 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.
void 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.
void deleteWhenStopped( SFXSource* source );
/// @}
/// @}
/// @}
/// @}
/// @name Listeners
/// @{
/// @name Listeners
/// @{
/// Return the number of listeners currently configured.
U32 getNumListeners() const { return mListeners.size(); }
/// Return the number of listeners currently configured.
U32 getNumListeners() const { return mListeners.size(); }
/// Set the number of concurrent listeners.
/// @note It depends on the selected device if more than one listener is actually supported.
void setNumListeners( U32 num );
/// Set the number of concurrent listeners.
/// @note It depends on the selected device if more than one listener is actually supported.
void setNumListeners( U32 num );
/// Set the property of the given listener.
const SFXListenerProperties& getListener( U32 index = 0 ) const { return mListeners[ index ]; }
/// Set the property of the given listener.
const SFXListenerProperties& getListener( U32 index = 0 ) const { return mListeners[ index ]; }
/// Set the 3D attributes of the given listener.
void setListener( U32 index, const MatrixF& transform, const Point3F& velocity );
void setListener( U32 index, const SFXListenerProperties& properties )
{
setListener( index, properties.getTransform(), properties.getVelocity() );
}
/// Set the 3D attributes of the given listener.
void setListener( U32 index, const MatrixF& transform, const Point3F& velocity );
void setListener( U32 index, const SFXListenerProperties& properties )
{
setListener( index, properties.getTransform(), properties.getVelocity() );
}
/// @}
/// @}
/// @name 3D Sound Configuration
/// {
/// @name 3D Sound Configuration
/// {
/// Return the curve model currently used distance attenuation of positional sounds.
SFXDistanceModel getDistanceModel() const { return mDistanceModel; }
/// Return the curve model currently used distance attenuation of positional sounds.
SFXDistanceModel getDistanceModel() const { return mDistanceModel; }
///
void setDistanceModel( SFXDistanceModel model );
///
void setDistanceModel( SFXDistanceModel model );
///
F32 getDopplerFactor() const { return mDopplerFactor; }
///
F32 getDopplerFactor() const { return mDopplerFactor; }
///
void setDopplerFactor( F32 factor );
///
void setDopplerFactor( F32 factor );
///
F32 getRolloffFactor() const { return mRolloffFactor; }
///
F32 getRolloffFactor() const { return mRolloffFactor; }
/// <summary>
/// Change the devices speed of sound.
/// </summary>
/// <param name="speedOfSound">F32 for speed of sound.</param>
void setSpeedOfSound(F32 speedOfSound);
///
void setRolloffFactor( F32 factor );
///
void setRolloffFactor( F32 factor );
///
const SFXReverbProperties& getReverb() const { return mReverb; }
///
const SFXReverbProperties& getReverb() const { return mReverb; }
///
void setReverb( const SFXReverbProperties& reverb );
///
void setReverb( const SFXReverbProperties& reverb );
/// @}
/// @}
///
SFXSoundscapeManager* getSoundscapeManager() const { return mSoundscapeMgr; }
///
SFXSoundscapeManager* getSoundscapeManager() const { return mSoundscapeMgr; }
/// Dump information about all current SFXSources to the console or
/// to the given StringBuilder.
void dumpSources( StringBuilder* toString = NULL, bool excludeGroups = true );
/// Dump information about all current SFXSources to the console or
/// to the given StringBuilder.
void dumpSources( StringBuilder* toString = NULL, bool excludeGroups = true );
/// Return the SFX system event signal.
EventSignalType& getEventSignal() { return mEventSignal; }
/// Return the SFX system event signal.
EventSignalType& getEventSignal() { return mEventSignal; }
/// Notify the SFX system that the given description has changed.
/// All sources currently using the description will be updated.
void notifyDescriptionChanged( SFXDescription* description);
/// Notify the SFX system that the given description has changed.
/// All sources currently using the description will be updated.
void notifyDescriptionChanged( SFXDescription* description);
///
void notifyTrackChanged( SFXTrack* track );
///
void notifyTrackChanged( SFXTrack* track );
};