home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilst / thsound / THSoundDoc < prev   
Text File  |  1995-12-21  |  3KB  |  76 lines
  1. THSound
  2. =======
  3. by:
  4.  
  5. Tony Houghton
  6. 271 Upper Weston Lane
  7. Southampton
  8. SO19 9HY
  9.  
  10. tonyh@tcp.co.uk
  11.  
  12. The purpose of THSound is to allow many different samples to be played
  13. without having to load each one as a module in its own right (often
  14. impractical due to potential name clashes). All it does is take a pointer to
  15. some data and use this to make a sound voice. THSound is deliberately very
  16. basic for flexibility. It is up to your program to manage memory for the
  17. sample data, and to attach the voice to channels and play it using the
  18. standard Sound SWIs.
  19.  
  20. I wrote THSound because I was writing a program which needed to play a large
  21. number of samples, the data for these being embedded in large files with
  22. other resources. I couldn't find a PD program which could do what I wanted
  23. (other modules only seem to be able to load samples as files) so I studied
  24. the PRM and THSound was born.
  25.  
  26. Conditions of use
  27. -----------------
  28. THSound may be freely distributed. It may be used in applications provided it
  29. is unaltered and you credit me, the author. If possible, please include this
  30. file with it (I know that won't always be possible), or at least indicate
  31. that it is available with instructions from PD libraries. As a courtesy it
  32. would be very nice if you send me copies of any programs you write which use
  33. it.
  34.  
  35. Technical details
  36. =================
  37. THSound contains three SWIs for sound sample handling; its SWI chunk is
  38. &4B780 (officially registered with Acorn).
  39.  
  40. SWI's
  41. -----
  42. THSound_InstallSample        &4b780
  43. Entry:    R0 = Address of sample (in VIDC 8-bit signed log format)
  44.     R1 = Size of sample in bytes (word aligned)
  45.     R2 = Slot to install in or 0 for next free slot (see
  46.         Sound_InstallVoice)
  47. Exit:    R0 = Sample's "handle" (pointer to workspace)
  48.     R1 = Voice slot sample is installed in
  49.     R2 = Voice slot (copy of R1)
  50.  
  51. It is recommended that sample data is kept in the RMA, using OS_Module for
  52. memory management (Archimedes), or in a dynamic area (Risc PC). Having sample
  53. data in application workspace could crash SoundDMA if the application is
  54. paged out eg by Wimp_Poll while the sample is playing.
  55.  
  56. Each sample's voice is given the name THSVoice<hh> where <hh> is a unique hex
  57. code.
  58.  
  59.  
  60. THSound_RemoveSample        &4b781
  61. Entry:    R0 = Sample's handle
  62. Exit:    R0   Preserved
  63.  
  64. Use this to kill a THSound sample, do not use Sound_RemoveVoice. The sample's
  65. data is not freed, just its workspace (handle) allocated when it was
  66. installed.
  67.  
  68.  
  69. THSound_GetVoiceSlot        &4b782
  70. Entry:    R0 = Sample's handle
  71. Exit:    R0   Preserved
  72.     R1 = Voice slot
  73.  
  74. Finds the sample's voice slot in case you haven't stored the value returned
  75. by THSound_InstallVoice.
  76.