home *** CD-ROM | disk | FTP | other *** search
/ Planet Source Code Jumbo …e CD Visual Basic 1 to 7 / 5_2007-2008.ISO / data / Zips / Play_multi20264710232006.psc / ReadMe.txt < prev    next >
Text File  |  2006-10-22  |  5KB  |  155 lines
  1. Grigri's Sound Manager for VB6
  2. ==============================
  3.  
  4. Written by
  5.   : grigri <grigri@shinyhappypixels.com>
  6.   
  7. Version
  8.   : 1.0 [22/10/2006]
  9.   
  10. Intro
  11. -----
  12.   
  13. Playing multiple sounds simultaneously is not an easy task, especially in VB.
  14. Most VB applications (and games!) that use sound use the PlaySound()
  15. API function [which only allows one sound at a time]; others resort to DirectX
  16. or third-party DLLs such as BASS. This project is a first step to ending all
  17. that, presenting an API-only method.
  18.  
  19. The multimedia API set is nasty, really nasty. Even in C it's not easy to
  20. manage, and in VB it just gets worse. I have waded through most of the ambiguous
  21. 'documentation' and the pathetic 'code examples' and I believe I've made a
  22. good start.
  23.  
  24. How It Works
  25. ------------
  26.  
  27. The system is deployed as one module and a notification interface.
  28. An internal array of sound buffers (limited to 32 but easily changed) is managed
  29. by the system. All external calls reference the buffer index.
  30.  
  31. Confused? Here's a really quick-and-dirty example of how to use it.
  32.  
  33.     ' Load, play and free a sound in one line of code
  34.     LoadSoundFile FreeBuffer, "c:\some\sound\file.wav", BufferFlagInstant
  35.  
  36. Important Point: At the end of the application, you **MUST** call
  37. `SoundManager.DestroySoundManager()`. If you don't, you'll end up crashing your
  38. application or VB, depending on whether you're in the IDE or not.
  39.  
  40. The notification interface allows you to be notified when a sound is loaded,
  41. freed, playing or stopped.
  42.     
  43. The demo application shows the proper usage.
  44.  
  45. SoundManager API
  46. ----------------
  47.  
  48. * `DestroySoundManager()`
  49.   Parameters  : None
  50.   Return Type : None (`Sub`)
  51.   
  52.   Frees all loaded sounds and destroys internal structures. This *MUST* be
  53.   called when you're done. I can't stress this enough.
  54.   
  55. * `FreeBuffer()`
  56.   Parameters  : None
  57.   Return Type : `Long`
  58.   
  59.   Returns the first free buffer index. Analogous to the VB `FreeFile()` function
  60.   
  61. * `SoundStatus()`
  62.   Parameters  : - `BufferIndex` (IN)          [`Long`]
  63.   Return Type : `SoundBufferStatus` (Enumeration)
  64.   
  65.   Returns the status of the buffer `BufferIndex`
  66.  
  67. * `LoadSoundFile()`
  68.   Parameters  : - `BufferIndex` (IN)          [`Long`]
  69.                 - `FileName`    (IN)          [`String`]
  70.                 - `Flags`       (IN,OPTIONAL) [`SoundBufferFlags` (Enumeration)]
  71.   Return Type : `Boolean`
  72.  
  73.   Loads the specified wave file into the specified buffer. The optional flags
  74.   can be used to make the buffer play/free itself automatically, and/or to not
  75.   generate notifications of status change.
  76.   If the specified buffer is not empty, it will be stopped/freed as required.
  77.   
  78. * `FreeSound()`
  79.   Parameters  : - `BufferIndex` (IN)          [`Long`]
  80.   Return Type : None (`Sub`)
  81.   
  82.   Frees the specified buffer. If it is currently playing, it will be stopped.
  83.  
  84. * `StopSound()`
  85.   Parameters  : - `BufferIndex` (IN)          [`Long`]
  86.   Return Type : None (`Sub`)
  87.  
  88.   Stops playback on the specified buffer. If not playing, nothing happens.
  89.   
  90. * `PlaySound()`
  91.   Parameters  : - `BufferIndex` (IN)          [`Long`]
  92.   Return Type : `Boolean`
  93.  
  94.   Begins playback of the specified buffer. If it is currently playing, it will
  95.   be stopped first, resulting in a "restart" -- playing the buffer from the
  96.   beginning.
  97.  
  98. Notification Interface Callback Methods
  99. ---------------------------------------
  100.  
  101. All callback methods have identical prototypes, passing the buffer index as the
  102. sole parameter, and not returning any value.
  103.  
  104. Each method corresponds to a status change of the specified buffer, and is
  105. called *after* the status has been updated.
  106.  
  107. The names are self-explanatory.
  108.  
  109. * `SoundLoaded()`    : Status is `BufferLoaded`
  110. * `SoundUnloaded()`  : Status is `BufferEmpty`
  111. * `SoundPlayStart()` : Status is `BufferPlaying`
  112. * `SoundPlayEnd()`   : Status is `BufferLoaded`
  113.  
  114. Error Handling
  115. --------------
  116.  
  117. Most functions will simply fail silently in case of an error, returning a
  118. `False` value, if appropriate.
  119.  
  120. The current exception is the `LoadSoundFile()` function, which uses
  121. `MsgBox()` to display errors.
  122.  
  123. Better error handling is being planned for the next version. Honestly.
  124.   
  125. Limitations
  126. -----------
  127.  
  128. * This version only supports uncompressed .WAV files. No .mp3, .au, .voc, .ogg
  129.   or .aac.
  130.   
  131. * Every sound to be played is loaded in memory entirely before playback begins.
  132.   This means that large sound files are not catered for by this method.
  133.   Streaming sounds IS possible with the API, using a free-threaded rotating
  134.   buffer chain, which seems to be impossible (or at least EXTREMELY difficult)
  135.   in VB.
  136.   
  137. * Although it seems stable now, it was quite unstable during development and I
  138.   had more than a few crashes. Each crash took VB down with it.
  139.   So be warned! Use at your own risk.
  140.  
  141. Future Enhancements Planned (short-term)
  142. ---------------------------
  143.  
  144. * Better error handling
  145. * Pause/Resume playback
  146. * Looping
  147. * Loading sounds from resources and memory
  148. * Volume and pitch control
  149.  
  150. Future Enhancements Hoped For (long-term)
  151. -----------------------------
  152.  
  153. * Streaming playback
  154. * Support for different sound formats
  155.