Main   Class List   Namespace List   Wiki

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.

3D Audio

Streaming vs. Buffered Audio

See also:
SFXDescription::isStreaming

Interactive Audio

See also:
SFXPlayList
SFXState

Ambient Audio

See also:
SFXAmbience

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

See also:
sfxGetAvailableDevices
sfxGetDeviceInfo
sfxCreateDevice
sfxDeleteDevice

Sound System Updates

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

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.

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.

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.

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.

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.

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



Copyright © GarageGames, LLC. All Rights Reserved.