Sound

A broad range of functionality for creating rich game audio.

Classes

• SFXAmbience
• SFXController
• SFXDescription
• SFXEmitter
• SFXEnvironment
• SFXParameter
• SFXPlayList
• SFXProfile
• SFXSound
• SFXSource
• SFXSpace
• SFXState
• SFXTrack

Enumeration

enum SFXChannel

Channels are individual properties of sound sources that may be animated over time.

Parameters:

• Volume – Channel controls volume level of attached sound sources. See also:SFXDescription::volume
• Pitch – Channel controls pitch of attached sound sources. See also:SFXDescription::pitch
• Priority – Channel controls virtualizaton priority level of attached sound sources. See also:SFXDescription::priority
• PositionX – Channel controls X coordinate of 3D sound position of attached sources.
• PositionY – Channel controls Y coordinate of 3D sound position of attached sources.
• PositionZ – Channel controls Z coordinate of 3D sound position of attached sources.
• RotationX – Channel controls X rotation (in degrees) of 3D sound orientation of attached sources.
• RotationY – Channel controls Y rotation (in degrees) of 3D sound orientation of attached sources.
• RotationZ – Channel controls Z rotation (in degrees) of 3D sound orientation of attached sources.
• VelocityX – Channel controls X coordinate of 3D sound velocity vector of attached sources.
• VelocityY – Channel controls Y coordinate of 3D sound velocity vector of attached sources.
• VelocityZ – Channel controls Z coordinate of 3D sound velocity vector of attached sources.
• ReferenceDistance – Channel controls reference distance of 3D sound of attached sources. See also:SFXDescription::referenceDistance
• MaxDistance – Channel controls max volume attenuation distance of 3D sound of attached sources. See also:SFXDescription::maxDistance
• ConeInsideAngle – Channel controls angle (in degrees) of 3D sound inner volume cone of attached sources. See also:SFXDescription::coneInsideAngle
• ConeOutsideAngle – Channel controls angle (in degrees) of 3D sound outer volume cone of attached sources. See also:SFXDescription::coneOutsideAngle
• ConeOutsideVolume – Channel controls volume outside of 3D sound outer cone of attached sources. See also:SFXDescription::coneOutsideVolume
• Cursor – Channel controls playback cursor of attached sound sources. Note:Be aware that different types of sound sources interpret play cursor positions differently or do not actually have play cursors (these sources will ignore the channel).
• Status – Channel controls playback status of attached sound sources. The channel’s value is rounded down to the nearest integer and interpreted in the following way:1: Play2: Stop3: Pause
• User0 – Channel available for custom use. By default ignored by sources. Note:For FMOD Designer event sources (SFXFMODEventSource), this channel is used for event parameters defined in FMOD Designer and should not be used otherwise.See also:SFXSource::onParameterValueChange
• User1 – Channel available for custom use. By default ignored by sources. See also:SFXSource::onParameterValueChange
• User2 – Channel available for custom use. By default ignored by sources. See also:SFXSource::onParameterValueChange
• User3 – Channel available for custom use. By default ignored by sources. See also:SFXSource::onParameterValueChange

enum SFXDistanceModel

Type of volume distance attenuation curve. The distance model determines the falloff curve applied to the volume of 3D sounds over distance.

Parameters:

• Linear – Volume attenuates linearly from the references distance onwards to max distance where it reaches zero.
• Logarithmic – Volume attenuates logarithmically starting from the reference distance and halving every reference distance step from there on. Attenuation stops at max distance but volume won’t reach zero.

enum SFXPlayListLoopMode

Playlist behavior when description is set to loop.

Parameters:

• All – Loop over all slots, i.e. jump from last to first slot after all slots have played.
• Single – Loop infinitely over the current slot. Only useful in combination with either states or manual playlist control.

enum SFXPlayListRandomMode

Randomization pattern to apply to playlist slot playback order.

Parameters:

