sfxCommon.h

Public Functions

DefineEnumType(SFXChannel )

DefineEnumType(SFXDistanceModel )

DefineEnumType(SFXStatus )

SFXDistanceAttenuation(SFXDistanceModel model, F32 minDistance, F32 maxDistance, F32 distance, F32 volume, F32 rolloffFactor)

Compute the distance attenuation based on the given distance model.

Parameters:

SFXStatusToString(SFXStatus status)

  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 _SFXCOMMON_H_
 25#define _SFXCOMMON_H_
 26
 27#ifndef _PLATFORM_H_
 28   #include "platform/platform.h"
 29#endif
 30#ifndef _MMATHFN_H_
 31   #include "math/mMathFn.h"
 32#endif
 33#ifndef _MRANDOM_H_
 34   #include "math/mRandom.h"
 35#endif
 36#ifndef _MMATRIX_H_
 37   #include "math/mMatrix.h"
 38#endif
 39#ifndef _MPOINT3_H_
 40   #include "math/mPoint3.h"
 41#endif
 42#ifndef _TYPETRAITS_H_
 43   #include "platform/typetraits.h"
 44#endif
 45#ifndef _DYNAMIC_CONSOLETYPES_H_
 46   #include "console/dynamicTypes.h"
 47#endif
 48
 49
 50
 51class SFXEnvironment;
 52class SFXPlayList;
 53
 54
 55//-----------------------------------------------------------------------------
 56//    SFXStatus.
 57//-----------------------------------------------------------------------------
 58
 59
 60/// The sound playback state.
 61enum SFXStatus 
 62{
 63   /// Initial state; no operation yet performed on sound.
 64   SFXStatusNull,
 65
 66   /// Sound is playing.
 67   SFXStatusPlaying,
 68
 69   /// Sound has been stopped.
 70   SFXStatusStopped,
 71
 72   /// Sound is paused.
 73   SFXStatusPaused,
 74
 75   /// Sound stream is starved and playback blocked.
 76   SFXStatusBlocked,
 77
 78   /// Temporary state while transitioning to another state.  This is used when multiple
 79   /// threads concurrently maintain a status and need to perform a sequence of actions before
 80   /// being able to fully go from a previous to a new current state.  In this case, the
 81   /// transition state marks the status as being under update on another thread.
 82   ///
 83   /// @note Not all places that use SFXStatus actually use this state.
 84   SFXStatusTransition,
 85};
 86
 87DefineEnumType( SFXStatus );
 88
 89
 90inline const char* SFXStatusToString( SFXStatus status )
 91{
 92   switch ( status )
 93   {
 94      case SFXStatusPlaying:     return "playing";
 95      case SFXStatusStopped:     return "stopped";
 96      case SFXStatusPaused:      return "paused";
 97      case SFXStatusBlocked:     return "blocked";
 98      case SFXStatusTransition:  return "transition";
 99      
100      case SFXStatusNull:
101      default: ;
102   }
103   
104   return "null";
105}
106
107
108//-----------------------------------------------------------------------------
109//    SFXChannel.
110//-----------------------------------------------------------------------------
111
112
113/// Animatable channels in the SFX system.
114enum SFXChannel
115{
116   SFXChannelVolume,
117   SFXChannelPitch,
118   SFXChannelPriority,
119   SFXChannelPositionX,
120   SFXChannelPositionY,
121   SFXChannelPositionZ,
122   SFXChannelRotationX,
123   SFXChannelRotationY,
124   SFXChannelRotationZ,
125   SFXChannelVelocityX,
126   SFXChannelVelocityY,
127   SFXChannelVelocityZ,
128   SFXChannelMinDistance,
129   SFXChannelMaxDistance,
130   SFXChannelConeInsideAngle,
131   SFXChannelConeOutsideAngle,
132   SFXChannelConeOutsideVolume,
133   SFXChannelCursor,
134   SFXChannelStatus,
135   SFXChannelUser0,
136   SFXChannelUser1,
137   SFXChannelUser2,
138   SFXChannelUser3,
139   
140   /// Total number of animatable channels.
141   SFX_NUM_CHANNELS
142};
143
144DefineEnumType( SFXChannel );
145
146
147//-----------------------------------------------------------------------------
148//    SFXDistanceModel.
149//-----------------------------------------------------------------------------
150
151
152/// Rolloff curve used for distance volume attenuation of 3D sounds.
153enum SFXDistanceModel
154{
155   SFXDistanceModelLinear,             ///< Volume decreases linearly from min to max where it reaches zero.
156   SFXDistanceModelLogarithmic,        ///< Volume halves every min distance steps starting from min distance; attenuation stops at max distance.
157   SFXDistanceModelExponent,           /// exponential falloff for distance attenuation.
158};
159
160DefineEnumType( SFXDistanceModel );
161
162/// Compute the distance attenuation based on the given distance model.
163///
164/// @param minDistance Reference distance; attenuation starts here.
165/// @param maxDistance
166/// @param distance Actual distance of sound from listener.
167/// @param volume Unattenuated volume.
168/// @param rolloffFactor Rolloff curve scale factor.
169///
170/// @return The attenuated volume.
171inline F32 SFXDistanceAttenuation( SFXDistanceModel model, F32 minDistance, F32 maxDistance, F32 distance, F32 volume, F32 rolloffFactor )
172{
173   F32 gain = 1.0f;
174      
175   switch( model )
176   {
177      case SFXDistanceModelLinear:
178      
179         distance = getMax( distance, minDistance );
180         distance = getMin( distance, maxDistance );
181         
182         gain = ( 1 - ( distance - minDistance ) / ( maxDistance - minDistance ) );
183         break;
184                  
185      case SFXDistanceModelLogarithmic:
186      
187         distance = getMax( distance, minDistance );
188         distance = getMin( distance, maxDistance );
189         
190         gain = minDistance / ( minDistance + rolloffFactor * ( distance - minDistance ) );
191         break;
192
193         ///create exponential distance model    
194      case SFXDistanceModelExponent:
195         distance = getMax(distance, minDistance);
196         distance = getMin(distance, maxDistance);
197
198         gain = pow((distance / minDistance), (-rolloffFactor));
199         break;
200         
201   }
202   
203   return ( volume * gain );
204}
205
206
207//-----------------------------------------------------------------------------
208//    SFXFormat.
209//-----------------------------------------------------------------------------
210
211
212/// This class defines the various types of sound data that may be
213/// used in the sound system.
214///
215/// Unlike with most sound APIs, we consider each sample point to comprise
216/// all channels in a sound stream rather than only one value for a single
217/// channel.
218class SFXFormat
219{
220   protected:
221
222      /// The number of sound channels in the data.
223      U8 mChannels;
224
225      /// The number of bits per sound sample.
226      U8 mBitsPerSample;
227
228      /// The frequency in samples per second.
229      U32 mSamplesPerSecond;
230
231   public:
232
233      SFXFormat(  U8 channels = 0,                  
234                  U8 bitsPerSample = 0,
235                  U32 samplesPerSecond = 0 )
236         :  mChannels( channels ),
237            mBitsPerSample( bitsPerSample ),
238            mSamplesPerSecond( samplesPerSecond )
239      {}
240
241      /// Copy constructor.
242      SFXFormat( const SFXFormat &format )
243         :  mChannels( format.mChannels ),
244            mBitsPerSample( format.mBitsPerSample ),
245            mSamplesPerSecond( format.mSamplesPerSecond )
246      {}
247
248   public:
249
250      /// Sets the format.
251      void set(   U8 channels,                  
252                  U8 bitsPerSample,
253                  U32 samplesPerSecond )
254      {
255         mChannels = channels;
256         mBitsPerSample = bitsPerSample;
257         mSamplesPerSecond = samplesPerSecond;
258      }
259
260      /// Comparision between formats.
261      bool operator ==( const SFXFormat& format ) const 
262      { 
263         return   mChannels == format.mChannels && 
264                  mBitsPerSample == format.mBitsPerSample &&
265                  mSamplesPerSecond == format.mSamplesPerSecond;
266      }
267
268      /// Returns the number of sound channels.
269      U8 getChannels() const { return mChannels; }
270
271      /// Returns true if there is a single sound channel.
272      bool isMono() const { return mChannels == 1; }
273
274      /// Is true if there are two sound channels.
275      bool isStereo() const { return mChannels == 2; }
276
277      /// Is true if there are more than two sound channels.
278      bool isMultiChannel() const { return mChannels > 2; }
279
280      /// 
281      U32 getSamplesPerSecond() const { return mSamplesPerSecond; }
282
283      /// The bits of data per channel.
284      U8 getBitsPerChannel() const { return mBitsPerSample / mChannels; }
285
286      /// The number of bytes of data per channel.
287      U8 getBytesPerChannel() const { return getBitsPerChannel() / 8; }
288
289      /// The number of bits per sound sample.
290      U8 getBitsPerSample() const { return mBitsPerSample; }
291
292      /// The number of bytes of data per sample.
293      /// @note Be aware that this comprises all channels.
294      U8 getBytesPerSample() const { return mBitsPerSample / 8; }
295
296      /// Returns the duration from the sample count.
297      U32 getDuration( U32 samples ) const
298      {
299         // Use 64bit types to avoid overflow during division. 
300         return ( (U64)samples * (U64)1000 ) / (U64)mSamplesPerSecond;
301      }
302
303      ///
304      U32 getSampleCount( U32 ms ) const
305      {
306         return U64( mSamplesPerSecond ) * U64( ms ) / U64( 1000 );
307      }
308
309      /// Returns the data length in bytes.
310      U32 getDataLength( U32 ms ) const
311      {
312         U32 bytes = ( ( (U64)ms * (U64)mSamplesPerSecond ) * (U64)getBytesPerSample() ) / (U64)1000;
313         return bytes;
314      }
315};
316
317
318//-----------------------------------------------------------------------------
319//    SFXReverb.
320//-----------------------------------------------------------------------------
321
322
323/// Reverb environment properties.
324///
325/// @note A given device may not implement all properties.
326///restructure our reverbproperties to match openal
327
328class SFXReverbProperties
329{
330public:
331
332   struct Parent;
333
334   float flDensity;
335   float flDiffusion;
336   float flGain;
337   float flGainHF;
338   float flGainLF;
339   float flDecayTime;
340   float flDecayHFRatio;
341   float flDecayLFRatio;
342   float flReflectionsGain;
343   float flReflectionsDelay;
344   float flReflectionsPan[3];
345   float flLateReverbGain;
346   float flLateReverbDelay;
347   float flLateReverbPan[3];
348   float flEchoTime;
349   float flEchoDepth;
350   float flModulationTime;
351   float flModulationDepth;
352   float flAirAbsorptionGainHF;
353   float flHFReference;
354   float flLFReference;
355   float flRoomRolloffFactor;
356   int   iDecayHFLimit;
357
358   ///set our defaults to be the same as no reverb otherwise our reverb
359   ///effects menu sounds
360   SFXReverbProperties()
361   {
362      flDensity = 0.0f;
363      flDiffusion = 0.0f;
364      flGain = 0.0f;
365      flGainHF = 0.0f;
366      flGainLF = 0.0000f;
367      flDecayTime = 0.0f;
368      flDecayHFRatio = 0.0f;
369      flDecayLFRatio = 0.0f;
370      flReflectionsGain = 0.0f;
371      flReflectionsDelay = 0.0f;
372      dMemset(flReflectionsPan, 0, sizeof(flReflectionsPan));
373      flLateReverbGain = 0.0f;
374      flLateReverbDelay = 0.0f;
375      dMemset(flLateReverbPan, 0, sizeof(flLateReverbPan));
376      flEchoTime = 0.0f;
377      flEchoDepth = 0.0f;
378      flModulationTime = 0.0f;
379      flModulationDepth = 0.0f;
380      flAirAbsorptionGainHF = 0.0f;
381      flHFReference = 0.0f;
382      flLFReference = 0.0f;
383      flRoomRolloffFactor = 0.0f;
384      iDecayHFLimit = 0;
385   }
386
387   void validate()
388   {
389      flDensity = mClampF(flDensity, 0.0f, 1.0f);
390      flDiffusion = mClampF(flDiffusion, 0.0f, 1.0f);
391      flGain = mClampF(flGain, 0.0f, 1.0f);
392      flGainHF = mClampF(flGainHF, 0.0f, 1.0f);
393      flGainLF = mClampF(flGainLF, 0.0f, 1.0f);
394      flDecayTime = mClampF(flDecayTime, 0.1f, 20.0f);
395      flDecayHFRatio = mClampF(flDecayHFRatio, 0.1f, 2.0f);
396      flDecayLFRatio = mClampF(flDecayLFRatio, 0.1f, 2.0f);
397      flReflectionsGain = mClampF(flReflectionsGain, 0.0f, 3.16f);
398      flReflectionsDelay = mClampF(flReflectionsDelay, 0.0f, 0.3f);
399      flReflectionsPan[0] = mClampF(flReflectionsPan[0], -1.0f, 1.0f);
400      flReflectionsPan[1] = mClampF(flReflectionsPan[1], -1.0f, 1.0f);
401      flReflectionsPan[2] = mClampF(flReflectionsPan[2], -1.0f, 1.0f);
402      flLateReverbGain = mClampF(flLateReverbGain, 0.0f, 10.0f);
403      flLateReverbDelay = mClampF(flLateReverbDelay, 0.0f, 0.1f);
404      flLateReverbPan[0] = mClampF(flLateReverbPan[0], -1.0f, 1.0f);
405      flLateReverbPan[1] = mClampF(flLateReverbPan[1], -1.0f, 1.0f);
406      flLateReverbPan[2] = mClampF(flLateReverbPan[2], -1.0f, 1.0f);
407      flEchoTime = mClampF(flEchoTime, 0.075f, 0.25f);
408      flEchoDepth = mClampF(flEchoDepth, 0.0f, 1.0f);
409      flModulationTime = mClampF(flModulationTime, 0.04f, 4.0f);
410      flModulationDepth = mClampF(flModulationDepth, 0.0f, 1.0f);
411      flAirAbsorptionGainHF = mClampF(flAirAbsorptionGainHF, 0.892f, 1.0f);
412      flHFReference = mClampF(flHFReference, 1000.0f, 20000.0f);
413      flLFReference = mClampF(flLFReference, 20.0f, 1000.0f);
414      flRoomRolloffFactor = mClampF(flRoomRolloffFactor, 0.0f, 10.0f);
415      iDecayHFLimit = mClampF(iDecayHFLimit, 0, 1);
416   }
417};
418
419
420//-----------------------------------------------------------------------------
421//    SFXSoundReverbProperties.
422//-----------------------------------------------------------------------------
423
424
425/// Sound reverb properties.
426///
427/// @note A given SFX device may not implement all properties.
428///not in use by openal yet if u are going to use ambient reverb zones its 
429///probably best to not have reverb on the sound effect itself.
430class SFXSoundReverbProperties
431{
432public:
433
434   typedef void Parent;
435
436   float flDensity;
437   float flDiffusion;
438   float flGain;
439   float flGainHF;
440   float flGainLF;
441   float flDecayTime;
442   float flDecayHFRatio;
443   float flDecayLFRatio;
444   float flReflectionsGain;
445   float flReflectionsDelay;
446   float flReflectionsPan[3];
447   float flLateReverbGain;
448   float flLateReverbDelay;
449   float flLateReverbPan[3];
450   float flEchoTime;
451   float flEchoDepth;
452   float flModulationTime;
453   float flModulationDepth;
454   float flAirAbsorptionGainHF;
455   float flHFReference;
456   float flLFReference;
457   float flRoomRolloffFactor;
458   int   iDecayHFLimit;
459
460
461   ///Set our defaults to have no reverb
462   ///if you are going to use zone reverbs its
463   ///probably best not to use per-voice reverb
464   SFXSoundReverbProperties()
465   {
466      flDensity = 0.0f;
467      flDiffusion = 0.0f;
468      flGain = 0.0f;
469      flGainHF = 0.0f;
470      flGainLF = 0.0000f;
471      flDecayTime = 0.0f;
472      flDecayHFRatio = 0.0f;
473      flDecayLFRatio = 0.0f;
474      flReflectionsGain = 0.0f;
475      flReflectionsDelay = 0.0f;
476      dMemset(flReflectionsPan, 0, sizeof(flReflectionsPan));
477      flLateReverbGain = 0.0f;
478      flLateReverbDelay = 0.0f;
479      dMemset(flLateReverbPan, 0, sizeof(flLateReverbPan));
480      flEchoTime = 0.0f;
481      flEchoDepth = 0.0f;
482      flModulationTime = 0.0f;
483      flModulationDepth = 0.0f;
484      flAirAbsorptionGainHF = 0.0f;
485      flHFReference = 0.0f;
486      flLFReference = 0.0f;
487      flRoomRolloffFactor = 0.0f;
488      iDecayHFLimit = 0;
489   }
490
491   void validate()
492   {
493      flDensity = mClampF(flDensity, 0.0f, 1.0f);
494      flDiffusion = mClampF(flDiffusion, 0.0f, 1.0f);
495      flGain = mClampF(flGain, 0.0f, 1.0f);
496      flGainHF = mClampF(flGainHF, 0.0f, 1.0f);
497      flGainLF = mClampF(flGainLF, 0.0f, 1.0f);
498      flDecayTime = mClampF(flDecayTime, 0.1f, 20.0f);
499      flDecayHFRatio = mClampF(flDecayHFRatio, 0.1f, 2.0f);
500      flDecayLFRatio = mClampF(flDecayLFRatio, 0.1f, 2.0f);
501      flReflectionsGain = mClampF(flReflectionsGain, 0.0f, 3.16f);
502      flReflectionsDelay = mClampF(flReflectionsDelay, 0.0f, 0.3f);
503      flReflectionsPan[0] = mClampF(flReflectionsPan[0], -1.0f, 1.0f);
504      flReflectionsPan[1] = mClampF(flReflectionsPan[1], -1.0f, 1.0f);
505      flReflectionsPan[2] = mClampF(flReflectionsPan[2], -1.0f, 1.0f);
506      flLateReverbGain = mClampF(flLateReverbGain, 0.0f, 10.0f);
507      flLateReverbDelay = mClampF(flLateReverbDelay, 0.0f, 0.1f);
508      flLateReverbPan[0] = mClampF(flLateReverbPan[0], -1.0f, 1.0f);
509      flLateReverbPan[1] = mClampF(flLateReverbPan[1], -1.0f, 1.0f);
510      flLateReverbPan[2] = mClampF(flLateReverbPan[2], -1.0f, 1.0f);
511      flEchoTime = mClampF(flEchoTime, 0.075f, 0.25f);
512      flEchoDepth = mClampF(flEchoDepth, 0.0f, 1.0f);
513      flModulationTime = mClampF(flModulationTime, 0.04f, 4.0f);
514      flModulationDepth = mClampF(flModulationDepth, 0.0f, 1.0f);
515      flAirAbsorptionGainHF = mClampF(flAirAbsorptionGainHF, 0.892f, 1.0f);
516      flHFReference = mClampF(flHFReference, 1000.0f, 20000.0f);
517      flLFReference = mClampF(flLFReference, 20.0f, 1000.0f);
518      flRoomRolloffFactor = mClampF(flRoomRolloffFactor, 0.0f, 10.0f);
519      iDecayHFLimit = mClampF(iDecayHFLimit, 0, 1);
520   }
521};
522
523
524//-----------------------------------------------------------------------------
525//    SFXListenerProperties.
526//-----------------------------------------------------------------------------
527
528
529///
530class SFXListenerProperties
531{
532   public:
533   
534      typedef void Parent;
535      
536      /// Position and orientation of the listener.
537      MatrixF mTransform;
538      
539      ///
540      Point3F mVelocity;
541
542      SFXListenerProperties()
543         : mTransform( true ),
544           mVelocity( 0.0f, 0.0f, 0.0f ) {}
545           
546      SFXListenerProperties( const MatrixF& transform, const Point3F& velocity )
547         : mTransform( transform ),
548           mVelocity( velocity ) {}
549           
550      ///
551      const MatrixF& getTransform() const { return mTransform; }
552      MatrixF& getTransform() { return mTransform; }
553      
554      ///
555      const Point3F& getVelocity() const { return mVelocity; }
556      Point3F& getVelocity() { return mVelocity; }
557};
558
559
560//-----------------------------------------------------------------------------
561//    SFXMaterialProperties.
562//-----------------------------------------------------------------------------
563
564
565///
566class SFXMaterialProperties
567{
568   public:
569   
570      typedef void Parent;
571   
572      ///
573      bool mDoubleSided;
574   
575      ///
576      F32 mDirectOcclusion;
577      
578      ///
579      F32 mReverbOcclusion;
580      
581      SFXMaterialProperties()
582         : mDoubleSided( false ),
583           mDirectOcclusion( 0.5f ),
584           mReverbOcclusion( 0.5f ) {}
585      
586      void validate()
587      {
588         mDirectOcclusion = mClampF( mDirectOcclusion, 0.0f, 1.0f );
589         mReverbOcclusion = mClampF( mReverbOcclusion, 0.0f, 1.0f );
590      }
591};
592
593
594//-----------------------------------------------------------------------------
595//    SFXVariantFloat.
596//-----------------------------------------------------------------------------
597
598
599/// An array of float values with optional random variances.
600template< S32 NUM_VALUES >
601struct SFXVariantFloat
602{
603   /// Base value.
604   F32 mValue[ NUM_VALUES ];
605      
606   /// Variance of value.  Final value will be
607   ///
608   ///   mClampF( randF( mValue + mVariance[ 0 ], mValue + mVariance[ 1 ] ), min, max )
609   ///
610   /// with min and max being dependent on the context of the value.
611   F32 mVariance[ NUM_VALUES ][ 2 ];
612            
613   F32 getValue( U32 index = 0, F32 min = TypeTraits< F32 >::MIN, F32 max = TypeTraits< F32 >::MAX ) const
614   {
615      AssertFatal( index < NUM_VALUES, "SFXVariantFloat::getValue() - index out of range!" );
616      
617      return mClampF( gRandGen.randF( mValue[ index ] + mVariance[ index ][ 0 ],
618                                      mValue[ index ] + mVariance[ index ][ 1 ] ),
619                      min, max );
620   }
621   
622   void validate()
623   {
624      for( U32 i = 0; i < NUM_VALUES; ++ i )
625         mVariance[ i ][ 0 ] = getMin( mVariance[ i ][ 0 ], mVariance[ i ][ 1 ] );
626   }
627};
628
629
630#endif // _SFXCOMMON_H_
631