home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilst / tapedeck / !TapeDeck / Resources / PM_Help < prev    next >
Text File  |  1991-05-23  |  23KB  |  635 lines
  1. !S/Tracker (Soundtracker/Tracker module music player)
  2. -----------------------------------------------------
  3.  
  4. Version 4.00 (23 May 1991)
  5.  
  6. Originally written by Hugo Fiennes and Fabrice Mercier [(c) The Serial Port]
  7. SWI interface and other bits added by Matt Farrow
  8.  
  9.  
  10. You are allowed to use this module with any demos or p.d. stuff you write,
  11. but permission is required before you can use it in any commercial software.
  12.  
  13. The !S/Tracker application may be freely copied if nothing more than the
  14. cost of a disc and a small amount for the trouble is charged, but it must be
  15. distributed with all the files complete and unchanged.
  16.  
  17.  
  18. DOCUMENTATION OF * COMMANDS AND SWI's
  19. -------------------------------------
  20.  
  21. *PlayMod     - Loads into memory and starts to play the specified Tracker or
  22.                Soundtracker module, determining automatically which format it
  23.                is.
  24.  
  25.                Syntax: *PlayMod <filename>
  26.          
  27.  
  28.  
  29.  
  30. *PlayPause   - Will pause the currently playing tune (kills all sound immed-
  31.                iately) but retains the soundtracker/tracker module in memory.
  32.                The tune can be restarted with a *PlayStart command.
  33.  
  34.                Syntax: *PlayPause
  35.  
  36.  
  37.  
  38.  
  39. *PlayStart   - Will resume playing a tune after a *PlayPause command.
  40.  
  41.                Syntax: *PlayStart
  42.  
  43.  
  44.  
  45.  
  46. *PlayPos     - Will set the current position in the sequence table, or if no
  47.                parameter is given, will simply return the current position.
  48.  
  49.                Syntax: *PlayPos [<0-127>]
  50.  
  51.                 
  52.  
  53.  
  54. *PlaySamples - Will list all the samples associated with the currently
  55.                installed music module. 
  56.  
  57.                Syntax: *PlaySamples
  58.  
  59.  
  60.  
  61.  
  62. *PlayStatus  - Will print information about the current tune module loaded
  63.                
  64.                Syntax: *PlayStatus
  65.  
  66.  
  67.  
  68.  
  69. *PlayStereo  - Controls the stereo settings while the older format sound-
  70.                tracker modules are playing (the stereo is fixed on an Amiga),
  71.                and will switch between five possible settings to cater for
  72.                most configurations:
  73.                    0 - Slightly off-centre left and right (normal)
  74.                    1 - Fully left and right (amiga-style)
  75.                    2 - Fully left
  76.                    3 - Fully right
  77.                    4 - Don't alter stereo settings
  78.                           (normally alters settings when a tune is loaded                               and when it plays a tracker stereo command - see
  79.                            SWI Tracker_Stereo)
  80.  
  81.                Syntax: *PlayStereo <0|1|2|3>
  82.  
  83.  
  84.  
  85.  
  86. *PlayStop    - Will stop and kill the currently playing tune module,
  87.                removing it from memory.
  88.  
  89.                Syntax: *PlayStop
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98. SWI COMMANDS
  99. ------------
  100. Several SWI commands have been added to the module in order to simplify the
  101. task of adding soundtracker/tracker music to your demos etc. (especially
  102. multi-tasking situations). These provide all of the facilities offered by
  103. the various * commands, but also allow a more detailed control of some of the
  104. module's features.
  105. All the SWI's remain in SVC mode, and do not alter the interrupt status.
  106. I think most are re-entrant, except those which use system SWI's (load, play,
  107. stop etc.), so avoid calling them from interrupts if you can avoid it.
  108.  
  109. The SWI chunk number given here (&43200) is an officially recognised chunk
  110. number issued by Acorn.
  111.  
  112.  
  113. -----------------------------------------------------------------------------
  114. Tracker_Version        (SWI &43200)
  115. -----------------------------------------------------------------------------
  116.  
  117. On Entry:  -
  118.  
  119. On Exit :  R0 = version number*100  (ie. for V1.23 = 123)
  120.  
  121. Use this call to ensure that the trackermodule installed is a recent enough
  122. version to support the SWI's you wish to use. Versions 4.00 onwards incorpor-
  123. ate the SWI's.
  124.  
  125.  
  126.  
  127.  
  128. -----------------------------------------------------------------------------
  129. Tracker_Load           (SWI &43201)
  130. -----------------------------------------------------------------------------
  131.  
  132. On Entry:  R0 = pointer to filename of soundtracker/tracker module
  133.  
  134. On Exit :  R0 preserved
  135.  
  136. This call will claim memory from the RMA and load the specified tune module,
  137. initialise the sound system, and set the playroutine in pause mode.
  138. You must then use the SWI Tracker_Play to start the tune playing.
  139. The command *PlayMod calls this routine, and then the SWI Tracker_Play.
  140.  
  141. An error will be generated if the module cannot be loaded or not enough
  142. memory can be claimed.
  143.  
  144.  
  145.  
  146.  
  147. -----------------------------------------------------------------------------
  148. Tracker_MemoryLoad     (SWI &43202)
  149. -----------------------------------------------------------------------------
  150.  
  151. On Entry:  R0 = pointer to first word of soundtracker/tracker module in
  152.                 memory (NB must be word-aligned)
  153.            R1 = length of module in bytes
  154.  
  155. On Exit :  R0 and R1 preserved
  156.  
  157. This call can be used by a non-multitasking application to specify an area
  158. of memory as a tune module, and thereby remove the need for a seperate file
  159. to hold a tune, and there is no need to claim a large amount of RMA space.
  160. Once this SWI is called, the module will be treated as if it was loaded in
  161. the module's own workspace.
  162.  Important: You must tell the trackermodule to forget the module if the
  163. memory will be overwritten, otherwise the module may crash.
  164. (*PlayStop or Tracker_Stop SWI)
  165.  
  166. NB This call will not work for programs running under the desktop if the
  167.    module is loaded in user memory.
  168.  
  169.    When a soundtracker module is loaded, it is partially converted to an
  170.    intermediate format between soundtracker and tracker to simplify the task
  171.    for the playroutine. Once the module is loaded (by any method) it is
  172.    permanently corrupted, and should not be re-saved. Tracker modules will be
  173.    unchanged, however, and soundtracker modules should be converted fully
  174.    into this format before being loaded to avoid this problem.
  175.  
  176.                                                               
  177.  
  178.  
  179. -----------------------------------------------------------------------------
  180. Tracker_Play           (SWI &43203)
  181. -----------------------------------------------------------------------------
  182.  
  183. On Entry:  -
  184.  
  185. On Exit :  -
  186.  
  187. This call will restart a tune after it has been paused or loaded with the
  188. Tracker_Load SWI.
  189.  
  190.  
  191.  
  192.  
  193.  
  194. -----------------------------------------------------------------------------
  195. Tracker_Stop           (SWI &43204)
  196. -----------------------------------------------------------------------------
  197.  
  198. On Entry:  -
  199.  
  200. On Exit :  -
  201.  
  202. This performs the same actions as *PlayStop
  203. Using *PlayStop or this SWI is the only way to get the trackermodule to
  204. release the memory taken up by the tune module, or to force it to forget the
  205. address of a module if it has been loaded with the 'Tracker_MemoryLoad' SWI.
  206.  
  207.  
  208.  
  209.  
  210. -----------------------------------------------------------------------------
  211. Tracker_Pause          (SWI &43205)
  212. -----------------------------------------------------------------------------
  213.  
  214. On Entry:  -
  215.  
  216. On Exit :  -
  217.  
  218. This performs the same actions as *PlayPause
  219.  
  220.  
  221.  
  222.  
  223.  
  224. -----------------------------------------------------------------------------
  225. Tracker_Stereo         (SWI &43206)
  226. -----------------------------------------------------------------------------
  227.  
  228. On Entry:  R0 = Stereo setting (0-4)
  229.  
  230. On Exit :  R0 preserved
  231.  
  232. This performs the same actions as *PlayStereo, with R0 passed as a parameter.
  233. If R0 is set to 4 on entry, then the stereo settings will be unaltered
  234. whenever a module is loaded or killed, and disables any stereo commands in
  235. tracker modules. This is to allow interfacing programs to provide their own
  236. stereo options, or to allow adjustment to the stereo positions while tracker
  237. tunes are playing (which have default stereo settings stored as part of the
  238. tune).
  239.  
  240.  
  241.  
  242.  
  243. -----------------------------------------------------------------------------
  244. Tracker_SetPos         (SWI &43207)
  245. -----------------------------------------------------------------------------
  246.  
  247. On Entry:  R0 = New sequence position (0-127 max)
  248.            R1 = Event (0-63 max)
  249.  
  250. On Exit :  R0 preserved
  251.  
  252. This performs the same actions as *PlayPos, except that the event with the
  253. pattern can be specified