• NotRandom – Play slots in sequential order. No randomization.
• StrictRandom – Play a strictly random selection of slots. In this mode, a set of numSlotsToPlay random numbers between 0 and numSlotsToPlay-1 (inclusive), i.e. in the range of valid slot indices, is generated and playlist slots are played back in the order of this list. This allows the same slot to occur multiple times in a list and, consequentially, allows for other slots to not appear at all in a given slot ordering.
• OrderedRandom – Play all slots in the list in a random order. In this mode, the numSlotsToPlay slots from the list with valid tracks assigned are put into a random order and played. This guarantees that each slots is played exactly once albeit at a random position in the total ordering.

enum SFXPlayListReplayMode

Behavior when hitting the play stage of a slot that is still playing from a previous cycle.

Parameters:

• IgnorePlaying – Ignore any sources that may already be playing on the slot and just create a new source.
• RestartPlaying – Restart all sources that was last created for the slot.
• KeepPlaying – Keep playing the current source(s) as if the source started last on the slot was created in this cycle. For this, the sources associated with the slot are brought to the top of the play stack.
• StartNew – Stop all sources currently playing on the slot and then create a new source.
• SkipIfPlaying – If there are sources already playing on the slot, skip the play stage.

enum SFXPlayListStateMode

Reaction behavior when a state is changed incompatibly on a slot that has already started playing.

Parameters:

• StopWhenDeactivated – Stop the sources playing on the slot when a state changes to a setting that is incompatible with the slot’s state setting.
• PauseWhenDeactivated – Pause all sources playing on the slot when a state changes to a setting that is incompatible with the slot’s state setting. When the slot’s state is reactivated again, the sources will resume playback.
• IgnoreWhenDeactivated – Ignore when a state changes to a setting incompatible with the slot’s state setting and just keep playing sources attached to the slot.

enum SFXPlayListTransitionMode

Playlist behavior when transitioning in and out of invididual slots. Transition behaviors apply when the playback controller starts processing a playlist slot and when it ends processing a slot. Using transition behaviors, playback can be synchronized.

Parameters:

• None – No transition. Immediately move on to processing the slot or immediately move on to the next slot.
• Wait – Wait for the sound source spawned last by this playlist to finish playing. Then proceed.
• WaitAll – Wait for all sound sources currently spawned by the playlist to finish playing. Then proceed.
• Stop – Stop the sound source spawned last by this playlist. Then proceed.
• StopAll – Stop all sound sources spawned by the playlist. Then proceed.

enum SFXStatus

Playback status of sound source.

Parameters:

• Playing – The source is currently playing.
• Stopped – Playback of the source is stopped. When transitioning to Playing state, playback will start at the beginning of the source.
• Paused – Playback of the source is paused. Resuming playback will play from the current playback position.

Functions

bool sfxCreateDevice(string provider, string device, bool useHardware, int maxBuffers)

Try to create a new sound device using the given properties. If a sound device is currently initialized, it will be uninitialized first. However, be aware that in this case, if this function fails, it will not restore the previously active device but rather leave the sound system in an uninitialized state. Sounds that are already playing while the new device is created will be temporarily transitioned to virtualized playback and then resume normal playback once the device has been created. In the core scripts, sound is automatically set up during startup in the sfxStartup() function. Providers and Devices

Parameters:

• provider – The name of the device provider as returned by sfxGetAvailableDevices().
• device – The name of the device as returned by sfxGetAvailableDevices().
• useHardware – Whether to enabled hardware mixing on the device or not. Only relevant if supported by the given device.
• maxBuffers – The maximum number of concurrent voices for this device to use or -1 for the device to pick its own reasonable default.

Returns:

True if the initialization was successful, false if not.

SFXSource sfxCreateSource(SFXTrack track)

Create a new source that plays the given track. The source will be returned in stopped state. Call SFXSource::play() to start playback. In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object. This function will automatically create the right SFXSource type for the given SFXTrack .

Parameters:track – The track the source should play. Returns:for playback of the given track or 0 if no source could be created from the given track.

Example:

// Create and play a source from a pre-existing profile:
%source = sfxCreateSource( SoundFileProfile );
%source.play();

SFXSource sfxCreateSource(SFXTrack track, float x, float y, float z)

