home *** CD-ROM | disk | FTP | other *** search
/ Large Pack of OldSkool DOS MOD Trackers / edlb105a.zip / USE / MPLAYER.DOC < prev    next >
Text File  |  1994-12-20  |  33KB  |  399 lines
  1. ┌──────────────────────────────────────────────────────────────────────────────┐
  2. │ How to use Player v04.00 ............................ by Jens-Christian Huus │
  3. ├──────────────────────────────────────────────────────────────────────────────┤
  4. │                                                                              │
  5. │                                                                              │
  6. │       INTRODUCTION                                                           │
  7. │       ────────────                                                           │
  8. │                                                                              │
  9. │       So you have finally managed to fumble you way  around the editor       │
  10. │       and now you want to use the music in your demo or other piece of       │
  11. │       programming not earning you any money (Because THAT's the deal)!       │
  12. │       All right, in this directory you will find the OBJ player needed       │
  13. │       to link onto your own program. This DOC  will tell you about the       │
  14. │       functions and variables in the player plus the file formats.           │
  15. │                                                                              │
  16. │       After having done your tune in the editor - saving the source to       │
  17. │       disk with Shift-F12 or Ctrl-F4 - you must convert it to a format       │
  18. │       with the ".D00" extension. Do this by  pressing Ctrl-F5 while in       │
  19. │       the editor. The music  will be packed to a fully playable format       │
  20. │       which takes up little memory (typically 2-5 Kb). Now you can use       │
  21. │       this file together with "MPLAYER.OBJ" in this directory.               │
  22. │                                                                              │
  23. │       NOTE: You cannot load ".D00" files into EdLib. Make sure you DID       │
  24. │       save that masterpiece with Shift-F12 or Ctrl-F4 before packing!        │
  25. │                                                                              │
  26. │                                                                              │
  27. │       THE TEST PROGRAM                                                       │
  28. │       ────────────────                                                       │
  29. │                                                                              │
  30. │       Before describing the functions in the player, have a look at my       │
  31. │       example file "TEST.ASM" to see how I use the "STR_WISE.D00" file       │
  32. │       by Drax. The source was assembled using Turbo Assembler v4.0 and       │
  33. │       linked using Turbo Link v6.00, both from Borland. You can use my       │
  34. │       makefile "-" to accomplish this, but check it out first - I have       │
  35. │       used the 4DOS command "keystack 13" to  skip the annoying "Press       │
  36. │       any key to continue" message before reentering my source editor.       │
  37. │       I have also  used a "mode co80,50" to switch into 50 lines mode,       │
  38. │       a mode I use a lot when programming.                                   │
  39. │                                                                              │
  40. │       The file "GLOBALS.INC" is included in the source. This file con-       │
  41. │       tains most of the variables in  the player, but in the TEST file       │
  42. │       I only use the "GLOBAL PLAYER:FAR" line to call the player. Some       │
  43. │       of the other  variables will be discussed  later, as they can be       │
  44. │       used to make scopes or the like in your own programs.                  │
  45. │                                                                              │
  46. │       The execution of the "TEST.ASM" file is simple - first it checks       │
  47. │       if an OPL2 chip is present using a function in the player. If it       │
  48. │       isn't, an error is printed and the program is aborted. Otherwise       │
  49. │       the ".D00" is loaded, the player initialized and started. I have       │
  50. │       used a standard timer interrupt routine to call the AdLib player       │
  51. │       as many times as it was used in the  editor (this information is       │
  52. │       saved into the ".D00" file). The source  code has been commented       │
  53. │       all the way, so I guess I don't have to say more than that.            │
  54. │                                                                              │
  55. │                                                                              │
  56. │       PLAYER FUNCTIONS                                                       │
  57. │       ────────────────                                                       │
  58. │                                                                              │
  59. │       Use the "CALL PLAYER" label prepared by "GLOBAL PLAYER:FAR" with       │
  60. │       registers prepared to access all player functions. The player is       │
  61. │       from my old school, so no registers are pushed I'm afraid. Do it       │
  62. │       yourself. Here is a list of the functions currently available in       │
  63. │       this version of the player.                                            │
  64. │                                                                              │
  65. │                                                                              │
  66. │       MAIN RESET      AH      00h                                            │
  67. │                       BX:CX   Segment:offset of ".D00" data #1               │
  68. │                       ES:DI   Segment:offset of ".D00" data #2               │
  69. │                                                                              │
  70. │       Initializes the soundcard, clears variables and resets constants       │
  71. │       as well as informing the player of the location of the tune. The       │
  72. │       ES:DI pair is normally  not of any interest  to you. It was used       │
  73. │       in games  such as "Lollypop" to split up musics and SFX into two       │
  74. │       parts; one for general stuff and one for level-specific stuff.         │
  75. │                                                                              │
  76. │                                                                              │
  77. │       RESET           AH      01h                                            │
  78. │                                                                              │
  79. │       Use this function whenever you want to stop the player. Eg, when       │
  80. │       quitting to DOS and stuff like that. Clears all variables too.         │
  81. │                                                                              │
  82. │                                                                              │
  83. │       START           AH      02h                                            │
  84. │                       BX      Tune number (Usually 0000h)                    │
  85. │                                                                              │
  86. │       Actually starts the tune. In BX more than one piece of music can       │
  87. │       be triggered, something that was useful in games. However, EdLib       │
  88. │       does not know how to pack more than one tune at this moment - so       │
  89. │       I guess you have to tap a 0000h there, no matter what.                 │
  90. │                                                                              │
  91. │                                                                              │
  92. │       PLAY            AH      03h                                            │
  93. │                                                                              │
  94. │       This is the function that goes into the timer interrupt or maybe       │
  95. │       the vertical retrace. Whatever. Just as long as you update it as       │
  96. │       many times as  the 8th byte  in the ".D00" file is set to. EdLib       │
  97. │       sets this byte to 70 (46h) as default.                                 │
  98. │                                                                              │
  99. │                                                                              │
  100. │       TOGGLE          AH      04h                                            │
  101. │                       BX      Tune number (Usually 0000h)                    │
  102. │                                                                              │
  103. │       Pauses the music instantly. This feature is very useful in games       │
  104. │       when the pause button is pressed. Calling it once more continues       │
  105. │       the music to the best of its abilities; notes falling in quickly       │
  106. │       makes the continuation faultless. But if the notes were long...        │
  107. │                                                                              │
  108. │                                                                              │
  109. │       MAINVOL         AH      05h                                            │
  110. │                       BL      Main volume for part one                       │
  111. │                       BH      Main volume for part two                       │
  112. │                       CL      Dividing line                                  │
  113. │                                                                              │
  114. │       This main volume is a little more complicated than a normal main       │
  115. │       volume routine. Using values of 00h-3Fh  in BL or/and BH you can       │
  116. │       split the main volume up into certain voice parts. Knowing  that       │
  117. │       AdLib has 9 voices, a value of 04h in CL splits up the two reg's       │
  118. │       into  voices 0-3 and 4-8. In  games such  as "Lollypop" this was       │
  119. │       very useful when seperating main volumes for music or SFX, since       │
  120. │       the SFX used voices 0-3 and the music voices 4-8. NOTE: AdLib is       │
  121. │       upside down concerning level (volume) values; use 3Fh as silent.       │
  122. │                                                                              │
  123. │                                                                              │
  124. │       SCAN            AH      06h                                            │
  125. │                                                                              │
  126. │                       CF=0    If the card was detected                       │
  127. │                                                                              │
  128. │       Tries to detect the OPL2 chip (standard AdLib FM chip) using the       │
  129. │       AdLib timer method. If it fails, the carry is set. NOTE: In some       │
  130. │       occasions the detection will fail if there is both a GUS (Gravis       │
  131. │       Ultrasound) and an OPL2 based soundcard in the computer at once.       │
  132. │       It is recommended that you make it possible to override it. Make       │
  133. │       a switch on the commandline or something like that.                    │
  134. │                                                                              │
  135. │                                                                              │
  136. │       BREAK/CONTINUE  AH      07h                                            │
  137. │                       BL=0    Break, otherwise (if BL<>0) continue           │
  138. │                                                                              │
  139. │       This is not a function I can imagine you're ever going to use. I       │
  140. │       made it to make it possible to  break the tune, "remember" where       │
  141. │       it came and start another tune (going into a sublevel). When the       │
  142. │       sublevel was over, this function would then continue on the song       │
  143. │       it "remembered". Since EdLib does not allow more  than one piece       │
  144. │       of music in a ".D00" file, it is not of much use to you! :(            │
  145. │                                                                              │
  146. │                                                                              │
  147. │       REQUEST         AH      08h                                            │
  148. │                       BX      Tune number (Usually 0000h)                    │
  149. │                                                                              │
  150. │                       CF=1    If it is still running                         │
  151. │                                                                              │
  152. │       Simply checks if a tune or SFX ends. Needless to say it requires       │
  153. │       that you use the "FFFExxxx" endmarks in all of the tracks! It is       │
  154. │       not of much use to you, but in games it was worth every penny.         │
  155. │                                                                              │
  156. │                                                                              │
  157. │       PLAYER HEADER VARIABLES                                                │
  158. │       ───────────────────────                                                │
  159. │                                                                              │
  160. │       From offset 0000h in the player I have put certain constants and       │
  161. │       variables at places that will stay the same in every player that       │
  162. │       may be developed for EdLib. These may come in handy if  creating       │
  163. │       some sort of ".D00" shell which loads the player.                      │
  164. │                                                                              │
  165. │                                                                              │
  166. │       Offset          Description                                            │
  167. │       ──────          ───────────                                            │
  168. │                                                                              │
  169. │       0000h-0002h     JMP to all functions which ends with RETF              │
  170. │                                                                              │
  171. │       0003h-0008h     Detection bytes ('JCH',26h,02h,66h)                    │
  172. │                                                                              │
  173. │       0009h-000ah     Current card player version (0400h)                    │
  174. │                                                                              │
  175. │       000bh           Indicates normal OPL2 player (00h)                     │
  176. │                                                                              │
  177. │       000ch           Number of voices supported (09h)                       │
  178. │                                                                              │
  179. │       000dh-002ch     32 bytes card name ('AdLib     ')                      │
  180. │                                                                              │
  181. │       002dh-002eh     Pointer to "Inst" variables                            │
  182. │                                                                              │
  183. │       002fh           Indicates that "Inst" is WORD-based (01h)              │
  184. │                                                                              │
  185. │       0030h-0031h     Pointer to "Dur" variables                             │
  186. │                                                                              │
  187. │       0032h           Indicates that "Dur" is WORD-based (01h)               │
  188. │                                                                              │
  189. │       0033h-0034h     Pointer to "SeqPoi" variables                          │
  190. │                                                                              │
  191. │       0035h           Indicates that "SeqPoi" is WORD-based (01h)            │
  192. │                                                                              │
  193. │       0036h-0037h     Pointer to "TrackPoi" variables                        │
  194. │                                                                              │
  195. │       0038h           Indicates that "TrackPoi" is WORD-based (01h)          │
  196. │                                                                              │
  197. │       0039h-003ah     Pointer to "Freq" variables                            │
  198. │                                                                              │
  199. │       003bh           Indicates that "Freq" is WORD-based (01h)              │
  200. │                                                                              │
  201. │       003ch-003dh     Pointer to "Spedr" variables                           │
  202. │                                                                              │
  203. │       003eh           Indicates that "Spedr" is BYTE-based (00h)             │
  204. │                                                                              │
  205. │       003fh-0040h     Pointer to "Gate" variables                            │
  206. │                                                                              │
  207. │       0041h           Indicates that "Gate" is BYTE-based (00h)              │
  208. │                                                                              │
  209. │       0042h-0043h     Pointer to "Nog" variables                             │
  210. │                                                                              │
  211. │       0044h           Indicates that "Nog" is BYTE-based (00h)               │
  212. │                                                                              │
  213. │       0045h-0046h     Pointer to "Note" variables                            │
  214. │                                                                              │
  215. │       0047h           Indicates that "Note" is BYTE-based (00h)              │
  216. │                                                                              │
  217. │       0048h-0067h     32 bytes reserved for future expansion                 │
  218. │                                                                              │
  219. │       0068h-0070h     ON/OFF flags for all 9 voices (00h=Off)                │
  220. │                                                                              │
  221. │       0071h-????h     Copyright string, and rest of player                   │
  222. │                                                                              │
  223. │                                                                              │
  224. │       Some notes about the information above may be necessary.               │
  225. │                                                                              │
  226. │       The JMP at position 0000h makes it  possible to turn  the player       │
  227. │       into a BIN-file and just call the player from offset 0000h.            │
  228. │                                                                              │
  229. │       You may wonder about the detection bytes. The 'JCH' is of course       │
  230. │       my initials. 26h,02h,66h is my birthdate; 26th of february 1966.       │
  231. │                                                                              │
  232. │       Offset 000bh-002ch was made to identify this player from players       │
  233. │       written for other soundcards. I soon burried this idea.                │
  234. │                                                                              │
  235. │       All the variables pointers each points to nine bytes or words in       │
  236. │       which you may find valuable information for shell programs. Here       │
  237. │       is a deeper explanation of these variables...                          │
  238. │                                                                              │
  239. │                                                                              │
  240. │       "Inst"          9 WORDS         Current instrument played              │
  241. │                                                                              │
  242. │       "Dur"           9 WORDS         Realtime note duration counters        │
  243. │                                                                              │
  244. │       "SeqPoi"        9 WORDS         Realtime sequence position             │
  245. │                                                                              │
  246. │       "TrackPoi"      9 WORDS         Realtime track position                │
  247. │                                                                              │
  248. │       "Freq"          9 WORDS         Actual raw frequency played            │
  249. │                                                                              │
  250. │       "Spedr"         9 BYTES         Current speed of the tune              │
  251. │                                                                              │
  252. │       "Gate"          9 BYTES         Key ON/OFF flags (+++/---)             │
  253. │                                                                              │
  254. │       "Nog"           9 BYTES         Tienote indicator flags                │
  255. │                                                                              │
  256. │       "Note"          9 BYTES         Current note including transp.         │
  257. │                                                                              │
  258. │                                                                              │
  259. │       Note that the variables offered in the header of the player will       │
  260. │       also be available though the "GlOBALS.INC" file when linking. It       │
  261. │       is recommended that you fetch the variables that way if you only       │
  262. │       plan on LINKING with the player.                                       │
  263. │                                                                              │
  264. │       There are more variables in the "GLOBALS.INC" file, but since it       │
  265. │       is beyond the scope of this DOC to describe them I will leave it       │
  266. │       up to you if you want to figure them all out! ;)                       │
  267. │                                                                              │
  268. │                                                                              │
  269. │       THE ".D00" FORMAT                                                      │
  270. │       ─────────────────                                                      │
  271. │                                                                              │
  272. │       Here comes an extensive description of the ".D00" files. With it       │
  273. │       you can make support for ".D00" files in your commandline player       │
  274. │       if you're working on such a program.                                   │
  275. │                                                                              │
  276. │                                                                              │
  277. │       Offset          Description                                            │
  278. │       ──────          ───────────                                            │
  279. │                                                                              │
  280. │       0000h-0005h     Detection bytes ('JCH',26h,02h,66h)                    │
  281. │                                                                              │
  282. │       0006h           Block type (00h for music data)                        │
  283. │                                                                              │
  284. │       0007h           Player version required (Usually 04h)                  │
  285. │                                                                              │
  286. │       0008h           Timer speed for the block (Usually 46h)                │
  287. │                                                                              │
  288. │       0009h           Number of music and SFX (Usually 01h)                  │
  289. │                                                                              │
  290. │       000ah           Soundcard (Usually 00h for AdLib)                      │
  291. │                                                                              │
  292. │       000bh-002ah     32 bytes name of the music                             │
  293. │                                                                              │
  294. │       002bh-004ah     32 bytes name of composer                              │
  295. │                                                                              │
  296. │       004bh-006ah     32 bytes reserved for future expansion                 │
  297. │                                                                              │
  298. │       006bh-006ch     Pointer to "Tpoin" tables                              │
  299. │                                                                              │
  300. │       006dh-006eh     Pointer to "SeqPointer" tables                         │
  301. │                                                                              │
  302. │       006fh-0070h     Pointer to "Instrument" tables                         │
  303. │                                                                              │
  304. │       0071h-0072h     Pointer to "DataInfo" text                             │
  305. │                                                                              │
  306. │       0073h-0074h     Pointer to "Special" tables (SpFX)                     │
  307. │                                                                              │
  308. │       0075h           Endmark (FFFFh)                                        │
  309. │                                                                              │
  310. │                                                                              │
  311. │       Again, some notes about the information above may be necessary.        │
  312. │                                                                              │
  313. │       Offset 0006h is always 00h. It was made to tell music data apart       │
  314. │       from sample data. EdLib of course always sets this to 00h.             │
  315. │                                                                              │
  316. │       Some years ago I spread some old ".D00" music files which I made       │
  317. │       in old AdLib players (v02.00 and below). Some of  this music may       │
  318. │       not sound too good in player v04.00. Check if this byte contains       │
  319. │       04h. If it doesn't, you better avoid playing it.                       │
  320. │                                                                              │
  321. │       When using the AdLib player you should always check offset 0008h       │
  322. │       to see how many times a second the player should be called.            │
  323. │                                                                              │
  324. │       EdLib always sets offset 0009h to 01h. You cannot make more than       │
  325. │       one piece of music at a time in the editor.                            │
  326. │                                                                              │
  327. │       Offset 000ah is always set to 00h in EdLib. If you encounter any       │
  328. │       strange ".D00" files containing any other value you better avoid       │
  329. │       playing it.                                                            │
  330. │                                                                              │
  331. │       Even though the ".D00" format allows 32 bytes for both the music       │
  332. │       name and the composer name, EdLib only accepts 20 characters.          │
  333. │                                                                              │
  334. │       The pointers to various tables is really  not of any interest to       │
  335. │       you, except "DataInfo" which in old songs occasionally contained       │
  336. │       additional text about the song. Tables  such as "Instrument" may       │
  337. │       be useful to know in case you want to edit the ".D00" file! ;)         │
  338. │                                                                              │
  339. │                                                                              │
  340. │       LAST WORDS                                                             │
  341. │       ──────────                                                             │
  342. │                                                                              │
  343. │       You may wonder why it takes so much  time to play a pesky little       │
  344. │       AdLib tune. After all, the player is not mixing like MOD players       │
  345. │       so what the hell is going on here? Bad programming? No!! It is a       │
  346. │       sad fact but true nonetheless; When outputting a value to the FM       │
  347. │       chip like OPL2 I must wait 6 "IN" instructions after the reg has       │
  348. │       been output, and 35 (!) "IN" instructions after the value itself       │
  349. │       has been sent. If I try to decrease the  number of instructions,       │
  350. │       some computers begins to play wrong; notes start falling out and       │
  351. │       play false. There ARE alternatives to using the "IN" method, one       │
  352. │       of the  best is to use the "timer tick" method - but there is an       │
  353. │       even better method.                                                    │
  354. │                                                                              │
  355. │       One of my friends who is working on an editor for OPL3 (the four       │
  356. │       operator chip on SB Pro II and SB 16 to mention a few) found out       │
  357. │       that this chip has been optimized so much, that instead of 6 and       │
  358. │       35 "IN's" it only requires 1 and 0 "IN's" !! I tried it on quite       │
  359. │       a lot of computers, it actually works! If the OPL3 exists it may       │
  360. │       play well in OPL2 mode with  a very small CPU usage. In fact, it       │
  361. │       takes as little time as a native GUS player! :)                        │
  362. │                                                                              │
  363. │       Only one problem arises however. I have not made a detection for       │
  364. │       the OPL3 chip. I haven't  even  tried to, but if I find a way to       │
  365. │       do it, I may very well implement it in the next player update. I       │
  366. │       need some response on this however. If you think AdLib sucks and       │
  367. │       it doesn't make any difference, well - TUFF!                           │
  368. │                                                                              │
  369. │       If you want to contact me, look in the DOC file for EdLib itself       │
  370. │       for a snail mail or FidoNet address.                                   │
  371. │                                                                              │
  372. │       This OBJ and the editor is freeware and may  be used in programs       │
  373. │       that does not earn  you any money, for free. If you  are working       │
  374. │       on one of those commandline players for MOD, S3M, MTM  (you name       │
  375. │       it), why not  make  support for the ".D00" format?  After all, I       │
  376. │       have done most of the work for you already! :)                         │
  377. │                                                                              │
  378. │                                                                              │
  379. │       THE BORING STUFF                                                       │
  380. │       ────────────────                                                       │
  381. │                                                                              │
  382. │       All files in the archive should be distributed in their original       │
  383. │       form - it is forbidden to modify anything. The player may not be       │
  384. │       used commercially in any way without permission from the author.       │
  385. │                                                                              │
  386. │       The names Vibrants, the SirFace System and EdLib  are trademarks       │
  387. │       of Jens-Christian Huus. Other product and  company names are the       │
  388. │       trademarks of their respective owners.                                 │
  389. │                                                                              │
  390. │       All warranties are disclaimed, including damage to your hardware       │
  391. │       and/or software from use of this product.  In no event will I be       │
  392. │       liable to you for any damages - including any lost profits, lost       │
  393. │       savings or other incidental or consequential damages arising out       │
  394. │       of your use or inability to use the  program, or any other claim       │
  395. │       by any other party.                                                    │
  396. │                                                                              │
  397. │                                                                              │
  398. └──────────────────────────────────────────────────────────────────────────────┘
  399.