Torque3D/Engine/source/sfx/sfxCommon.h

//-----------------------------------------------------------------------------
// Copyright (c) 2012 GarageGames, LLC
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
// IN THE SOFTWARE.
//-----------------------------------------------------------------------------

#ifndef _SFXCOMMON_H_
#define _SFXCOMMON_H_

#ifndef _PLATFORM_H_
   #include "platform/platform.h"
#endif
#ifndef _MMATHFN_H_
   #include "math/mMathFn.h"
#endif
#ifndef _MRANDOM_H_
   #include "math/mRandom.h"
#endif
#ifndef _MMATRIX_H_
   #include "math/mMatrix.h"
#endif
#ifndef _MPOINT3_H_
   #include "math/mPoint3.h"
#endif
#ifndef _TYPETRAITS_H_
   #include "platform/typetraits.h"
#endif
#ifndef _DYNAMIC_CONSOLETYPES_H_
   #include "console/dynamicTypes.h"
#endif



class SFXEnvironment;
class SFXPlayList;


//-----------------------------------------------------------------------------
//    SFXStatus.
//-----------------------------------------------------------------------------


/// The sound playback state.
enum SFXStatus 
{
   /// Initial state; no operation yet performed on sound.
   SFXStatusNull,

   /// Sound is playing.
   SFXStatusPlaying,

   /// Sound has been stopped.
   SFXStatusStopped,

   /// Sound is paused.
   SFXStatusPaused,

   /// Sound stream is starved and playback blocked.
   SFXStatusBlocked,

   /// Temporary state while transitioning to another state.  This is used when multiple
   /// threads concurrently maintain a status and need to perform a sequence of actions before
   /// being able to fully go from a previous to a new current state.  In this case, the
   /// transition state marks the status as being under update on another thread.
   ///
   /// @note Not all places that use SFXStatus actually use this state.
   SFXStatusTransition,
};

DefineEnumType( SFXStatus );


inline const char* SFXStatusToString( SFXStatus status )
{
   switch ( status )
   {
      case SFXStatusPlaying:     return "playing";
      case SFXStatusStopped:     return "stopped";
      case SFXStatusPaused:      return "paused";
      case SFXStatusBlocked:     return "blocked";
      case SFXStatusTransition:  return "transition";
      
      case SFXStatusNull:
      default: ;
   }
   
   return "null";
}


//-----------------------------------------------------------------------------
//    SFXChannel.
//-----------------------------------------------------------------------------


/// Animatable channels in the SFX system.
enum SFXChannel
{
   SFXChannelVolume,
   SFXChannelPitch,
   SFXChannelPriority,
   SFXChannelPositionX,
   SFXChannelPositionY,
   SFXChannelPositionZ,
   SFXChannelRotationX,
   SFXChannelRotationY,
   SFXChannelRotationZ,
   SFXChannelVelocityX,
   SFXChannelVelocityY,
   SFXChannelVelocityZ,
   SFXChannelMinDistance,
   SFXChannelMaxDistance,
   SFXChannelConeInsideAngle,
   SFXChannelConeOutsideAngle,
   SFXChannelConeOutsideVolume,
   SFXChannelCursor,
   SFXChannelStatus,
   SFXChannelUser0,
   SFXChannelUser1,
   SFXChannelUser2,
   SFXChannelUser3,
   
   /// Total number of animatable channels.
   SFX_NUM_CHANNELS
};

DefineEnumType( SFXChannel );


//-----------------------------------------------------------------------------
//    SFXDistanceModel.
//-----------------------------------------------------------------------------


/// Rolloff curve used for distance volume attenuation of 3D sounds.
enum SFXDistanceModel
{
   SFXDistanceModelLinear,             ///< Volume decreases linearly from min to max where it reaches zero.
   SFXDistanceModelLogarithmic,        ///< Volume halves every min distance steps starting from min distance; attenuation stops at max distance.
   SFXDistanceModelExponent,           /// exponential falloff for distance attenuation.
};

DefineEnumType( SFXDistanceModel );