Create a new source that plays the given track and position its 3D sounds source at the given coordinates (if it is a 3D sound). The source will be returned in stopped state. Call SFXSource::play() to start playback. In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object. This function will automatically create the right SFXSource type for the given SFXTrack .

Parameters:

• track – The track the source should play.
• x – The X coordinate of the 3D sound position.
• y – The Y coordinate of the 3D sound position.
• z – The Z coordinate of the 3D sound position.

Returns:

for playback of the given track or 0 if no source could be created from the given track.

Example:

// Create and play a source from a pre-existing profile and position it at (100, 200, 300):
%source = sfxCreateSource( SoundFileProfile, 100, 200, 300 );
%source.play();

SFXSound sfxCreateSource(SFXDescription description, string filename)

Create a temporary SFXProfile from the given description and filename and then create and return a new source that plays the profile. The source will be returned in stopped state. Call SFXSource::play() to start playback. In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.

Parameters:

• description – The description to use for setting up the temporary SFXProfile.
• filename – Path to the sound file to play.

Returns:

for playback of the given track or 0 if no source or no temporary profile could be created.

Example:

// Create a source for a music track:
%source = sfxCreateSource( AudioMusicLoop2D, "art/sound/backgroundMusic" );
%source.play();

SFXSound sfxCreateSource(SFXDescription description, string filename, float x, float y, float z)

Create a temporary SFXProfile from the given description and filename and then create and return a new source that plays the profile. Position the sound source at the given coordinates (if it is a 3D sound). The source will be returned in stopped state. Call SFXSource::play() to start playback. In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.

Parameters:

• description – The description to use for setting up the temporary SFXProfile.
• filename – Path to the sound file to play.
• x – The X coordinate of the 3D sound position.
• y – The Y coordinate of the 3D sound position.
• z – The Z coordinate of the 3D sound position.

Returns:

for playback of the given track or 0 if no source or no temporary profile could be created.

Example:

// Create a source for a music track and position it at (100, 200, 300):
%source = sfxCreateSource( AudioMusicLoop3D, "art/sound/backgroundMusic", 100, 200, 300 );
%source.play();

void sfxDeleteDevice()

Delete the currently active sound device and release all its resources. SFXSources that are still playing will be transitioned to virtualized playback mode. When creating a new device, they will automatically transition back to normal playback. In the core scripts, this is done automatically for you during shutdown in the sfxShutdown() function. Providers and Devices

void sfxDeleteWhenStopped(SFXSource source)

Mark the given source for deletion as soon as it moves into stopped state. This function will retroactively turn the given source into a play-once source (see Play-Once Sources ).

Parameters:source – A sound source.

void sfxDumpSources(bool includeGroups)

Dump information about all current SFXSource instances to the console. The dump includes information about the playback status for each source, volume levels, virtualization, etc.

Parameters:includeGroups – If true, direct instances of SFXSources (which represent logical sound groups) will be included. Otherwise only instances of subclasses of SFXSources are included in the dump.

string sfxDumpSourcesToString(bool includeGroups)

Dump information about all current SFXSource instances to a string. The dump includes information about the playback status for each source, volume levels, virtualization, etc.

Parameters:includeGroups – If true, direct instances of SFXSources (which represent logical sound groups) will be included. Otherwise only instances of subclasses of SFXSources are included in the dump. Returns:A string containing a dump of information about all currently instantiated SFXSources.

string sfxGetActiveStates()

Return a newline-separated list of all active states.

Returns:where each element is the name of an active state object.

Example:

// Disable all active states.
foreach$( %state in sfxGetActiveStates() )
   %state.disable();

string sfxGetAvailableDevices()

Get a list of all available sound devices. The return value will be a newline-separated list of entries where each line describes one available sound device. Each such line will have the following format:

Returns:A newline-separated list of information about all available sound devices.

string sfxGetDeviceInfo()

Return information about the currently active sound device. The return value is a tab-delimited string of the following format:

Returns:A tab-separated list of properties of the currently active sound device or the empty string if no sound device has been initialized.

