sfxModifier.h

  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 _SFXMODIFIER_H_
 25#define _SFXMODIFIER_H_
 26
 27#ifndef _TSTREAM_H_
 28   #include "core/stream/tStream.h"
 29#endif
 30
 31
 32class SFXSource;
 33
 34
 35/// An SFXModifier modifies the properties of an SFXSource while its playback
 36/// is running.
 37class SFXModifier : public IPolled
 38{
 39   protected:
 40      
 41      /// The source that this effect works on.
 42      SFXSource* mSource;
 43      
 44      /// If true, the effect is removed from the effects stack
 45      bool mRemoveWhenDone;
 46            
 47   public:
 48   
 49      /// Create an effect that operates on "source".
 50      SFXModifier( SFXSource* source, bool removeWhenDone = false )
 51         : mSource( source ), mRemoveWhenDone(removeWhenDone) {}
 52   
 53      virtual ~SFXModifier() {}
 54};
 55
 56/// An SFXModifier that is triggered once after passing a certain playback position.
 57class SFXOneShotModifier : public SFXModifier
 58{
 59   public:
 60   
 61      typedef SFXModifier Parent;
 62      
 63   protected:
 64   
 65      /// Playback position that triggers the effect.
 66      F32 mTriggerPos;
 67      
 68      ///
 69      virtual void _onTrigger() = 0;
 70      
 71   public:
 72   
 73      /// Create an effect that triggers when playback of "source" passes "triggerPos".
 74      SFXOneShotModifier( SFXSource* source, F32 triggerPos, bool removeWhenDone = false );
 75   
 76      // IPolled.
 77      virtual bool update();
 78};
 79
 80/// An SFXModifier that is spans a certain range of playback time.
 81class SFXRangeModifier : public SFXModifier
 82{
 83   public:
 84
 85      typedef SFXModifier Parent;
 86      
 87   protected:
 88   
 89      /// If true, the effect is currently being applied to the source.
 90      bool mIsActive;
 91         
 92      /// Playback position in milliseconds when this effect becomes active.
 93      F32 mStartTime;
 94      
 95      /// Playback position in milliseconds when this effect becomes inactive.
 96      F32 mEndTime;
 97      
 98      /// Called when the play cursor passes mStartTime.
 99      /// @note There may be latency between the cursor actually passing mStartTime
100      ///   and this method being called.
101      virtual void _onStart() {}
102      
103      /// Called on each update() while the play cursor is in range.
104      virtual void _onUpdate() {}
105      
106      /// Called when the play cursor passes mEndTime.
107      /// @note There may be latency between the cursor actually passing mEndTime
108      ///   and this method being called.
109      virtual void _onEnd() {}
110      
111   public:
112   
113      /// Create an effect that operates on "source" between "startTime" seconds
114      /// (inclusive) and "endTime" seconds (exclusive).
115      SFXRangeModifier( SFXSource* source, F32 startTime, F32 endTime, bool removeWhenDone = false );
116         
117      ///
118      bool isActive() const { return mIsActive; }
119      
120      // IPolled.
121      virtual bool update();
122};
123
124/// A volume fade effect (fade-in or fade-out).
125class SFXFadeModifier : public SFXRangeModifier
126{
127   public:
128   
129      typedef SFXRangeModifier Parent;
130      
131      enum EOnEnd
132      {
133         ON_END_Nop,       ///< Do nothing with source when fade is complete.
134         ON_END_Stop,      ///< Stop source when fade is complete.
135         ON_END_Pause,     ///< Pause source when fade is complete.
136      };
137      
138   protected:
139      
140      /// Volume when beginning fade.  Set when effect is activated.
141      F32 mStartVolume;
142      
143      /// Volume when ending fade.
144      F32 mEndVolume;
145      
146      /// Current volume level.
147      F32 mCurrentVolume;
148      
149      /// Action to perform when the fade has been completed.  Defaults to no action.
150      EOnEnd mOnEnd;
151      
152      // SFXModifier.
153      virtual void _onStart();
154      virtual void _onUpdate();
155      virtual void _onEnd();
156      
157   public:
158   
159      /// Create an effect that fades the volume of "source" to "endVolume" over the
160      /// period of  "time" seconds.  The fade will start at "referenceTime" using the
161      /// source's current volume at the time as the start.
162      SFXFadeModifier( SFXSource* source, F32 time, F32 endVolume, F32 startTime, EOnEnd onEndDo = ON_END_Nop, bool removeWhenDone = false );
163      
164      virtual ~SFXFadeModifier();
165};
166
167/// A modifer that calls a method on the SFXSource when a particular playback position
168/// is passed.
169///
170/// @note At the moment, doing a setPosition() on a source will not cause markers that have
171///   been jumped over in the operation to be ignored.  Instead they will trigger on the
172///   next update.
173class SFXMarkerModifier : public SFXOneShotModifier
174{
175   public:
176   
177      typedef SFXOneShotModifier Parent;
178      
179   protected:
180   
181      /// Symbolic marker name that is passed to the "onMarkerPassed" callback.
182      String mMarkerName;
183      
184      // SFXOneShotModifier
185      virtual void _onTrigger();
186   
187   public:
188   
189      SFXMarkerModifier( SFXSource* source, const String& name, F32 pos, bool removeWhenDone = false );
190};
191
192#endif // !_SFXMODIFIER_H_
193