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};
158
159DefineEnumType( SFXDistanceModel );
160
161/// Compute the distance attenuation based on the given distance model.
162///
163/// @param minDistance Reference distance; attenuation starts here.
164/// @param maxDistance
165/// @param distance Actual distance of sound from listener.
166/// @param volume Unattenuated volume.
167/// @param rolloffFactor Rolloff curve scale factor.
168///
169/// @return The attenuated volume.
170inline F32 SFXDistanceAttenuation( SFXDistanceModel model, F32 minDistance, F32 maxDistance, F32 distance, F32 volume, F32 rolloffFactor )
171{
172   F32 gain = 1.0f;
173      
174   switch( model )
175   {
176      case SFXDistanceModelLinear:
177      
178         distance = getMax( distance, minDistance );
179         distance = getMin( distance, maxDistance );
180         
181         gain = ( 1 - ( distance - minDistance ) / ( maxDistance - minDistance ) );
182         break;
183                  
184      case SFXDistanceModelLogarithmic:
185      
186         distance = getMax( distance, minDistance );
187         distance = getMin( distance, maxDistance );
188         
189         gain = minDistance / ( minDistance + rolloffFactor * ( distance - minDistance ) );
190         break;
191         
192   }
193   
194   return ( volume * gain );
195}
196
197
198//-----------------------------------------------------------------------------
199//    SFXFormat.
200//-----------------------------------------------------------------------------
201
202
203/// This class defines the various types of sound data that may be
204/// used in the sound system.
205///
206/// Unlike with most sound APIs, we consider each sample point to comprise
207/// all channels in a sound stream rather than only one value for a single
208/// channel.
209class SFXFormat
210{
211   protected:
212
213      /// The number of sound channels in the data.
214      U8 mChannels;
215
216      /// The number of bits per sound sample.
217      U8 mBitsPerSample;
218
219      /// The frequency in samples per second.
220      U32 mSamplesPerSecond;
221
222   public:
223
224      SFXFormat(  U8 channels = 0,                  
225                  U8 bitsPerSample = 0,
226                  U32 samplesPerSecond = 0 )
227         :  mChannels( channels ),
228            mBitsPerSample( bitsPerSample ),
229            mSamplesPerSecond( samplesPerSecond )
230      {}
231
232      /// Copy constructor.
233      SFXFormat( const SFXFormat &format )
234         :  mChannels( format.mChannels ),
235            mBitsPerSample( format.mBitsPerSample ),
236            mSamplesPerSecond( format.mSamplesPerSecond )
237      {}
238
239   public:
240
241      /// Sets the format.
242      void set(   U8 channels,                  
243                  U8 bitsPerSample,
244                  U32 samplesPerSecond )
245      {
246         mChannels = channels;
247         mBitsPerSample = bitsPerSample;
248         mSamplesPerSecond = samplesPerSecond;
249      }
250
251      /// Comparision between formats.
252      bool operator ==( const SFXFormat& format ) const 
253      { 
254         return   mChannels == format.mChannels && 
255                  mBitsPerSample == format.mBitsPerSample &&
256                  mSamplesPerSecond == format.mSamplesPerSecond;
257      }
258
259      /// Returns the number of sound channels.
260      U8 getChannels() const { return mChannels; }
261
262      /// Returns true if there is a single sound channel.
263      bool isMono() const { return mChannels == 1; }
264
265      /// Is true if there are two sound channels.
266      bool isStereo() const { return mChannels == 2; }
267
268      /// Is true if there are more than two sound channels.
269      bool isMultiChannel() const { return mChannels > 2; }
270
271      /// 
272      U32 getSamplesPerSecond() const { return mSamplesPerSecond; }
273
274      /// The bits of data per channel.
275      U8 getBitsPerChannel() const { return mBitsPerSample / mChannels; }
276
277      /// The number of bytes of data per channel.
278      U8 getBytesPerChannel() const { return getBitsPerChannel() / 8; }
279
280      /// The number of bits per sound sample.
281      U8 getBitsPerSample() const { return mBitsPerSample; }
282
283      /// The number of bytes of data per sample.
284      /// @note Be aware that this comprises all channels.
285      U8 getBytesPerSample() const { return mBitsPerSample / 8; }
286
287      /// Returns the duration from the sample count.
288      U32 getDuration( U32 samples ) const
289      {
290         // Use 64bit types to avoid overflow during division. 
291         return ( (U64)samples * (U64)1000 ) / (U64)mSamplesPerSecond;
292      }
293
294      ///
295      U32 getSampleCount( U32 ms ) const
296      {
297         return U64( mSamplesPerSecond ) * U64( ms ) / U64( 1000 );
298      }
299
300      /// Returns the data length in bytes.
301      U32 getDataLength( U32 ms ) const
302      {
303         U32 bytes = ( ( (U64)ms * (U64)mSamplesPerSecond ) * (U64)getBytesPerSample() ) / (U64)1000;
304         return bytes;
305      }
306};
307
308
309//-----------------------------------------------------------------------------
310//    SFXReverb.
311//-----------------------------------------------------------------------------
312
313
314/// Reverb environment properties.
315///
316/// @note A given device may not implement all properties.
317class SFXReverbProperties
318{
319   public:
320   
321      typedef void Parent;
322         
323      F32   mEnvSize;
324      F32   mEnvDiffusion;
325      S32   mRoom;
326      S32   mRoomHF;
327      S32   mRoomLF;
328      F32   mDecayTime;
329      F32   mDecayHFRatio;
330      F32   mDecayLFRatio;
331      S32   mReflections;
332      F32   mReflectionsDelay;
333      F32   mReflectionsPan[ 3 ];
334      S32   mReverb;
335      F32   mReverbDelay;
336      F32   mReverbPan[ 3 ];
337      F32   mEchoTime;
338      F32   mEchoDepth;
339      F32   mModulationTime;
340      F32   mModulationDepth;
341      F32   mAirAbsorptionHF;
342      F32   mHFReference;
343      F32   mLFReference;
344      F32   mRoomRolloffFactor;
345      F32   mDiffusion;
346      F32   mDensity;
347      S32   mFlags;
348      
349      SFXReverbProperties()
350         : mEnvSize( 7.5f ),
351           mEnvDiffusion( 1.0f ),
352           mRoom( -1000 ),
353           mRoomHF( -100 ),
354           mRoomLF( 0 ),
355           mDecayTime( 1.49f ),
356           mDecayHFRatio( 0.83f ),
357           mDecayLFRatio( 1.0f ),
358           mReflections( -2602 ),
359           mReflectionsDelay( 0.007f ),
360           mReverb( 200 ),
361           mReverbDelay( 0.011f ),
362           mEchoTime( 0.25f ),
363           mEchoDepth( 0.0f ),
364           mModulationTime( 0.25f ),
365           mModulationDepth( 0.0f ),
366           mAirAbsorptionHF( -5.0f ),
367           mHFReference( 5000.0f ),
368           mLFReference( 250.0f ),
369           mRoomRolloffFactor( 0.0f ),
370           mDiffusion( 100.0f ),
371           mDensity( 100.0f ),
372           mFlags( 0 )
373      {
374         mReflectionsPan[ 0 ] = 0.0f;
375         mReflectionsPan[ 1 ] = 0.0f;
376         mReflectionsPan[ 2 ] = 0.0f;
377         
378         mReverbPan[ 0 ] = 0.0f;
379         mReverbPan[ 1 ] = 0.0f;
380         mReverbPan[ 2 ] = 0.0f;
381      }
382      
383      void validate()
384      {
385         mEnvSize                = mClampF( mEnvSize,                1.0f,     100.0f );
386         mEnvDiffusion           = mClampF( mEnvDiffusion,           0.0f,     1.0f );
387         mRoom                   = mClamp( mRoom,                    -10000,  0 );
388         mRoomHF                 = mClamp( mRoomHF,                  -10000,  0 );
389         mRoomLF                 = mClamp( mRoomLF,                  -10000,  0 );
390         mDecayTime              = mClampF( mDecayTime,              0.1f,     20.0f );
391         mDecayHFRatio           = mClampF( mDecayHFRatio,           0.1f,     2.0f );
392         mDecayLFRatio           = mClampF( mDecayLFRatio,           0.1f,     2.0f );
393         mReflections            = mClamp( mReflections,             -10000,  1000 );
394         mReflectionsDelay       = mClampF( mReflectionsDelay,       0.0f,     0.3f );
395         mReverb                 = mClamp( mReverb,                  -10000,  2000 );
396         mReverbDelay            = mClampF( mReverbDelay,            0.0f,     0.1f );
397         mEchoTime               = mClampF( mEchoTime,               0.075f,   0.25f );
398         mEchoDepth              = mClampF( mEchoDepth,              0.0f,     1.0f );
399         mModulationTime         = mClampF( mModulationTime,         0.04f,    4.0f );
400         mModulationDepth        = mClampF( mModulationDepth,        0.0f,     1.0f );
401         mAirAbsorptionHF        = mClampF( mAirAbsorptionHF,        -100.0f,    0.0f );
402         mHFReference            = mClampF( mHFReference,            1000.0f,  20000.0f );
403         mLFReference            = mClampF( mLFReference,            20.0f,    1000.0f );
404         mRoomRolloffFactor      = mClampF( mRoomRolloffFactor,      0.0f,     10.0f );
405         mDiffusion              = mClampF( mDiffusion,              0.0f,     100.0f );
406         mDensity                = mClampF( mDensity,                0.0f,     100.0f );
407      }
408};
409
410
411//-----------------------------------------------------------------------------
412//    SFXSoundReverbProperties.
413//-----------------------------------------------------------------------------
414
415
416/// Sound reverb properties.
417///
418/// @note A given SFX device may not implement all properties.
419class SFXSoundReverbProperties
420{
421   public:
422   
423      typedef void Parent;
424   
425      S32   mDirect;
426      S32   mDirectHF;
427      S32   mRoom;
428      S32   mRoomHF;
429      S32   mObstruction;
430      F32   mObstructionLFRatio;
431      S32   mOcclusion;
432      F32   mOcclusionLFRatio;
433      F32   mOcclusionRoomRatio;
434      F32   mOcclusionDirectRatio;
435      S32   mExclusion;
436      F32   mExclusionLFRatio;
437      S32   mOutsideVolumeHF;
438      F32   mDopplerFactor;
439      F32   mRolloffFactor;
440      F32   mRoomRolloffFactor;
441      F32   mAirAbsorptionFactor;
442      S32   mFlags;
443      
444      SFXSoundReverbProperties()
445         : mDirect( 0 ),
446           mDirectHF( 0 ),
447           mRoom( 0 ),
448           mRoomHF( 0 ),
449           mObstruction( 0 ),
450           mObstructionLFRatio( 0.0f ),
451           mOcclusion( 0 ),
452           mOcclusionLFRatio( 0.25f ),
453           mOcclusionRoomRatio( 1.5f ),
454           mOcclusionDirectRatio( 1.0f ),
455           mExclusion( 0 ),
456           mExclusionLFRatio( 1.0f ),
457           mOutsideVolumeHF( 0 ),
458           mDopplerFactor( 0.0f ),
459           mRolloffFactor( 0.0f ),
460           mRoomRolloffFactor( 0.0f ),
461           mAirAbsorptionFactor( 1.0f ),
462           mFlags( 0 )
463      {
464      }
465      
466      void validate()
467      {
468         mDirect              = mClamp( mDirect,                -10000,  1000 );
469         mDirectHF            = mClamp( mDirectHF,              -10000,  0 );
470         mRoom                = mClamp( mRoom,                  -10000,  1000 );
471         mRoomHF              = mClamp( mRoomHF,                -10000,  0 );
472         mObstruction         = mClamp( mObstruction,           -10000,  0 );
473         mObstructionLFRatio  = mClampF( mObstructionLFRatio,   0.0f,     1.0f );
474         mOcclusion           = mClamp( mOcclusion,             -10000,  0 );
475         mOcclusionLFRatio    = mClampF( mOcclusionLFRatio,     0.0f,     1.0f );
476         mOcclusionRoomRatio  = mClampF( mOcclusionRoomRatio,   0.0f,     10.0f );
477         mOcclusionDirectRatio= mClampF( mOcclusionDirectRatio, 0.0f,     10.0f );
478         mExclusion           = mClamp( mExclusion,             -10000,  0 );
479         mExclusionLFRatio    = mClampF( mExclusionLFRatio,     0.0f,     1.0f );
480         mOutsideVolumeHF     = mClamp( mOutsideVolumeHF,       -10000,  0 );
481         mDopplerFactor       = mClampF( mDopplerFactor,        0.0f,     10.0f );
482         mRolloffFactor       = mClampF( mRolloffFactor,        0.0f,     10.0f );
483         mRoomRolloffFactor   = mClampF( mRoomRolloffFactor,    0.0f,     10.0f );
484         mAirAbsorptionFactor = mClampF( mAirAbsorptionFactor,  0.0f,     10.0f );
485      }
486};
487
488
489//-----------------------------------------------------------------------------
490//    SFXListenerProperties.
491//-----------------------------------------------------------------------------
492
493
494///
495class SFXListenerProperties
496{
497   public:
498   
499      typedef void Parent;
500      
501      /// Position and orientation of the listener.
502      MatrixF mTransform;
503      
504      ///
505      Point3F mVelocity;
506
507      SFXListenerProperties()
508         : mTransform( true ),
509           mVelocity( 0.0f, 0.0f, 0.0f ) {}
510           
511      SFXListenerProperties( const MatrixF& transform, const Point3F& velocity )
512         : mTransform( transform ),
513           mVelocity( velocity ) {}
514           
515      ///
516      const MatrixF& getTransform() const { return mTransform; }
517      MatrixF& getTransform() { return mTransform; }
518      
519      ///
520      const Point3F& getVelocity() const { return mVelocity; }
521      Point3F& getVelocity() { return mVelocity; }
522};
523
524
525//-----------------------------------------------------------------------------
526//    SFXMaterialProperties.
527//-----------------------------------------------------------------------------
528
529
530///
531class SFXMaterialProperties
532{
533   public:
534   
535      typedef void Parent;
536   
537      ///
538      bool mDoubleSided;
539   
540      ///
541      F32 mDirectOcclusion;
542      
543      ///
544      F32 mReverbOcclusion;
545      
546      SFXMaterialProperties()
547         : mDoubleSided( false ),
548           mDirectOcclusion( 0.5f ),
549           mReverbOcclusion( 0.5f ) {}
550      
551      void validate()
552      {
553         mDirectOcclusion = mClampF( mDirectOcclusion, 0.0f, 1.0f );
554         mReverbOcclusion = mClampF( mReverbOcclusion, 0.0f, 1.0f );
555      }
556};
557
558
559//-----------------------------------------------------------------------------
560//    SFXVariantFloat.
561//-----------------------------------------------------------------------------
562
563
564/// An array of float values with optional random variances.
565template< S32 NUM_VALUES >
566struct SFXVariantFloat
567{
568   /// Base value.
569   F32 mValue[ NUM_VALUES ];
570      
571   /// Variance of value.  Final value will be
572   ///
573   ///   mClampF( randF( mValue + mVariance[ 0 ], mValue + mVariance[ 1 ] ), min, max )
574   ///
575   /// with min and max being dependent on the context of the value.
576   F32 mVariance[ NUM_VALUES ][ 2 ];
577            
578   F32 getValue( U32 index = 0, F32 min = TypeTraits< F32 >::MIN, F32 max = TypeTraits< F32 >::MAX ) const
579   {
580      AssertFatal( index < NUM_VALUES, "SFXVariantFloat::getValue() - index out of range!" );
581      
582      return mClampF( gRandGen.randF( mValue[ index ] + mVariance[ index ][ 0 ],
583                                      mValue[ index ] + mVariance[ index ][ 1 ] ),
584                      min, max );
585   }
586   
587   void validate()
588   {
589      for( U32 i = 0; i < NUM_VALUES; ++ i )
590         mVariance[ i ][ 0 ] = getMin( mVariance[ i ][ 0 ], mVariance[ i ][ 1 ] );
591   }
592};
593
594
595#endif // _SFXCOMMON_H_
596