Engine/source/sfx/sfxAmbience.cpp

   1 //-----------------------------------------------------------------------------
   2 // Copyright (c) 2012 GarageGames, LLC
   3 //
   4 // Permission is hereby granted, free of charge, to any person obtaining a copy
   5 // of this software and associated documentation files (the "Software"), to
   6 // deal in the Software without restriction, including without limitation the
   7 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
   8 // sell copies of the Software, and to permit persons to whom the Software is
   9 // furnished to do so, subject to the following conditions:
  10 //
  11 // The above copyright notice and this permission notice shall be included in
  12 // all copies or substantial portions of the Software.
  13 //
  14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  17 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  19 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  20 // IN THE SOFTWARE.
  21 //-----------------------------------------------------------------------------
  22
  23 #include "sfx/sfxAmbience.h"
  24 #include "sfx/sfxEnvironment.h"
  25 #include "sfx/sfxTrack.h"
  26 #include "sfx/sfxSystem.h"
  27 #include "sfx/sfxTypes.h"
  28 #include "math/mathTypes.h"
  29 #include "core/stream/bitStream.h"
  30
  31
  32 IMPLEMENT_CO_DATABLOCK_V1( SFXAmbience );
  33
  34
  35 ConsoleDocClass( SFXAmbience,
  36    "@brief A datablock that describes an ambient sound space.\n\n"
  37
  38    "Each ambience datablock captures the properties of a unique ambient sound space.  A sound space is comprised of:\n"
  39
  40    "- an ambient audio track that is played when the listener is inside the space,\n"
  41    "- a reverb environment that is active inside the space, and\n"
  42    "- a number of SFXStates that are activated when entering the space and deactivated when exiting it.\n"
  43    "\n"
  44
  45    "Each of these properties is optional.\n\n"
  46
  47    "An important characteristic of ambient audio spaces is that their unique nature is not determined by their location "
  48    "in space but rather by their SFXAmbience datablock.  This means that the same SFXAmbience datablock assigned to "
  49    "multiple locations in a level represents the same unique audio space to the sound system.\n\n"
  50
  51    "This is an important distinction for the ambient sound mixer which will activate a given ambient audio space only "
  52    "once at any one time regardless of how many intersecting audio spaces with the same SFXAmbience datablock assigned "
  53    "the listener may currently be in.\n\n"
  54
  55    "All SFXAmbience instances are automatically added to the global @c SFXAmbienceSet.\n\n"
  56
  57    "At the moment, transitions between reverb environments are not blended and different reverb environments from multiple "
  58    "active SFXAmbiences will not be blended together.  This will be added in a future version.\n\n"
  59
  60    "@tsexample\n"
  61    "singleton SFXAmbience( Underwater )\n"
  62    "{\n"
  63    "   environment = AudioEnvUnderwater;\n"
  64    "   soundTrack = ScubaSoundList;\n"
  65    "   states[ 0 ] = AudioLocationUnderwater;\n"
  66    "};\n"
  67    "@endtsexample\n\n"
  68
  69    "@see SFXEnvironment\n"
  70    "@see SFXTrack\n"
  71    "@see SFXState\n"
  72    "@see LevelInfo::soundAmbience\n"
  73    "@see Zone::soundAmbience\n\n"
  74    "@ref Datablock_Networking\n"
  75    "@ingroup SFX\n"
  76    "@ingroup Datablocks\n"
  77 );
  78
  79
  80 SFXAmbience::ChangeSignal SFXAmbience::smChangeSignal;
  81
  82
  83 //-----------------------------------------------------------------------------
  84
  85 SFXAmbience::SFXAmbience()
  86    : mEnvironment( NULL ),
  87      mSoundTrack( NULL ),
  88      mRolloffFactor( 1.f ),
  89      mDopplerFactor( 0.5f )
  90 {
  91    dMemset( mState, 0, sizeof( mState ) );
  92 }
  93
  94 //-----------------------------------------------------------------------------
  95
  96 void SFXAmbience::initPersistFields()
  97 {
  98    addGroup( "Sound" );
  99
 100       addField( "environment",            TypeSFXEnvironmentName, Offset( mEnvironment, SFXAmbience ),
 101          "Reverb environment active in the ambience zone.\n"
 102          "@ref SFX_reverb" );
 103       addField( "soundTrack",             TypeSFXTrackName,       Offset( mSoundTrack, SFXAmbience ),
 104          "Sound track to play in the ambience zone." );
 105       addField( "rolloffFactor",          TypeF32, Offset( mRolloffFactor, SFXAmbience ),
 106          "The rolloff factor to apply to distance-based volume attenuation in this space.\n"
 107          "Defaults to 1.0.\n\n"
 108          "@note This applies to the logarithmic distance model only.\n\n"
 109          "@ref SFXSource_volume" );
 110       addField( "dopplerFactor",          TypeF32, Offset( mDopplerFactor, SFXAmbience ),
 111          "The factor to apply to the doppler affect in this space.\n"
 112          "Defaults to 0.5.\n\n"
 113          "@ref SFXSource_doppler" );
 114       addField( "states",                 TypeSFXStateName,       Offset( mState, SFXAmbience ),
 115          MaxStates,
 116          "States to activate when the ambient zone is entered.\n"
 117          "When the ambient sound state is entered, all states associated with the state will "
 118          "be activated (given that they are not disabled) and deactivated when the space "
 119          "is exited again." );
 120
 121    endGroup( "Sound" );
 122
 123    Parent::initPersistFields();
 124 }
 125
 126 //-----------------------------------------------------------------------------
 127
 128 bool SFXAmbience::onAdd()
 129 {
 130    if( !Parent::onAdd() )
 131       return false;
 132
 133    Sim::getSFXAmbienceSet()->addObject( this );
 134
 135    return true;
 136 }
 137
 138 //-----------------------------------------------------------------------------
 139
 140 bool SFXAmbience::preload( bool server, String& errorStr )
 141 {
 142    if( !Parent::preload( server, errorStr ) )
 143       return false;
 144
 145    validate();
 146
 147    // Resolve datablocks on client.
 148
 149    if( !server )
 150    {
 151       if( !sfxResolve( &mEnvironment, errorStr ) )
 152          return false;
 153
 154       if( !sfxResolve( &mSoundTrack, errorStr ) )
 155          return false;
 156
 157       for( U32 i = 0; i < MaxStates; ++ i )
 158          if( !sfxResolve( &mState[ i ], errorStr ) )
 159             return false;
 160    }
 161
 162    return true;
 163 }
 164
 165 //-----------------------------------------------------------------------------
 166
 167 void SFXAmbience::packData( BitStream* stream )
 168 {
 169    Parent::packData( stream );
 170
 171    sfxWrite( stream, mEnvironment );
 172    sfxWrite( stream, mSoundTrack );
 173
 174    stream->write( mRolloffFactor );
 175    stream->write( mDopplerFactor );
 176
 177    for( U32 i = 0; i < MaxStates; ++ i )
 178       sfxWrite( stream, mState[ i ] );
 179 }
 180
 181 //-----------------------------------------------------------------------------
 182
 183 void SFXAmbience::unpackData( BitStream* stream )
 184 {
 185    Parent::unpackData( stream );
 186
 187    sfxRead( stream, &mEnvironment );
 188    sfxRead( stream, &mSoundTrack );
 189
 190    stream->read( &mRolloffFactor );
 191    stream->read( &mDopplerFactor );
 192
 193    for( U32 i = 0; i < MaxStates; ++ i )
 194       sfxRead( stream, &mState[ i ] );
 195 }
 196
 197 //-----------------------------------------------------------------------------
 198
 199 void SFXAmbience::inspectPostApply()
 200 {
 201    Parent::inspectPostApply();
 202
 203    validate();
 204
 205    smChangeSignal.trigger( this );
 206 }
 207
 208 //-----------------------------------------------------------------------------
 209
 210 void SFXAmbience::validate()
 211 {
 212 }