home *** CD-ROM | disk | FTP | other *** search
/ Game Audio Programming / GameAudioProgramming.iso / Game_Audio / audio_sdk / include / AudioLib / IAudioExt.h < prev    next >
Encoding:
C/C++ Source or Header  |  2002-07-28  |  14.3 KB  |  415 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 IAUDIOEXT_H__
  12. #define IAUDIOEXT_H__
  13.  
  14. #include "3dl2.h"
  15. #include "3dl2help.h"
  16. #include "eax.h"
  17. #include "ZoomFX.h"
  18.  
  19. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  20. namespace Audio
  21. {
  22. #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  23.  
  24. /*! \file IAudioExt.h*/ 
  25.  
  26. //! EAXListenerProps is used to set all EAX listener properties at once
  27. /*!
  28. EAXListenerProps is derived from the EAX structure _EAXLISTENERPROPERTIES.
  29. The structure is made slightly more user friendly by providing a Clear()
  30. function which resets all EAX listener properties to their default 
  31. values.  The Clear() function is also automatically called when the
  32. structure is created.  Because it is derived from _EAXLISTENERPROPERTIES,
  33. it can be used interchangeably with this structure since it is binary
  34. compatible.
  35. */
  36. struct EAXListenerProps : public _EAXLISTENERPROPERTIES
  37. {
  38.     //! Default constructor calls the Clear() function.
  39.     EAXListenerProps()
  40.     {  Clear();  }
  41.     //! Sets all members to their default values, as defined in eax.h
  42.     void Clear()
  43.     {
  44.         lRoom = EAXLISTENER_DEFAULTROOM;                    
  45.         lRoomHF = EAXLISTENER_DEFAULTROOMHF;                  
  46.         flRoomRolloffFactor = EAXLISTENER_DEFAULTROOMROLLOFFFACTOR;     
  47.         flDecayTime = EAXLISTENER_DEFAULTDECAYTIME;             
  48.         flDecayHFRatio = EAXLISTENER_DEFAULTDECAYHFRATIO;          
  49.         lReflections = EAXLISTENER_DEFAULTREFLECTIONS;             
  50.         flReflectionsDelay = EAXLISTENER_DEFAULTREFLECTIONSDELAY;      
  51.         lReverb = EAXLISTENER_DEFAULTREVERB;                  
  52.         flReverbDelay = EAXLISTENER_DEFAULTREVERBDELAY;           
  53.         dwEnvironment = EAXLISTENER_DEFAULTENVIRONMENT;   
  54.         flEnvironmentSize = EAXLISTENER_DEFAULTENVIRONMENTSIZE;       
  55.         flEnvironmentDiffusion = EAXLISTENER_DEFAULTENVIRONMENTDIFFUSION;  
  56.         flAirAbsorptionHF = EAXLISTENER_DEFAULTAIRABSORPTIONHF;       
  57.         dwFlags = EAXLISTENER_DEFAULTFLAGS;         
  58.     }
  59. };
  60.  
  61. //! Public EAX listener interface extension
  62. /*!
  63. IEAXListener is a public interface class designed to provide an
  64. easy-to-use interface to a listener's EAX properties.  The interface
  65. is obtained through the function Listener::EAX(), and it always
  66. guaranteed to return a valid interface, even if EAX is disabled.
  67. The specialized interface is much easier to use than a generic
  68. property set interface.  IEAXListener and any related structures
  69. and interfaces are based on the EAX 2.0 specifications.
  70. \sa IEAXBuffer, IListener, IListener::EAX()
  71. */
  72. class IEAXListener
  73. {
  74. public:
  75.  
  76.     /*!
  77.     Sets the room effect level.
  78.     \param iRoom Valid range from -10000 to 0.  Defaults to -1000
  79.     */
  80.     virtual void SetRoom(int32 iRoom) = 0;
  81.     /*!
  82.     Sets the room effect level at high frequencies.
  83.     \param iRoomHF Valid range from -10000 to 0.  Defaults to -1000
  84.     */
  85.     virtual void SetRoomHF(int32 iRoomHF) = 0;
  86.     /*!
  87.     Sets the room effect rolloff factor.
  88.     \param fRoomRolloffFactor Valid range from 0.0 to 10.0.  Defaults to 0.0
  89.     */
  90.     virtual void SetRoomRolloffFactor(float fRoomRolloffFactor) = 0;
  91.     /*!
  92.     Sets the reverberation decay time in seconds.
  93.     \param fRoomRolloffFactor Valid range from 0.1 to 20.0.  Defaults to 1.49
  94.     */
  95.     virtual void SetDecayTime(float fDecayTime) = 0;
  96.     /*!
  97.     Sets the decay high-frequency ratio.
  98.     \param fDecayHFRatio Valid range from 0.1 to 2.0.  Defaults to 0.83
  99.     */
  100.     virtual void SetDecayHFRatio(float fDecayHFRatio) = 0;
  101.     /*!
  102.     Sets the early reflections level relative to room effect.
  103.     \param iReflections Valid range from -10000 to 1000.  Defaults to -2602
  104.     */
  105.     virtual void SetReflections(int32 iReflections) = 0;
  106.     /*!
  107.     Sets the initial early reflections delay time.
  108.     \param fReflectionsDelay Valid range from 0.0 to 0.3.  Defaults to .007
  109.     */
  110.     virtual void SetReflectionsDelay(float fReflectionsDelay) = 0;
  111.     /*!
  112.     Sets the reverberation level.
  113.     \param iReverb Valid range from -10000 to 2000.  Defaults to 200
  114.     */
  115.     virtual void SetReverb(int32 iReverb) = 0;
  116.     /*!
  117.     Sets the late reverberation delay time relative to the early reflections
  118.     delay time.
  119.     \param fReverbDelay Valid range from 0.0 to 0.1.  Defaults to 0.011
  120.     */
  121.     virtual void SetReverbDelay(float fReverbDelay) = 0;
  122.     /*!
  123.     Sets a preset environment (see eax documentation for listing)
  124.     \param nEnvironment preset environment enumeration
  125.     */
  126.     virtual void SetEnvironment(uint32 nEnvironment) = 0;
  127.     /*!
  128.     Sets the approximate environment size in meters
  129.     \param fEnvironmentSize Valid range from 1.0 to 100.0.  Defaults to 7.5
  130.     */
  131.     virtual void SetEnvironmentSize(float fEnvironmentSize) = 0;
  132.     /*!
  133.     Sets the level of environment diffusion
  134.     \param fEnvironmentDiffusion Valid range from 0.0 to 1.0.  Defaults to 1.0
  135.     */
  136.     virtual void SetEnvironmentDiffusion(float fEnvironmentDiffusion) = 0;
  137.     /*!
  138.     Sets the air absorption factor
  139.     \param fAirAbsorption Valid range from -100.0 to 0.0.  Defaults to -5.0
  140.     */
  141.     virtual void SetAirAbsorptionHF(float fAirAbsorption) = 0;
  142.     /*!
  143.     Sets all EAX listener flags - see EAX documentation for details
  144.     \param fEnvironmentDiffusion all EAX listener flags
  145.     */
  146.     virtual void SetFlags(uint32 nFlags) = 0;
  147.     /*!
  148.     Sets all current EAX listener parameters
  149.     \param props all EAX listener properties
  150.     */
  151.     virtual void SetProperties(const EAXListenerProps& props) = 0;
  152.     /*!
  153.     Gets all current EAX listener parameters
  154.     \param props all EAX listener properties
  155.     */
  156.     virtual void GetProperties(EAXListenerProps& props) = 0;
  157. };
  158.  
  159. //! EAXBufferProps is used to set all EAX buffer properties at once
  160. /*!
  161. EAXBufferProps is derived from the EAX structure _EAXBUFFERPROPERTIES.
  162. The structure is made slightly more user friendly by providing a Clear()
  163. function which resets all EAX buffer properties to their default 
  164. values.  The Clear() function is also automatically called when the
  165. structure is created.  Because it is derived from _EAXBUFFERPROPERTIES,
  166. it can be used interchangeably with this structure since it is binary
  167. compatible.
  168. */
  169. struct EAXBufferProps : public _EAXBUFFERPROPERTIES
  170. {
  171.     //! Default constructor calls the Clear() function.
  172.     EAXBufferProps()
  173.     {  Clear();  }
  174.     //! Sets all members to their default values, as defined in eax.h
  175.     void Clear()
  176.     {
  177.         lDirect = EAXBUFFER_DEFAULTDIRECT;                
  178.         lDirectHF = EAXBUFFER_DEFAULTDIRECTHF;              
  179.         lRoom = EAXBUFFER_DEFAULTROOM;                  
  180.         lRoomHF = EAXBUFFER_DEFAULTROOMHF;                
  181.         flRoomRolloffFactor = EAXBUFFER_DEFAULTROOMROLLOFFFACTOR;   
  182.         lObstruction = EAXBUFFER_DEFAULTOBSTRUCTION;           
  183.         flObstructionLFRatio = EAXBUFFER_DEFAULTOBSTRUCTIONLFRATIO;  
  184.         lOcclusion = EAXBUFFER_DEFAULTOCCLUSION;             
  185.         flOcclusionLFRatio = EAXBUFFER_DEFAULTOCCLUSIONLFRATIO;    
  186.         flOcclusionRoomRatio = EAXBUFFER_DEFAULTOCCLUSIONROOMRATIO;  
  187.         lOutsideVolumeHF = EAXBUFFER_DEFAULTOUTSIDEVOLUMEHF;       
  188.         flAirAbsorptionFactor = EAXBUFFER_DEFAULTAIRABSORPTIONFACTOR; 
  189.         dwFlags = EAXBUFFER_DEFAULTFLAGS;       
  190.     }
  191. };
  192.  
  193.  
  194. //! Public EAX buffer interface extension
  195. /*!
  196. IEAXBuffer is a public interface class designed to provide an
  197. easy-to-use interface to a buffer's EAX properties.  The interface
  198. is obtained through the function ISound3D::EAX(), and it always
  199. guaranteed to return a valid interface, even if EAX is disabled.
  200. The specialized interface is much easier to use than a generic
  201. property set interface.  IEAXBuffer and any related structures
  202. and interfaces are based on the EAX 2.0 specifications.
  203. \sa IEAXListener, ISound3D, ISound3D::EAX()
  204. */
  205. class IEAXBuffer
  206. {
  207. public:
  208.     /*!
  209.     Sets the direct path audio level
  210.     \param iDirect Valid range from -10000 to 1000.  Defaults to 0
  211.     */
  212.     virtual void SetDirect(int32 iDirect) = 0;
  213.     /*!
  214.     Sets the direct path audio level at high frequencies
  215.     \param iDirectHF Valid range from -10000 to 0.  Defaults to 0
  216.     */
  217.     virtual void SetDirectHF(int32 iDirectHF) = 0;
  218.     /*!
  219.     Sets the room effect level
  220.     \param iRoom Valid range from -10000 to 1000.  Defaults to 0
  221.     */
  222.     virtual void SetRoom(int32 iRoom) = 0;
  223.     /*!
  224.     Sets the room effect level at high frequencies
  225.     \param iRoomHF Valid range from -10000 to 0.  Defaults to 0
  226.     */
  227.     virtual void SetRoomHF(int32 iRoomHF) = 0;
  228.     /*!
  229.     Sets the room effect rolloff factor
  230.     \param fRoomRolloffFactor Valid range from 0.0 to 10.0.  Defaults to 0.0
  231.     */
  232.     virtual void SetRoomRolloffFactor(float fRoomRolloffFactor) = 0;
  233.     /*!
  234.     Sets the buffer's obstruction level
  235.     \param iObstruction Valid range from -10000 to 0.  Defaults to 0
  236.     */
  237.     virtual void SetObstruction(int32 iObstruction) = 0;
  238.     /*!
  239.     Sets the buffer's obstruction low-frequency level
  240.     \param fObstructionLFRatio Valid range from 0.0 to 1.0.  Defaults to 0.0
  241.     */
  242.     virtual void SetObstructionLFRatio(float fObstructionLFRatio) = 0;
  243.     /*!
  244.     Sets the buffer's occlusion level
  245.     \param iOcclusion Valid range from -10000 to 0.  Defaults to 0
  246.     */
  247.     virtual void SetOcclusion(int32 iOcclusion) = 0;
  248.     /*!
  249.     Sets the buffer's occlusion low-frequency level
  250.     \param fOcclusionLFRatio Valid range from 0.0 to 1.0.  Defaults to 0.25
  251.     */
  252.     virtual void SetOcclusionLFRatio(float fOcclusionLFRatio) = 0;
  253.     /*!
  254.     Sets the buffer's room-level occlusion control
  255.     \param fOcclusionRoomRatio Valid range from 0.0 to 10.0.  Defaults to 0.5
  256.     */
  257.     virtual void SetOcclusionRoomRatio(float fOcclusionRoomRatio) = 0;
  258.     /*!
  259.     Sets the buffer's outside volume for high frequencies
  260.     \param iOutsideVolumeHF Valid range from -10000 to 0.  Defaults to 0
  261.     */
  262.     virtual void SetOutsideVolumeHF(int32 iOutsideVolumeHF) = 0;
  263.     /*!
  264.     Sets the air absorption factor
  265.     \param fAirAbsorption Valid range from 0.0 to 10.0.  Defaults to 1.0
  266.     */
  267.     virtual void SetAirAbsorptionFactor(float fAirAbsorptionFactor) = 0;
  268.     /*!
  269.     Sets all EAX buffer flags - see EAX documentation for details
  270.     \param fEnvironmentDiffusion all EAX buffer flags
  271.     */
  272.     virtual void SetFlags(uint32 nFlags) = 0;
  273.     /*!
  274.     Sets all current EAX buffer parameters
  275.     \param props all EAX buffer properties
  276.     */
  277.     virtual void SetProperties(const EAXBufferProps& props) = 0;
  278.     /*!
  279.     Gets all current EAX buffer parameters
  280.     \param props all EAX buffer properties
  281.     */
  282.     virtual void GetProperties(EAXBufferProps& props) = 0;
  283. };
  284.  
  285.  
  286. //! ZoomFXBox is used to set all ZoomFX orientation properties
  287. /*!
  288. ZoomFXBox is derived from the ZoomFX structure ZOOMFX_BOX.
  289. The structure is made slightly more user friendly by providing a Clear()
  290. function which resets all ZoomFX buffer properties to their default 
  291. values.  The Clear() function is also automatically called when the
  292. structure is created.  Because it is derived from ZOOMFX_BOX,
  293. it can be used interchangeably with this structure since it is binary
  294. compatible.
  295. */
  296. struct ZoomFXBox : public ZOOMFX_BOX
  297. {
  298.     //! Default constructor calls the Clear() function.
  299.     ZoomFXBox()    { Clear(); }
  300.     //! Sets all members to their default values, as defined in zoomfx.h
  301.     void Clear()
  302.     {
  303.         vMin.x = 0.0f;  
  304.         vMin.y = 0.0f;  
  305.         vMin.z = 0.0f;
  306.         vMax.x = 0.0f;  
  307.         vMax.y = 0.0f;  
  308.         vMax.z = 0.0f;
  309.     }
  310. };
  311.  
  312. //! ZoomFXOrientation is used to set all ZoomFX orientation properties
  313. /*!
  314. ZoomFXOrientation is derived from the ZoomFX structure ZOOMFX_ORIENTATION.
  315. The structure is made slightly more user friendly by providing a Clear()
  316. function which resets all ZoomFX buffer properties to their default 
  317. values.  The Clear() function is also automatically called when the
  318. structure is created.  Because it is derived from ZOOMFX_ORIENTATION,
  319. it can be used interchangeably with this structure since it is binary
  320. compatible.
  321. */
  322. struct ZoomFXOrientation : public ZOOMFX_ORIENTATION
  323. {
  324.     //! Default constructor calls the Clear() function.
  325.     ZoomFXOrientation()    { Clear(); }
  326.     //! Sets all members to their default values, as defined in zoomfx.h
  327.     void Clear()
  328.     {
  329.         vFront.x = 0.0f;  
  330.         vFront.y = 0.0f;  
  331.         vFront.z = 1.0f;
  332.         vTop.x = 0.0f;  
  333.         vTop.y = 1.0f;  
  334.         vTop.z = 0.0f;
  335.     }
  336. };
  337.  
  338. //! ZoomFXProps is used to set all ZoomFX buffer properties at once
  339. /*!
  340. ZoomFXProps is derived from the ZoomFX structure ZOOMFX_BUFFERPROPERTIES.
  341. The structure is made slightly more user friendly by providing a Clear()
  342. function which resets all ZoomFX buffer properties to their default 
  343. values.  The Clear() function is also automatically called when the
  344. structure is created.  Because it is derived from ZOOMFX_BUFFERPROPERTIES,
  345. it can be used interchangeably with this structure since it is binary
  346. compatible.
  347. */
  348. struct ZoomFXProps : public ZOOMFX_BUFFERPROPERTIES
  349. {
  350.     //! Default constructor calls the Clear() function.
  351.     ZoomFXProps()    { Clear(); }
  352.     //! Sets all members to their default values, as defined in zoomfx.h
  353.     void Clear()
  354.     {
  355.         box.vMin.x = 0.0f;  
  356.         box.vMin.y = 0.0f;  
  357.         box.vMin.z = 0.0f;
  358.         box.vMax.x = 0.0f;  
  359.         box.vMax.y = 0.0f;  
  360.         box.vMax.z = 0.0f;
  361.         orientation.vFront.x = 0.0f;  
  362.         orientation.vFront.y = 0.0f;  
  363.         orientation.vFront.z = 1.0f;
  364.         orientation.vTop.x = 0.0f;  
  365.         orientation.vTop.y = 1.0f;  
  366.         orientation.vTop.z = 0.0f;
  367.         lMacroFx = ZOOMFXBUFFER_MACROFX_DEFAULT;
  368.     }
  369. };
  370.  
  371.  
  372.  
  373.  
  374.  
  375. //! Public ZoomFX buffer interface extension
  376. class IZoomFX
  377. {
  378. public:
  379.     /*!
  380.     Set the ZoomFX bounding box dimensions.
  381.     \param box ZoomFXBox used to set the min and max coordinates 
  382.     of the bounding box
  383.     */
  384.     virtual void SetBox(const ZoomFXBox& box) = 0;
  385.     /*!
  386.     Set the ZoomFX bounding box orientation.
  387.     \param orientation The ZoomFXOrientation structure uses two
  388.     vectors to define the bounding box orientation.
  389.     */
  390.     virtual void SetOrientation(const ZoomFXOrientation& orientation) = 0;
  391.     /*!
  392.     Sets the percentage level of the MacroFX near-position effect.
  393.     \param nMacroFX percentage of effect
  394.     */
  395.     virtual void SetMacroFX(uint32 nMacroFX) = 0;
  396.     /*!
  397.     Sets all ZoomFX and MacroFX properties at once.
  398.     \param props all properties to set
  399.     */
  400.     virtual void SetProperties(const ZoomFXProps& props) = 0;
  401.     /*!
  402.     Gets all ZoomFX and MacroFX properties at once.
  403.     \param props all properties to get
  404.     */
  405.     virtual void GetProperties(ZoomFXProps& props) = 0;
  406.  
  407. };
  408.  
  409. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  410. }; // namespace Audio
  411. #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  412.  
  413.  
  414. #endif // IAUDIOEXT_H__
  415.