/// Compute the distance attenuation based on the given distance model.
///
/// @param minDistance Reference distance; attenuation starts here.
/// @param maxDistance
/// @param distance Actual distance of sound from listener.
/// @param volume Unattenuated volume.
/// @param rolloffFactor Rolloff curve scale factor.
///
/// @return The attenuated volume.
inline F32 SFXDistanceAttenuation( SFXDistanceModel model, F32 minDistance, F32 maxDistance, F32 distance, F32 volume, F32 rolloffFactor )
{
   F32 gain = 1.0f;
      
   switch( model )
   {
      case SFXDistanceModelLinear:
      
         distance = getMax( distance, minDistance );
         distance = getMin( distance, maxDistance );
         
         gain = ( 1 - ( distance - minDistance ) / ( maxDistance - minDistance ) );
         break;
                  
      case SFXDistanceModelLogarithmic:
      
         distance = getMax( distance, minDistance );
         distance = getMin( distance, maxDistance );
         
         gain = minDistance / ( minDistance + rolloffFactor * ( distance - minDistance ) );
         break;

         ///create exponential distance model    
      case SFXDistanceModelExponent:
         distance = getMax(distance, minDistance);
         distance = getMin(distance, maxDistance);

         gain = pow((distance / minDistance), (-rolloffFactor));
         break;
         
   }
   
   return ( volume * gain );
}


//-----------------------------------------------------------------------------
//    SFXFormat.
//-----------------------------------------------------------------------------


/// This class defines the various types of sound data that may be
/// used in the sound system.
///
/// Unlike with most sound APIs, we consider each sample point to comprise
/// all channels in a sound stream rather than only one value for a single
/// channel.
class SFXFormat
{
   protected:

      /// The number of sound channels in the data.
      U8 mChannels;

      /// The number of bits per sound sample.
      U8 mBitsPerSample;

      /// The frequency in samples per second.
      U32 mSamplesPerSecond;

   public:

      SFXFormat(  U8 channels = 0,                  
                  U8 bitsPerSample = 0,
                  U32 samplesPerSecond = 0 )
         :  mChannels( channels ),
            mBitsPerSample( bitsPerSample ),
            mSamplesPerSecond( samplesPerSecond )
      {}

      /// Copy constructor.
      SFXFormat( const SFXFormat &format )
         :  mChannels( format.mChannels ),
            mBitsPerSample( format.mBitsPerSample ),
            mSamplesPerSecond( format.mSamplesPerSecond )
      {}

   public:

      /// Sets the format.
      void set(   U8 channels,                  
                  U8 bitsPerSample,
                  U32 samplesPerSecond )
      {
         mChannels = channels;
         mBitsPerSample = bitsPerSample;
         mSamplesPerSecond = samplesPerSecond;
      }

      /// Comparision between formats.
      bool operator == ( const SFXFormat& format ) const 
      { 
         return   mChannels == format.mChannels && 
                  mBitsPerSample == format.mBitsPerSample &&
                  mSamplesPerSecond == format.mSamplesPerSecond;
      }

      /// Returns the number of sound channels.
      U8 getChannels() const { return mChannels; }

      /// Returns true if there is a single sound channel.
      bool isMono() const { return mChannels == 1; }

      /// Is true if there are two sound channels.
      bool isStereo() const { return mChannels == 2; }

      /// Is true if there are more than two sound channels.
      bool isMultiChannel() const { return mChannels > 2; }

      /// 
      U32 getSamplesPerSecond() const { return mSamplesPerSecond; }

      /// The bits of data per channel.
      U8 getBitsPerChannel() const { return mBitsPerSample / mChannels; }

      /// The number of bytes of data per channel.
      U8 getBytesPerChannel() const { return getBitsPerChannel() / 8; }

      /// The number of bits per sound sample.
      U8 getBitsPerSample() const { return mBitsPerSample; }

      /// The number of bytes of data per sample.
      /// @note Be aware that this comprises all channels.
      U8 getBytesPerSample() const { return mBitsPerSample / 8; }

      /// Returns the duration from the sample count.
      U32 getDuration( U32 samples ) const
      {
         // Use 64bit types to avoid overflow during division. 
         return ( (U64)samples * (U64)1000 ) / (U64)mSamplesPerSecond;
      }

      ///
      U32 getSampleCount( U32 ms ) const
      {
         return U64( mSamplesPerSecond ) * U64( ms ) / U64( 1000 );
      }

