sfxSoundscape.h

Engine/source/sfx/sfxSoundscape.h

The soundscape system is responsible for controlling ambient audio.

More...

Classes:

Detailed Description

The soundscape system is responsible for controlling ambient audio.

It is largely driven by SFXWorld's listener tracking.

  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 _SFXSOUNDSCAPE_H_
 25#define _SFXSOUNDSCAPE_H_
 26
 27#ifndef _SFXCOMMON_H_
 28#include "sfx/sfxCommon.h"
 29#endif
 30
 31#ifndef _TVECTOR_H_
 32#include "core/util/tVector.h"
 33#endif
 34
 35#ifndef _DATACHUNKER_H_
 36#include "core/dataChunker.h"
 37#endif
 38
 39#ifndef _BITSET_H_
 40#include "core/bitSet.h"
 41#endif
 42
 43#ifndef _TRESPONSECURVE_H_
 44#include "math/util/tResponseCurve.h"
 45#endif
 46
 47#ifndef _SFXAMBIENCE_H_
 48#include "sfx/sfxAmbience.h"
 49#endif
 50
 51
 52/// @file
 53/// The soundscape system is responsible for controlling ambient audio.
 54/// It is largely driven by SFXWorld's listener tracking.
 55
 56
 57class SFXSource;
 58
 59
 60
 61
 62/// An instance of an SFXAmbience on the soundscape mixer stack.
 63///
 64class SFXSoundscape
 65{
 66   public:
 67   
 68      typedef void Parent;
 69      friend class SFXSoundscapeManager;
 70      
 71      enum Flags
 72      {
 73         FlagOverridden    = BIT( 0 ),    ///< Same ambience is pushed lower down onto the stack.
 74         FlagUnique        = BIT( 1 ),    ///< No other instance of this ambience on stack.
 75      };
 76      
 77      enum DirtyBits : U32
 78      {
 79         AmbienceDirty = BIT( 0 ),        ///< Associated ambience has changed.
 80         AllDirty = 0xFFFFFFFF
 81      };
 82      
 83   protected:
 84   
 85      ///
 86      BitSet32 mFlags;
 87   
 88      ///
 89      BitSet32 mDirtyBits;
 90
 91      /// The current soundtrack playing in this soundscape.  This is either the
 92      /// ambient track or the surround sound track depending on whether
 93      SimObjectPtr< SFXSource> mSource;
 94      
 95      /// The ambient space assigned to this soundscape.
 96      SFXAmbience* mAmbience;
 97      
 98      /// States activated by this soundscape.
 99      SFXState* mStates[ SFXAmbience::MaxStates ];
100      
101      /// Return true if another soundscape lower down the stack is using the same
102      /// ambient space as this soundscape.
103      bool _isOverridden() const { return mFlags.test( FlagOverridden ); }
104      
105      /// Return true if this soundscape is the only soundscape using the assigned
106      /// ambient space.
107      bool _isUnique() const { return mFlags.test( FlagUnique ); }
108
109   public:
110   
111      /// Create a soundscape associated with the given ambient space.
112      SFXSoundscape( SFXAmbience* ambience );
113
114      /// Return the ambient space associated with this soundscape.
115      SFXAmbience* getAmbience() const { return mAmbience; }
116      
117      /// Set the ambient space associated with this soundscape.  Triggers corresponding
118      /// recomputations on the next soundscape manager update.
119      void setAmbience( SFXAmbience* ambience );
120};
121
122
123/// The soundscape manager produces a dynamic mix between multiple active soundscapes.
124///
125/// @note The more layered soundscapes there are, the costlier ambient sound updates will get.
126///
127class SFXSoundscapeManager
128{
129   public:
130   
131      typedef void Parent;
132      
133   protected:
134
135      /// Linear stack of soundscapes.  Evaluated bottom to top.  Scapes
136      /// being faded out are always last on the stack.
137      Vector< SFXSoundscape*> mStack;
138      
139      /// Stack of soundscape that are currently being faded out.  These are
140      /// kept around so that when their ambient spaces are activated again,
141      /// they can be brought back with their fades simply being reversed.
142      ///
143      /// All soundscapes on this stack are unique.
144      Vector< SFXSoundscape*> mFadeStack;
145
146      /// Index into #mStack for the soundscape that defines the current
147      /// reverb settings.  -1 if no current ambience has reverb settings.
148      S32 mCurrentReverbIndex;
149
150      /// Memory manager of soundscape instances.
151      FreeListChunker< SFXSoundscape> mChunker;
152      
153      /// Default global SFXAmbience.  Not a registered object.
154      SFXAmbience* mDefaultGlobalAmbience;
155      
156      /// Found the topmost instance on the given stack associated with the given
157      /// ambient space.
158      S32 _findOnStack( SFXAmbience* ambience, const Vector< SFXSoundscape*>& stack );
159      
160      /// Find the topmost soundscape on the given stack that has a reverb environment
161      /// defined on its ambient space.
162      S32 _findTopmostReverbOnStack( const Vector< SFXSoundscape*>& stack );
163      
164      /// Method hooked up to the SFXAmbience change signal to automatically
165      /// make soundscapes using the given ambience as dirty and trigger
166      /// a recomputation of their properties.
167      void _notifyAmbienceChanged( SFXAmbience* ambience );
168
169   public:
170   
171      ///
172      SFXSoundscapeManager();
173      
174      ///
175      ~SFXSoundscapeManager();
176   
177      /// Update the current soundscape mix.
178      void update();
179      
180      /// Return the total number of soundscape instances currently on the stack.
181      /// Always >=1.
182      U32 getNumTotalSoundscapes() const { return mStack.size(); }
183   
184      /// Insert a new soundscape instance associated with the given ambient space
185      /// at the given stack index.
186      SFXSoundscape* insertSoundscape( U32 index, SFXAmbience* ambience );
187      
188      /// Remove the given soundscape from the stack.
189      void removeSoundscape( SFXSoundscape* soundscape );
190      
191      /// Return the topmost soundscape.  This soundscape is always defined and cannot
192      /// be removed.
193      SFXSoundscape* getGlobalSoundscape() const { return mStack[ 0 ]; }
194};
195
196#endif // !_SFXSOUNDSCAPE_H_
197