home *** CD-ROM | disk | FTP | other *** search
/ No Fragments Archive 10: Diskmags / nf_archive_10.iso / MAGS / LEDGERS / LEDG_13.MSA / DISK_2 / ULTRA2 / ULTRA.TXT next >
Text File  |  1985-11-20  |  13KB  |  270 lines
  1. Documentation to BDOZ Software Development's Ultraplayer II
  2. ===========================================================
  3.  
  4. Release date of version 2.00: 26/01/1992.
  5.  
  6. Introduction
  7. ============
  8.  
  9. The whole idea of creating a 'player' that is able to recognize as 
  10. many musical formats as possible, was thought of by a guy called 
  11. Arnoud (personally, I believe it was I who came up with the idea, but 
  12. alas ...). He had made one, in GfA (Musica 1.0). It was, to be fair, 
  13. crap. Pure bull.
  14. I had made one too, in assembler, independent from Arnoud, at the 
  15. same time. This was a sad program, like Musica was. Then, one day, 
  16. much later, someone called 'Vincent Partington' shows me a player he 
  17. had designed (he had no knowledge of the fact that I had created one 
  18. too!). It worked as an ACC, played correctly on all resolutions and 
  19. worked, in general, fine (no music recognition though; you had to 
  20. choose what music type was to be played ...). It was called 
  21. GigaMus(ic).
  22. So I started to program one too (yes, I do copy much ;)): the 
  23. Ultraplayer. It had about the same features as GigaMusic, but was 
  24. much easier to use (and was much more unstable, too ...). Despite of 
  25. it's potential, however, I did not continue developing the 
  26. Ultraplayer, hence Vincent did continue the work on GigaMusic. Just 
  27. two weeks ago, I thought: "Well! Let's make a new player!" ... So I 
  28. sat down, took a deep breath, and looked at the source of the 
  29. Ultraplayer ... And what I mess it was! I threw it away, and started 
  30. anew. Now, behold, for your very eyes: "The Brand New, Improved 
  31. Ultraplayer II!"! I think I did quite a good job: programming a 
  32. player from scratch in less then a weeks time, using Assembler, but 
  33. let us not fall into temptation about talking how marvellous we are 
  34. (hehe) ...
  35.  
  36. Usage
  37. =====
  38.  
  39. Using the Ultraplayer II should be simple. It is advised that you've 
  40. got a large library of Mad Max/Count Zero/Big Alec musics, for one 
  41. music will annoy you pretty fast ...
  42.  
  43. Copy ULTRAII.ACC and ULTRAII.RSC onto your bootdrive (usually A: or 
  44. C:), and reboot your computer, or rename ULTRAII.ACC to ULTRAII.PRG 
  45. and run it (the Ultraplayer may be loaded using the Chameleon, but 
  46. this is NOT advised!). After rebooting, you will find the name 
  47. "Ultraplayer II" in your menubar. After clicking on it, you will have 
  48. entered the Ultraplayer II (eerie, no?).
  49.  
  50. The dialog you are now presented with, offers you the following 
  51. information:
  52.  
  53. Music On/Off    : Determines whether the music is ON or OFF ...
  54. Fast Forward    : Clicking (and HOLDING!) this button will allow you 
  55.                   to quickly scan through musix.
  56. No Buffer Active: The Ultraplayer II has a built in buffer of 25 Kb. 
  57.                   If, however, a musicfile is larger, the Ultraplayer 
  58.                   will activate a buffer to load the music file into. 
  59.                   The disadvantage is, that buffered musix can't be 
  60.                   played in the background (allocated memory has to 
  61.                   be returned to GEMDOS ...) ...
  62. Mus. Type Loaded: Tells you what music type has been loaded.
  63. File Loaded     : Filename of the loaded file, without extension.
  64. Playing Mus. No.: As music files often contain >1 compositions, you 
  65.                   can use the arrows to advance or decrease the music 
  66.                   number.
  67. Current Status  : Tells you what's happening.
  68. Information     : Gives you some information about the Ultraplayer 
  69.                   II, for you have surely forgot to read the 
  70.                   documents ...
  71. Continue        : Continues, exits.
  72. Load Music      : Let's you load a music file.
  73.  
  74. Let's play some music. Click on 'Load Music'. In the fileselector 
  75. that now appears, you can select a music file (for example 
  76. 'AWESOME.MUS', supplied in the archive). The Ultraplayer II will 
  77. return to the main menu, soothing (?) your ears with some music. To 
  78. see if there's more music in the file, fiddle around with the 'Music 
  79. No.' indicator for a while (but be careful: although the Ultraplayer 
  80. II catches off most errors, it might still bomb out!).
  81.  
  82. The Ultraplayer II features flying dialogs, too: click & hold a grey 
  83. part in any of the dialogs, and you can place it anywhere you like. 
  84. If there isn't enough memory to buffer the complete screen (32Kb on 
  85. an ST, 150 Kb on a TT ...), flying the dialog will cause it not to be 
  86. removed; click on 'Continue' however, and your screen will be back to 
  87. normal again (sometimes, that is!) The dialog position is remembered.
  88.  
  89. From version 2.10 and onwards, it is possible to let the Ultraplayer 
  90. II 'autoload' a music file; it will be played whenever you run the 
  91. Ultraplayer! Setting up an auto-file can be done in two ways: either 
  92. you fetch a diskmonitor, and search around the Ultraplayer for the 
  93. bytes '&^&' and '^&^' (they lie somewhere at the end of the program). 
  94. These two signs respectively mark the start of the filename to load & 
  95. the start of the pathname (pathname+filename, I mean ...). Just type 
  96. the file over there, and be sure to terminate the two strings using a 
  97. NULL byte.
  98. Or you can use the program that's included in the LZH, which is much 
  99. easier, infact :) ... You'll have to specify the filename of the 
  100. Ultraplayer II, and after having scanned the file for the two marks 
  101. (see above), you can select a file, clear the autofile, or quit the 
  102. program.
  103. NOTE: You cannot set musix larger then 25 K, or musix that cannot be 
  104. played in the background to autoload.
  105.  
  106. Program specifications & queer things for version 2.10
  107. ======================================================
  108.  
  109. - Recognizes & plays the following music types (types with an 
  110.   asterisk in front can't be played in the background):
  111.  
  112.   "Mad Max" PC Relativ (his newer ones, NOT Thrust or Warhawk or 
  113.   (Arjen!)) ....
  114.   "Big Alec" without digidrums.
  115.   "Count Zero" with header.
  116.   "Count Zero" without header (TriSound MODules (converted with the 
  117.   program "TRIMOD" are recognized and played as Count Zero without 
  118.   header! And it works! I'll get myself a copy of this TRIMOD as soon 
  119.   as possible!)).
  120.   *"Mad Max Digidrum" only the types that are ripped correctly (ONE 
  121.   file!)
  122.   *"Synth Dream" digidrum, only the 10Khz ones (samples+song in one 
  123.   file).
  124.  
  125. - Keyclick remains on (if it WAS on!), while playing. This is crazy, 
  126.   but I fancied it to be the best solution after all.
  127. - Should work on all ST-compatible models (ST/Mega ST/STE/Mega 
  128.   STE/Stacy/TT/ST-Book/Falcon), but I ain't sure (I've only got an 
  129.   ST!).
  130. - As the Mad Max format is VERY 'global' (ie. Synth Dream music looks 
  131.   a LOT like it!), it might be that the player mistakes something for 
  132.   a Mad Max thingie. LOAD A NEW FILE as soon as possible (if 
  133.   possible, that is!!!) when this happens!!! It might crash your ST!
  134. - During file transfers, it might be that the Ultraplayer shuts 
  135.   down for a while (leaving you with an annoying 'BEEEEEEP!'). This 
  136.   is normal, and is caused by the OS, which temporarily shuts Timer C 
  137.   down when doing certain (?) things with the RS232 (Modem).
  138. - A feature called 'autoloading' has been added in version 2.10. It 
  139.   will cause the Ultraplayer II to load a music file when it is 
  140.   started. See 'Usage'.
  141.  
  142. Known bugs
  143. ==========
  144.  
  145. - 'Drag' your mousepointer over the 'music on/off' button; and the 
  146.   music will do exactly the opposite of what the box says it does! 
  147.   Doubleclicking also does the job.
  148.  
  149. Technical Titbits
  150. =================
  151.  
  152. The Ultraplayer II is a rather low-level program, despite of it's 
  153. nice and harmless look. I do not know how well (if ...) it will work 
  154. on TT's and Mega STE's, but it should work fine.
  155. The Ultraplayer II installs a cookie of 'XMuz', with a pointer to 
  156. it's cookieblock, offering you some useable information (see below). 
  157. It also installs an XBRA ID of 'XMuz'.
  158. To achieve 50hz playing on all syncmodes, the Ultraplayer II uses 
  159. Timer C for replaying the music (200hz/4=50hz ...). The routine was 
  160. written as fast as I possibly could, and uses about 1 to 2 percents 
  161. of the CPU time, including the music replay routine (NOTE: some music 
  162. programmers use very slow replay routines, sometimes needing upto 7 
  163. percent of time!). To get a clear look at the time usage, try Quick 
  164. Index (run before and after!).
  165. The phase where most musix bomb, is the initialising phase; so the 
  166. Ultraplayer II installs it's own bomb routines for the time the music 
  167. is inited. Afterwards, the old bomb routines are given back 
  168. (ofcourse).
  169. The screen buffering is resolution independent, although I do not use 
  170. any VDI copy functions (buffering the whole screen is much easier, 
  171. and as the Ultraplayer II was written in ASM, it might be faster too 
  172. :) ...).
  173.  
  174.    The Cookieblock:
  175.  
  176.    Name:       Size:    Description:
  177.    Ultra_Id    LONG     Pointer to the Application ID returned by 
  178.                         AES. Can be used to call upon the Ultraplayer 
  179.                         II by using APPL_WRITE.
  180.    Ultra_Vers  LONG     Pointer to the string which tells you the 
  181.                         version number.
  182.    Ultra_Num   WORD     How many music types can be played and 
  183.                         recognized (rather: the space there is for 
  184.                         music init routines etc.).
  185.    Ultra_Desc  LONG     Pointer to the music descriptor strings. Each 
  186.                         of the strings is 21 bytes in size, 
  187.                         terminated by a NULL byte.
  188.    Ultra_Init  LONG     Pointer to the Initialization table of the 
  189.                         Ultraplayer II. This is built up of several 
  190.                         pairs of LONGs, in which the first LONG 
  191.                         points to the routine to jump to, and the 
  192.                         second is the offset to jump with. If the 
  193.                         first LONG (routine) is 0, the Ultraplayer II 
  194.                         jumps to the buffer (taking the offset into 
  195.                         account, ofcourse). An example:
  196.  
  197.                         init_routs: DC.L rts,0 ; Jumps to routine 
  198.                                                  RTS, with an offset 
  199.                                                  of 0 bytes.
  200.                                     DC.L 0,8   ; Jumps to the buffer, 
  201.                                                  with an offset of 8 
  202.                                                  bytes.
  203.  
  204.    Ultra_Play  LONG     See above, but for the play routines.
  205.  
  206.    Ultra_Type  LONG     Pointer to the WORD that specifies which 
  207.                         music type we loaded (this is used to jump to 
  208.                         the correct Init & Play routines, and also 
  209.                         for the descriptions; eg. Ultra_Type is 4, 
  210.                         then the 4th 'line' in Ultra_Init and 
  211.                         Ultra_Play are used (Ultra_Type * 8 bytes is 
  212.                         added to Ultra_Init and Ultra_Play)).
  213.    Ultra_Mtype LONG     Pointer to the routine that checks the music 
  214.                         types.
  215.  
  216.    Ultra_Buf   LONG     Pointer to the pointer (...) of the buffer 
  217.                         (as the Ultraplayer II will Malloc() buffers 
  218.                         too, when the internal 25 K buffer is too 
  219.                         small).
  220.  
  221.    If you want to write your own play routines etc., you must proceed 
  222.    as follows:
  223.  
  224.    1) Replace the Ultra_Mtype routine with one of yourself (Move.L 
  225.    #newtype,Ultra_Mtype).
  226.    2) Fill in the Ultra_Type flag.
  227.    3) Check how many music types can be recognized (= how large is 
  228.    space for the initrouts etc ...), and fill in the Ultra_Play and 
  229.    Ultra_Init tables (MAY NOT CONTAIN MORE MUSIX THEN SPECIFIED IN 
  230.    ULTRA_NUM, OR YOU'LL OVERWRITE VARIOUS OTHER FLAGS (among which 
  231.    the cookieblock)!)
  232.    4) Change the Ultra_Desc descriptor strings.
  233.    5) Pray.
  234.  
  235.    I haven't tested this myself, so I don't know how this 'll work! 
  236.    But, all of the code is there, so ...
  237.  
  238. Disclaimer
  239. ==========
  240.  
  241. ********************************************************************
  242. ********************************************************************
  243. ***  TAKE GREAT CARE IN USING THE ULTRAPLAYER II! WHEN IN DOUBT  ***
  244. ***  OVER A MUSIC FILE, SAVE!!! NEVER TRY A NEW MUSIC FILE YOU   ***
  245. ***  JUST GOT WITHOUT SAVING! ALTHOUGH I DID THE BEST I COULD    *** 
  246. ***  TO CATCH ERRORS AND REMOVE BUGS, IT IS IMPOSSIBLE TO SAY    ***  
  247. ***  WHETHER A MUSIC FILE IS ERRORFREE AND CLEAN!                ***
  248. ***  I CANNOT BE HELD RESPONSIBLE FOR ANY DAMAGE DONE BY THE     ***
  249. ***  ULTRAPLAYER II TO EITHER YOUR HARD- OR SOFTWARE!!!          ***
  250. ********************************************************************
  251. ********************************************************************
  252.  
  253. Things yet to do
  254. ================
  255.  
  256. - Buffer size determinable by the user.
  257. - Sort of 'modular' concept.
  258.  
  259. But, nobody uses this program anyway, except me, so ... <schnuff> ...
  260.  
  261. Update history
  262. ==============
  263.  
  264. Ultraplayer II/2.10: Removed a little (stupid) bug, and added the 
  265. nice 'autoload' feature. Also made a program which enables you to 
  266. edit the autoload swiftly.
  267.  
  268. Ultraplayer II/2.00: The first version ever, hope you like it (well, 
  269. what should I say!!!)!!!
  270.