sfxFMODProject.h

Classes:

class
Datablock that loads an FMOD Designer project.
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 _SFXFMODPROJECT_H_
 25#define _SFXFMODPROJECT_H_
 26
 27#ifndef _SIMDATABLOCK_H_
 28   #include "console/simDatablock.h"
 29#endif
 30#ifndef _CONSOLETYPES_H_
 31   #include "console/consoleTypes.h"
 32#endif
 33#ifndef _TVECTOR_H_
 34   #include "core/util/tVector.h"
 35#endif
 36#ifndef _SFXSYSTEM_H_
 37   #include "sfx/sfxSystem.h"
 38#endif
 39
 40#include "fmod_event.h"
 41
 42
 43class SFXFMODEvent;
 44class SFXFMODEventGroup;
 45class SimGroup;
 46
 47
 48
 49/// Datablock that loads an FMOD Designer project.
 50///
 51/// All events in the project are automatically made available as SFXFMODEvent track
 52/// datablock instances.  Each event object is automatically named by substituting
 53/// the slashes in its fully qualified name with underscores and preprending the project
 54/// name to this; event 'group1/group2/event' in the SFXFMODProject instance called
 55/// 'project', for example, will be available as a TorqueScript object called
 56/// 'project_group1_group2_event'.
 57///
 58/// This class also works in a client-server environment where the server is
 59/// not running FMOD.  The event objects are cached in an auto-generated TorqueScript
 60/// file alongside the .fev project file (x/y.fev -> x/y.fev.cs) which, when available
 61/// and up-to-date, does not require FMOD for the server-side objects to correctly
 62/// initialize.
 63///
 64/// To establish good loading behavior and for good memory management, it is necessary to
 65/// wisely distribute events to groups and to manually pre-load groups.  The best solution
 66/// probably is to have one group of common events that is loaded during game startup and
 67/// then have one event group for each level in the game that is only loaded for the
 68/// duration of its particular level.
 69///
 70/// SFXFMODProject will propagate it's networking model to all its contents.  This means
 71/// that if the project is a non-networked datablock, then all event groups, events, and
 72/// descriptions contained in the project will also be non-networked datablocks.
 73///
 74/// It usually makes the most sense to use non-networked ("client-only") datablocks as
 75/// otherwise the FMOD datablocks will be purged on each mission load.
 76///
 77/// @note Only one project's music data can ever be loaded at any one time.
 78///   Usually you wouldn't want more than a single SFXFMODProject instance in your game
 79///   data.  Also, only a single media path can be set through the designer API so when
 80///   loading multiple projects, note that each project will set the media path to its
 81///   own directory.  For data loading to work, all project thus need to be placed in
 82///   the same directory.
 83///
 84class SFXFMODProject : public SimDataBlock
 85{
 86   public:
 87   
 88      typedef SimDataBlock Parent;
 89      friend class SFXFMODEventGroup; // _addGroup
 90      friend class SFXFMODEvent; // _addEvent
 91      
 92   protected:
 93   
 94      ///
 95      String mFileName;
 96      
 97      ///
 98      String mMediaPath;
 99      
100      ///
101      SFXFMODEventGroup* mRootGroups;
102      
103      /// A flat list of all the groups in this projet.
104      Vector< SFXFMODEventGroup*> mGroups;
105
106      /// A flat list of all the events in the project.
107      Vector< SFXFMODEvent*> mEvents;
108      
109      ///
110      FMOD_EVENTPROJECT* mHandle;
111      
112      ///
113      void _onSystemEvent( SFXSystemEventType event );
114      
115      ///
116      void _clear();
117      
118      ///
119      bool _load();
120      
121      ///
122      void _addEvent( SFXFMODEvent* event );
123      
124      ///
125      void _addGroup( SFXFMODEventGroup* group );
126      
127      ///
128      void _removeEvent( SFXFMODEvent* event );
129      
130      ///
131      void _removeGroup( SFXFMODEventGroup* group );
132   
133   public:
134   
135      ///
136      SFXFMODProject();
137      
138      virtual ~SFXFMODProject();
139            
140      ///
141      void acquire( bool recursive = false );
142      
143      ///
144      void release();
145      
146      ///
147      const String& getFileName() const { return mFileName; }
148
149      // SimDataBlock.
150      virtual bool onAdd();
151      virtual void onRemove();
152      virtual bool preload( bool server, String& errorStr );
153      virtual void packData( BitStream* stream );
154      virtual void unpackData( BitStream* stream );
155      
156      static void initPersistFields();
157   
158      DECLARE_CONOBJECT( SFXFMODProject );
159      DECLARE_CATEGORY( "SFX FMOD" );
160      DECLARE_DESCRIPTION( "An FMOD Designer project." );
161};
162
163#endif // !_SFXFMODPROJECT_H_
164