Sound

A broad range of functionality for creating rich game audio. More...

Classes
class	SFXAmbience
	A datablock that describes an ambient sound space. More...
class	SFXController
	A sound source that drives multi-source playback. More...
class	SFXDescription
	A description for how a sound should be played. More...
class	SFXEmitter
	An invisible 3D object that emits sound. More...
class	SFXEnvironment
	Description of a reverb environment. More...
class	SFXParameter
	A sound channel value that can be bound to multiple sound sources. More...
class	SFXPlayList
	A datablock describing a playback pattern of sounds. More...
class	SFXProfile
	Encapsulates a single sound file for playback by the sound system. More...
class	SFXSound
	A sound controller that directly plays a single sound file. More...
class	SFXSource
	Playback controller for a sound source. More...
class	SFXSpace
	A volume in space that defines an ambient sound zone. More...
class	SFXState
	A boolean switch used to modify playlist behavior. More...
class	SFXTrack
	Abstract base class for sound data that can be played back by the sound system. More...
Modules
	FMOD
	Functionality specific to the FMOD SFX implementation.
Enumerations
enum	SFXChannel { Volume, Pitch, Priority, PositionX, PositionY, PositionZ, RotationX, RotationY, RotationZ, VelocityX, VelocityY, VelocityZ, ReferenceDistance, MaxDistance, ConeInsideAngle, ConeOutsideAngle, ConeOutsideVolume, Cursor, Status, User0, User1, User2, User3 }
	Channels are individual properties of sound sources that may be animated over time. More...
enum	SFXDistanceModel { Linear, Logarithmic }
	Type of volume distance attenuation curve. More...
enum	SFXPlayListLoopMode { All, Single }
	Playlist behavior when description is set to loop. More...
enum	SFXPlayListRandomMode { NotRandom, StrictRandom, OrderedRandom }
	Randomization pattern to apply to playlist slot playback order. More...
enum	SFXPlayListReplayMode { IgnorePlaying, RestartPlaying, KeepPlaying, StartNew, SkipIfPlaying }
	Behavior when hitting the play stage of a slot that is still playing from a previous cycle. More...
enum	SFXPlayListStateMode { StopWhenDeactivated, PauseWhenDeactivated, IgnoreWhenDeactivated }
	Reaction behavior when a state is changed incompatibly on a slot that has already started playing. More...
enum	SFXPlayListTransitionMode { None, Wait, WaitAll, Stop, StopAll }
	Playlist behavior when transitioning in and out of invididual slots. More...
enum	SFXStatus { Playing, Stopped, Paused }
	Playback status of sound source. More...
Functions
bool	sfxCreateDevice (string provider, string device, bool useHardware, int maxBuffers)
	Try to create a new sound device using the given properties.
SFXSource	sfxCreateSource (SFXTrack track)
	Create a new source that plays the given track.
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).
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.
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).
void	sfxDeleteDevice ()
	Delete the currently active sound device and release all its resources.
void	sfxDeleteWhenStopped (SFXSource source)
	Mark the given source for deletion as soon as it moves into stopped state.
void	sfxDumpSources (bool includeGroups=false)
	Dump information about all current SFXSource instances to the console.
string	sfxDumpSourcesToString (bool includeGroups=false)
	Dump information about all current SFXSource instances to a string.
string	sfxGetActiveStates ()
	Return a newline-separated list of all active states.
string	sfxGetAvailableDevices ()
	Get a list of all available sound devices.
string	sfxGetDeviceInfo ()
	Return information about the currently active sound device.
SFXDistanceModel	sfxGetDistanceModel ()
	Get the falloff curve type currently being applied to 3D sounds.
float	sfxGetDopplerFactor ()
	Get the current global doppler effect setting.
float	sfxGetRolloffFactor ()
	Get the current global scale factor applied to volume attenuation of 3D sounds in the logarithmic model.
SFXSource	sfxPlay (SFXSource source)
	Start playback of the given source.
void	sfxPlay (SFXTrack track)
	Create a new play-once source for the given track and start playback of the source.
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.
SFXSource	sfxPlayOnce (SFXTrack track)
	Create a play-once source for the given track.
