SFXPlayList Class Reference
[Sound]

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

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:

• Before a controller starts processing a slot it checks whether the slot is assigned a state. If this is the case, the controller checks whether the particular state is active. If it is not, the entire slot is skipped. If it is, the controller goes on to process the slot.
• If a controller is in one of the delay stages for a slot that has a state assigned and the state is deactivated, the controller will stop the delay and skip any of the remaining processing stages for the slot.
• Once the play stage has been processed for a slot that has a state assigned, the slot's stateMode will determine what happens with the playing sound source if the slot's state is deactivated while the sound is still playing.

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