sfxPlayList.h

Public Functions

DefineEnumType(SFXPlayListLoopMode )

DefineEnumType(SFXPlayListRandomMode )

DefineEnumType(SFXPlayListReplayMode )

DefineEnumType(SFXPlayListStateMode )

DefineEnumType(SFXPlayListTransitionMode )

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _SFXPLAYLIST_H_
 25#define _SFXPLAYLIST_H_
 26
 27#ifndef _SFXCOMMON_H_
 28   #include "sfx/sfxCommon.h"
 29#endif
 30#ifndef _SFXTRACK_H_
 31   #include "sfx/sfxTrack.h"
 32#endif
 33
 34
 35class SFXState;
 36
 37
 38/// A playback list of SFXTracks.
 39///
 40/// Note that since SFXPlayLists are SFXTracks, play lists can be cascaded.
 41///
 42/// Play lists are comprised of a sequence of slots.  Each slot can be assigned
 43/// a track (SFXProfile or another SFXPlayList) as well as a number of options
 44/// that determine how the particular slot should behave.
 45///
 46/// In addition to playing a track, each slot can do an arbitrary combination
 47/// of the following operations:
 48///
 49/// - Wait: wait for the previous or all sources to stop playing
 50/// - Stop: stop the previous or all sources from playing
 51/// - Delay: wait some (optionally randomized) amount of time
 52/// - Shift Pitch: scale pitch when playing by optionally randomized amount
 53/// - Shift Volume: scale volume when playing by optionally randomized amount
 54/// - Fade: perform volume fade-in/out
 55/// - Distance: only start playing track when listener is within a certain range
 56/// - Loop: loop a set number of times
 57/// - State: play only when the given SFXState is active; transitions out of
 58///      slot when state is deactivated
 59///
 60/// The order in which slots are played is either sequential (NotRandom),
 61/// or a random selection (StrictRandom), or a random ordering (OrderedRandom).
 62///
 63/// Additionally, the list may be looped over in entirety (All) or looped
 64/// on single slots (useful for either manual playback control or lists that
 65/// exclusively use states).
 66///
 67/// Be aware that playlists are affected by SFXDescriptions the same way that an
 68/// SFXProfile is, i.e. fades, looping, 3D sound, etc. all take effect.
 69///
 70/// @note Playlists offer a lot of control but unfortunately they also make it
 71///   pretty easy at the moment to shoot yourself in the foot.
 72///
 73class SFXPlayList : public SFXTrack
 74{
 75   public:
 76   
 77      typedef SFXTrack Parent;
 78      
 79      enum
 80      {
 81         /// Number of slots in a playlist.
 82         ///
 83         /// @note To have longer playlists, simply cascade playlists and use
 84         ///   wait behaviors.
 85         NUM_SLOTS = 12, // AFX (was 16)
 86         
 87         NUM_TRANSITION_MODE_BITS = 3,
 88         NUM_LOOP_MODE_BITS = 1,
 89         NUM_RANDOM_MODE_BITS = 2,
 90         NUM_SLOTS_TO_PLAY_BITS = 5,
 91         NUM_REPLAY_MODE_BITS = 3,
 92         NUM_STATE_MODE_BITS = 2,
 93      };
 94      
 95      /// Behavior when description is set to loop.
 96      enum ELoopMode
 97      {
 98         /// Start over after completing a cycle.
 99         LOOP_All,
100
101         /// Loop a single slot over and over.
102         ///
103         /// @note This behavior is only useful in combination with states or manual
104         ///   playback control.  To just loop over a slot for some time, set its loop
105         ///   count instead.
106         LOOP_Single,
107      };
108      
109      /// Random playback mode.
110      enum ERandomMode
111      {
112         /// No randomization of playback order.
113         RANDOM_NotRandom,
114         
115         /// Playback order that jumps to a random slot after completing
116         /// a given slot.  The slot being jumped to, however, may be any
117         /// slot in the list including the slot that has just played.
118         ///
119         /// @note In order to ensure cycles are always finite, this mode will
120         ///   also just do NUM_SLOTS number of transitions and then stop the
121         ///   current cycle whether all slots have played or not.  Otherwise,
122         ///   it would be dependent on the random number sequence generated when
123         ///   and whether at all a given cycle finishes.
124         RANDOM_StrictRandom,
125         
126         /// Before a cycle over the playlist starts, a random total ordering of
127         /// the slots is established and then played.  No slot will be played
128         /// twice in a single cycle.
129         RANDOM_OrderedRandom,
130      };
131        
132      /// Transitioning behavior when moving in and out of slots.
133      enum ETransitionMode
134      {
135         /// No specific behavior for transitioning between slots.
136         TRANSITION_None,
137
138         /// Wait for single slot to stop playing.  If transitioning into slot,
139         /// this is the slot being transitioned from.  If transitioning out of slot,
140         /// this is the current slot. 
141         TRANSITION_Wait,
142         
143         /// Wait for all slots to stop playing.
144         TRANSITION_WaitAll,
145
146         /// Stop single slot before proceeding.  If transitioning into slot, this
147         /// is the slot being transitioned from.  If transitioning out of slot,
148         /// this is the current slot.
149         TRANSITION_Stop,
150         
151         /// Stop all playing slots before proceeding.
152         TRANSITION_StopAll,
153      };
154      
155      /// Behavior when hitting play() on a slot that is still playing from
156      /// a previous cycle.
157      enum EReplayMode
158      {
159         /// Do not check if a source is already playing on the slot.
160         REPLAY_IgnorePlaying,
161         
162         /// Stop the currently playing source and start playing it from the
163         /// beginning.
164         REPLAY_RestartPlaying,
165         
166         /// Move the currently playing source to the top of the stack and pretend
167         /// it was started by this cycle.
168         ///
169         /// When using STATE_PauseInactive, it is usally best to also use REPLAY_KeepPlaying
170         /// as otherwise a new source will be spawned when the state becomes active again.
171         ///
172         /// @note When the currently playing source is paused, KeepPlaying will
173         ///   resume playback.
174         REPLAY_KeepPlaying,
175         
176         /// Let the old source play and start a new one on the same slot.
177         REPLAY_StartNew,
178
179         /// If there is a source currently playing on this slot, skip the play() stage.
180         REPLAY_SkipIfPlaying,
181      };
182      
183      /// State-reaction behavior of slot once a source has started playing.
184      enum EStateMode
185      {
186         /// Stop and remove source when state becomes inactive.
187         STATE_StopInactive,
188         
189         /// Pause source when state becomes inactive and resume playback
190         /// when state becomes active again.
191         STATE_PauseInactive,
192         
193         /// Once a source has started to play, it will not be stopped due to
194         /// state changes.  A source will, however, still be prevented from starting
195         /// to play when its assigned state is not active.
196         STATE_IgnoreInactive,
197      };
198            
199      // All structures here are laid out as structures of arrays instead of arrays of structures
200      // to allow them to be used as fixed-size TorqueScript arrays.
201
202      struct VariantFloat : SFXVariantFloat< NUM_SLOTS >
203      {
204         VariantFloat()
205         {
206            dMemset( mValue, 0, sizeof( mValue ) );
207            dMemset( mVariance, 0, sizeof( mVariance ) );
208         }
209      };
210      
211      /// Settings for the playback slots.
212      struct SlotData
213      {
214         /// Behavior when a sound is already playing on a slot from a previous cycle.
215         EReplayMode mReplayMode[ NUM_SLOTS ];
216         
217         /// Behavior when transitioning into the slot.
218         ETransitionMode mTransitionIn[ NUM_SLOTS ];
219         
220         /// Behavior when transitioning out of the slot.
221         ETransitionMode mTransitionOut[ NUM_SLOTS ];
222         
223         /// Seconds to fade sound in.  -1 to leave at default.
224         VariantFloat mFadeTimeIn;
225         
226         /// Seconds to fade sound out.  -1 to leave at default.
227         VariantFloat mFadeTimeOut;
228         
229         /// Time to delay before mTransitionIn.
230         VariantFloat mDelayTimeIn;
231         
232         /// Time to delay before mTransitionOut.
233         VariantFloat mDelayTimeOut;
234         
235         /// Volume scale factor.
236         VariantFloat mVolumeScale;
237         
238         /// Pitch scale factor.
239         VariantFloat mPitchScale;
240         
241         /// Min distance for 3D sounds.
242         VariantFloat mMinDistance;
243         
244         /// Max distance for 3D sounds.
245         VariantFloat mMaxDistance;
246                  
247         /// Number of times to loop over this slot.
248         /// @note Each iteration will do a full transition as if proceeding
249         ///   to a different slot.
250         U32 mRepeatCount[ NUM_SLOTS ];
251         
252         /// State restriction for this slot.  Slot will only play when the given
253         /// state is active and will be automatically transitioned from
254         /// if the state becomes inactive.
255         SFXState* mState[ NUM_SLOTS ];
256         
257         /// Bahavior when state of this slot is deactivated and the slot's track
258         /// is playing.
259         EStateMode mStateMode[ NUM_SLOTS ];
260         
261         /// Track to play in this slot.
262         SFXTrack* mTrack[ NUM_SLOTS ];
263         
264         SlotData()
265         {
266            dMemset( mReplayMode, 0, sizeof( mReplayMode ) );
267            dMemset( mTransitionIn, 0, sizeof( mTransitionIn ) );
268            dMemset( mTransitionOut, 0, sizeof( mTransitionOut ) );
269            dMemset( mRepeatCount, 0, sizeof( mRepeatCount ) );
270            dMemset( mState, 0, sizeof( mState ) );
271            dMemset( mTrack, 0, sizeof( mTrack ) );
272            dMemset( mStateMode, 0, sizeof( mStateMode ) );
273            
274            for( U32 i = 0; i < NUM_SLOTS; ++ i )
275            {
276               mTransitionOut[ i ]        = TRANSITION_Wait;
277               mVolumeScale.mValue[ i ]   = 1.f;
278               mPitchScale.mValue[ i ]    = 1.f;
279               mFadeTimeIn.mValue[ i ]    = -1.f;  // Don't touch by default.
280               mFadeTimeOut.mValue[ i ]   = -1.f;  // Don't touch by default.
281               mMinDistance.mValue[ i ]   = -1.f;  // Don't touch by default.
282               mMaxDistance.mValue[ i ]   = -1.f;  // Don't touch by default.
283            }
284         }
285      };
286                        
287   protected:
288   
289      /// Trace interpreter execution.  This field is not networked.
290      bool mTrace;
291   
292      /// Select slots at random.
293      ERandomMode mRandomMode;
294         
295      /// Loop over slots in this list.
296      ELoopMode mLoopMode;
297      
298      /// Number of slots to play from list.  This can be used, for example,
299      /// to create a list of tracks where only a single track is selected and
300      /// played for each cycle.
301      U32 mNumSlotsToPlay;
302      
303      /// Data for each of the playlist slots.
304      SlotData mSlots;
305               
306   public:
307   
308      SFXPlayList();
309      
310      /// Make all settings conform to constraints.
311      void validate();
312      
313      /// Return true if execution tracing is enabled on this list.
314      bool trace() const { return mTrace; }
315      
316      /// Return the number of slots to play from this list in a single cycle.
317      U32 getNumSlotsToPlay() const { return mNumSlotsToPlay; }
318      
319      /// Return the slot order randomization behavior.
320      ERandomMode getRandomMode() const { return mRandomMode; }
321      
322      /// Return the loop mode (only relevant if this is a looped playlist).
323      ELoopMode getLoopMode() const { return mLoopMode; }
324      
325      /// Return the total number of slots in the list.
326      U32 getNumSlots() const { return NUM_SLOTS; }
327      
328      /// Return the slot data for this list.
329      const SlotData& getSlots() const { return mSlots; }
330                  
331      DECLARE_CONOBJECT( SFXPlayList );
332      DECLARE_CATEGORY( "SFX" );
333      DECLARE_DESCRIPTION( "A playback list of SFXProfiles or nested SFXPlayLists." );
334      
335      // SimDataBlock.
336      virtual bool preload( bool server, String& errorStr );
337      virtual void packData( BitStream* stream );
338      virtual void unpackData( BitStream* stream );
339      virtual void inspectPostApply();
340      
341      static void initPersistFields();
342};
343
344
345typedef SFXPlayList::ELoopMode SFXPlayListLoopMode;
346typedef SFXPlayList::ETransitionMode SFXPlayListTransitionMode;
347typedef SFXPlayList::EStateMode SFXPlayListStateMode;
348typedef SFXPlayList::ERandomMode SFXPlayListRandomMode;
349typedef SFXPlayList::EReplayMode SFXPlayListReplayMode;
350
351DefineEnumType( SFXPlayListLoopMode );
352DefineEnumType( SFXPlayListTransitionMode );
353DefineEnumType( SFXPlayListStateMode );
354DefineEnumType( SFXPlayListRandomMode );
355DefineEnumType( SFXPlayListReplayMode );
356
357#endif // _SFXPLAYLIST_H_
358