SFXSource	sfxPlayOnce (SFXTrack track, float x, float y, float z, float fadeInTime=-1)
	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).
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.
SFXSource	sfxPlayOnce (SFXDescription description, string filename, float x, float y, float z, float fadeInTime=-1)
	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).
void	sfxSetDistanceModel (SFXDistanceModel model)
	Set the falloff curve type to use for distance-based volume attenuation of 3D sounds.
void	sfxSetDopplerFactor (float value)
	Set the global doppler effect scale factor.
void	sfxSetRolloffFactor (float value)
	Set the global scale factor to apply to volume attenuation of 3D sounds in the logarithmic model.
void	sfxStop (SFXSource source)
	Stop playback of the given source.
void	sfxStopAndDelete (SFXSource source)
	Stop playback of the given source (if it is not already stopped) and delete the source.
Variables
int	$SFX::ambientUpdateTime
	Milliseconds spent on the last ambient audio update.
const int	$SFX::DEVICE_CAPS_DSPEFFECTS
	Sound device capability flag indicating that the sound device supports adding DSP effect chains to sounds.
const int	$SFX::DEVICE_CAPS_FMODDESIGNER
	Sound device capability flag indicating that the sound device supports FMOD Designer audio projects.
const int	$SFX::DEVICE_CAPS_MULTILISTENER
	Sound device capability flag indicating that the sound device supports multiple concurrent listeners.
const int	$SFX::DEVICE_CAPS_OCCLUSION
	Sound device capability flag indicating that the sound device implements sound occlusion.
const int	$SFX::DEVICE_CAPS_REVERB
	Sound device capability flag indicating that the sound device supports reverb.
const int	$SFX::DEVICE_CAPS_VOICEMANAGEMENT
	Sound device capability flag indicating that the sound device implements its own voice virtualization.
const int	$SFX::DEVICE_INFO_CAPS
	Index of device capability flags in device info string.
const int	$SFX::DEVICE_INFO_MAXBUFFERS
	Index of buffer limit number in device info string.
const int	$SFX::DEVICE_INFO_NAME
	Index of device name field in device info string.
const int	$SFX::DEVICE_INFO_PROVIDER
	Index of sound provider field in device info string.
const 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.
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.
static ColorI	SFXEmitter::renderColorInnerCone
	The color with which to render dots in the inner sound cone (Editor only).
static ColorI	SFXEmitter::renderColorOuterCone
	The color with which to render dots in the outer sound cone (Editor only).
static ColorI	SFXEmitter::renderColorOutsideVolume
	The color with which to render dots outside of the outer sound cone (Editor only).
static ColorI	SFXEmitter::renderColorPlayingInRange
	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.
static ColorI	SFXEmitter::renderColorPlayingOutOfRange
	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.
static ColorI	SFXEmitter::renderColorRangeSphere
	The color of the range sphere with which to render sound emitters in the editor.
static ColorI	SFXEmitter::renderColorStoppedInRange
	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.
static ColorI	SFXEmitter::renderColorStoppedOutOfRange
	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.
static bool	SFXEmitter::renderEmitters
	Whether to render enhanced range feedback in the editor on all emitters regardless of selection state.
static float	SFXEmitter::renderPointDistance
	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.
static float	SFXEmitter::renderRadialIncrements
	The stepping (in degrees) for the radial sweep along the axis of the XY plane sweep for sound emitter rendering in the editor.
static float	SFXEmitter::renderSweepIncrements
	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.

Detailed Description

A broad range of functionality for creating rich game audio.

Streaming vs. Buffered Audio

See also:: SFXDescription::isStreaming

Audio Reverb

Please consult the EAX documentation for more information

Note:: Reverb currently only works with FMOD.

See also:: http://www.atc.creative.com/algorithms/eax20.pdf; http://connect.creativelabs.com/developer/Gaming/Forms/AllItems.aspx; SFXEnvironment; SFXDescription::useCustomReverb

Supported Sound File Formats

Note:: When using FMOD, the sound system supports all formats implemented by FMOD. Before applying file lookup patterns to a sound file path, the file name is first passed unaltered to FMOD. This allows to, for example, use URLs for internet radio playback.

Providers and Devices

FMOD
OpenAL
XAudio2
DirectSound
Null

See also:: sfxGetAvailableDevices; sfxGetDeviceInfo; sfxCreateDevice; sfxDeleteDevice