      /// Returns the data length in bytes.
      U32 getDataLength( U32 ms ) const
      {
         U32 bytes = ( ( (U64)ms * (U64)mSamplesPerSecond ) * (U64)getBytesPerSample() ) / (U64)1000;
         return bytes;
      }
};


//-----------------------------------------------------------------------------
//    SFXReverb.
//-----------------------------------------------------------------------------


/// Reverb environment properties.
///
/// @note A given device may not implement all properties.
///restructure our reverbproperties to match openal

class SFXReverbProperties
{
public:

   struct Parent;

   float flDensity;
   float flDiffusion;
   float flGain;
   float flGainHF;
   float flGainLF;
   float flDecayTime;
   float flDecayHFRatio;
   float flDecayLFRatio;
   float flReflectionsGain;
   float flReflectionsDelay;
   float flReflectionsPan[3];
   float flLateReverbGain;
   float flLateReverbDelay;
   float flLateReverbPan[3];
   float flEchoTime;
   float flEchoDepth;
   float flModulationTime;
   float flModulationDepth;
   float flAirAbsorptionGainHF;
   float flHFReference;
   float flLFReference;
   float flRoomRolloffFactor;
   int   iDecayHFLimit;

   ///set our defaults to be the same as no reverb otherwise our reverb
   ///effects menu sounds
   SFXReverbProperties()
   {
      flDensity = 0.0f;
      flDiffusion = 0.0f;
      flGain = 0.0f;
      flGainHF = 0.0f;
      flGainLF = 0.0000f;
      flDecayTime = 0.0f;
      flDecayHFRatio = 0.0f;
      flDecayLFRatio = 0.0f;
      flReflectionsGain = 0.0f;
      flReflectionsDelay = 0.0f;
      dMemset(flReflectionsPan, 0, sizeof(flReflectionsPan));
      flLateReverbGain = 0.0f;
      flLateReverbDelay = 0.0f;
      dMemset(flLateReverbPan, 0, sizeof(flLateReverbPan));
      flEchoTime = 0.0f;
      flEchoDepth = 0.0f;
      flModulationTime = 0.0f;
      flModulationDepth = 0.0f;
      flAirAbsorptionGainHF = 0.0f;
      flHFReference = 0.0f;
      flLFReference = 0.0f;
      flRoomRolloffFactor = 0.0f;
      iDecayHFLimit = 0;
   }

   void validate()
   {
      flDensity = mClampF(flDensity, 0.0f, 1.0f);
      flDiffusion = mClampF(flDiffusion, 0.0f, 1.0f);
      flGain = mClampF(flGain, 0.0f, 1.0f);
      flGainHF = mClampF(flGainHF, 0.0f, 1.0f);
      flGainLF = mClampF(flGainLF, 0.0f, 1.0f);
      flDecayTime = mClampF(flDecayTime, 0.1f, 20.0f);
      flDecayHFRatio = mClampF(flDecayHFRatio, 0.1f, 2.0f);
      flDecayLFRatio = mClampF(flDecayLFRatio, 0.1f, 2.0f);
      flReflectionsGain = mClampF(flReflectionsGain, 0.0f, 3.16f);
      flReflectionsDelay = mClampF(flReflectionsDelay, 0.0f, 0.3f);
      flReflectionsPan[0] = mClampF(flReflectionsPan[0], -1.0f, 1.0f);
      flReflectionsPan[1] = mClampF(flReflectionsPan[1], -1.0f, 1.0f);
      flReflectionsPan[2] = mClampF(flReflectionsPan[2], -1.0f, 1.0f);
      flLateReverbGain = mClampF(flLateReverbGain, 0.0f, 10.0f);
      flLateReverbDelay = mClampF(flLateReverbDelay, 0.0f, 0.1f);
      flLateReverbPan[0] = mClampF(flLateReverbPan[0], -1.0f, 1.0f);
      flLateReverbPan[1] = mClampF(flLateReverbPan[1], -1.0f, 1.0f);
      flLateReverbPan[2] = mClampF(flLateReverbPan[2], -1.0f, 1.0f);
      flEchoTime = mClampF(flEchoTime, 0.075f, 0.25f);
      flEchoDepth = mClampF(flEchoDepth, 0.0f, 1.0f);
      flModulationTime = mClampF(flModulationTime, 0.04f, 4.0f);
      flModulationDepth = mClampF(flModulationDepth, 0.0f, 1.0f);
      flAirAbsorptionGainHF = mClampF(flAirAbsorptionGainHF, 0.892f, 1.0f);
      flHFReference = mClampF(flHFReference, 1000.0f, 20000.0f);
      flLFReference = mClampF(flLFReference, 20.0f, 1000.0f);
      flRoomRolloffFactor = mClampF(flRoomRolloffFactor, 0.0f, 10.0f);
      iDecayHFLimit = mClampF(iDecayHFLimit, 0, 1);
   }
};


