1 /*==========================================================================
3 * Copyright (C) 1995 Microsoft Corporation. All Rights Reserved.
6 * Content: Routines for dealing with sounds from resources
9 ***************************************************************************/
15 ///////////////////////////////////////////////////////////////////////////////
17 // DSLoadSoundBuffer Loads an IDirectSoundBuffer from a Win32 resource in
18 // the current application.
21 // pDS -- Pointer to an IDirectSound that will be used to create
24 // lpName -- Name of WAV resource to load the data from. Can be a
25 // resource id specified using the MAKEINTRESOURCE macro.
27 // Returns an IDirectSoundBuffer containing the wave data or NULL on error.
30 // in the application's resource script (.RC file)
31 // Turtle WAV turtle.wav
33 // some code in the application:
34 // IDirectSoundBuffer *pDSB = DSLoadSoundBuffer(pDS, "Turtle");
38 // IDirectSoundBuffer_Play(pDSB, 0, 0, DSBPLAY_TOEND);
41 ///////////////////////////////////////////////////////////////////////////////
42 IDirectSoundBuffer *DSLoadSoundBuffer(IDirectSound *pDS, LPCTSTR lpName);
44 ///////////////////////////////////////////////////////////////////////////////
46 // DSReloadSoundBuffer Reloads an IDirectSoundBuffer from a Win32 resource in
47 // the current application. normally used to handle
48 // a DSERR_BUFFERLOST error.
50 // pDSB -- Pointer to an IDirectSoundBuffer to be reloaded.
52 // lpName -- Name of WAV resource to load the data from. Can be a
53 // resource id specified using the MAKEINTRESOURCE macro.
55 // Returns a BOOL indicating whether the buffer was successfully reloaded.
58 // in the application's resource script (.RC file)
59 // Turtle WAV turtle.wav
61 // some code in the application:
63 // HRESULT hres = IDirectSoundBuffer_Play(pDSB, 0, 0, DSBPLAY_TOEND);
67 // if ((hres == DSERR_BUFFERLOST) &&
68 // DSReloadSoundBuffer(pDSB, "Turtle"))
72 // /* deal with other errors... */
75 ///////////////////////////////////////////////////////////////////////////////
76 BOOL DSReloadSoundBuffer(IDirectSoundBuffer *pDSB, LPCTSTR lpName);
78 ///////////////////////////////////////////////////////////////////////////////
80 // DSGetWaveResource Finds a WAV resource in a Win32 module.
83 // hModule -- Win32 module handle of module containing WAV resource.
84 // Pass NULL to indicate current application.
86 // lpName -- Name of WAV resource to load the data from. Can be a
87 // resource id specified using the MAKEINTRESOURCE macro.
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.
93 // ppbWaveData -- Optional pointer to BYTE * to receive a pointer to the
94 // waveform data in the specified WAV resource. Pass NULL if
97 // pdwWaveSize -- Optional pointer to DWORD to receive the size of the
98 // waveform data in the specified WAV resource. Pass NULL if
101 // Returns a BOOL indicating whether a valid WAV resource was found.
103 ///////////////////////////////////////////////////////////////////////////////
104 BOOL DSGetWaveResource(HMODULE hModule, LPCTSTR lpName,
105 WAVEFORMATEX **ppWaveHeader, BYTE **ppbWaveData, DWORD *pdwWaveSize);
107 ///////////////////////////////////////////////////////////////////////////////
109 // HSNDOBJ Handle to a SNDOBJ object.
111 // SNDOBJs are implemented in dsutil as an example layer built on top
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.
119 // A SNDOBJ also automatically reloads the sound resource when
120 // DirectSound returns a DSERR_BUFFERLOST
122 ///////////////////////////////////////////////////////////////////////////////
123 #ifndef _HSNDOBJ_DEFINED
124 DECLARE_HANDLE32(HSNDOBJ);
127 ///////////////////////////////////////////////////////////////////////////////
129 // SndObjCreate Loads a SNDOBJ from a Win32 resource in
130 // the current application.
133 // pDS -- Pointer to an IDirectSound that will be used to create
136 // lpName -- Name of WAV resource to load the data from. Can be a
137 // resource id specified using the MAKEINTRESOURCE macro.
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.
144 // Returns an HSNDOBJ or NULL on error.
147 // SNDOBJs automatically restore and reload themselves as required.
149 ///////////////////////////////////////////////////////////////////////////////
150 HSNDOBJ SndObjCreate(IDirectSound *pDS, LPCTSTR lpName, int iConcurrent);
152 ///////////////////////////////////////////////////////////////////////////////
154 // SndObjDestroy Frees a SNDOBJ and releases all of its buffers.
157 // hSO -- Handle to a SNDOBJ to free.
159 ///////////////////////////////////////////////////////////////////////////////
160 void SndObjDestroy(HSNDOBJ hSO);
162 ///////////////////////////////////////////////////////////////////////////////
164 // SndObjPlay Plays a buffer in a SNDOBJ.
167 // hSO -- Handle to a SNDOBJ to play a buffer from.
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.
173 ///////////////////////////////////////////////////////////////////////////////
174 BOOL SndObjPlay(HSNDOBJ hSO, DWORD dwPlayFlags);
176 ///////////////////////////////////////////////////////////////////////////////
178 // SndObjStop Stops one or more buffers in a SNDOBJ.
181 // hSO -- Handle to a SNDOBJ to play a buffer from.
183 ///////////////////////////////////////////////////////////////////////////////
184 BOOL SndObjStop(HSNDOBJ hSO);
186 ///////////////////////////////////////////////////////////////////////////////
188 // SndObjGetFreeBuffer returns one of the cloned buffers that is
189 // not currently playing
192 // hSO -- Handle to a SNDOBJ
195 // This function is provided so that callers can set things like pan etc
196 // before playing the buffer.
201 ///////////////////////////////////////////////////////////////////////////////
202 IDirectSoundBuffer *SndObjGetFreeBuffer(HSNDOBJ hSO);
204 ///////////////////////////////////////////////////////////////////////////////
208 ///////////////////////////////////////////////////////////////////////////////
210 BOOL DSFillSoundBuffer(IDirectSoundBuffer *pDSB, BYTE *pbWaveData, DWORD dwWaveSize);
211 BOOL DSParseWaveResource(void *pvRes, WAVEFORMATEX **ppWaveHeader, BYTE **ppbWaveData, DWORD *pdwWaveSize);