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