home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / f / frodo / !FrodoRsrc / DocDRender < prev    next >
Encoding:
Text File  |  1997-05-17  |  4.4 KB  |  290 lines
  1. THE DIGITAL RENDERER MODULE, V0.00
  2. ==================================
  3.  
  4.  
  5.  
  6. This module provides a polling-interface between applications and the sound
  7. system. It should be used if you wish to playback a sample of unknown length
  8. like when emulating another computer's sound system and/or control playback
  9. from applications which might be mapped out during WIMP polls. Otherwise you
  10. better use voice generators.
  11.  
  12. You tell it the number of channels, sample period and buffer size (as needed for
  13. SWI Sound_Configure) when activating it. The module will then claim a buffer of
  14. the specified size and take over the sound system. Your job as a client is
  15. polling with DigitalRenderer_ReadState and to provide new samples when needed
  16. using DigitalRenderer_NewSample.
  17.  
  18. DigitalRenderer only supports 8 bit logarithmic sound ATM since I have absolutely
  19. no documentation about 16 bit linear sound (and the PRMs are pretty useless as
  20. far as DMA- and Channel-Handlers are concerned). If any of you provided me with
  21. the necessary docs I might update it.
  22.  
  23.  
  24.  
  25.  
  26. The DigitalRenderer uses SWI chunk &4f700 (officially registered). It provides
  27. the following SWI calls:
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35. DigitalRenderer_Activate        SWI &4F700
  36. ========================
  37.  
  38.  
  39. On Entry:
  40. ---------
  41.  
  42. R0    number of channels, will get rounded up to (1,2,4,8).
  43. R1    Sample length (bytes per channel, must be a multiple of 16 bytes)
  44. R2    Sample period (microseconds between reading two consecutive sample bytes)
  45.  
  46.  
  47. On Exit:
  48. --------
  49.  
  50. ---
  51.  
  52.  
  53. Usage:
  54. ------
  55.  
  56. Your application must call this SWI to take over the sound system. For typical
  57. values of sample length and sample period see PRM 4. Once (successfully)
  58. activated things like the system beep won't work any more.
  59.  
  60.  
  61. Errors:
  62. -------
  63.  
  64.     - already active
  65.     - can't claim memory for buffer / handler
  66.     - bad buffer size (not a multiple of 16)
  67.  
  68.  
  69.  
  70.  
  71.  
  72. DigitalRenderer_Deactivate        SWI &4F701
  73. ==========================
  74.  
  75.  
  76. On Entry:
  77. ---------
  78.  
  79. ---
  80.  
  81.  
  82. On Exit:
  83. --------
  84.  
  85. ---
  86.  
  87.  
  88. Usage:
  89. ------
  90.  
  91. If your application doesn't need sound any more it must return control to the
  92. old handlers by issuing this SWI.
  93.  
  94.  
  95. Errors:
  96. -------
  97.  
  98.     - not active
  99.  
  100.  
  101.  
  102.  
  103.  
  104. DigitalRenderer_Pause            SWI &4F702
  105. =====================
  106.  
  107.  
  108. On Entry:
  109. ---------
  110.  
  111. ---
  112.  
  113.  
  114. On Exit:
  115. --------
  116.  
  117. ---
  118.  
  119.  
  120. Usage:
  121. ------
  122.  
  123. This SWI suspends sound playback (disabling DMA on sample buffers and so on).
  124. In contrast to deactivating DR this will not install the old handlers but merely
  125. mute the entire sound system.
  126.  
  127.  
  128. Errors:
  129. -------
  130.  
  131.     - not active
  132.  
  133.  
  134.  
  135.  
  136.  
  137. DigitalRenderer_Resume            SWI &4F703
  138. ======================
  139.  
  140.  
  141. On Entry:
  142. ---------
  143.  
  144. ---
  145.  
  146.  
  147. On Exit:
  148. --------
  149.  
  150. ---
  151.  
  152.  
  153. Usage:
  154. ------
  155.  
  156. Call this to resume playback after it was paused.
  157.  
  158.  
  159. Errors:
  160. -------
  161.  
  162.     - not active
  163.  
  164.  
  165.  
  166.  
  167.  
  168. DigitalRenderer_GetTables        SWI &4F704
  169. =========================
  170.  
  171.  
  172. On Entry:
  173. ---------
  174.  
  175. ---
  176.  
  177.  
  178. On Exit:
  179. --------
  180.  
  181. R0    pointer to 8k LinToLog table for translating 13 bit signed integers
  182.     to 8 bit logarithmic samples as required by the VIDC, scaled to the
  183.     currently selected volume (--> SWI Sound_Volume)
  184.  
  185. R1    Pointer to 256 byte LogScale table for scaling 8 bit logarithmic
  186.     samples according to the currently selected volume.
  187.  
  188.  
  189. Errors:
  190. -------
  191.  
  192.     - not active
  193.  
  194.  
  195.  
  196.  
  197.  
  198. DigitalRenderer_ReadState        SWI &4F705
  199. =========================
  200.  
  201.  
  202. On Entry:
  203. ---------
  204.  
  205. ---
  206.  
  207.  
  208. On Exit:
  209. --------
  210.  
  211. R0    Digital Renderer State. Bits and their meaning when set:
  212.  
  213.     0:    DigitalRenderer active
  214.     1:    New sample data required
  215.     2:    Buffer overflow occurred
  216.  
  217.  
  218. Usage:
  219. ------
  220.  
  221. Call this SWI to poll DigitalRenderer. If Bit 1 is set you have to provide a
  222. new sample buffer by calling DigitalRenderer_NewSample. Bit 2 lets you check
  223. for buffer overflows (i.e. your application took too long to provide the next
  224. sample).
  225.  
  226.  
  227.  
  228.  
  229.  
  230. DigitalRenderer_NewSample        SWI &4F706
  231. =========================
  232.  
  233.  
  234. On Entry:
  235. ---------
  236.  
  237. R0    Pointer to buffer holding new sample.
  238.  
  239.  
  240. On Exit:
  241. --------
  242.  
  243. ---
  244.  
  245.  
  246. Usage:
  247. ------
  248.  
  249. Call this when DigitalRenderer_ReadState returned with Bit 1 set. The buffer must
  250. have the correct size (number of channels * Sample length) and contain data that
  251. can be sent directly to the VIDC, i.e. 8 bit logarithmic data, interleafed for
  252. multiple channels.
  253.  
  254.  
  255. Errors:
  256. -------
  257.  
  258.     - not active
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267. LEGAL STUFF:
  268. ============
  269.  
  270.  
  271. The DigitalRenderer module is Freeware. You may use it for your own programs as
  272. long as this file is included unchanged. I won't be held responsible for any kind
  273. of damage resulting from the use of this module, use it entirely at your own risk.
  274.  
  275.  
  276.  
  277.  
  278.  
  279. CONTACT:
  280. ========
  281.  
  282.  
  283. Andreas Dehmel
  284. Am Schorn 18
  285. 82327 Tutzing
  286. Germany
  287.  
  288. email:    dehmel@informatik.tu-muenchen.de
  289.     (will become invalid soon)
  290.