home *** CD-ROM | disk | FTP | other *** search
/ Game Audio Programming / GameAudioProgramming.iso / Game_Audio / audio_sdk / include / AudioScript / IMusic.h < prev    next >
Encoding:
C/C++ Source or Header  |  2002-07-25  |  3.9 KB  |  122 lines
  1. /***********************************************************\
  2. Copyright (C) James Boer, 2002. 
  3. All rights reserved worldwide.
  4.  
  5. This software is provided "as is" without express or implied
  6. warranties. You may freely copy and compile this source into
  7. applications you distribute provided that the copyright text
  8. below is included in the resulting source code, for example:
  9. "Portions Copyright (C) James Boer, 2002"
  10. \***********************************************************/
  11. #ifndef IMUSIC_H__
  12. #define IMUSIC_H__
  13.  
  14. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  15. namespace Audio
  16. {
  17. #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  18.  
  19. /*! \file IMusic.h*/ 
  20.  
  21. //! High-level music management interface class
  22. /*!
  23. This class allows loading and playback of music scripts.
  24. Each script contains a number of themes, each containing a
  25. complete transition mapping of segments.  Different themes
  26. may be transitioned to at run-time, and specific transition
  27. mappings based on segments or themes may be defined.
  28. */
  29. class IMusicManager : public IMusicCallback
  30. {
  31. public:
  32.  
  33.     /*!
  34.     Initializes the music manager.  This must be called
  35.     after IAudioManager::Init() is called.
  36.     \return true indicates success, false indicates failure
  37.     \sa Term(), IAudioManager::Init()
  38.     */
  39.     virtual bool Init() = 0;
  40.     /*!
  41.     Shuts down the music manager.  This must be called
  42.     before IAudioManager::Term() is called.
  43.     \sa Init(), IAudioManager::Term()
  44.     */
  45.     virtual void Term() = 0;
  46.     /*!
  47.     Determines if the music manager is initialized.
  48.     \return true indicates the manager is initialized, false indicates the 
  49.     manager is not initialized.
  50.     \sa Init(), Term()
  51.     */
  52.     virtual bool IsInitialized() = 0;
  53.  
  54.     /*!
  55.     Loads a music script and all associated segments, DLS
  56.     collections, and themes.
  57.     \param sFileName is the name of the script file to load
  58.     \return true indicates success, false indicates failure
  59.     \sa RemoveTheme(), RemoveAll()
  60.     */
  61.     virtual bool LoadScript(std::string sFileName) = 0;
  62.  
  63.     /*!
  64.     Plays a new theme based on its given script string ID
  65.     \param sThemeName is the name of the theme ID as defined
  66.     in the script file.  There is no method to stop the
  67.     theme.  Instead, simply retrieve the current theme
  68.     from the audio manager and stop it in the normal
  69.     fashion.
  70.     \return true indicates success, false indicates failure
  71.     \sa IAudioManager::GetCurrentSegment(), IPlayable::Stop()
  72.     */
  73.     virtual bool PlayTheme(std::string sThemeName) = 0;
  74.     /*!
  75.     Resets an internal iterator used to cycle though and
  76.     retrieve all currently registered themes.
  77.     \sa GetNextTheme()
  78.     */
  79.     virtual void ResetThemeItr() = 0;
  80.     /*!
  81.     Retrieves the next theme name.  This function can be called
  82.     repeatedly until it returns false.
  83.     \param sThemeName contains the name of the retrieved
  84.     theme unless the function returns false, in which case
  85.     the string will remain unmodified.
  86.     \return true indicates another theme was found, false
  87.     indicates that no more themes were found.
  88.     \sa ResetThemeItr()
  89.     */
  90.     virtual bool GetNextTheme(std::string& sThemeName) = 0;
  91.     /*!
  92.     Removes a specific theme from the active set.  Keep in 
  93.     mind that only the theme definition, not any associated
  94.     segments and DLS files are removed, since these are
  95.     defined independently of the themes.
  96.     */
  97.     virtual bool RemoveTheme(std::string& sThemeName) = 0;
  98.  
  99.     /*!
  100.     Removes all segments, DLS collections, and themes
  101.     currently mapped in the music manager.  This is provided
  102.     as a convenient method of clearing out all current
  103.     musical content loaded from any number of scripts.
  104.     \return true indicates success, false indicates failure
  105.     */
  106.     virtual bool RemoveAll() = 0;
  107. };
  108.  
  109. /*!
  110. MusicMgr() is used to access a single static sound manager object from anywhere 
  111. in the code.
  112. \sa IMusicManager
  113. */
  114. inline static IMusicManager* MusicMgr()
  115. {  return AudioScriptFactory::GetMusicMgr();  }
  116.  
  117. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  118. }; // namespace Audio
  119. #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  120.  
  121.  
  122. #endif // IMUSIC_H__