//-----------------------------------------------------------------------------
//    SFXSoundReverbProperties.
//-----------------------------------------------------------------------------


/// Sound reverb properties.
///
/// @note A given SFX device may not implement all properties.
///not in use by openal yet if u are going to use ambient reverb zones its 
///probably best to not have reverb on the sound effect itself.
class SFXSoundReverbProperties
{
public:

   typedef void Parent;

   float flDensity;
   float flDiffusion;
   float flGain;
   float flGainHF;
   float flGainLF;
   float flDecayTime;
   float flDecayHFRatio;
   float flDecayLFRatio;
   float flReflectionsGain;
   float flReflectionsDelay;
   float flReflectionsPan[3];
   float flLateReverbGain;
   float flLateReverbDelay;
   float flLateReverbPan[3];
   float flEchoTime;
   float flEchoDepth;
   float flModulationTime;
   float flModulationDepth;
   float flAirAbsorptionGainHF;
   float flHFReference;
   float flLFReference;
   float flRoomRolloffFactor;
   int   iDecayHFLimit;


   ///Set our defaults to have no reverb
   ///if you are going to use zone reverbs its
   ///probably best not to use per-voice reverb
   SFXSoundReverbProperties()
   {
      flDensity = 0.0f;
      flDiffusion = 0.0f;
      flGain = 0.0f;
      flGainHF = 0.0f;
      flGainLF = 0.0000f;
      flDecayTime = 0.0f;
      flDecayHFRatio = 0.0f;
      flDecayLFRatio = 0.0f;
      flReflectionsGain = 0.0f;
      flReflectionsDelay = 0.0f;
      dMemset(flReflectionsPan, 0, sizeof(flReflectionsPan));
      flLateReverbGain = 0.0f;
      flLateReverbDelay = 0.0f;
      dMemset(flLateReverbPan, 0, sizeof(flLateReverbPan));
      flEchoTime = 0.0f;
      flEchoDepth = 0.0f;
      flModulationTime = 0.0f;
      flModulationDepth = 0.0f;
      flAirAbsorptionGainHF = 0.0f;
      flHFReference = 0.0f;
      flLFReference = 0.0f;
      flRoomRolloffFactor = 0.0f;
      iDecayHFLimit = 0;
   }

   void validate()
   {
      flDensity = mClampF(flDensity, 0.0f, 1.0f);
      flDiffusion = mClampF(flDiffusion, 0.0f, 1.0f);
      flGain = mClampF(flGain, 0.0f, 1.0f);
      flGainHF = mClampF(flGainHF, 0.0f, 1.0f);
      flGainLF = mClampF(flGainLF, 0.0f, 1.0f);
      flDecayTime = mClampF(flDecayTime, 0.1f, 20.0f);
      flDecayHFRatio = mClampF(flDecayHFRatio, 0.1f, 2.0f);
      flDecayLFRatio = mClampF(flDecayLFRatio, 0.1f, 2.0f);
      flReflectionsGain = mClampF(flReflectionsGain, 0.0f, 3.16f);
      flReflectionsDelay = mClampF(flReflectionsDelay, 0.0f, 0.3f);
      flReflectionsPan[0] = mClampF(flReflectionsPan[0], -1.0f, 1.0f);
      flReflectionsPan[1] = mClampF(flReflectionsPan[1], -1.0f, 1.0f);
      flReflectionsPan[2] = mClampF(flReflectionsPan[2], -1.0f, 1.0f);
      flLateReverbGain = mClampF(flLateReverbGain, 0.0f, 10.0f);
      flLateReverbDelay = mClampF(flLateReverbDelay, 0.0f, 0.1f);
      flLateReverbPan[0] = mClampF(flLateReverbPan[0], -1.0f, 1.0f);
      flLateReverbPan[1] = mClampF(flLateReverbPan[1], -1.0f, 1.0f);
      flLateReverbPan[2] = mClampF(flLateReverbPan[2], -1.0f, 1.0f);
      flEchoTime = mClampF(flEchoTime, 0.075f, 0.25f);
      flEchoDepth = mClampF(flEchoDepth, 0.0f, 1.0f);
      flModulationTime = mClampF(flModulationTime, 0.04f, 4.0f);
      flModulationDepth = mClampF(flModulationDepth, 0.0f, 1.0f);
      flAirAbsorptionGainHF = mClampF(flAirAbsorptionGainHF, 0.892f, 1.0f);
      flHFReference = mClampF(flHFReference, 1000.0f, 20000.0f);
      flLFReference = mClampF(flLFReference, 20.0f, 1000.0f);
      flRoomRolloffFactor = mClampF(flRoomRolloffFactor, 0.0f, 10.0f);
      iDecayHFLimit = mClampF(iDecayHFLimit, 0, 1);
   }
};