SFXDistanceModel sfxGetDistanceModel()

Get the falloff curve type currently being applied to 3D sounds. Volume Attenuation 3D Audio

Returns:The current distance model type.

float sfxGetDopplerFactor()

Get the current global doppler effect setting. Doppler Effect

Returns:=0).

float sfxGetRolloffFactor()

Get the current global scale factor applied to volume attenuation of 3D sounds in the logarithmic model. Volume Attenuation 3D Audio

Returns:The current scale factor for logarithmic 3D sound falloff curves.

SFXSource sfxPlay(SFXSource source)

Start playback of the given source. This is the same as calling SFXSource::play() directly.

Parameters:source – The source to start playing. Returns:.

Example:

// Create and play a source from a pre-existing profile:
%source = sfxCreateSource( SoundFileProfile );
%source.play();

void sfxPlay(SFXTrack track)

Create a new play-once source for the given track and start playback of the source. This is equivalent to calling sfxCreateSource() on and SFXSource::play() on the resulting source. Play-Once Sources

Parameters:track – The sound datablock to play. Returns:The newly created play-once source or 0 if the creation failed.

void sfxPlay(SFXTrack track, float x, float y, float z)

Create a new play-once source for the given track , position its 3D sound at the given coordinates (if the track’s description is set up for 3D sound) and start playback of the source. This is equivalent to calling sfxCreateSource() on and SFXSource::play() on the resulting source. Play-Once Sources

Parameters:

• track – The sound datablock to play.
• x – The X coordinate of the 3D sound position.
• y – The Y coordinate of the 3D sound position.
• z – The Z coordinate of the 3D sound position.

Returns:

The newly created play-once source or 0 if the creation failed.

SFXSource sfxPlayOnce(SFXTrack track)

Create a play-once source for the given track . Once playback has finished, the source will be automatically deleted in the next sound system update. Play-Once Sources

Parameters:track – The sound datablock. Returns:A newly created temporary source in “Playing” state or 0 if the operation failed.

SFXSource sfxPlayOnce(SFXTrack track, float x, float y, float z, float fadeInTime)

Create a play-once source for the given given track and position the source’s 3D sound at the given coordinates only if the track’s description is set up for 3D sound). Once playback has finished, the source will be automatically deleted in the next sound system update. Play-Once Sources

Parameters:

• track – The sound datablock.
• x – The X coordinate of the 3D sound position.
• y – The Y coordinate of the 3D sound position.
• z – The Z coordinate of the 3D sound position.
• fadeInTime – If >=0, this overrides the SFXDescription::fadeInTime value on the track’s description.

Returns:

A newly created temporary source in “Playing” state or 0 if the operation failed.

Example:

// Immediately start playing the given track.  Fade it in to full volume over 5 seconds.
sfxPlayOnce( MusicTrack, 0, 0, 0, 5.f );

SFXSource sfxPlayOnce(SFXDescription description, string filename)

Create a new temporary SFXProfile from the given description and filename , then create a play-once source for it and start playback. Once playback has finished, the source will be automatically deleted in the next sound system update. If not referenced otherwise by then, the temporary SFXProfile will also be deleted. Play-Once Sources

Parameters:

• description – The description to use for playback.
• filename – Path to the sound file to play.

Returns:

A newly created temporary source in “Playing” state or 0 if the operation failed.

Example:

// Play a sound effect file once.
sfxPlayOnce( AudioEffects, "art/sound/weapons/Weapon_pickup" );

SFXSource sfxPlayOnce(SFXDescription description, string filename, float x, float y, float z, float fadeInTime)

Create a new temporary SFXProfile from the given description and filename , then create a play-once source for it and start playback. Position the source’s 3D sound at the given coordinates (only if the description is set up for 3D sound). Once playback has finished, the source will be automatically deleted in the next sound system update. If not referenced otherwise by then, the temporary SFXProfile will also be deleted. Play-Once Sources

Parameters:

• description – The description to use for playback.
• filename – Path to the sound file to play.
• x – The X coordinate of the 3D sound position.
• y – The Y coordinate of the 3D sound position.
• z – The Z coordinate of the 3D sound position.
• fadeInTime – If >=0, this overrides the SFXDescription::fadeInTime value on the track’s description.

Returns:

A newly created temporary source in “Playing” state or 0 if the operation failed.

Example:

// Play a sound effect file once using a 3D sound with a default falloff placed at the origin.
sfxPlayOnce( AudioDefault3D, "art/sound/weapons/Weapon_pickup", 0, 0, 0 );

void sfxSetDistanceModel(SFXDistanceModel model)

Set the falloff curve type to use for distance-based volume attenuation of 3D sounds.

Parameters:model – The distance model to use for 3D sound.

void sfxSetDopplerFactor(float value)

Set the global doppler effect scale factor. Doppler Effect

Parameters:value – The new doppler shift scale factor.

void sfxSetRolloffFactor(float value)

Set the global scale factor to apply to volume attenuation of 3D sounds in the logarithmic model. Volume Attenuation 3D Audio

Parameters:value – The new scale factor for logarithmic 3D sound falloff curves.

void sfxStop(SFXSource source)

Stop playback of the given source . This is equivalent to calling SFXSource::stop() .

Parameters:source – The source to put into stopped state.

void sfxStopAndDelete(SFXSource source)

Stop playback of the given source (if it is not already stopped) and delete the source . The advantage of this function over directly calling delete() is that it will correctly handle volume fades that may be configured on the source. Whereas calling delete() would immediately stop playback and delete the source, this functionality will wait for the fade-out to play and only then stop the source and delete it. Volume Fades

Parameters:source – A sound source.

Variables

int $SFX::ambientUpdateTime

Milliseconds spent on the last ambient audio update. Sound System Updates Ambient Audio

int $SFX::DEVICE_CAPS_DSPEFFECTS

Sound device capability flag indicating that the sound device supports adding DSP effect chains to sounds.

int $SFX::DEVICE_CAPS_FMODDESIGNER

Sound device capability flag indicating that the sound device supports FMOD Designer audio projects. FMOD Designer Audio

int $SFX::DEVICE_CAPS_MULTILISTENER

Sound device capability flag indicating that the sound device supports multiple concurrent listeners.

int $SFX::DEVICE_CAPS_OCCLUSION

Sound device capability flag indicating that the sound device implements sound occlusion.

int $SFX::DEVICE_CAPS_REVERB

Sound device capability flag indicating that the sound device supports reverb. Audio Reverb

int $SFX::DEVICE_CAPS_VOICEMANAGEMENT

Sound device capability flag indicating that the sound device implements its own voice virtualization. For these devices, the sound system will deactivate its own voice management and leave voice virtualization entirely to the device. Sounds and Voices

int $SFX::DEVICE_INFO_CAPS

Index of device capability flags in device info string.

int $SFX::DEVICE_INFO_MAXBUFFERS

Index of buffer limit number in device info string.

int $SFX::DEVICE_INFO_NAME

Index of device name field in device info string.

int $SFX::DEVICE_INFO_PROVIDER

Index of sound provider field in device info string.

int $SFX::DEVICE_INFO_USEHARDWARE

Index of use hardware flag in device info string.

int $SFX::numCulled

Number of SFXSounds that are currently in virtualized playback mode. Sounds and Voices

int $SFX::numPlaying

Number of SFXSources that are currently in playing state.

int $SFX::numSounds

Number of SFXSound type objects (i.e. actual single-file sounds) that are currently instantiated.

int $SFX::numSources

Number of SFXSource type objects that are currently instantiated.

int $SFX::numVoices

Number of voices that are currently allocated on the sound device.

int $SFX::parameterUpdateTime

Milliseconds spent on the last SFXParameter update loop. Sound System Updates Interactive Audio

ColorI SFXEmitter::renderColorInnerCone[static, inherited]

The color with which to render dots in the inner sound cone (Editor only).

ColorI SFXEmitter::renderColorOuterCone[static, inherited]

The color with which to render dots in the outer sound cone (Editor only).

