home *** CD-ROM | disk | FTP | other *** search
/ Game Audio Programming / GameAudioProgramming.iso / Game_Audio / audio_sdk / include / AudioScript / ISound.h < prev   
Encoding:
C/C++ Source or Header  |  2002-07-25  |  8.9 KB  |  264 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 ISOUND_H__
  12. #define ISOUND_H__
  13.  
  14. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  15. namespace Audio
  16. {
  17. #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  18.  
  19. /*! \file ISound.h*/ 
  20.  
  21. //! struct used for initializing a background looping element
  22. struct BackgroundInit
  23. {
  24.     //! Constructor clears all values to defaults
  25.     BackgroundInit()    {  Clear();  }
  26.     //! Clears all structure members to default values
  27.     void Clear()
  28.     {
  29.         m_pSound = 0;
  30.         m_fMinVolume = 1.0f;
  31.         m_fMaxVolume = 1.0f;
  32.         m_fMinVolumeTime = 0.0f;
  33.         m_fMaxVolumeTime = 0.0f;
  34.         m_fMinPitch = 1.0f;
  35.         m_fMaxPitch = 1.0f;
  36.         m_fMinPitchTime = 0.0f;
  37.         m_fMaxPitchTime = 0.0f;
  38.     };
  39.  
  40.     //! Sound to play as background loop
  41.     ISound*                m_pSound;
  42.     //! Minimum sound volume
  43.     float                m_fMinVolume;
  44.     //! Maximum sound volume
  45.     float                m_fMaxVolume;
  46.     //! Minimum time to take when transitioning to a new volume
  47.     float                m_fMinVolumeTime;
  48.     //! Maximum time to take when transitioning to a new volume
  49.     float                m_fMaxVolumeTime;
  50.     //! Minimum sound pitch
  51.     float                m_fMinPitch;
  52.     //! Maximum sound pitch
  53.     float                m_fMaxPitch;
  54.     //! Minimum time to take when transitioning to a new pitch
  55.     float                m_fMinPitchTime;
  56.     //! Maximum time to take when transitioning to a new pitch
  57.     float                m_fMaxPitchTime;
  58. };
  59.  
  60. //! struct used for initializing a peroidic element
  61. struct PeriodicInit
  62. {
  63.     //! Constructor clears all values to defaults
  64.     PeriodicInit()    {  Clear();  }
  65.     //! Clears all structure members to default values
  66.     void Clear()
  67.     {
  68.         m_pSound3D = 0;
  69.         m_fMinPitch = 1.0f;
  70.         m_fMaxPitch = 1.0f;
  71.         m_fMinDelay = 0.0f;
  72.         m_fMaxDelay = 0.0f;
  73.         m_fXRange = 25.0f;
  74.         m_fYRange = 25.0f;
  75.         m_fZRange = 25.0f;
  76.         m_fMinDistance = 0.0f;
  77.     };
  78.     //! 3D Sound to play as periodic element
  79.     ISound3D*            m_pSound3D;
  80.     //! Minimum random pitch
  81.     float                m_fMinPitch;
  82.     //! Maximum random pitch
  83.     float                m_fMaxPitch;
  84.     //! Minimum delay between random plays
  85.     float                m_fMinDelay;
  86.     //! Maximum delay between random plays
  87.     float                m_fMaxDelay;
  88.     //! Maximum distance from listener on the x axis (both pos and neg)
  89.     float                m_fXRange;
  90.     //! Maximum distance from listener on the y axis (both pos and neg)
  91.     float                m_fYRange;
  92.     //! Maximum distance from listener on the z axis (both pos and neg)
  93.     float                m_fZRange;
  94.     //! Minimum distance from listener on all axes
  95.     float                m_fMinDistance;
  96. };
  97.  
  98.  
  99. //! Class defining a collection of sounds which make up a soundscape
  100. /*!
  101. ISoundScape represents a collection of looping background sounds and
  102. randomly firing 3D positional elements which can be collectively
  103. adjusted and controlled via the IPlayable interface.
  104. */
  105. class ISoundScape : public IPlayable
  106. {
  107. public:
  108.     virtual bool Init() = 0;
  109.  
  110.     /*!
  111.     Adds a background element to the soundscape.
  112.     \param init defines the characteristics of the background element
  113.     \return true indicates success, false indicates failure.
  114.     */
  115.     virtual bool AddElement(const BackgroundInit& init) = 0;
  116.     /*!
  117.     Adds a periodic element to the soundscape.
  118.     \param init defines the characteristics of the periodic element
  119.     \return true indicates success, false indicates failure.
  120.     */
  121.     virtual bool AddElement(const PeriodicInit& init) = 0;
  122.  
  123.     /*!
  124.     Sets the collective volume of a soundscape.  This value will decrease
  125.     the volume in addition to any decrease from maximum volume set in the master
  126.     volume controls.  
  127.     \param fVolume sets the volume desired
  128.     \return true indicates success, false indicates failure.
  129.     \sa GetVolume()
  130.     */
  131.     virtual bool SetVolume(float fVolume) = 0;
  132.     /*!
  133.     Gets the volume for this soundscape.
  134.     \param fVolume retrieves the current object's volume
  135.     \return true indicates success, false indicates failure.
  136.     \sa SetVolume()
  137.     */
  138.     virtual bool GetVolume(float& fVolume) const = 0;
  139.  
  140. };
  141.  
  142. //! Controls and manages high-level sound objects
  143. /*!
  144. ISoundManager is responsible for managing high-level sound objects, including
  145. multiple-instance ISound and ISound3D objects, and ISoundScape objects.  Definitions
  146. are loaded using a text-based script, and individual objects are instantiated using
  147. the string-based identifiers found in the scripts.
  148. */
  149. class ISoundManager
  150. {
  151. public:
  152.  
  153.     /*!
  154.     Initializes the sound manager.  This must be called after the low-level
  155.     audio manager has been initalized, and before any other sound manager
  156.     calls are made, except for IsInitialized().
  157.     \return true indicates success, false indicates failure.
  158.     \sa Term(), IsInitialized()
  159.     */
  160.     virtual bool Init() = 0;
  161.     /*!
  162.     Shuts down the sound manager.  This should be called before the low-level
  163.     audio manager is shut down.  Any calls made to this interface after Term() is
  164.     called will fail except for Init() and IsInitialized(), which simply reports
  165.     status and cannot fail.
  166.     \sa Init(), IsInitialized()
  167.     */
  168.     virtual void Term() = 0;
  169.     /*!
  170.     Determines if the sound manager is initialized.
  171.     \return true indicates the manager is initialized, false indicates the 
  172.     manager is not initialized.
  173.     \sa Init(), Term()
  174.     */
  175.     virtual bool IsInitialized() = 0;
  176.  
  177.     /*!
  178.     Loads a sound script containing ISound, ISound3D, or ISoundScape
  179.     definitions.
  180.     \param sFileName name of the sound script to load
  181.     \return true indicates success, false indicates failure.
  182.     \sa RemoveAll()
  183.     */
  184.     virtual bool LoadScript(std::string sFileName) = 0;
  185.     /*!
  186.     Removes all ISound, ISound3D, and ISoundscape definitions.  In addition,
  187.     all sound objects currently associated with ISound or ISound3D
  188.     definitions will be removed.
  189.     \param sFileName name of the sound script to load
  190.     \return true indicates success, false indicates failure.
  191.     \sa RemoveAll()
  192.     */
  193.     virtual bool RemoveAll() = 0;
  194.  
  195.     /*!
  196.     Gets a cached sound if one is available.  If not, the function
  197.     creates and returns a new sound object.
  198.     \param sSoundName name of the sound definition as defined 
  199.     in a loaded script file.
  200.     \param pSound ISound interface to retrieve.
  201.     \return true indicates success, false indicates failure.
  202.     \sa ReleaseSound()
  203.     */
  204.     virtual bool GetSound(std::string sSoundName, ISound*& pSound) = 0;
  205.     /*!
  206.     Retrieves a sound initialization structure for a given sound script
  207.     definition.  This allows you to create sounds indepenent of the 
  208.     sound caching mechanism while still using the script system.
  209.     \return true indicates success, false indicates failure.
  210.     */
  211.     virtual bool GetSoundInit(std::string sSoundName, SoundInit& init) = 0;
  212.     virtual bool ReleaseSound(std::string sSoundName, ISound* pSound) = 0;
  213.     virtual bool IsSoundRegistered(std::string sSoundName) = 0;
  214.     virtual void ResetSoundItr() = 0;
  215.     virtual bool GetNextSound(std::string& sSoundName) = 0;
  216.     virtual bool RemoveSound(std::string sSoundName) = 0;
  217.     virtual bool RemoveAllSounds() = 0;
  218.  
  219.     /*!
  220.     Gets a cached 3D sound if one is available.  If not, the function
  221.     creates and returns a new 3D sound object.
  222.     \param sSound3DName name of the 3D sound definition as defined 
  223.     in a loaded script file.
  224.     \param pSound3D ISound3D interface to retrieve.
  225.     \return true indicates success, false indicates failure.
  226.     \sa ReleaseSound3D()
  227.     */
  228.     virtual bool GetSound3D(std::string sSound3DName, ISound3D*& pSound3D) = 0;
  229.     /*!
  230.     Retrieves a 3D sound initialization structure for a given sound script
  231.     definition.  This allows you to create 3D sounds indepenent of the 
  232.     sound caching mechanism while still using the script system.
  233.     \return true indicates success, false indicates failure.
  234.     */
  235.     virtual bool GetSound3DInit(std::string sSound3DName, Sound3DInit& init) = 0;
  236.     virtual bool ReleaseSound3D(std::string sSound3DName, ISound3D* pSound3D) = 0;
  237.     virtual bool IsSound3DRegistered(std::string sSound3DName) = 0;
  238.     virtual void ResetSound3DItr() = 0;
  239.     virtual bool GetNextSound3D(std::string& sSound3DName) = 0;
  240.     virtual bool RemoveSound3D(std::string sSound3DName) = 0;
  241.     virtual bool RemoveAllSounds3D() = 0;
  242.  
  243.     virtual bool CreateSoundScape(ISoundScape*& pSoundScape) = 0;
  244.     virtual bool InitSoundScape(std::string sSoundScapeName, ISoundScape*& pSoundScape) = 0;
  245.     virtual bool IsSoundScapeRegistered(std::string sSoundScapeName) = 0;
  246.     virtual void ResetSoundScapeItr() = 0;
  247.     virtual bool GetNextSoundScape(std::string& sSoundScapeName) = 0;
  248.     virtual bool RemoveSoundScape(std::string sSoundScapeName) = 0;
  249.     virtual bool RemoveAllSoundScapes() = 0;
  250. };
  251.  
  252. /*!
  253. SoundMgr() is used to access a single static sound manager object from anywhere 
  254. in the code.
  255. \sa ISoundManager
  256. */
  257. inline static ISoundManager* SoundMgr()
  258. {  return AudioScriptFactory::GetSoundMgr();  }
  259.  
  260. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  261. }; // namespace Audio
  262. #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  263.  
  264. #endif // ISOUND_H__