sfxDescription.h
Engine/source/sfx/sfxDescription.h
Classes:
class
The SFXDescription defines how a sound should be played.
Detailed Description
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 _SFXDESCRIPTION_H_ 25#define _SFXDESCRIPTION_H_ 26 27#ifndef _CONSOLETYPES_H_ 28 #include "console/consoleTypes.h" 29#endif 30#ifndef _SIMDATABLOCK_H_ 31 #include "console/simDatablock.h" 32#endif 33#ifndef _MPOINT3_H_ 34 #include "math/mPoint3.h" 35#endif 36#ifndef _SFXCOMMON_H_ 37 #include "sfx/sfxCommon.h" 38#endif 39#ifndef _MEASE_H_ 40 #include "math/mEase.h" 41#endif 42 43 44class SFXSource; 45 46 47/// The SFXDescription defines how a sound should be played. 48/// 49/// If mConeInsideAngle and mConeOutsideAngle are not both 50/// 360 then the sound will be directional and facing out 51/// the Y axis. To reorient the cones, reorient the emitter 52/// object. 53/// 54/// A few tips: 55/// 56/// Make sure that server SFXDescription are defined with the 57/// datablock keyword, and that client SFXDescription are defined 58/// with the 'new' or 'singleton' keyword. 59/// 60class SFXDescription : public SimDataBlock 61{ 62 typedef SimDataBlock Parent; 63 64 public: 65 66 enum 67 { 68 MaxNumParameters = 8, 69 }; 70 71 /// The 0 to 1 volume scale. 72 F32 mVolume; 73 74 /// The pitch scale. 75 F32 mPitch; 76 77 /// If true the sound will loop. 78 bool mIsLooping; 79 80 /// If true the sound data will be streamed from 81 /// disk and not loaded completely into memory. 82 bool mIsStreaming; 83 84 /// If true the sound will be 3D positional. 85 bool mIs3D; 86 87 /// If this sound is allowed to be mixed in hardware. 88 bool mUseHardware; 89 90 /// If true the sound uses custom reverb properties. 91 bool mUseReverb; 92 93 /// The distance from the emitter at which the 94 /// sound volume is unchanged. Beyond this distance 95 /// the volume begins to falloff. 96 /// 97 /// This is only valid for 3D sounds. 98 F32 mMinDistance; 99 100 /// The distance from the emitter at which the 101 /// sound volume becomes zero. 102 /// 103 /// This is only valid for 3D sounds. 104 F32 mMaxDistance; 105 106 /// The angle in degrees of the inner part of 107 /// the cone. It must be within 0 to 360. 108 /// 109 /// This is only valid for 3D sounds. 110 U32 mConeInsideAngle; 111 112 /// The angle in degrees of the outer part of 113 /// the cone. It must be greater than mConeInsideAngle 114 /// and less than to 360. 115 /// 116 /// This is only valid for 3D sounds. 117 U32 mConeOutsideAngle; 118 119 /// The volume scalar for on/beyond the outside angle. 120 /// 121 /// This is only valid for 3D sounds. 122 F32 mConeOutsideVolume; 123 124 /// Local logarithmic distance attenuation rolloff factor. -1 to use global setting. 125 /// Per-sound rolloff settings only supported with some SFX providers. 126 F32 mRolloffFactor; 127 128 /// Max distance in both directions along each axis by which the 129 /// sound position of a 3D sound will be randomly scattered. 130 /// 131 /// Example: if you set x=5, then the final x coordinate of the 3D 132 /// sound will be (OriginalX + randF( -5, +5 )). 133 Point3F mScatterDistance; 134 135 /// The source to which sources playing with this description will 136 /// be added. 137 SFXSource* mSourceGroup; 138 139 /// Number of seconds until playback reaches full volume after starting/resuming. 140 /// Zero to deactivate (default). 141 F32 mFadeInTime; 142 143 /// Number of seconds to fade out fading before stopping/pausing. 144 /// Zero to deactivate (default). 145 F32 mFadeOutTime; 146 147 /// Easing curve for fade-in. 148 EaseF mFadeInEase; 149 150 /// Easing curve for fade-out. 151 EaseF mFadeOutEase; 152 153 /// When mIsLooping is true, the fades will apply to each cycle. Otherwise, only 154 /// the first cycle will have a fade-in applied and no fade-out happens when a cycle 155 /// ends. 156 /// 157 /// This also affects the playtime that is used to place fades. If mFadeLoops is 158 /// false, the total playtime so far will be used rather than the playtime of the 159 /// current cycle. This makes it possible to apply fades that extend across two or 160 /// more loops of the sound, i.e. are longer than the actual sound duration. 161 bool mFadeLoops; 162 163 /// The number of seconds of sound data to read per streaming 164 /// packet. Only relevant if "isStreaming" is true. 165 U32 mStreamPacketSize; 166 167 /// The number of streaming packets to read and buffer in advance. 168 /// Only relevant if "isStreaming" is true. 169 U32 mStreamReadAhead; 170 171 /// Reverb properties for sound playback. 172 SFXSoundReverbProperties mReverb; 173 174 /// Parameters to which sources playing with this description should automatically 175 /// connect when created. 176 StringTableEntry mParameters[ MaxNumParameters ]; 177 178 /// Priority level for sounds. Higher priority sounds are less likely to be 179 /// culled. 180 F32 mPriority; 181 182 SFXDescription(); 183 SFXDescription( const SFXDescription& desc ); 184 DECLARE_CONOBJECT( SFXDescription ); 185 static void initPersistFields(); 186 187 // SimDataBlock. 188 virtual bool onAdd(); 189 virtual void packData( BitStream* stream ); 190 virtual void unpackData( BitStream* stream ); 191 virtual void inspectPostApply(); 192 193 /// Validates the description fixing any 194 /// parameters that are out of range. 195 void validate(); 196}; 197 198 199#endif // _SFXDESCRIPTION_H_ 200