Main   Class List   Namespace List   Wiki

SFXPlayList Class Reference
[Sound]

A datablock describing a playback pattern of sounds. More...

Inheritance diagram for SFXPlayList:
Inheritance graph
[legend]

List of all members.

Public Attributes

Sound

float delayTimeIn [16]
 Seconds to wait after moving into slot before transitionIn.
Point2F delayTimeInVariance [16]
 Bounds on randomization of delayTimeIn.
float delayTimeOut [16]
 Seconds to wait before moving out of slot after transitionOut.
Point2F delayTimeOutVariance [16]
 Bounds on randomization of delayTimeOut.
float fadeTimeIn [16]
 Seconds to fade sound in (-1 to use the track's own fadeInTime.).
Point2F fadeTimeInVariance [16]
 Bounds on randomization of fadeInTime.
float fadeTimeOut [16]
 Seconds to fade sound out (-1 to use the track's own fadeOutTime.).
Point2F fadeTimeOutVariance [16]
 Bounds on randomization of fadeOutTime.
SFXPlayListLoopMode loopMode
 Behavior when description has looping enabled.
float maxDistance [16]
 maxDistance to apply to 3D sounds in this slot (<1 to use maxDistance of track's own description).
Point2F maxDistanceVariance [16]
 Bounds on randomization of maxDistance.
int numSlotsToPlay
 Number of slots to play.
float pitchScale [16]
 Scale factor to apply to pitch of sounds played on this list slot.
Point2F pitchScaleVariance [16]
 Bounds on randomization of pitchScale.
SFXPlayListRandomMode random
 Slot playback order randomization pattern.
float referenceDistance [16]
 referenceDistance to set for 3D sounds in this slot (<1 to use referenceDistance of track's own description).
Point2F referenceDistanceVariance [16]
 Bounds on randomization of referenceDistance.
int repeatCount [16]
 Number of times to loop this slot.
SFXPlayListReplayMode replay [16]
 Behavior when an already playing sound is encountered on this slot from a previous cycle.
SFXState state [16]
 State that must be active for this slot to play.
SFXPlayListStateMode stateMode [16]
 Behavior when assigned state is deactivated while slot is playing.
SFXTrack track [16]
 Track to play in this slot.
SFXPlayListTransitionMode transitionIn [16]
 Behavior when moving into this slot.
SFXPlayListTransitionMode transitionOut [16]
 Behavior when moving out of this slot.
float volumeScale [16]
 Scale factor to apply to volume of sounds played on this list slot.
Point2F volumeScaleVariance [16]
 Bounds on randomization of volumeScale.
Debug

bool trace
 Enable/disable execution tracing for this playlist (local only).

Detailed Description

A datablock describing a playback pattern of sounds.

Playlists allow to define intricate playback patterns of invidual tracks and thus allow the sound system to be easily used for playing multiple sounds in single operations.

As playlists are SFXTracks, they can thus be used anywhere in the engine where sound data can be assigned.

Each playlist can hold a maximum of 16 tracks. Longer playlists may be constructed by cascading lists, i.e. by creating a playlist that references other playlists.

Processing of a single playlist slot progresses in a fixed set of steps that are invariably iterated through for each slot (except the slot is assigned a state and its state is deactivated; in this case, the controller will exit out of the slot directly):

  1. delayIn:

    Waits a set amount of time before processing the slot. This is 0 by default and is determined by the delayTimeIn (seconds to wait) and delayTimeInVariance (bounds on randomization) properties.

  2. transitionIn:

    Decides what to do before playing the slot. Defaults to None which makes this stage a no-operation. Alternatively, the slot can be configured to wait for playback of other slots to finish (Wait and WaitAll) or to stop playback of other slots (Stop and StopAll). Note that Wait and Stop always refer to the source that was last started by the list.

  3. play:

    Finally, the track attached to the slot is played. However, this will only start playback of the track and then immediately move on to the next stage. It will not wait for the track to finish playing. Note also that depending on the replay setting for the slot, this stage may pick up a source that is already playing on the slot rather than starting a new one.

    Several slot properties (fade times, min/max distance, and volume/pitch scale) are used in this stage.

  4. delayOut:

    Waits a set amount of time before transitioning out of the slot. This works the same as delayIn and is set to 0 by default (i.e. no delay).

  5. transitionOut:

    Decides what to do after playing the slot. This works like transitionIn.

This is a key difference to playlists in normal music players where upon reaching a certain slot, the slot will immediately play and the player then wait for playback to finish before moving on to the next slot.

Note:
Be aware that time limits set on slot delays are soft limits. The sound system updates sound sources in discrete (and equally system update frequency dependent) intervals which thus determines the granularity at which time-outs can be handled.

Value Randomization

For greater variety, many of the values for individual slots may be given a randomization limit that will trigger a dynamic variance of the specified base value.

Any given field xyz that may be randomized has a corresponding field xyzVariance which is a two-dimensional vector. The first number specifies the greatest value that may be subtracted from the given base value (i.e. the xyz field) whereas the second number specifies the greatest value that may be added to the base value. Between these two limits, a random number is generated.

The default variance settings of "0 0" will thus not allow to add or subtract anything from the base value and effectively disable randomization.

Randomization is re-evaluated on each cycle through a list.

Playlists and States

A unique aspect of playlists is that they allow their playback to be tied to the changing set of active sound states. This feature enables playlists to basically connect to an extensible state machine that can be leveraged by the game code to signal a multitude of different gameplay states with the audio system then automatically reacting to state transitions.

Playlists react to states in three ways:

A simple example of how to make use of states in combination with playlists would be to set up a playlist for background music that reacts to the mood of the current gameplay situation. For example, during combat, tenser music could play than during normal exploration. To set this up, different SFXStates would represent different moods in the game and the background music playlist would have one slot set up for each such mood. By making use of volume fades and the PauseWhenDeactivated stateMode, smooth transitions between the various audio tracks can be produced.

Example:
// Create a play list from two SFXProfiles.
%playList = new SFXPlayList()
{
   // Use a looped description so the list playback will loop.
   description = AudioMusicLoop2D;

   track[ 0 ] = Profile1;
   track[ 1 ] = Profile2;
};

// Play the list.
sfxPlayOnce( %playList );

Interactive Audio


Member Data Documentation

Seconds to wait after moving into slot before transitionIn.

Bounds on randomization of delayTimeIn.

Value Randomization

Seconds to wait before moving out of slot after transitionOut.

Bounds on randomization of delayTimeOut.

Value Randomization

Seconds to fade sound in (-1 to use the track's own fadeInTime.).

See also:
SFXDescription::fadeTimeIn

Bounds on randomization of fadeInTime.

Value Randomization

Seconds to fade sound out (-1 to use the track's own fadeOutTime.).

See also:
SFXDescription::fadeTimeOut

Bounds on randomization of fadeOutTime.

Value Randomization

Behavior when description has looping enabled.

The loop mode determines whether the list will loop over a single slot or loop over all the entire list of slots being played.

See also:
SFXDescription::isLooping

maxDistance to apply to 3D sounds in this slot (<1 to use maxDistance of track's own description).

See also:
SFXDescription::maxDistance

Bounds on randomization of maxDistance.

Value Randomization

Number of slots to play.

Up to a maximum of 16, this field determines the number of slots that are taken from the list for playback. Only slots that have a valid track assigned will be considered for this.

Scale factor to apply to pitch of sounds played on this list slot.

This value will scale the actual pitch set on the track assigned to the slot, i.e. a value of 0.5 will cause the track to play at half its assigned speed.

Bounds on randomization of pitchScale.

Value Randomization

Slot playback order randomization pattern.

By setting this field to something other than "NotRandom" to order in which slots of the playlist are processed can be changed from sequential to a random pattern. This allows to to create more varied playback patterns. Defaults to "NotRandom".

referenceDistance to set for 3D sounds in this slot (<1 to use referenceDistance of track's own description).

See also:
SFXDescription::referenceDistance

Bounds on randomization of referenceDistance.

Value Randomization

Number of times to loop this slot.

Behavior when an already playing sound is encountered on this slot from a previous cycle.

Each slot can have an arbitrary number of sounds playing on it from previous cycles. This field determines how SFXController will handle these sources.

State that must be active for this slot to play.

Playlists and States

Behavior when assigned state is deactivated while slot is playing.

Playlists and States

Enable/disable execution tracing for this playlist (local only).

If this is true, SFXControllers attached to the list will automatically run in trace mode.

Track to play in this slot.

This must be set for the slot to be considered for playback. Other settings for a slot will not take effect except this field is set.

Behavior when moving into this slot.

After the delayIn time has expired (if any), this slot determines what the controller will do before actually playing the slot.

Behavior when moving out of this slot.

After the detailTimeOut has expired (if any), this slot determines what the controller will do before moving on to the next slot.

Scale factor to apply to volume of sounds played on this list slot.

This value will scale the actual volume level set on the track assigned to the slot, i.e. a value of 0.5 will cause the track to play at half-volume.

Bounds on randomization of volumeScale.

Value Randomization



Copyright © GarageGames, LLC. All Rights Reserved.