sfxEmitter.h
Engine/source/T3D/sfx/sfxEmitter.h
Classes:
class
The SFXEmitter is used to place 2D or 3D sounds into a mission.
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 _SFXEMITTER_H_ 25#define _SFXEMITTER_H_ 26 27#ifndef _SCENEOBJECT_H_ 28 #include "scene/sceneObject.h" 29#endif 30#ifndef _SFXPROFILE_H_ 31 #include "sfx/sfxProfile.h" 32#endif 33#ifndef _SFXDESCRIPTION_H_ 34 #include "sfx/sfxDescription.h" 35#endif 36#ifndef _GFXSTATEBLOCK_H_ 37 #include "gfx/gfxStateBlock.h" 38#endif 39 40 41class SFXSource; 42class SFXTrack; 43 44//RDTODO: make 3D sound emitters yield their source when being culled 45 46/// The SFXEmitter is used to place 2D or 3D sounds into a 47/// mission. 48/// 49/// If the profile is set then the emitter plays that. If the 50/// profile is null and the filename is set then the local emitter 51/// options are used. 52/// 53/// Note that you can call SFXEmitter.play() and SFXEmitter.stop() 54/// to control playback from script. 55/// 56class SFXEmitter : public SceneObject 57{ 58 public: 59 60 typedef SceneObject Parent; 61 62 protected: 63 64 /// Network update masks. 65 enum UpdateMasks 66 { 67 InitialUpdateMask = BIT(0), 68 TransformUpdateMask = BIT(1), 69 DirtyUpdateMask = BIT(2), 70 71 SourcePlayMask = BIT(3), 72 SourceStopMask = BIT(4), 73 74 AllSourceMasks = SourcePlayMask | SourceStopMask, 75 }; 76 77 /// Dirty flags used to handle sound property 78 /// updates locally and across the network. 79 enum Dirty 80 { 81 Track = BIT( 0 ), 82 Filename = BIT( 2 ), 83 Volume = BIT( 4 ), 84 IsLooping = BIT( 5 ), 85 Is3D = BIT( 6 ), 86 MinDistance = BIT( 7 ), 87 MaxDistance = BIT( 8 ), 88 ConeInsideAngle = BIT( 9 ), 89 ConeOutsideAngle = BIT( 10 ), 90 ConeOutsideVolume = BIT( 11 ), 91 Transform = BIT( 12 ), 92 SourceGroup = BIT( 13 ), 93 OutsideAmbient = BIT( 14 ), 94 IsStreaming = BIT( 15 ), 95 FadeInTime = BIT( 16 ), 96 FadeOutTime = BIT( 17 ), 97 Pitch = BIT( 18 ), 98 ScatterDistance = BIT( 19 ), 99 TrackOnly = BIT( 20 ), 100 101 AllDirtyMask = 0xFFFFFFFF, 102 }; 103 104 /// The current dirty flags. 105 BitSet32 mDirty; 106 107 /// The sound source for the emitter. 108 SFXSource *mSource; 109 110 /// The selected track or null if the local 111 /// profile should be used. 112 SFXTrack *mTrack; 113 114 /// Whether to leave sound setup exclusively to the assigned mTrack and not 115 /// override part of the track's description with emitter properties. 116 bool mUseTrackDescriptionOnly; 117 118 /// A local profile object used to coax the 119 /// sound system to play a custom sound. 120 SFXProfile mLocalProfile; 121 122 /// The description used by the local profile. 123 SFXDescription mDescription; 124 125 /// If true playback starts when the emitter 126 /// is added to the scene. 127 bool mPlayOnAdd; 128 129 /// State block for cone rendering in editor. 130 GFXStateBlockRef mRenderSB; 131 132 /// If true, render all emitters when in editor (not only selected one). 133 static bool smRenderEmitters; 134 135 /// Point size for rendering point clouds of emitter cones in editor. 136 /// @todo Currently not implemented. 137 static F32 smRenderPointSize; 138 139 /// 140 static F32 smRenderRadialIncrements; 141 142 /// 143 static F32 smRenderSweepIncrements; 144 145 /// 146 static F32 smRenderPointDistance; 147 148 /// Point color when emitter is playing and in range of listener. 149 static ColorI smRenderColorPlayingInRange; 150 151 /// Point color when emitter is playing but out of range of listern. 152 static ColorI smRenderColorPlayingOutOfRange; 153 154 /// Point color when emitter is not playing but in range of listener. 155 static ColorI smRenderColorStoppedInRange; 156 157 /// Point color when emitter is not playing and not in range of listener. 158 static ColorI smRenderColorStoppedOutOfRange; 159 160 /// 161 static ColorI smRenderColorInnerCone; 162 163 /// 164 static ColorI smRenderColorOuterCone; 165 166 /// 167 static ColorI smRenderColorOutsideVolume; 168 169 /// 170 static ColorI smRenderColorRangeSphere; 171 172 /// Helper which reads a flag from the stream and 173 /// updates the mDirty bits. 174 bool _readDirtyFlag( BitStream *stream, U32 flag ); 175 176 /// Called when the emitter state has been marked 177 /// dirty and the source needs to be updated. 178 void _update(); 179 180 /// Render emitter object in editor. 181 void _renderObject( ObjectRenderInst* ri, SceneRenderState* state, BaseMatInstance* overrideMat ); 182 183 /// Render visual feedback for 3D sounds in editor. 184 void _render3DVisualFeedback(); 185 186 /// 187 void _renderCone( F32 radialIncrements, 188 F32 sweepIncrements, 189 F32 pointDistance, 190 F32 startAngle, 191 F32 stopAngle, 192 F32 startVolume, 193 F32 stopVolume, 194 const ColorI& color ); 195 196 /// Return the playback status of the emitter's associated sound. 197 /// This should only be called on either the ghost or the server object if the server is running 198 /// in-process. Otherwise, the method will not return a meaningful value. 199 SFXStatus _getPlaybackStatus() const; 200 201 public: 202 203 SFXEmitter(); 204 virtual ~SFXEmitter(); 205 206 /// Return the sound source object associated with the emitter. 207 /// @note This will only return a meaningful result when called on ghost objects. 208 SFXSource* getSource() const { return mSource; } 209 210 /// Return true if this object emits a 3D sound. 211 bool is3D() const; 212 213 /// Return true if the SFX system's listener is in range of this emitter. 214 bool isInRange() const; 215 216 /// Sends network event to start playback if 217 /// the emitter source is not already playing. 218 void play(); 219 220 /// Sends network event to stop emitter 221 /// playback on all ghosted clients. 222 void stop(); 223 224 // SimObject 225 bool onAdd(); 226 void onRemove(); 227 void onStaticModified( const char *slotName, const char *newValue = NULL ); 228 U32 packUpdate( NetConnection *conn, U32 mask, BitStream *stream ); 229 void unpackUpdate( NetConnection *conn, BitStream *stream ); 230 void setTransform( const MatrixF &mat ); 231 void setScale( const VectorF &scale ); 232 bool containsPoint( const Point3F& point ) { return false; } 233 void prepRenderImage( SceneRenderState* state ); 234 void inspectPostApply(); 235 236 static void initPersistFields(); 237 static void consoleInit(); 238 239 DECLARE_CONOBJECT( SFXEmitter ); 240 DECLARE_DESCRIPTION( "A 3D object emitting sound." ); 241 DECLARE_CATEGORY( "3D Sound" ); 242}; 243 244#endif // _SFXEMITTER_H_ 245