DSUTIL.H

/*========================================================================== 
 * 
 *  Copyright (C) 1995 Microsoft Corporation. All Rights Reserved. 
 * 
 *  File:       dsutil.cpp 
 *  Content:    Routines for dealing with sounds from resources 
 * 
 * 
 ***************************************************************************/ 
 
#ifdef __cplusplus 
extern "C" { 
#endif 
 
/////////////////////////////////////////////////////////////////////////////// 
// 
// DSLoadSoundBuffer    Loads an IDirectSoundBuffer from a Win32 resource in 
//                      the current application. 
// 
// Params: 
//  pDS         -- Pointer to an IDirectSound that will be used to create 
//                 the buffer. 
// 
//  lpName      -- Name of WAV resource to load the data from.  Can be a 
//                 resource id specified using the MAKEINTRESOURCE macro. 
// 
// Returns an IDirectSoundBuffer containing the wave data or NULL on error. 
// 
// example: 
//  in the application's resource script (.RC file) 
//      Turtle WAV turtle.wav 
// 
//  some code in the application: 
//      IDirectSoundBuffer *pDSB = DSLoadSoundBuffer(pDS, "Turtle"); 
// 
//      if (pDSB) 
//      { 
//          IDirectSoundBuffer_Play(pDSB, 0, 0, DSBPLAY_TOEND); 
//          /* ... */ 
// 
/////////////////////////////////////////////////////////////////////////////// 
IDirectSoundBuffer *DSLoadSoundBuffer(IDirectSound *pDS, LPCTSTR lpName); 
 
/////////////////////////////////////////////////////////////////////////////// 
// 
// DSReloadSoundBuffer  Reloads an IDirectSoundBuffer from a Win32 resource in 
//                      the current application. normally used to handle 
//                      a DSERR_BUFFERLOST error. 
// Params: 
//  pDSB        -- Pointer to an IDirectSoundBuffer to be reloaded. 
// 
//  lpName      -- Name of WAV resource to load the data from.  Can be a 
//                 resource id specified using the MAKEINTRESOURCE macro. 
// 
// Returns a BOOL indicating whether the buffer was successfully reloaded. 
// 
// example: 
//  in the application's resource script (.RC file) 
//      Turtle WAV turtle.wav 
// 
//  some code in the application: 
//  TryAgain: 
//      HRESULT hres = IDirectSoundBuffer_Play(pDSB, 0, 0, DSBPLAY_TOEND); 
// 
//      if (FAILED(hres)) 
//      { 
//          if ((hres == DSERR_BUFFERLOST) && 
//              DSReloadSoundBuffer(pDSB, "Turtle")) 
//          { 
//              goto TryAgain; 
//          } 
//          /* deal with other errors... */ 
//      } 
// 
/////////////////////////////////////////////////////////////////////////////// 
BOOL DSReloadSoundBuffer(IDirectSoundBuffer *pDSB, LPCTSTR lpName); 
 
/////////////////////////////////////////////////////////////////////////////// 
// 
// DSGetWaveResource    Finds a WAV resource in a Win32 module. 
// 
// Params: 
//  hModule     -- Win32 module handle of module containing WAV resource. 
//                 Pass NULL to indicate current application. 
// 
//  lpName      -- Name of WAV resource to load the data from.  Can be a 
//                 resource id specified using the MAKEINTRESOURCE macro. 
// 
//  ppWaveHeader-- Optional pointer to WAVEFORMATEX * to receive a pointer to 
//                 the WAVEFORMATEX header in the specified WAV resource. 
//                 Pass NULL if not required. 
// 
//  ppbWaveData -- Optional pointer to BYTE * to receive a pointer to the 
//                 waveform data in the specified WAV resource.  Pass NULL if 
//                 not required. 
// 
//  pdwWaveSize -- Optional pointer to DWORD to receive the size of the 
//                 waveform data in the specified WAV resource.  Pass NULL if 
//                 not required. 
// 
// Returns a BOOL indicating whether a valid WAV resource was found. 
// 
/////////////////////////////////////////////////////////////////////////////// 
BOOL DSGetWaveResource(HMODULE hModule, LPCTSTR lpName, 
    WAVEFORMATEX **ppWaveHeader, BYTE **ppbWaveData, DWORD *pdwWaveSize); 
 
/////////////////////////////////////////////////////////////////////////////// 
// 
// HSNDOBJ             Handle to a SNDOBJ object. 
// 
//  SNDOBJs are implemented in dsutil as an example layer built on top 
//      of DirectSound. 
// 
//      A SNDOBJ is generally used to manage individual 
//      sounds which need to be played multiple times concurrently.  A 
//      SNDOBJ represents a queue of IDirectSoundBuffer objects which 
//      all refer to the same buffer memory. 
// 
//      A SNDOBJ also automatically reloads the sound resource when 
//      DirectSound returns a DSERR_BUFFERLOST 
// 
/////////////////////////////////////////////////////////////////////////////// 
#ifndef _HSNDOBJ_DEFINED 
DECLARE_HANDLE32(HSNDOBJ); 
#endif 
 
/////////////////////////////////////////////////////////////////////////////// 
// 
// SndObjCreate     Loads a SNDOBJ from a Win32 resource in 
//                  the current application. 
// 
// Params: 
//  pDS         -- Pointer to an IDirectSound that will be used to create 
//                 the SNDOBJ. 
// 
//  lpName      -- Name of WAV resource to load the data from.  Can be a 
//                 resource id specified using the MAKEINTRESOURCE macro. 
// 
//  iConcurrent -- Integer representing the number of concurrent playbacks of 
//                 to plan for.  Attempts to play more than this number will 
//                 succeed but will restart the least recently played buffer 
//                 even if it is not finished playing yet. 
// 
// Returns an HSNDOBJ or NULL on error. 
// 
// NOTES: 
//      SNDOBJs automatically restore and reload themselves as required. 
// 
/////////////////////////////////////////////////////////////////////////////// 
HSNDOBJ SndObjCreate(IDirectSound *pDS, LPCTSTR lpName, int iConcurrent); 
 
/////////////////////////////////////////////////////////////////////////////// 
// 
// SndObjDestroy  Frees a SNDOBJ and releases all of its buffers. 
// 
// Params: 
//  hSO         -- Handle to a SNDOBJ to free. 
// 
/////////////////////////////////////////////////////////////////////////////// 
void SndObjDestroy(HSNDOBJ hSO); 
 
/////////////////////////////////////////////////////////////////////////////// 
// 
// SndObjPlay   Plays a buffer in a SNDOBJ. 
// 
// Params: 
//  hSO         -- Handle to a SNDOBJ to play a buffer from. 
// 
//  dwPlayFlags -- Flags to pass to IDirectSoundBuffer::Play.  It is not 
//                 legal to play an SndObj which has more than one buffer 
//                 with the DSBPLAY_LOOPING flag.  Pass 0 to stop playback. 
// 
/////////////////////////////////////////////////////////////////////////////// 
BOOL SndObjPlay(HSNDOBJ hSO, DWORD dwPlayFlags); 
 
/////////////////////////////////////////////////////////////////////////////// 
// 
// SndObjStop   Stops one or more buffers in a SNDOBJ. 
// 
// Params: 
//  hSO         -- Handle to a SNDOBJ to play a buffer from. 
// 
/////////////////////////////////////////////////////////////////////////////// 
BOOL SndObjStop(HSNDOBJ hSO); 
 
/////////////////////////////////////////////////////////////////////////////// 
// 
// SndObjGetFreeBuffer      returns one of the cloned buffers that is 
//                          not currently playing 
// 
// Params: 
//  hSO         -- Handle to a SNDOBJ 
// 
// NOTES: 
//  This function is provided so that callers can set things like pan etc 
//  before playing the buffer. 
// 
// EXAMPLE: 
//  ... 
// 
/////////////////////////////////////////////////////////////////////////////// 
IDirectSoundBuffer *SndObjGetFreeBuffer(HSNDOBJ hSO); 
 
/////////////////////////////////////////////////////////////////////////////// 
// 
// helper routines 
// 
/////////////////////////////////////////////////////////////////////////////// 
 
BOOL DSFillSoundBuffer(IDirectSoundBuffer *pDSB, BYTE *pbWaveData, DWORD dwWaveSize); 
BOOL DSParseWaveResource(void *pvRes, WAVEFORMATEX **ppWaveHeader, BYTE **ppbWaveData, DWORD *pdwWaveSize); 
 
#ifdef __cplusplus 
} 
#endif