home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / AMP / !Amp / Docs / XprMod < prev   
Text File  |  1998-08-25  |  10KB  |  350 lines
  1.  
  2. Documentation for XprMod v1.10 
  3. (Tab width 8)
  4.  
  5.  
  6. XprMod by Skoe of Expression
  7. Thanks to MikMak for many sources!
  8.  
  9.  
  10. ================================================================
  11. Introduction
  12. ================================================================
  13.  
  14. XprMod is a multitrack, multiformat (multimedia, hehe) sound
  15. module player. It can play up to 32 channels with real panning
  16. (stereo) effects and on fast processors with interpolation.
  17.  
  18. This version can load various PC, Amiga and Atari MOD files,
  19. XM, S3M and MTM. Other formats will be added in future versions.
  20.  
  21. Several SWIs can be used to control the player, see below. You
  22. can (and shall) use the auto-setup option to get the best
  23. quality on fast processors (ARM7, SA110) and the highest speed
  24. on slow ones (ARM 3).
  25.  
  26. XprMod runs also on cacheless processors, but they are history
  27. and so nothing is optimised for these ones. I could make the 
  28. player about 30% faster on ARM2, but it's a senseless waste of
  29. time.
  30.  
  31. Don't use it for tracks with 8 voices or less - convert them!
  32. Players like DigitalSymphony or MatrixTrack8 (using the 8 
  33. physical channels of the Acorn sound system) are much faster
  34. with these tracks than XprMod, because it uses always software
  35. mixing. Perhaps I will implement 2 different routines later...
  36.  
  37.  
  38. ================================================================
  39. Copyright
  40. ================================================================
  41.  
  42. XprMod is based on MikMaks MikMod. It is no simple port but
  43. was totally revised and partly re-written. Future releases will
  44. have only less in common with MikMod, because even the internal
  45. structure of this player and most routines will be changed.
  46.  
  47. You may (and must :) use XprMod (unchanged) in your products. 
  48. Please credit me with something like "Music player by Skoe of 
  49. Expression". If you use it in a commercial product of any kind
  50. (CD-ROM's, Games etc.) and you'll sell more than 20 copies of
  51. it, you must (!) give me 20 pounds or a free copy of this
  52. product. If you don't do that, it is a violation of the copy-
  53. right laws!
  54.  
  55. If you include the player module as a single file into your
  56. application, please copy this file into it, too. You needn't do
  57. this if you have real problems with space (e.g. a 1599 kB demo).
  58.  
  59. The author of this player will not be responsible for any
  60. loss or damage caused by this software.
  61.  
  62.  
  63. My addy:
  64.  
  65. Thomas Giesel
  66. Hauptstr. 61
  67. D-03246 Crinitz
  68. Germany
  69.  
  70.  
  71. ================================================================
  72. Speed
  73. ================================================================
  74.  
  75. It is possible to play
  76.  
  77. - up to about 10 channels on ARM2 with 14kHz (in a bad quality)
  78.   (but who cares about 8Mhz machines?!)
  79.   -> use DSym or similar programs !!!
  80. - up to about 24 channels on ARM3
  81. - up to 32 channels with 41kHz mixing and interpolation
  82.   on SA110 (needs 20% processor (or better: RAM) speed or less)
  83.  
  84. Following tests were made by Mr. Hill of Icebird (thanx!) with an
  85. older XprMod v0.30:
  86.  
  87. SA110, 60ns RAM (RPC 600 board): 41kHz, real stereo, interpolated
  88.  
  89.               XprMod  QuantumPlayer(24µs)  MatrixPlayer(24µs)
  90.     4 channel  6.38%        5.42%             -not tested-
  91.     8 channel  8.47%      -gave up-           -not tested-
  92.    11 channel 12.24%      -gave up-              23.54%
  93.    16 channel 16.41%      -gave up-              24.91%
  94.    20 channel 14.30%      -gave up-           -not tested-
  95.    30 channel 21.71%      -gave up-           -not tested-
  96.  
  97.  
  98. The player needs about half of the speed without interpolation 
  99. and real stereo mixing (depending on hardware configuration).
  100.  
  101.  
  102. ================================================================
  103. Mixing Quality
  104. ================================================================
  105.  
  106. If you use the auto-setup option, you can be sure that the
  107. player will find a good compromise between quality and speed on
  108. nearly every machine.
  109.  
  110. You may choose following modes:
  111.  
  112. high quality:
  113.  use a high sampling frequency, real stereo (all panning
  114.  effects) and interpolate if possible
  115.  
  116. normal quality:
  117.  use a medium frequency and real stereo
  118.  
  119. fast mode:
  120.  use a low quality (max. 22kHz) and fast stereo mode (mix to two
  121.  fix stereo positions, panning disabled)
  122.  
  123. If the computer system to slow or to fast :) you could get also
  124. 15kHz with fast stereo mode when chosen "high quality" or
  125. real stereo in "fast mode".
  126.  
  127. I offer you to use "high quality" in desktop players and music-
  128. compilations, "normal quality" in demos and "fast mode" only if
  129. you or your computer is ill. Or simple include a button...
  130.  
  131.  
  132.  
  133.  
  134. ================================================================
  135. Fast Guide
  136. ================================================================
  137.  
  138. SYS"ExpressionMod_Load", "ADFS::4.$.XMFile", 0, -2
  139. REM 0 -> file, -2 -> normal quality
  140. SYS"ExpressionMod_Play", 1
  141. REM 1 -> restart after end
  142.  
  143. Enough for a first test?!
  144.  
  145. - Don't forget to stop your track before exit your program
  146. - Don't start other players while XprMod is playing! To get
  147.   a higher speed XprMod and most other players are not 100%
  148.   Acorn conform and could crash or play strange sounds.
  149.  
  150.  
  151. ================================================================
  152. Software Interrupts
  153. ================================================================
  154.  
  155. temporary SWI chunk base number 0x8A800, NOT allocated by Acorn
  156.               - Use it on your own risk !!! -
  157.  
  158. Note:    "Returns error block" means: if an error is occurred,
  159.     the SWI will return with V set and R0 pointing to a
  160.     standard Risc OS error block. If the SWI X-bit is not
  161.     set, the OS will report the error as usual.
  162.     If nothing unpleasant happened the registers return
  163.     like described.
  164.  
  165.  
  166. ================================================================
  167. SWI ExpressionMod_Load        base + 0x00
  168. ================================================================
  169.  
  170. Use this SWI to load a file from a FS or RAM and to choose the
  171. quality. If the file doesn't exist or cannot be loaded, an error
  172. will be returned. Loading could take some seconds, because the 
  173. track will be converted into an internal format. This is the
  174. only chance to change the setup, after loading you can't do it.
  175.  
  176. Entry:
  177.     R0    pointer to filename (or pointer to track in
  178.         memory if R1 > 0)
  179.  
  180.     R1    0 to load from file, else length of track
  181.         in memory
  182.  
  183.     R2    quality
  184.  
  185.         if minus: auto setup DEPENDING FROM SYSTEM SPEED
  186.         for detailed notes see chapter "Mixing Quality"
  187.  
  188.             -1: try to use high quality
  189.                 (interpolated, real stereo,
  190.                 high mixing frequency)
  191.  
  192.             -2: normal
  193.                 (real stereo, normal mixing
  194.                 frequency)
  195.  
  196.             -3: fast, (avoid this mode!)
  197.                 (left - right only, low freq)
  198.  
  199.         else: custom setup
  200.  
  201.             bit 0: interpolate samples
  202.             bit 1: use real stereo mixing
  203.  
  204.     R3    mixing frequency only if custom setup
  205.         14000 <= R2 <= 41000, other values will become
  206.         clipped
  207.     R4    0 !!! (for future extensions, not tested yet)
  208.  
  209. Exit:
  210.     returns error block or
  211.     all    preserved
  212.  
  213.  
  214. ================================================================
  215. SWI ExpressionMod_Play        base + 0x01
  216. ================================================================
  217.  
  218. After loading or pausing you can (re)start playing with this
  219. SWI. It is possible to repeat a song or to play it only once.
  220. After playing once, ExpressionMod_Stop will be called
  221. automatically. It is not impossible that an error occurres!
  222.  
  223. Entry:
  224.     R0    = 0 for playing only once
  225.             anything else for repeating song
  226.             (ignored at restart after pausing)
  227.     R1    = 0 (for future extensions)
  228.  
  229. Exit:
  230.     returns error block or
  231.     all    preserved
  232.  
  233.  
  234. ================================================================
  235. SWI ExpressionMod_Pause        base + 0x02
  236. ================================================================
  237.  
  238. Does not detach the channels, only stops playing until
  239. ExpressionMod_Play was called.
  240.  
  241. Entry:
  242.     -
  243.  
  244. Exit:
  245.     all    preserved
  246.  
  247.  
  248.  
  249. ================================================================
  250. SWI ExpressionMod_Stop        base + 0x03
  251. ================================================================
  252.  
  253. Stop playing and discard loaded song.
  254.  
  255. Entry:
  256.     -
  257.  
  258. Exit:
  259.     all    preserved
  260.  
  261.  
  262.  
  263. ================================================================
  264. SWI ExpressionMod_Position    base + 0x04
  265. ================================================================
  266.  
  267. You can set the song position (patter number) and/or read the
  268. position and row number. This can be done before starting,
  269. while playing or pause.
  270.  
  271. Entry:
  272.     R0    = 0 to read
  273.     or
  274.     R0    position to set
  275.     
  276. Exit:
  277.     R0    position (pattern number)
  278.     R1    row
  279.     rest    preserved
  280.  
  281.  
  282. ================================================================
  283. SWI ExpressionMod_Info        base + 0x05
  284. ================================================================
  285.  
  286. Read various infos.
  287.  
  288. Entry:
  289.     -
  290.  
  291. Exit:
  292.     R0    pointer to songname
  293.     R1    pointer to modtype
  294.         e.g. "FastTracker v2.00"
  295.     R2    number of logical channels
  296.     R3    number of patterns
  297.     R4    used mixing frequency in Hertz
  298.     R5    mixing mode:
  299.         bit 0 set if interpolated (else normal)
  300.         bit 1 set if real stereo (else fast left/right)
  301.  
  302. ================================================================
  303. SWI ExpressionMod_Volume    base + 0x06
  304. ================================================================
  305.  
  306. Set volume 0 (silent) to 128. Forbidden values will be treated
  307. as 128. No error returning necessary. This can be done always.
  308.  
  309. Normally the amplifier uses the right setting for a high volume
  310. without distortion. Nevertheless it may happen that the player
  311. overdrives and plays crackling sounds. In this case choose a 
  312. lower volume.
  313.  
  314. Entry:
  315.     R0    volume
  316.  
  317. Exit:
  318.     all    preserved
  319.  
  320.  
  321. ================================================================
  322. SWI ExpressionMod_Prev        base + 0x07
  323. ================================================================
  324.  
  325. Jump to previous pattern (if existing).
  326.  
  327. Entry:
  328.     -
  329.     
  330. Exit:
  331.     all    preserved
  332.  
  333.  
  334. ================================================================
  335. SWI ExpressionMod_Next        base + 0x08
  336. ================================================================
  337.  
  338. Jump to next pattern (if existing).
  339.  
  340.  
  341. Entry:
  342.     -
  343.  
  344. Exit:
  345.     all    preserved
  346.  
  347.  
  348.  
  349.  
  350. EOF