sfxProfile.h

Classes:

class
The SFXProfile is used to define a sound for playback.
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
 29#ifndef _SFXPROFILE_H_
 30#define _SFXPROFILE_H_
 31
 32#ifndef _SFXTRACK_H_
 33   #include "sfx/sfxTrack.h"
 34#endif
 35#ifndef _SFXRESOURCE_H_
 36   #include "sfx/sfxResource.h"
 37#endif
 38#ifndef _SFXBUFFER_H_
 39   #include "sfx/sfxBuffer.h"
 40#endif
 41#ifndef _SFXSYSTEM_H_
 42   #include "sfx/sfxSystem.h"
 43#endif
 44#ifndef _TSIGNAL_H_
 45   #include "core/util/tSignal.h"
 46#endif
 47
 48
 49class SFXDescription;
 50
 51
 52/// The SFXProfile is used to define a sound for playback.
 53///
 54/// An SFXProfile will first try to load its file directly through the SFXDevice.
 55/// Only if this fails (which is the case for most SFXDevices as these do not
 56/// implement their own custom sound format loading), the file is loaded through
 57/// SFXResource.
 58///
 59/// A few tips:
 60///
 61/// Make sure each of the defined SFXProfile's fileName doesn't specify 
 62/// an extension. An extension does not need to be specified and by not
 63/// explicitly saying .ogg or .wav it will allow you to change from one 
 64/// format to the other without having to change the scripts.
 65///
 66/// Make sure that server SFXProfiles are defined with the datablock 
 67/// keyword, and that client SFXProfiles are defined with the 'new' 
 68/// keyword.
 69///
 70/// Make sure SFXDescriptions exist for your SFXProfiles. Also make sure
 71/// that SFXDescriptions are defined BEFORE SFXProfiles. This is especially
 72/// important if your SFXProfiles are located in different files than your
 73/// SFXDescriptions. In this case, make sure the files containing SFXDescriptions
 74/// are exec'd before the files containing the SFXProfiles.
 75///
 76/// @note Live asset update will not work with files loaded directly through
 77///   the SFXDevice.
 78class SFXProfile : public SFXTrack
 79{
 80   public:
 81   
 82      friend class SFXEmitter; // For access to mFilename
 83      
 84      typedef SFXTrack Parent;
 85      
 86      typedef Signal< void( SFXProfile* ) > ChangedSignal;
 87
 88   protected:
 89
 90      /// The sound data.
 91      /// @note ATM only valid if loaded through SFX's loading system rather than
 92      ///   through the SFXDevice's loading system.
 93      Resource< SFXResource> mResource;
 94      
 95      /// The sound filename.  If no extension is specified
 96      /// the system will try .wav first then other formats.
 97      String mFilename;
 98
 99      /// If true the sound data will be loaded from
100      /// disk and possibly cached with the active 
101      /// device before the first call for playback.
102      bool mPreload;
103
104      /// The device specific data buffer.
105      /// This is only used if for non-streaming sounds.
106      StrongWeakRefPtr< SFXBuffer> mBuffer;
107      
108      ///
109      ChangedSignal mChangedSignal;
110
111      /// Called when the buffer needs to be preloaded.
112      bool _preloadBuffer();
113
114      /// Callback for device events.
115      void _onDeviceEvent( SFXSystemEventType evt );
116
117      ///
118      SFXBuffer* _createBuffer();
119      
120      ///
121      void _onResourceChanged( const Torque::Path& path );
122      
123      ///
124      void _registerSignals();
125      
126      ///
127      void _unregisterSignals();
128
129   public:
130
131      /// This is only here to allow DECLARE_CONOBJECT 
132      /// to create us from script.  You shouldn't use
133      /// this constructor from C++.
134      explicit SFXProfile();
135
136      /// The constructor.
137      SFXProfile( SFXDescription* desc, 
138                  const String& filename = String(), 
139                  bool preload = false );
140
141      /// The destructor.
142      virtual ~SFXProfile();
143
144      DECLARE_CONOBJECT( SFXProfile );
145
146      static void initPersistFields();
147      
148      // SFXTrack.
149      virtual bool isLooping() const;
150
151      // SimObject 
152      bool onAdd();
153      void onRemove();
154      void packData( BitStream* stream );
155      void unpackData( BitStream* stream );
156
157      /// Returns the sound filename.
158      const String& getSoundFileName() const { return mFilename; }
159
160      /// @note This has nothing to do with mPreload.
161      /// @see SimDataBlock::preload
162      bool preload( bool server, String &errorStr );
163
164      /// Returns the sound resource loading it from
165      /// disk if it hasn't been preloaded.
166      ///
167      /// @note May be NULL if file is loaded directly through SFXDevice.
168      Resource<SFXResource>& getResource();
169
170      /// Returns the device specific buffer for this for this 
171      /// sound.  If it hasn't been preloaded it will be loaded
172      /// at this time.
173      ///
174      /// If this is a streaming profile then the buffer
175      /// returned must be deleted by the caller.
176      SFXBuffer* getBuffer();
177
178      /// Gets the sound duration in milliseconds or 
179      /// returns 0 if the resource was not found.
180      U32 getSoundDuration();
181      
182      ///
183      ChangedSignal& getChangedSignal() { return mChangedSignal; }
184   public:
185      /*C*/          SFXProfile(const SFXProfile&, bool = false);
186      SFXProfile*    cloneAndPerformSubstitutions(const SimObject*, S32 index=0);
187      virtual void   onPerformSubstitutions();
188      virtual bool   allowSubstitutions() const { return true; }
189};
190
191
192#endif  // _SFXPROFILE_H_
193