SFXPlayList
Engine/source/sfx/sfxPlayList.h
A playback list of SFXTracks.
Classes:
Settings for the playback slots.
Public Types
_Anonymous_ { NUM_SLOTS = 12 NUM_TRANSITION_MODE_BITS = 3 NUM_LOOP_MODE_BITS = 1 NUM_RANDOM_MODE_BITS = 2 NUM_SLOTS_TO_PLAY_BITS = 5 NUM_REPLAY_MODE_BITS = 3 NUM_STATE_MODE_BITS = 2 }
ELoopMode { LOOP_All LOOP_Single }
Behavior when description is set to loop.
ERandomMode { RANDOM_NotRandom RANDOM_StrictRandom RANDOM_OrderedRandom }
Random playback mode.
EReplayMode { REPLAY_IgnorePlaying REPLAY_RestartPlaying REPLAY_KeepPlaying REPLAY_StartNew REPLAY_SkipIfPlaying }
Behavior when hitting play() on a slot that is still playing from a previous cycle.
EStateMode { STATE_StopInactive STATE_PauseInactive STATE_IgnoreInactive }
State-reaction behavior of slot once a source has started playing.
ETransitionMode { TRANSITION_None TRANSITION_Wait TRANSITION_WaitAll TRANSITION_Stop TRANSITION_StopAll }
Transitioning behavior when moving in and out of slots.
Parent
Protected Attributes
Number of slots to play from list.
Select slots at random.
bool
Trace interpreter execution. This field is not networked.
Public Functions
DECLARE_CATEGORY("SFX" )
DECLARE_DESCRIPTION("A playback list of SFXProfiles or nested SFXPlayLists." )
Return the loop mode (only relevant if this is a looped playlist).
Return the total number of slots in the list.
Return the number of slots to play from this list in a single cycle.
Return the slot order randomization behavior.
Called after any property of the object is changed in the world editor.
bool
bool
trace()
Return true if execution tracing is enabled on this list.
unpackData(BitStream * stream)
Public Static Functions
Detailed Description
A playback list of SFXTracks.
Note that since SFXPlayLists are SFXTracks, play lists can be cascaded.
Play lists are comprised of a sequence of slots. Each slot can be assigned a track (SFXProfile or another SFXPlayList) as well as a number of options that determine how the particular slot should behave.
In addition to playing a track, each slot can do an arbitrary combination of the following operations:
Wait: wait for the previous or all sources to stop playing
Stop: stop the previous or all sources from playing
Delay: wait some (optionally randomized) amount of time
Shift Pitch: scale pitch when playing by optionally randomized amount
Shift Volume: scale volume when playing by optionally randomized amount
Fade: perform volume fade-in/out
Distance: only start playing track when listener is within a certain range
Loop: loop a set number of times
State: play only when the given SFXState is active; transitions out of slot when state is deactivated
The order in which slots are played is either sequential (NotRandom), or a random selection (StrictRandom), or a random ordering (OrderedRandom).
Additionally, the list may be looped over in entirety (All) or looped on single slots (useful for either manual playback control or lists that exclusively use states).
Be aware that playlists are affected by SFXDescriptions the same way that an SFXProfile is, i.e. fades, looping, 3D sound, etc. all take effect.
note:Playlists offer a lot of control but unfortunately they also make it pretty easy at the moment to shoot yourself in the foot.
Public Types
@171
Enumerator
- NUM_SLOTS = 12
Number of slots in a playlist.
@note To have longer playlists, simply cascade playlists and use wait behaviors.- NUM_TRANSITION_MODE_BITS = 3
- NUM_LOOP_MODE_BITS = 1
- NUM_RANDOM_MODE_BITS = 2
- NUM_SLOTS_TO_PLAY_BITS = 5
- NUM_REPLAY_MODE_BITS = 3
- NUM_STATE_MODE_BITS = 2
ELoopMode
Enumerator
- LOOP_All
Start over after completing a cycle.
- LOOP_Single
Loop a single slot over and over.
@note This behavior is only useful in combination with states or manual playback control. To just loop over a slot for some time, set its loop count instead.
Behavior when description is set to loop.
ERandomMode
Enumerator
- RANDOM_NotRandom
No randomization of playback order.
- RANDOM_StrictRandom
Playback order that jumps to a random slot after completing a given slot.
The slot being jumped to, however, may be any slot in the list including the slot that has just played.
note:
In order to ensure cycles are always finite, this mode will also just do NUM_SLOTS number of transitions and then stop the current cycle whether all slots have played or not. Otherwise, it would be dependent on the random number sequence generated when and whether at all a given cycle finishes.
- RANDOM_OrderedRandom
Before a cycle over the playlist starts, a random total ordering of the slots is established and then played.
No slot will be played twice in a single cycle.
Random playback mode.
EReplayMode
Enumerator
- REPLAY_IgnorePlaying
Do not check if a source is already playing on the slot.
- REPLAY_RestartPlaying
Stop the currently playing source and start playing it from the beginning.
- REPLAY_KeepPlaying
Move the currently playing source to the top of the stack and pretend it was started by this cycle.
When using STATE_PauseInactive, it is usally best to also use REPLAY_KeepPlaying as otherwise a new source will be spawned when the state becomes active again.
note:
When the currently playing source is paused, KeepPlaying will resume playback.
- REPLAY_StartNew
Let the old source play and start a new one on the same slot.
- REPLAY_SkipIfPlaying
If there is a source currently playing on this slot, skip the play() stage.
Behavior when hitting play() on a slot that is still playing from a previous cycle.
EStateMode
Enumerator
- STATE_StopInactive
Stop and remove source when state becomes inactive.
- STATE_PauseInactive
Pause source when state becomes inactive and resume playback when state becomes active again.
- STATE_IgnoreInactive
Once a source has started to play, it will not be stopped due to state changes.
A source will, however, still be prevented from starting to play when its assigned state is not active.
State-reaction behavior of slot once a source has started playing.
ETransitionMode
Enumerator
- TRANSITION_None
No specific behavior for transitioning between slots.
- TRANSITION_Wait
Wait for single slot to stop playing.
If transitioning into slot, this is the slot being transitioned from. If transitioning out of slot, this is the current slot.
- TRANSITION_WaitAll
Wait for all slots to stop playing.
- TRANSITION_Stop
Stop single slot before proceeding.
If transitioning into slot, this is the slot being transitioned from. If transitioning out of slot, this is the current slot.
- TRANSITION_StopAll
Stop all playing slots before proceeding.
Transitioning behavior when moving in and out of slots.
typedef SFXTrack Parent
Protected Attributes
ELoopMode mLoopMode
Loop over slots in this list.
U32 mNumSlotsToPlay
Number of slots to play from list.
This can be used, for example, to create a list of tracks where only a single track is selected and played for each cycle.
ERandomMode mRandomMode
Select slots at random.
SlotData mSlots
Data for each of the playlist slots.
bool mTrace
Trace interpreter execution. This field is not networked.
Public Functions
SFXPlayList()
DECLARE_CATEGORY("SFX" )
DECLARE_CONOBJECT(SFXPlayList )
DECLARE_DESCRIPTION("A playback list of SFXProfiles or nested SFXPlayLists." )
getLoopMode()
Return the loop mode (only relevant if this is a looped playlist).
getNumSlots()
Return the total number of slots in the list.
getNumSlotsToPlay()
Return the number of slots to play from this list in a single cycle.
getRandomMode()
Return the slot order randomization behavior.
getSlots()
Return the slot data for this list.
inspectPostApply()
Reimplemented from: SFXTrack
packData(BitStream * stream)
Reimplemented from: SFXTrack
preload(bool server, String & errorStr)
Reimplemented from: SFXTrack
trace()
Return true if execution tracing is enabled on this list.
unpackData(BitStream * stream)
Reimplemented from: SFXTrack
validate()
Make all settings conform to constraints.