home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / msdn_vcb / samples / vc98 / sdk / graphics / directx / misc / dsutil.h < prev    next >
C/C++ Source or Header  |  1997-07-14  |  8KB  |  216 lines
  1. /*==========================================================================
  2.  *
  3.  *  Copyright (C) 1995 Microsoft Corporation. All Rights Reserved.
  4.  *
  5.  *  File:       dsutil.cpp
  6.  *  Content:    Routines for dealing with sounds from resources
  7.  *
  8.  *
  9.  ***************************************************************************/
  10.  
  11. #ifdef __cplusplus
  12. extern "C" {
  13. #endif
  14.  
  15. ///////////////////////////////////////////////////////////////////////////////
  16. //
  17. // DSLoadSoundBuffer    Loads an IDirectSoundBuffer from a Win32 resource in
  18. //                      the current application.
  19. //
  20. // Params:
  21. //  pDS         -- Pointer to an IDirectSound that will be used to create
  22. //                 the buffer.
  23. //
  24. //  lpName      -- Name of WAV resource to load the data from.  Can be a
  25. //                 resource id specified using the MAKEINTRESOURCE macro.
  26. //
  27. // Returns an IDirectSoundBuffer containing the wave data or NULL on error.
  28. //
  29. // example:
  30. //  in the application's resource script (.RC file)
  31. //      Turtle WAV turtle.wav
  32. //
  33. //  some code in the application:
  34. //      IDirectSoundBuffer *pDSB = DSLoadSoundBuffer(pDS, "Turtle");
  35. //
  36. //      if (pDSB)
  37. //      {
  38. //          IDirectSoundBuffer_Play(pDSB, 0, 0, DSBPLAY_TOEND);
  39. //          /* ... */
  40. //
  41. ///////////////////////////////////////////////////////////////////////////////
  42. IDirectSoundBuffer *DSLoadSoundBuffer(IDirectSound *pDS, LPCTSTR lpName);
  43.  
  44. ///////////////////////////////////////////////////////////////////////////////
  45. //
  46. // DSReloadSoundBuffer  Reloads an IDirectSoundBuffer from a Win32 resource in
  47. //                      the current application. normally used to handle
  48. //                      a DSERR_BUFFERLOST error.
  49. // Params:
  50. //  pDSB        -- Pointer to an IDirectSoundBuffer to be reloaded.
  51. //
  52. //  lpName      -- Name of WAV resource to load the data from.  Can be a
  53. //                 resource id specified using the MAKEINTRESOURCE macro.
  54. //
  55. // Returns a BOOL indicating whether the buffer was successfully reloaded.
  56. //
  57. // example:
  58. //  in the application's resource script (.RC file)
  59. //      Turtle WAV turtle.wav
  60. //
  61. //  some code in the application:
  62. //  TryAgain:
  63. //      HRESULT hres = IDirectSoundBuffer_Play(pDSB, 0, 0, DSBPLAY_TOEND);
  64. //
  65. //      if (FAILED(hres))
  66. //      {
  67. //          if ((hres == DSERR_BUFFERLOST) &&
  68. //              DSReloadSoundBuffer(pDSB, "Turtle"))
  69. //          {
  70. //              goto TryAgain;
  71. //          }
  72. //          /* deal with other errors... */
  73. //      }
  74. //
  75. ///////////////////////////////////////////////////////////////////////////////
  76. BOOL DSReloadSoundBuffer(IDirectSoundBuffer *pDSB, LPCTSTR lpName);
  77.  
  78. ///////////////////////////////////////////////////////////////////////////////
  79. //
  80. // DSGetWaveResource    Finds a WAV resource in a Win32 module.
  81. //
  82. // Params:
  83. //  hModule     -- Win32 module handle of module containing WAV resource.
  84. //                 Pass NULL to indicate current application.
  85. //
  86. //  lpName      -- Name of WAV resource to load the data from.  Can be a
  87. //                 resource id specified using the MAKEINTRESOURCE macro.
  88. //
  89. //  ppWaveHeader-- Optional pointer to WAVEFORMATEX * to receive a pointer to
  90. //                 the WAVEFORMATEX header in the specified WAV resource.
  91. //                 Pass NULL if not required.
  92. //
  93. //  ppbWaveData -- Optional pointer to BYTE * to receive a pointer to the
  94. //                 waveform data in the specified WAV resource.  Pass NULL if
  95. //                 not required.
  96. //
  97. //  pdwWaveSize -- Optional pointer to DWORD to receive the size of the
  98. //                 waveform data in the specified WAV resource.  Pass NULL if
  99. //                 not required.
  100. //
  101. // Returns a BOOL indicating whether a valid WAV resource was found.
  102. //
  103. ///////////////////////////////////////////////////////////////////////////////
  104. BOOL DSGetWaveResource(HMODULE hModule, LPCTSTR lpName,
  105.     WAVEFORMATEX **ppWaveHeader, BYTE **ppbWaveData, DWORD *pdwWaveSize);
  106.  
  107. ///////////////////////////////////////////////////////////////////////////////
  108. //
  109. // HSNDOBJ             Handle to a SNDOBJ object.
  110. //
  111. //  SNDOBJs are implemented in dsutil as an example layer built on top
  112. //      of DirectSound.
  113. //
  114. //      A SNDOBJ is generally used to manage individual
  115. //      sounds which need to be played multiple times concurrently.  A
  116. //      SNDOBJ represents a queue of IDirectSoundBuffer objects which
  117. //      all refer to the same buffer memory.
  118. //
  119. //      A SNDOBJ also automatically reloads the sound resource when
  120. //      DirectSound returns a DSERR_BUFFERLOST
  121. //
  122. ///////////////////////////////////////////////////////////////////////////////
  123. #ifndef _HSNDOBJ_DEFINED
  124. DECLARE_HANDLE32(HSNDOBJ);
  125. #endif
  126.  
  127. ///////////////////////////////////////////////////////////////////////////////
  128. //
  129. // SndObjCreate     Loads a SNDOBJ from a Win32 resource in
  130. //            the current application.
  131. //
  132. // Params:
  133. //  pDS         -- Pointer to an IDirectSound that will be used to create
  134. //                 the SNDOBJ.
  135. //
  136. //  lpName      -- Name of WAV resource to load the data from.  Can be a
  137. //                 resource id specified using the MAKEINTRESOURCE macro.
  138. //
  139. //  iConcurrent -- Integer representing the number of concurrent playbacks of
  140. //                 to plan for.  Attempts to play more than this number will
  141. //                 succeed but will restart the least recently played buffer
  142. //                 even if it is not finished playing yet.
  143. //
  144. // Returns an HSNDOBJ or NULL on error.
  145. //
  146. // NOTES:
  147. //      SNDOBJs automatically restore and reload themselves as required.
  148. //
  149. ///////////////////////////////////////////////////////////////////////////////
  150. HSNDOBJ SndObjCreate(IDirectSound *pDS, LPCTSTR lpName, int iConcurrent);
  151.  
  152. ///////////////////////////////////////////////////////////////////////////////
  153. //
  154. // SndObjDestroy  Frees a SNDOBJ and releases all of its buffers.
  155. //
  156. // Params:
  157. //  hSO         -- Handle to a SNDOBJ to free.
  158. //
  159. ///////////////////////////////////////////////////////////////////////////////
  160. void SndObjDestroy(HSNDOBJ hSO);
  161.  
  162. ///////////////////////////////////////////////////////////////////////////////
  163. //
  164. // SndObjPlay    Plays a buffer in a SNDOBJ.
  165. //
  166. // Params:
  167. //  hSO         -- Handle to a SNDOBJ to play a buffer from.
  168. //
  169. //  dwPlayFlags -- Flags to pass to IDirectSoundBuffer::Play.  It is not
  170. //                 legal to play an SndObj which has more than one buffer
  171. //                 with the DSBPLAY_LOOPING flag.  Pass 0 to stop playback.
  172. //
  173. ///////////////////////////////////////////////////////////////////////////////
  174. BOOL SndObjPlay(HSNDOBJ hSO, DWORD dwPlayFlags);
  175.  
  176. ///////////////////////////////////////////////////////////////////////////////
  177. //
  178. // SndObjStop    Stops one or more buffers in a SNDOBJ.
  179. //
  180. // Params:
  181. //  hSO         -- Handle to a SNDOBJ to play a buffer from.
  182. //
  183. ///////////////////////////////////////////////////////////////////////////////
  184. BOOL SndObjStop(HSNDOBJ hSO);
  185.  
  186. ///////////////////////////////////////////////////////////////////////////////
  187. //
  188. // SndObjGetFreeBuffer        returns one of the cloned buffers that is
  189. //                not currently playing
  190. //
  191. // Params:
  192. //  hSO     -- Handle to a SNDOBJ
  193. //
  194. // NOTES:
  195. //  This function is provided so that callers can set things like pan etc
  196. //  before playing the buffer.
  197. //
  198. // EXAMPLE:
  199. //  ...
  200. //
  201. ///////////////////////////////////////////////////////////////////////////////
  202. IDirectSoundBuffer *SndObjGetFreeBuffer(HSNDOBJ hSO);
  203.  
  204. ///////////////////////////////////////////////////////////////////////////////
  205. //
  206. // helper routines
  207. //
  208. ///////////////////////////////////////////////////////////////////////////////
  209.  
  210. BOOL DSFillSoundBuffer(IDirectSoundBuffer *pDSB, BYTE *pbWaveData, DWORD dwWaveSize);
  211. BOOL DSParseWaveResource(void *pvRes, WAVEFORMATEX **ppWaveHeader, BYTE **ppbWaveData, DWORD *pdwWaveSize);
  212.  
  213. #ifdef __cplusplus
  214. }
  215. #endif
  216.