Live Asset Updates of Sound Files

Enumeration Type Documentation

enum SFXChannel

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

See also:: SFXParameter

Interactive Audio

Enumerator:

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: Play 2: Stop 3: 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.

Volume Attenuation

3D Audio

Enumerator:

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.

See also:: SFXDescription::isLooping; SFXPlayList::loopMode

Enumerator:

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.

See also:: SFXPlayList::random

Enumerator:

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.

See also:: SFXPlayList::replay

Enumerator:

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.

See also:: SFXPlayList::stateMode

Enumerator:

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.

See also:: SFXPlayList::transitionIn; SFXPlayList::transitionOut

Enumerator:

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.

Enumerator:

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.

Function Documentation

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.

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.

Note:: This function must be called before any of the sound playback functions can be used.

See also:: sfxGetAvailableDevices; sfxGetDeviceInfo; sfxDeleteDevice

Providers and Devices

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:: A new SFXSource for playback of the given track or 0 if no source could be created from the given track.

Note:: Trying to create a source for a device-specific track type will fail if the currently selected device does not support the type. Example: trying to create a source for an FMOD Designer event when not running FMOD.

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:: A new SFXSource for playback of the given track or 0 if no source could be created from the given track.

Note:: Trying to create a source for a device-specific track type will fail if the currently selected device does not support the type. Example: trying to create a source for an FMOD Designer event when not running FMOD.

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:: A new SFXSource 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();

See also:: SFXProfile

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:: A new SFXSource 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();

See also:: SFXProfile

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.

See also:: sfxCreateDevice

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 = false )

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.

See also:: SFXSource; sfxDumpSourcesToString

string sfxDumpSourcesToString ( bool includeGroups = false )

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.

See also:: SFXSource; sfxDumpSources

string sfxGetActiveStates ( )

Return a newline-separated list of all active states.

Returns:

A list of the form

stateName1 NL stateName2 NL stateName3 ...

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:

provider TAB device TAB hasHardware TAB numMaxBuffers

provider: The name of the device provider (e.g. "FMOD").
device: The name of the device as returned by the device layer.
hasHardware: Whether the device supports hardware mixing or not.
numMaxBuffers: The maximum number of concurrent voices supported by the device's mixer. If this limit limit is exceeded, i.e. if there are more active sounds playing at any one time, then voice virtualization will start culling voices and put them into virtualized playback mode. Voice virtualization may or may not be provided by the device itself; if not provided by the device, it will be provided by Torque's sound system.

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

See also:: sfxCreateDevice; sfxGetDeviceInfo; $SFX::DEVICE_INFO_PROVIDER; $SFX::DEVICE_INFO_NAME; $SFX::DEVICE_INFO_USEHARDWARE; $SFX::DEVICE_INFO_MAXBUFFERS

Providers and Devices

string sfxGetDeviceInfo ( )

Return information about the currently active sound device.

The return value is a tab-delimited string of the following format:

provider TAB device TAB hasHardware TAB numMaxBuffers TAB caps

provider: The name of the device provider (e.g. "FMOD").
device: The name of the device as returned by the device layer.
hasHardware: Whether the device supports hardware mixing or not.
numMaxBuffers: The maximum number of concurrent voices supported by the device's mixer. If this limit limit is exceeded, i.e. if there are more active sounds playing at any one time, then voice virtualization will start culling voices and put them into virtualized playback mode. Voice virtualization may or may not be provided by the device itself; if not provided by the device, it will be provided by Torque's sound system.
caps: A bitfield of capability flags.

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

See also:: sfxCreateDevice; sfxGetAvailableDevices; $SFX::DEVICE_INFO_PROVIDER; $SFX::DEVICE_INFO_NAME; $SFX::DEVICE_INFO_USEHARDWARE; $SFX::DEVICE_INFO_MAXBUFFERS; $SFX::DEVICE_INFO_CAPS; $SFX::DEVICE_CAPS_REVERB; $SFX::DEVICE_CAPS_VOICEMANAGEMENT; $SFX::DEVICE_CAPS_OCCLUSION; $SFX::DEVICE_CAPS_DSPEFFECTS; $SFX::DEVICE_CAPS_MULTILISTENER; $SFX::DEVICE_CAPS_FMODDESIGNER

Providers and Devices

