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