home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Internet / PD / News_Email / Messenger / !Messenger / Resources / THSoundDoc < prev   
Text File  |  1996-12-12  |  5KB  |  148 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. Version 1.20
  13.  
  14. The purpose of THSound is to allow many different samples to be played
  15. without having to load each one as a module in its own right (often
  16. impractical due to potential name clashes). All it does is take a pointer to
  17. some data in raw 8-bit VIDC format and use this to make a sound voice.
  18. THSound is deliberately very basic for flexibility. It is up to your program
  19. to manage memory for the sample data, and to attach the voice to channels and
  20. play it using the standard Sound SWIs.
  21.  
  22. I wrote THSound because I was writing a program which needed to play a large
  23. number of samples, the data for these being embedded in large files with
  24. other resources. I couldn't find a PD program which could do what I wanted
  25. (other modules only seem to be able to load samples as files) so I studied
  26. the PRM and THSound was born.
  27.  
  28. Conditions of use
  29. -----------------
  30. THSound may be freely distributed. It may be used in applications provided it
  31. is unaltered and you credit me, the author. If possible, please include this
  32. file with it (I know that won't always be possible), or at least indicate
  33. that it is available with instructions from PD libraries. As a courtesy it
  34. would be very nice if you send me copies of any programs you write which use
  35. it.
  36.  
  37. Technical details
  38. =================
  39. THSound contains three SWIs for sound sample handling; its SWI chunk is
  40. &4B780 (officially registered with Acorn).
  41.  
  42. SWI's
  43. -----
  44. THSound_InstallSample        &4b780
  45. Entry:    R0 = Address of sample (in VIDC 8-bit signed log format)
  46.     R1 = Size of sample in bytes (word aligned)
  47.     R2 = Slot to install in or 0 for next free slot (see
  48.         Sound_InstallVoice)
  49. Exit:    R0 = Sample's "handle" (pointer to workspace)
  50.     R1 = Voice slot sample is installed in
  51.     R2 = Voice slot (copy of R1)
  52.  
  53. It is recommended that sample data is kept in the RMA, using OS_Module for
  54. memory management (Archimedes), or in a dynamic area (Risc PC). Having sample
  55. data in application workspace could crash SoundDMA if the application is
  56. paged out eg by Wimp_Poll while the sample is playing.
  57.  
  58. Each sample's voice is given the name THSVoice<hh> where <hh> is a unique hex
  59. code.
  60.  
  61.  
  62. THSound_RemoveSample        &4b781
  63. Entry:    R0 = Sample's handle
  64. Exit:    R0   Preserved
  65.  
  66. Use this to kill a THSound sample, do not use Sound_RemoveVoice. The sample's
  67. data is not freed, just its workspace (handle) allocated when it was
  68. installed.
  69.  
  70.  
  71. THSound_GetVoiceSlot        &4b782
  72. Entry:    R0 = Sample's handle
  73. Exit:    R0   Preserved
  74.     R1 = Voice slot
  75.  
  76. Finds the sample's voice slot in case you haven't stored the value returned
  77. by THSound_InstallVoice.
  78.  
  79.  
  80. THSound_ChannelInUse        &4b783
  81. Entry:    R0 = Channel number
  82. Exit:    R0   Non-zero if a THSound sample is playing on specified channel.
  83.  
  84. New in version 1.10, remember to check the version if you use this SWI.
  85.  
  86. This reads data from the SCCB to test whether a THSound voice is
  87. currently playing (it won't work for most other samples, because THSound
  88. uses the SCCB in a slightly non-standard way). The necessary information
  89. in the SCCB is invalid immediately after calling Sound_Control and may
  90. wrongly show the channel not to be in use, so if you want to wait for a
  91. channel to become free you should use something like:
  92.  
  93.   REM First wait for SCCB to be updated, showing channel is in use
  94.   REPEAT
  95.   SYS"THSound_ChannelInUse",1 TO inuse%
  96.   UNTIL inuse%
  97.   REM Now wait until channel is free
  98.   REPEAT
  99.   SYS"THSound_ChannelInUse",1 TO inuse%
  100.   UNTIL NOT inuse%
  101.  
  102. The second loop can be after, say, a Wimp_Poll, but I suggest you put
  103. the first loop immediately after a Sound_Control (or similar)
  104. instruction.
  105.  
  106. THSound_GetPollWord        &4b784
  107. Entry:    R0 = Sample's handle
  108. Exit:    R0   Preserved
  109.     R1 = (Pointer to) poll word
  110.  
  111. New in version 1.20
  112.  
  113. This is more useful than THSound_ChannelInUse for multitasking programs.
  114. Before playing a sample you can set the pollword to 0, and it will be
  115. altered when the sample finishes playing or is interrupted by being detached
  116. from its channel. Therefore you can use PollWordNonZero Wimp events to
  117. receive notification.
  118.  
  119. If the sample finishes playing without being interrupted, -1 or &FFFFFFFF
  120. will be written to the pollword, otherwise another non-zero value will be
  121. written.
  122.  
  123. THPlay
  124. ======
  125. THPlay is a short BASIC program that can be used to play a sample in the
  126. background. It must be given a file containing raw sample data in 8-bit VIDC
  127. format, using the -file parameter in its command line. THPlay loads the
  128. sample into the RMA, starts playing it, then polls the Wimp until it has
  129. finished playing or a time limit is reached. Then THPlay releases the sample
  130. and its memory and quits.
  131.  
  132. Other parameters are optional and are:
  133.  
  134. Parameter    Default    Meaning
  135. ---------    -------    -------
  136. -chan        1    Channel to play sample on
  137. -vol        &17F    Volume to play sample at
  138. -pitch        &2000    Pitch to play sample at
  139. -maxtime    10    Maximum time in seconds before sample is killed
  140.  
  141. THPlay requires at least a 12K WimpSlot. You might like to run it via an Obey
  142. file to ensure THSound gets loaded first and that THPlay isn't allocated an
  143. unnecessarily large Wimpslot. For example:
  144.  
  145. RMEnsure THSound 1.20 RMLoad <Obey$Dir>.THSound
  146. WimpSlot -min 12k -max 12k
  147. <Obey$Dir>.THPlay -pitch &3000 -file %0
  148.