arch/win32/d3dframe/dsutil.h

   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