SFXDistanceModel sfxGetDistanceModel ( )

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

Returns:: The current distance model type.

Volume Attenuation

3D Audio

float sfxGetDopplerFactor ( )

Get the current global doppler effect setting.

Returns:: The current global doppler effect scale factor (>=0).

See also:: sfxSetDopplerFactor

Doppler Effect

float sfxGetRolloffFactor ( )

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

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

See also:: sfxGetDistanceModel; SFXDistanceModel

Volume Attenuation 3D Audio

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:: source.

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.

Parameters:

track

The sound datablock to play.

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

Play-Once Sources

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.

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.

Play-Once Sources

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.

Parameters:

track

The sound datablock.

Returns:: A newly created temporary source in "Playing" state or 0 if the operation failed.

Play-Once Sources

SFXSource sfxPlayOnce	(	SFXTrack	track,
		float	x,
		float	y,
		float	z,
		float	fadeInTime = `-1`
	)

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.

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 );

Play-Once Sources

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.

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" );

Play-Once Sources

SFXSource sfxPlayOnce	(	SFXDescription	description,
		string	filename,
		float	x,
		float	y,
		float	z,
		float	fadeInTime = `-1`
	)

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.

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 );

Play-Once Sources

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.

Note:: This setting takes effect globally and is applied to all 3D sounds.

void sfxSetDopplerFactor ( float value )

Set the global doppler effect scale factor.

Parameters:

value

The new doppler shift scale factor.

Precondition:: value must be >= 0.

See also:: sfxGetDopplerFactor

Doppler Effect

void sfxSetRolloffFactor ( float value )

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

Parameters:

value

The new scale factor for logarithmic 3D sound falloff curves.

Precondition:: value must be > 0.

Note:: This function has no effect if the currently distance model is set to SFXDistanceModel::Linear.

See also:: sfxGetDistanceModel; SFXDistanceModel

Volume Attenuation 3D Audio

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.

Parameters:

source

A sound source.

Volume Fades

Variable Documentation

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.

See also:: sfxGetDeviceInfo

Note:: This is not yet used by the sound system.

See also:: sfxGetDeviceInfo

int $SFX::DEVICE_CAPS_FMODDESIGNER

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

Note:: This is exclusive to FMOD. If the FMOD Event DLLs are in place and could be successfully loaded, this flag will be set after initializating an FMOD audio device.

See also:: sfxGetDeviceInfo

FMOD Designer Audio

int $SFX::DEVICE_CAPS_MULTILISTENER

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

Note:: Currently only FMOD implements this.

See also:: sfxGetDeviceInfo

int $SFX::DEVICE_CAPS_OCCLUSION

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

Note:: This is not yet used by the sound system.

See also:: sfxGetDeviceInfo

int $SFX::DEVICE_CAPS_REVERB

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

Note:: Currently only FMOD implements this.

See also:: sfxGetDeviceInfo

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.

Note:: Currently only FMOD implements this.

See also:: sfxGetDeviceInfo

Sounds and Voices

int $SFX::DEVICE_INFO_CAPS

Index of device capability flags in device info string.

See also:: sfxGetDeviceInfo; sfxGetAvailableDevices

int $SFX::DEVICE_INFO_MAXBUFFERS

Index of buffer limit number in device info string.

See also:: sfxGetDeviceInfo; sfxGetAvailableDevices

int $SFX::DEVICE_INFO_NAME

Index of device name field in device info string.

See also:: sfxGetDeviceInfo; sfxGetAvailableDevices

int $SFX::DEVICE_INFO_PROVIDER

Index of sound provider field in device info string.

See also:: sfxGetDeviceInfo; sfxGetAvailableDevices

int $SFX::DEVICE_INFO_USEHARDWARE

Index of use hardware flag in device info string.

See also:: sfxGetDeviceInfo; sfxGetAvailableDevices

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

Torque 3D - Script Manual: Sound

TorqueScript

Sound

Classes

Modules

Enumerations

Functions

Variables

Detailed Description

3D Audio

Streaming vs. Buffered Audio

Interactive Audio

Ambient Audio

Audio Reverb

Supported Sound File Formats

Providers and Devices

Sound System Updates

Live Asset Updates of Sound Files

Enumeration Type Documentation

Function Documentation

Variable Documentation

Get in touch