home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1B / DATAFILE_PDCD1B.iso / _pocketbk / pocketbook / 003 / sndfrc_zip / SNDFRC.DOC next >
Text File  |  1992-05-13  |  7KB  |  168 lines
  1. Using SNDFRC.LDD from Opl
  2. =========================
  3. These notes comment the associated program, TESTMUS.OPL.
  4. This demonstrates the use of SNDFRC.LDD, which is an extension of the
  5. Operating System allowing better access to the loudspeaker on the
  6. Series3.  Sounds played via the loudspeaker are generally louder than
  7. those played via the buzzer (eg the output of BEEP commands in Opl).
  8.  
  9. In order for the program to work, the file SNDFRC.LDD should be
  10. placed in M:\ on the Series3.  Somebody who wanted to place this LDD
  11. elsewhere could alter the code inside the routine InstMus:.
  12.  
  13. Overview
  14. --------
  15.  
  16. TESTMUS.OPL demonstrates:
  17.     (1) Installing and removing the LDD
  18.     (2) Simple playing of "tunes"
  19.     (3) More advanced playing of "tunes" that can be cancelled.
  20.  
  21. The easiest bit to understand is (2), which involves the routines
  22. OpenMus:, play:, and CloseMus:.  (Many users could get by with a
  23. simpler version of OpenMus:, to start with.)
  24. The only variables needed for these are mcb% and vals%().
  25. The variable mcb% is the handle of the control block filled in by
  26. ioopen.  It needs to be passed to subsequent calls ioclose and
  27. iowrite.
  28.  
  29. The essence of OpenMus: is the single line
  30.     ioopen(mcb%,"MUS:",-1)
  31. The rest of it is just error handling to cope with the case when
  32. another application already has the sound channel in use (eg an
  33. application which is DTMF dialling).
  34.  
  35. The way the sounds are actually emitted is in response to the iowrite
  36. call.  The buf% parameter here is the address of an array of
  37. integers, as set up by the caller.  The len% parameter is how many
  38. notes to play.
  39.  
  40. Each "note" is made up of three parts: tone, length, and volume.
  41. Eg in
  42.     vals%(9) = $3b + (40*256) + (3*64)
  43. the tone is $3b, the length (duration) is 40, and the volume is 3.
  44.  
  45. There are only 4 possible values of volume: 0 (the quietest), 1, 2,
  46. and 3 (the loudest).
  47.  
  48. The duration is measured in 1/100 ths of a second, and can have any
  49. value from 1 to 255.  Note that because of the limitations of Opl you
  50. cannot type in eg
  51.     vals%(2) = $0 + (150*256) + (2*64)
  52. (without getting an OVERFLOW error raised)
  53. but you can instead use
  54.     vals%(2) = $0 + ((256-150)*256) + (2*64)
  55.  
  56. The allowed values of tone in principle range from $0 to $3f.
  57. In practice you may consider using:
  58.  
  59. DTMF (dual) tones:
  60. ------------------
  61. $10 for digit 0, $11 for digit 1, ..., $19 for digit 9, $1a for a
  62. (defined for some telephone systems), ..., $1d for d, $1e for * and
  63. $1f for #.
  64.  
  65. MODEM tones:
  66. ------------
  67. $24 gives 1300 Hz, $25 gives 2100 Hz, then 1200, 2200, 980, 1180,
  68. 1070, 1270, 1650, 1850, 2025, and $2f gives 2225 Hz.
  69.  
  70. MUSICAL tones:
  71. --------------
  72. Twenty five notes are possible, incrementing by semi-tones over a 2
  73. octave interval from D#5 to D#7:
  74. $30, $31, $32, $33, $34, $35, $36, $37, $38, $39, $3a, $29, $3b, $3c,
  75. $3d, $0e, $3e, $2c, $3f, $04, $05, $25, $2f, $06, $07.
  76.  
  77. Pauses:
  78. -------
  79. If tone is set to $0, the speaker will remain silent for the
  80. specified duration.
  81.  
  82. When to open and close the MUS: device
  83. --------------------------------------
  84. If you like, just copy TESTMUS.OPL and open and close the device at
  85. the beginning and end of your program.
  86.  
  87. But this is actually very anti-social!!
  88.  
  89. For example, if you have MUS: open, it prevents any other application
  90. using the loudspeaker at all.  if you wrote a game which opened
  91. MUS: at its beginning, and only made sounds from time to time, and
  92. left this game in the background while you went to the Data
  93. application to look up a telephone number, you would find the DTMF
  94. dialler would be unable to beep, and would report "Sound system in
  95. use" - even though the game is silent at the time.
  96.  
  97. Far better in these situations for a program to open MUS: just before
  98. it needs to do some playing, and then close it again immediately
  99. afterwards.  Ie put the open and close code inside the play: routine.
  100.  
  101. When to install and free SNDFRC.LDD
  102. -----------------------------------
  103. This is potentially a lengthy topic, and the following notes only
  104. skim the surface.
  105. The best advice is probably that a program which needs to use MUS:
  106. should always call the equivalent of InstMus: on its start up, and
  107. ignore any error message given if the device is already installed. 
  108. Further, it should probably *NOT* call FreeMus: at its close, since
  109. this may have an unexpected effect on other applications running
  110. simultaneously, which also access MUS:.
  111.  
  112. Instead, leave the LDD permanently installed if you can (it takes up
  113. around 1.5k of ram), but provide another OPO whose sole content is
  114. the equivalent of FreeMus:, so that someone who wants to recover the
  115. ram space later can do so.
  116.  
  117. The magic runes inside InstMus: invoke an operating system routine to
  118. install the LDD, so that any subsequent reference to "MUS:" will be
  119. accepted by the operating system (the code to inplement MUS: being
  120. located inside the LDD).
  121.  
  122. Allowing tunes to be cancelled
  123. ------------------------------
  124. If you run TESTMUS, you will find it has four phases:
  125.     A musical scale, with varying volume and duration
  126.     A constant note with varying volume
  127.     Some DTMF tones
  128.     The same DTMF tones repeated.
  129. The difference between the two sets of DTMF tones is just that the
  130. first set can be abandoned part way through, if the user presses Esc.
  131. Pressing Esc during any of the other phases of the program has no
  132. effect.
  133.  
  134. The sole use of the variables mstat%, kstat%, and key%() in the
  135. program is to allow this cancelling to take place.
  136.  
  137. (Opl programmers unfamiliar with asynchronous i/o may wish to stop
  138. reading here.)
  139.  
  140. The best general mechanism for this is demonstrated in the program:
  141. instead of using the (synchronous) IOWRITE, change to the
  142. asynchronous IOA(...,2,...), which supports a later cancel using
  143. IOW(...,3).
  144.  
  145. The loop of the form
  146.     WHILE 1
  147.         IOWAIT
  148.         ....
  149.     ENDWH
  150. is the standard way of being able to respond to events which can
  151. occur in an order the program cannot predict (in this case, whether
  152. the user presses a key first, or the DTMF tones finish playing). 
  153. After the IOWAIT returns, you test the various stat% variables to see
  154. which of the events has indeed completed.
  155.  
  156. What various procedure names mean:
  157. ----------------------------------
  158. queplay: is the asynchronous form of play:
  159. quekey: queues an asynchronous keyboard read
  160. cankey: cancels any outstanding asynchronous keyboard read
  161. canplay: cancels any ongoing (asynchronously-launched) tone emission
  162. flushkey: flushes the keyboard buffer.
  163.  
  164. These notes prepared:
  165. ---------------------
  166. By DavidW, 13/05/92.
  167.  
  168.