//-----------------------------------------------------------------------------
//    SFXListenerProperties.
//-----------------------------------------------------------------------------


///
class SFXListenerProperties
{
   public:
   
      typedef void Parent;
      
      /// Position and orientation of the listener.
      MatrixF mTransform;
      
      ///
      Point3F mVelocity;

      SFXListenerProperties()
         : mTransform( true ),
           mVelocity( 0.0f, 0.0f, 0.0f ) {}
           
      SFXListenerProperties( const MatrixF& transform, const Point3F& velocity )
         : mTransform( transform ),
           mVelocity( velocity ) {}
           
      ///
      const MatrixF& getTransform() const { return mTransform; }
      MatrixF& getTransform() { return mTransform; }
      
      ///
      const Point3F& getVelocity() const { return mVelocity; }
      Point3F& getVelocity() { return mVelocity; }
};


//-----------------------------------------------------------------------------
//    SFXMaterialProperties.
//-----------------------------------------------------------------------------


///
class SFXMaterialProperties
{
   public:
   
      typedef void Parent;
   
      ///
      bool mDoubleSided;
   
      ///
      F32 mDirectOcclusion;
      
      ///
      F32 mReverbOcclusion;
      
      SFXMaterialProperties()
         : mDoubleSided( false ),
           mDirectOcclusion( 0.5f ),
           mReverbOcclusion( 0.5f ) {}
      
      void validate()
      {
         mDirectOcclusion = mClampF( mDirectOcclusion, 0.0f, 1.0f );
         mReverbOcclusion = mClampF( mReverbOcclusion, 0.0f, 1.0f );
      }
};


//-----------------------------------------------------------------------------
//    SFXVariantFloat.
//-----------------------------------------------------------------------------


/// An array of float values with optional random variances.
template< S32 NUM_VALUES >
struct SFXVariantFloat
{
   /// Base value.
   F32 mValue[ NUM_VALUES ];
      
   /// Variance of value.  Final value will be
   ///
   ///   mClampF( randF( mValue + mVariance[ 0 ], mValue + mVariance[ 1 ] ), min, max )
   ///
   /// with min and max being dependent on the context of the value.
   F32 mVariance[ NUM_VALUES ][ 2 ];
            
   F32 getValue( U32 index = 0, F32 min = TypeTraits< F32 >::MIN, F32 max = TypeTraits< F32 >::MAX ) const
   {
      AssertFatal( index < NUM_VALUES, "SFXVariantFloat::getValue() - index out of range!" );
      
      return mClampF( gRandGen.randF( mValue[ index ] + mVariance[ index ][ 0 ],
                                      mValue[ index ] + mVariance[ index ][ 1 ] ),
                      min, max );
   }
   
   void validate()
   {
      for( U32 i = 0; i < NUM_VALUES; ++ i )
         mVariance[ i ][ 0 ] = getMin( mVariance[ i ][ 0 ], mVariance[ i ][ 1 ] );
   }
};


#endif // _SFXCOMMON_H_