home *** CD-ROM | disk | FTP | other *** search
/ Microsoft Multimedia Jumpstart 1.1a / CD_ROM.BIN / develpmt / source / wavemix / wavemix.txt < prev   
Encoding:
Text File  |  1993-08-26  |  16.5 KB  |  515 lines
  1. The wavemix DLL is a utility that allows multiple wav files to be played
  2. simultaneously. It is designed to be as simple to use as possilbe but still
  3. have the power to do what is required by games.  The DLL supports 8 channels
  4. of simultaneous wave play, the ability to queue up waves along the same
  5. channel and wave completion notification.
  6.  
  7. The wavemix DLL currently supports 11.025 Khz, 22.05 Khz and 44.1 Khz 8-bit Mono.
  8. Wave conversion from the file format is done automatically to the output sampling rate
  9. when the file is opened.  The sampling rate is set in wavemix.ini.  See wavemix.ini for
  10. details.  Stereo files and 16 bit files are converted to 8-bit mono when the wave is loaded.
  11.  
  12. The API consists of the following functions:
  13.  
  14. HANDLE WINAPI WaveMixInit(void);
  15. HANDLE WINAPI WaveMixActivate(HANDLE hMixSession, BOOL fActivate);
  16. LPMIXWAVE WINAPI WaveMixOpenWave(HANDLE hMixSession, LPSTR szWaveFilename, HINSTANCE hInst, DWORD dwFlags);
  17. UINT WINAPI WaveMixOpenChannel(HANDLE hMixSession, int iChannel, DWORD dwFlags);
  18. UINT WINAPI WaveMixPlay(LPMIXPLAYPARAMS lpMixPlayParams);
  19. UINT WINAPI WaveMixFlushChannel(HANDLE hMixSession, int iChannel, DWORD dwFlags);
  20. UINT WINAPI WaveMixCloseChannel(HANDLE hMixSession, int iChannel, DWORD dwFlags);
  21. UINT WINAPI WaveMixFreeWave(LPMIXWAVE lpMixWave);
  22. UINT WINAPI WaveMixCloseSession(HANDLE hMixSession);
  23. void WINAPI WaveMixPump(void);
  24. WORD WINAPI WaveMixGetInfo(LPWAVEMIXINFO lpWaveMixInfo);
  25.  
  26. In order to play a file a program must: 
  27. 1. Initialize the DLL with WaveMixInit()
  28. 2. Open a wave file with WaveMixOpenFile()
  29. 3. Open a channel with WaveMixOpenChannel()
  30. 4. Play the file using WaveMixPlay()
  31.  
  32. A given channel can be silenced by calling WaveMixFlushChannel() at any time.
  33.  
  34. When the program is done with playing sounds it should
  35.  
  36. 1. Close the open channels using WaveMixCloseChannel()
  37. 2. Free the memmory for the waves using WaveMixFreeWave()
  38. 3. End the session with WaveMixCloseSession()
  39.  
  40. Note 1:
  41. An appliction should call WaveMixActivate(FALSE) when it loses the focus so that
  42. the waveform device can be freed for other applications.  When focus is regained
  43. the application can call WaveMixActivate(TRUE);
  44.  
  45. Note 2:
  46. An application that does not release the processor can cause the sound to "skip"
  47. To avoid this it can call WaveMixPump() frequently.
  48. -------------------------------------------------------------------------------
  49.  
  50. WORD WINAPI WaveMixGetInfo(LPWAVEMIXINFO lpWaveMixInfo);
  51.  
  52. parameters
  53.  
  54. lpMixWaveMixInfo
  55.  
  56.     a pointer to a WAVEMIXINFO structure that will get filled in by the WaveMix DLL:
  57.  
  58.     typedef struct
  59.     {
  60.         WORD wSize;
  61.         BYTE bVersionMajor;
  62.         BYTE bVersionMinor;
  63.         char szDate[12]; /* Mmm dd yyyy */
  64.         DWORD dwFormats; /* see waveOutGetDevCaps (wavemix requires synchronous device) */
  65.     }
  66.     WAVEMIXINFO, *PWAVEMIXINFO, FAR * LPWAVEMIXINFO;
  67.  
  68.     wSize: should be set to sizeof(WAVEMIXINFO) before calling WaveMixGetInfo.
  69.  
  70.     bVersionMajor: the major version of the DLL.
  71.  
  72.     bVersionMinor: the minor version of the DLL.
  73.  
  74.     szDate: The compilation date of the DLL, Null terminated string in form Mmm dd yyyy
  75.             where Mmm is one of the following:  "Jan","Feb","Mar","Apr","May","Jun","Jul","Aug",
  76.             "Sep","Oct","Nov","Dec".
  77.  
  78.     dwFormats: Specifies which standard formats are supported. The supported formats are specified
  79.                with a logical OR of the flags listed in WAVEOUTCAPS documentation:
  80.  
  81.                for version 1.0: the following wave formats are supported:
  82.  
  83.                     WAVE_FORMAT_1M08  /* 11.025 kHz, Mono,   8-bit  */
  84.                     WAVE_FORMAT_1S08  /* 11.025 kHz, Stereo, 8-bit  */
  85.                     WAVE_FORMAT_1M16  /* 11.025 kHz, Mono,   16-bit */
  86.                     WAVE_FORMAT_1S16  /* 11.025 kHz, Stereo, 16-bit */
  87.                     WAVE_FORMAT_2M08  /* 22.05  kHz, Mono,   8-bit  */
  88.                     WAVE_FORMAT_2S08  /* 22.05  kHz, Stereo, 8-bit  */
  89.                     WAVE_FORMAT_2M16  /* 22.05  kHz, Mono,   16-bit */
  90.                     WAVE_FORMAT_2S16  /* 22.05  kHz, Stereo, 16-bit */
  91.                     WAVE_FORMAT_4M08  /* 44.1   kHz, Mono,   8-bit  */
  92.                     WAVE_FORMAT_4S08  /* 44.1   kHz, Stereo, 8-bit  */
  93.                     WAVE_FORMAT_4M16  /* 44.1   kHz, Mono,   16-bit */
  94.                     WAVE_FORMAT_4S16  /* 44.1   kHz, Stereo, 16-bit */
  95.  
  96.                 this is done by converting the wave format of the input wave to the current
  97.                 output format when the wave is opened.
  98.  
  99. return value
  100.  
  101. zero will be returned if the size fields match and the structure will be filled in.
  102.  
  103. if the size fields do not match the DLL will return the size that it expected.  None of the fields
  104. in the structure will be filled in.
  105.  
  106. -------------------------------------------------------------------------------
  107.  
  108. HANDLE WINAPI WaveMixInit(void);
  109.  
  110. This function should be called before any of the other functions.  It will return
  111. a handle that should be used for subsequent API calls.
  112.  
  113. Parameters
  114.  
  115. none
  116.  
  117. Return Value
  118.  
  119. NULL will be returned if an error occurs
  120.  
  121. -------------------------------------------------------------------------------
  122.  
  123. UINT WINAPI WaveMixActivate(HANDLE hMixSession, BOOL fActivate);
  124.  
  125. This function should be called when an application loses the focus or otherwise
  126. becomes inactive.  This will permit other applications to aquire the wave output
  127. device. Calling this function keeps all the channels open.
  128.  
  129. Note:
  130.  
  131. 1. The wavemix DLL will keep sounds that were queued while the application was
  132. active in the queue.  When wavemix play is subsequently reactivated the sounds will
  133. continue from where they were.  (there will be a small amount of data loss equivalent
  134. to the amount of data that was buffered in the wave driver).  
  135.  
  136. 2. Calls to WaveMixPlay that are made while the application is not active will not be queued.
  137.  
  138. 3. The Application can call WaveMixFlush if it does not wish the data to be pending while
  139. it is inactive.
  140.  
  141. Parameters
  142.  
  143. HANDLE hMixSession
  144.  
  145. handle that was returned by WaveMixInit()
  146.  
  147. BOOL fActivate
  148.  
  149.     TRUE:  The application is being activated and wishes to regain the wave output
  150.            device
  151.     FALSE: The application is not active and wishes to be a good Windows Citizen and
  152.            allow other applications to use the wave output device.  This call will
  153.            cause all the channels to be flushed.
  154.  
  155. Return Value
  156.  
  157. Returns zero if the function was successful. Otherwise, it returns an error
  158. number. Possible error returns are:
  159.  
  160. MMSYSERR_ALLOCATED
  161.  
  162. Specified resource is already allocated to a process. try again later.
  163.  
  164. MMSYSERR_NOMEM
  165.  
  166. Unable to allocate or lock memory.
  167.  
  168. MMSYSERR_ERROR
  169.  
  170. an internal error
  171.  
  172. -------------------------------------------------------------------------------
  173.  
  174. LPMIXWAVE WINAPI WaveMixOpenWave(HANDLE hMixSession, LPSTR szWaveFilename,
  175.                                  HINSTANCE hInst, DWORD dwFlags);
  176.  
  177. Parameters
  178.  
  179. HANDLE hMixSession
  180.  
  181. handle that was returned by WaveMixInit()
  182.  
  183. LPSTR  szWaveFileName
  184.  
  185. szWaveFileName can be the name of a wave file to open, or the name of a WAVE resource
  186. to open, or an integer ID of a WAVE resource to open.  See the dwFlags parameter for
  187. details
  188.  
  189. HINSTANCE hInst
  190.  
  191. Identifies the instance of the module whose executable file contains the resource.
  192. See the dwFlags parameter for details.
  193.  
  194. DWORD dwFlags
  195.  
  196.     WMIX_FILE: if this bit is set then szWaveFileName specifies a far pointer to a
  197.                string containing the filename of the file to open.  hInst is ignored.
  198.  
  199.                The MS-DOS filename should not be longer than 128 bytes, including the
  200.                terminating NULL.
  201.  
  202.                Currently the DLL will only permit 11Khz 8-bit mono files to be opened.
  203.  
  204.                This flag should not be set with WMIX_RESOURCE    
  205.  
  206.     WMIX_RESOURCE:  if this bit is set then szWaveFileName specifies a WAVE resource
  207.                to be opened in hInst.
  208.  
  209.                If the high-order word of the szWaveFileName is zero, the low-order word
  210.                specifies the integer identifier of the name or type of the given resource.
  211.                Otherwise, the parameter is a long pointers to a null-terminated string. If
  212.                the first character of the string is a pound sign (#), the remaining
  213.                characters represent a decimal number that specifies the integer identifier
  214.                of the resource's name or type. For example, the string #258 represents the
  215.                integer ID 258. 
  216.  
  217.                To embed a wave file in a resource use the following format in your .rc file:
  218.                
  219.                GameSound WAVE gamesnd.wav
  220.  
  221.                Note: to reduce the amount of memory required for the resources used by an
  222.                application, the application should refer to the resources by integer
  223.                identifier instead of by name.
  224.  
  225. Return Value
  226.  
  227. NULL will be returned if the dll was unable to open the file or resource.
  228.  
  229. -------------------------------------------------------------------------------
  230.  
  231. UINT WINAPI WaveMixOpenChannel(HANDLE hMixSession, int iChannel, DWORD dwFlags);
  232.  
  233. Parameters
  234.  
  235. HANDLE hMixSession
  236.  
  237. handle that was returned by WaveMixInit()
  238.  
  239. int iChannel
  240.  
  241. Specifies a number which indicates which channel should be opened.  Currently 
  242. the DLL supports channels 0 though 7.
  243.  
  244. It is not necessary to open or close them in any particular order.
  245.  
  246. DWORD dwFlags
  247.     WMIX_OPENSINGLE: iChannel specifies the single channel to be opened.
  248.     WMIX_ALL:    all the available channels will be opened. iChannel is ignored.
  249.     WMIX_OPENCOUNT: iChannel specifies the number of channels to open.  
  250.                eg. if iChannel==4 then channels 0 through 3 will be opend.
  251.  
  252.  
  253. Return Value
  254.  
  255. Returns zero if the function was successful. Otherwise, it returns an error
  256. number. Possible error returns are:
  257.  
  258. MMSYSERR_INVALHANDLE
  259.  
  260. if an invalid channel (ie > 7) was specified
  261.  
  262. MMSYSERR_BADDEVICEID
  263.  
  264. Specified device ID is out of range.
  265.  
  266. MMSYSERR_ALLOCATED
  267.  
  268. Specified resource is already allocated.
  269. Or the channel has already been opened.
  270.  
  271. MMSYSERR_NOMEM
  272.  
  273. Unable to allocate or lock memory.
  274.  
  275. WAVERR_BADFORMAT
  276.  
  277. Attempted to open with an unsupported wave format.
  278.  
  279. WAVERR_SYNC
  280.  
  281. Attempted to open a synchronous driver without specifying the WAVE_ALLOWSYNC flag.
  282.  
  283. MMSYSERR_ERROR
  284.  
  285. an internal error
  286.  
  287. -------------------------------------------------------------------------------
  288.  
  289. UINT WINAPI WaveMixPlay(LPMIXPLAYPARAMS lpMixPlayParams);
  290.  
  291. parameters
  292.  
  293. lpMixPlayParams
  294.  
  295.     a pointer to a MIXPLAYPARAMS structure:
  296.  
  297.     typedef struct
  298.     {
  299.         WORD wSize;
  300.         HANDLE hMixSession;
  301.         int iChannel;
  302.         LPMIXWAVE lpMixWave;
  303.         HWND hWndNotify;
  304.         DWORD dwFlags;
  305.         WORD wLoops;  /* 0xFFFF means loop forever */
  306.     }
  307.     MIXPLAYPARAMS, * PMIXPLAYPARAM, FAR * LPMIXPLAYPARAMS;
  308.  
  309.     wSize: should be set to sizeof(MIXPLAYPARAMS)
  310.  
  311.     hMixSession: the handle that was returned by WaveMixInit()
  312.  
  313.     iChannel: the channel on which the wave should be played.
  314.  
  315.     lpMixWave: a wave which was opened using WaveMixOpenWave()
  316.  
  317.     hWndNotify: a window handle to receive the MM_WOM_DONE message
  318.         when the wave completes.  If this value is set to NULL then
  319.         the message will not be posted.
  320.  
  321.     dwFlags: WMIX_QUEUEWAVE: the wave will be placed on the specified channel
  322.                              and played after all waves which are currently
  323.                              waiting to play on that channel.
  324.              WMIX_CLEARQUEUE:this wave will preempt all waves currently playing
  325.                               on the specified channel.  Notification messages
  326.                              will not be sent for any waves that get dumped.
  327.                              This message should not be combined with WMIX_QUEUEWAVE
  328.              WMIX_HIGHPRIORITY: Play this way immediately.  This flag will interrupt
  329.                              the data buffered in the wave driver and remix the sound.
  330.                              If this flag is not set you could experience up to a half
  331.                              second delay before sound is played.
  332.  
  333.                              Note: if WMIX_QUEUEWAVE is set with this flag then a sound
  334.                              playing on the channel will not be prempted, but it will
  335.                              begin immediately after the previous sound finishes.  If no
  336.                              sound is currently playing on this channel then a remix will
  337.                              occur.
  338.                              
  339.              WMIX_USELRUCHANNEL: the wave should be played on any available channel
  340.                              or played on the channel that was least recently used.
  341.                              This flag should be combined with WMIX_QUEUEWAVE or
  342.                              WMIX_CLEARQUEUE.
  343.  
  344.             WMIX_WAIT:         setting this flag cause waveMixPlay to put the play information on
  345.                              a "waiting list" to play.  when waveMixPlay is called without this
  346.                              flag set it will process the calls in the order they were received.
  347.                              This is useful if you want to play multiple sounds simultaneously.
  348.  
  349.                              Note 1: This flag is not a 'pause'.  Waves that are playing will continue
  350.                              to play regardless of how many files are on the wait list.
  351.  
  352.                              Note 2: Since the waves that are submitted with this flag set are not
  353.                              checked until waveMixPlay is called without the flag set you should
  354.                              be careful about using other API calls before playing the sounds.
  355.                              eg. WaveMixFlushChannel and WaveMixCloseChannel do not process the
  356.                              wait list.
  357.  
  358.     wLoops: The number of times the wave should be repeated.  If dwLoops is set to 
  359.             0xFFFF the wave will loop until the channel it is on is flushed, preempted,
  360.             or closed.
  361.  
  362. Return Value
  363.  
  364. Returns zero if the function was successful. Otherwise, it returns an error
  365. number. Possible error returns are:
  366.  
  367. MMSYSERR_INVALHANDLE
  368.  
  369. The specified channel has not been opened or invalid lpMixWave was passed in
  370.  
  371. MMSYSERR_NOMEM
  372.  
  373. The dll has run out of internal memory to queue up waves.  Wait until some 
  374. sounds complete and then try again.
  375.  
  376. -------------------------------------------------------------------------------
  377.  
  378. UINT WINAPI WaveMixFlushChannel(HANDLE hMixSession, int iChannel, DWORD dwFlags);
  379.  
  380. This function will empty the queue of any waves waiting to play on this channel.
  381. This function can be called to stop a wave that is playing on the channel without
  382. affecting any of the other channels.
  383.  
  384. Parameters
  385.  
  386. HANDLE hMixSession
  387.  
  388. The handle that was returned by WaveMixInit()
  389.  
  390. int iChannel
  391.  
  392. an integer which specifies a previously opened channel
  393.  
  394. DWORD dwFlags
  395.                                                      
  396.     WMIX_ALL: causes all the channels to be flushed. iChannel is ignored.
  397.     WMIX_NOREMIX: prevents WaveMixFlushChannel from causing the data to be
  398.                   immediately remixed.  This is useful if you want to flush
  399.                   more than one channel, or if you will be calling WaveMixPlay
  400.                   with a HIPRIORITY wave following WaveMixFlushChannel
  401.  
  402. Return Value
  403.  
  404. Returns zero if the function was successful. Otherwise, it returns an error
  405. number. Possible error returns are:
  406.  
  407. MMSYSERR_INVALHANDLE
  408.  
  409. The specified channel was not open
  410.  
  411. MMSYSERR_INVALPARAM
  412.  
  413. One of the parameters passed to the function is not valid
  414.  
  415. -------------------------------------------------------------------------------
  416.  
  417. UINT WINAPI WaveMixCloseChannel(HANDLE hMixSession, int iChannel, DWORD dwFlags);
  418.  
  419. This function will flush and close the specified channel.
  420.  
  421. Parameters
  422.  
  423. HANDLE hMixSession
  424.  
  425. The handle that was returned by WaveMixInit()
  426.  
  427. int iChannel
  428.  
  429. an integer which specifies a previously opened channel
  430.  
  431. DWORD dwFlags
  432.                                                      
  433.     WMIX_ALL: causes all the channels to be flushed. iChannel is ignored.
  434.  
  435. Return Value
  436.  
  437. Returns zero if the function was successful. Otherwise, it returns an error
  438. number. Possible error returns are:
  439.  
  440. MMSYSERR_INVALHANDLE
  441.  
  442. The specified channel was not open
  443.  
  444. -------------------------------------------------------------------------------
  445.  
  446. UINT WINAPI WaveMixFreeWave(HANDLE hMixSession, LPMIXWAVE lpMixWave);
  447.  
  448. Parameters
  449.  
  450. HANDLE hMixSession
  451.  
  452. The handle that was returned by WaveMixInit()
  453.  
  454. lpMixWave
  455.  
  456. A pointer that was created by WaveMixOpenWave()
  457.  
  458. Return Value
  459.  
  460. Returns zero if the function was successful. Otherwise, it returns an error
  461. number. Possible error returns are:
  462.  
  463. MMSYSERR_INVALHANDLE
  464.  
  465. The given pointer was not valid
  466.  
  467. -------------------------------------------------------------------------------
  468. UINT WINAPI WaveMixCloseSession(HANDLE hMixSession);
  469.  
  470. This function pairs up with WaveMixInit().  It should be called before the 
  471. application terminates.
  472.  
  473. Parameters
  474.  
  475. HANDLE hMixSession
  476.  
  477. The handle that was returned by WaveMixInit()
  478.  
  479. Return Value
  480.  
  481. Returns zero if the function was successful. Otherwise, it returns an error
  482. number. Possible error returns are:
  483.  
  484. MMSYSERR_INVALHANDLE
  485.  
  486. The given handle was not a valid session
  487.  
  488. -------------------------------------------------------------------------------
  489.  
  490. void WINAPI WaveMixPump(void);
  491.  
  492. Calling this function causes the WaveMix DLL to mix the next slice of wave data
  493. and submit it to the wave drivers.  This function can be called if the application
  494. does a lot of processing and fails to allow messages to reach the WaveMix DLL in 
  495. time to avoid drying up the wave queue.
  496.  
  497. Parameters
  498.  
  499. none
  500.  
  501. Return Value
  502.  
  503. none
  504.  
  505. -------------------------------------------------------------------------------
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.