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 217