home *** CD-ROM | disk | FTP | other *** search
/ NEXT Generation 27 / NEXT27.iso / pc / demos / emperor / dx3.exe / SDK / SAMPLES / DS3DVIEW / DSUTIL3D.H < prev    next >
C/C++ Source or Header  |  1996-08-28  |  10KB  |  265 lines
  1.  
  2. /*==========================================================================
  3.  *
  4.  *  Copyright (C) 1995-1996 Microsoft Corporation. All Rights Reserved.
  5.  *
  6.  *  File:       dsutil.cpp
  7.  *  Content:    Routines for dealing with sounds from resources
  8.  *
  9.  *
  10.  ***************************************************************************/
  11.  
  12. #ifdef __cplusplus
  13. extern "C" {
  14. #endif
  15.  
  16. ///////////////////////////////////////////////////////////////////////////////
  17. //
  18. // These Load functions will first look in the Win32 resources, and then they
  19. //   will attempt to find the given name as a file on disk.
  20. //
  21. // DSLoadSoundBuffer    Loads an IDirectSoundBuffer from a Win32 resource in
  22. //                      the current application, or alternately from disk.
  23. //
  24. // DSLoad3DSoundBuffer  Loads an IDirectSoundBuffer from a Win32 resource in
  25. //                      the current application, and asks for DSBCAPS_CTRL3D.
  26. //
  27. // Params:
  28. //  pDS         -- Pointer to an IDirectSound that will be used to create
  29. //                 the buffer.
  30. //
  31. //  lpName      -- Name of WAV resource to load the data from.  Can be a
  32. //                 resource id specified using the MAKEINTRESOURCE macro.
  33. //
  34. // Returns an IDirectSoundBuffer containing the wave data or NULL on error.
  35. //
  36. // example:
  37. //  in the application's resource script (.RC file)
  38. //      Turtle WAV turtle.wav
  39. //
  40. //  some code in the application:
  41. //      IDirectSoundBuffer *pDSB = DSLoadSoundBuffer(pDS, "Turtle");
  42. //
  43. //      if (pDSB)
  44. //      {
  45. //          IDirectSoundBuffer_Play(pDSB, 0, 0, DSBPLAY_TOEND);
  46. //          /* ... */
  47. //
  48. //  or you can substitute the first line above as:
  49. //     IDirectSoundBuffer *pDSB = DSLoadSoundBuffer(pDS, "turtle.wav");
  50. //
  51. ///////////////////////////////////////////////////////////////////////////////
  52. IDirectSoundBuffer *DSLoadSoundBuffer(IDirectSound *pDS, LPCTSTR lpName);
  53. IDirectSoundBuffer *DSLoad3DSoundBuffer(IDirectSound *pDS, LPCTSTR lpName);
  54.  
  55. ///////////////////////////////////////////////////////////////////////////////
  56. //
  57. // DSReloadSoundBuffer  Reloads an IDirectSoundBuffer from a Win32 resource in
  58. //                      the current application. normally used to handle
  59. //                      a DSERR_BUFFERLOST error. Will also attempt to find
  60. //                      the given name as a file, if there is no resource.
  61. // Params:
  62. //  pDSB        -- Pointer to an IDirectSoundBuffer to be reloaded.
  63. //
  64. //  lpName      -- Name of WAV resource to load the data from.  Can be a
  65. //                 resource id specified using the MAKEINTRESOURCE macro.
  66. //
  67. // Returns a BOOL indicating whether the buffer was successfully reloaded.
  68. //
  69. // example:
  70. //  in the application's resource script (.RC file)
  71. //      Turtle WAV turtle.wav
  72. //
  73. //  some code in the application:
  74. //  TryAgain:
  75. //      HRESULT hres = IDirectSoundBuffer_Play(pDSB, 0, 0, DSBPLAY_TOEND);
  76. //
  77. //      if (FAILED(hres))
  78. //      {
  79. //          if ((hres == DSERR_BUFFERLOST) &&
  80. //              DSReloadSoundBuffer(pDSB, "Turtle"))
  81. //          {
  82. //              goto TryAgain;
  83. //          }
  84. //          /* deal with other errors... */
  85. //      }
  86. //
  87. ///////////////////////////////////////////////////////////////////////////////
  88. BOOL DSReloadSoundBuffer(IDirectSoundBuffer *pDSB, LPCTSTR lpName);
  89.  
  90. ///////////////////////////////////////////////////////////////////////////////
  91. //
  92. // DSGetWaveResource    Finds a WAV resource in a Win32 module.
  93. //
  94. // Params:
  95. //  hModule     -- Win32 module handle of module containing WAV resource.
  96. //                 Pass NULL to indicate current application.
  97. //
  98. //  lpName      -- Name of WAV resource to load the data from.  Can be a
  99. //                 resource id specified using the MAKEINTRESOURCE macro.
  100. //
  101. //  ppWaveHeader-- Optional pointer to WAVEFORMATEX * to receive a pointer to
  102. //                 the WAVEFORMATEX header in the specified WAV resource.
  103. //                 Pass NULL if not required.
  104. //
  105. //  ppbWaveData -- Optional pointer to BYTE * to receive a pointer to the
  106. //                 waveform data in the specified WAV resource.  Pass NULL if
  107. //                 not required.
  108. //
  109. //  pdwWaveSize -- Optional pointer to DWORD to receive the size of the
  110. //                 waveform data in the specified WAV resource.  Pass NULL if
  111. //                 not required.
  112. //
  113. // Returns a BOOL indicating whether a valid WAV resource was found.
  114. //
  115. ///////////////////////////////////////////////////////////////////////////////
  116. BOOL DSGetWaveResource(HMODULE hModule, LPCTSTR lpName,
  117.     WAVEFORMATEX **ppWaveHeader, BYTE **ppbWaveData, DWORD *pdwWaveSize);
  118.  
  119. ///////////////////////////////////////////////////////////////////////////////
  120. //
  121. // DSGetWaveFile    Finds a WAV file on disk and uses a memory mapped file to
  122. //                    get a memory image of the file.
  123. //
  124. // Params:
  125. //  hModule     -- Win32 module handle of module containing WAV resource.
  126. //                 Pass NULL to indicate current application.
  127. //
  128. //  lpName      -- Name of WAV resource to load the data from.  Can be a
  129. //                 resource id specified using the MAKEINTRESOURCE macro.
  130. //
  131. //  ppWaveHeader-- Optional pointer to WAVEFORMATEX * to receive a pointer to
  132. //                 the WAVEFORMATEX header in the specified WAV resource.
  133. //                 Pass NULL if not required.
  134. //
  135. //  ppbWaveData -- Optional pointer to BYTE * to receive a pointer to the
  136. //                 waveform data in the specified WAV resource.  Pass NULL if
  137. //                 not required.
  138. //
  139. //  pdwWaveSize -- Optional pointer to DWORD to receive the size of the
  140. //                 waveform data in the specified WAV resource.  Pass NULL if
  141. //                 not required.
  142. //
  143. //  ppvBase     -- Required out-parameter which receives the base-address of
  144. //                 the file mapping.  This is needed for the caller to Unmap
  145. //                 the file.
  146. //
  147. // Returns a BOOL indicating whether a valid WAV file was found and mapped.
  148. // The caller is responsible for calling UnmapViewOfFile(*ppvBase) when they
  149. // are done with the "memory" for the file.
  150. //
  151. ///////////////////////////////////////////////////////////////////////////////
  152. BOOL DSGetWaveFile(HMODULE hModule, LPCTSTR lpName, WAVEFORMATEX **ppWaveHeader,
  153.      BYTE **ppbWaveData, DWORD *pdwWaveSize, void **ppvBase);
  154.  
  155. ///////////////////////////////////////////////////////////////////////////////
  156. //
  157. // HSNDOBJ             Handle to a SNDOBJ object.
  158. //
  159. //  SNDOBJs are implemented in dsutil as an example layer built on top
  160. //      of DirectSound.
  161. //
  162. //      A SNDOBJ is generally used to manage individual
  163. //      sounds which need to be played multiple times concurrently.  A
  164. //      SNDOBJ represents a queue of IDirectSoundBuffer objects which
  165. //      all refer to the same buffer memory.
  166. //
  167. //      A SNDOBJ also automatically reloads the sound resource when
  168. //      DirectSound returns a DSERR_BUFFERLOST
  169. //
  170. ///////////////////////////////////////////////////////////////////////////////
  171. #ifndef _HSNDOBJ_DEFINED
  172. #define _HSNDOBJ_DEFINED
  173. DECLARE_HANDLE32(HSNDOBJ);
  174. #endif
  175.  
  176. ///////////////////////////////////////////////////////////////////////////////
  177. //
  178. // SndObjCreate     Loads a SNDOBJ from a Win32 resource in
  179. //                  the current application.
  180. //
  181. // Params:
  182. //  pDS         -- Pointer to an IDirectSound that will be used to create
  183. //                 the SNDOBJ.
  184. //
  185. //  lpName      -- Name of WAV resource to load the data from.  Can be a
  186. //                 resource id specified using the MAKEINTRESOURCE macro.
  187. //
  188. //  iConcurrent -- Integer representing the number of concurrent playbacks of
  189. //                 to plan for.  Attempts to play more than this number will
  190. //                 succeed but will restart the least recently played buffer
  191. //                 even if it is not finished playing yet.
  192. //
  193. // Returns an HSNDOBJ or NULL on error.
  194. //
  195. // NOTES:
  196. //      SNDOBJs automatically restore and reload themselves as required.
  197. //
  198. ///////////////////////////////////////////////////////////////////////////////
  199. HSNDOBJ SndObjCreate(IDirectSound *pDS, LPCTSTR lpName, int iConcurrent);
  200.  
  201. ///////////////////////////////////////////////////////////////////////////////
  202. //
  203. // SndObjDestroy  Frees a SNDOBJ and releases all of its buffers.
  204. //
  205. // Params:
  206. //  hSO         -- Handle to a SNDOBJ to free.
  207. //
  208. ///////////////////////////////////////////////////////////////////////////////
  209. void SndObjDestroy(HSNDOBJ hSO);
  210.  
  211. ///////////////////////////////////////////////////////////////////////////////
  212. //
  213. // SndObjPlay   Plays a buffer in a SNDOBJ.
  214. //
  215. // Params:
  216. //  hSO         -- Handle to a SNDOBJ to play a buffer from.
  217. //
  218. //  dwPlayFlags -- Flags to pass to IDirectSoundBuffer::Play.  It is not
  219. //                 legal to play an SndObj which has more than one buffer
  220. //                 with the DSBPLAY_LOOPING flag.  Pass 0 to stop playback.
  221. //
  222. ///////////////////////////////////////////////////////////////////////////////
  223. BOOL SndObjPlay(HSNDOBJ hSO, DWORD dwPlayFlags);
  224.  
  225. ///////////////////////////////////////////////////////////////////////////////
  226. //
  227. // SndObjStop   Stops one or more buffers in a SNDOBJ.
  228. //
  229. // Params:
  230. //  hSO         -- Handle to a SNDOBJ to play a buffer from.
  231. //
  232. ///////////////////////////////////////////////////////////////////////////////
  233. BOOL SndObjStop(HSNDOBJ hSO);
  234.  
  235. ///////////////////////////////////////////////////////////////////////////////
  236. //
  237. // SndObjGetFreeBuffer      returns one of the cloned buffers that is
  238. //                          not currently playing
  239. //
  240. // Params:
  241. //  hSO         -- Handle to a SNDOBJ
  242. //
  243. // NOTES:
  244. //  This function is provided so that callers can set things like pan etc
  245. //  before playing the buffer.
  246. //
  247. // EXAMPLE:
  248. //  ...
  249. //
  250. ///////////////////////////////////////////////////////////////////////////////
  251. IDirectSoundBuffer *SndObjGetFreeBuffer(HSNDOBJ hSO);
  252.  
  253. ///////////////////////////////////////////////////////////////////////////////
  254. //
  255. // helper routines
  256. //
  257. ///////////////////////////////////////////////////////////////////////////////
  258.  
  259. BOOL DSFillSoundBuffer(IDirectSoundBuffer *pDSB, BYTE *pbWaveData, DWORD dwWaveSize);
  260. BOOL DSParseWaveResource(void *pvRes, WAVEFORMATEX **ppWaveHeader, BYTE **ppbWaveData, DWORD *pdwWaveSize);
  261.  
  262. #ifdef __cplusplus
  263. }
  264. #endif
  265.