ColorI SFXEmitter::renderColorOutsideVolume[static, inherited]

The color with which to render dots outside of the outer sound cone (Editor only).

ColorI SFXEmitter::renderColorPlayingInRange[static, inherited]

The color with which to render a sound emitter’s marker cube in the editor when the emitter’s sound is playing and in range of the listener.

ColorI SFXEmitter::renderColorPlayingOutOfRange[static, inherited]

The color with which to render a sound emitter’s marker cube in the editor when the emitter’s sound is playing but out of the range of the listener.

ColorI SFXEmitter::renderColorRangeSphere[static, inherited]

The color of the range sphere with which to render sound emitters in the editor.

ColorI SFXEmitter::renderColorStoppedInRange[static, inherited]

The color with which to render a sound emitter’s marker cube in the editor when the emitter’s sound is not playing but the emitter is in range of the listener.

ColorI SFXEmitter::renderColorStoppedOutOfRange[static, inherited]

The color with which to render a sound emitter’s marker cube in the editor when the emitter’s sound is not playing and the emitter is out of range of the listener.

bool SFXEmitter::renderEmitters[static, inherited]

Whether to render enhanced range feedback in the editor on all emitters regardless of selection state.

float SFXEmitter::renderPointDistance[static, inherited]

The distance between individual points in the sound emitter rendering in the editor as the points move from the emitter’s center away to maxDistance.

float SFXEmitter::renderRadialIncrements[static, inherited]

The stepping (in degrees) for the radial sweep along the axis of the XY plane sweep for sound emitter rendering in the editor.

float SFXEmitter::renderSweepIncrements[static, inherited]

The stepping (in degrees) for the radial sweep on the XY plane for sound emitter rendering in the editor.

int $SFX::sourceUpdateTime

Milliseconds spent on the last SFXSource update loop. Sound System Updates

FMOD

Functionality specific to the FMOD SFX implementation.

Classes

• SFXFMODEvent
• SFXFMODEventGroup
• SFXFMODEventSource
• SFXFMODProject

Description

When using FMOD for audio output in combination with Torque’s sound system, an extended set of features is available to the user. This includes:

• Reverb support
• Enhanced voice virtualization
• Support for multiple listeners
• Enhanced sound format support: .aiff, .asf, .asx, .dls, .flac .fsb, .it, .m3u, .mid, .mod, .mp2, .mp3, .ogg, .pls, .s3m, .vag, .wav, .wax, .wma, .xm, .xma (on Xbox only)
• FMOD Designer enhanced audio design support

Functions

void fmodDumpDSPInfo()

Dump information about the standard DSP effects.

void fmodDumpMemoryStats()

Returns:Prints the current memory consumption of the FMOD module

Variables

bool $pref::SFX::FMOD::disableSoftware

Whether to disable the FMOD software mixer to conserve memory. All sounds not created with SFXDescription::useHardware or using DSP effects will fail to load.

string $pref::SFX::FMOD::DSoundHRTF

The type of HRTF to use for hardware-mixed 3D sounds when FMOD is using DirectSound for sound output and hardware-acceleration is not available. Options are

• “none”: simple stereo panning/doppler/attenuation
• “light”: slightly higher quality than “none”
• “full”: full quality 3D playback

bool $pref::SFX::FMOD::enableProfile

Whether to enable support for FMOD’s profiler. Using the FMOD Profiler with Torque

int $SFX::Device::fmodCoreMem

Current number of bytes allocated by the core FMOD sound system.

int $SFX::Device::fmodEventMem

Current number of bytes allocated by the FMOD Designer event system.

int $SFX::Device::fmodNumEventSources

The current number of SFXFMODEventSource instances in the system. This tells the number of sounds in the system that are currently playing FMOD Designer events.

string $pref::SFX::FMOD::pluginPath

Path to additional FMOD plugins.

bool $pref::SFX::FMOD::useSoftwareHRTF

Whether to enable HRTF in FMOD’s software mixer. This will add a lowpass filter effect to the DSP effect chain of all sounds mixed in software.