
Extension:	.d00
Version:	4.00 (Player Version)
Created by:	Jens-Christian Huus (JCH/Vibrants)
Tracker:	Edlib Tracker
Players:	Edlib, ...
Description by: JCH/Vibrants
Taken from:	Edlib v1.05a rev 055
Note:		Adlib (OPL2) music format


Ŀ
 How to use Player v04.00 ............................ by Jens-Christian Huus
Ĵ
                                                                             
                                                                             
       INTRODUCTION                                                          
                                                                 
                                                                             
       So you have finally managed to fumble you way  around the editor      
       and now you want to use the music in your demo or other piece of      
       programming not earning you any money (Because THAT's the deal)!      
       All right, in this directory you will find the OBJ player needed      
       to link onto your own program. This DOC  will tell you about the      
       functions and variables in the player plus the file formats.          
                                                                             
       After having done your tune in the editor - saving the source to      
       disk with Shift-F12 or Ctrl-F4 - you must convert it to a format      
       with the ".D00" extension. Do this by  pressing Ctrl-F5 while in      
       the editor. The music  will be packed to a fully playable format      
       which takes up little memory (typically 2-5 Kb). Now you can use      
       this file together with "MPLAYER.OBJ" in this directory.              
                                                                             
       NOTE: You cannot load ".D00" files into EdLib. Make sure you DID      
       save that masterpiece with Shift-F12 or Ctrl-F4 before packing!       
                                                                             
                                                                             
       THE TEST PROGRAM                                                      
                                                             
                                                                             
       Before describing the functions in the player, have a look at my      
       example file "TEST.ASM" to see how I use the "STR_WISE.D00" file      
       by Drax. The source was assembled using Turbo Assembler v4.0 and      
       linked using Turbo Link v6.00, both from Borland. You can use my      
       makefile "-" to accomplish this, but check it out first - I have      
       used the 4DOS command "keystack 13" to  skip the annoying "Press      
       any key to continue" message before reentering my source editor.      
       I have also  used a "mode co80,50" to switch into 50 lines mode,      
       a mode I use a lot when programming.                                  
                                                                             
       The file "GLOBALS.INC" is included in the source. This file con-      
       tains most of the variables in  the player, but in the TEST file      
       I only use the "GLOBAL PLAYER:FAR" line to call the player. Some      
       of the other  variables will be discussed  later, as they can be      
       used to make scopes or the like in your own programs.                 
                                                                             
       The execution of the "TEST.ASM" file is simple - first it checks      
       if an OPL2 chip is present using a function in the player. If it      
       isn't, an error is printed and the program is aborted. Otherwise      
       the ".D00" is loaded, the player initialized and started. I have      
       used a standard timer interrupt routine to call the AdLib player      
       as many times as it was used in the  editor (this information is      
       saved into the ".D00" file). The source  code has been commented      
       all the way, so I guess I don't have to say more than that.           
                                                                             
                                                                             
       PLAYER FUNCTIONS                                                      
                                                             
                                                                             
       Use the "CALL PLAYER" label prepared by "GLOBAL PLAYER:FAR" with      
       registers prepared to access all player functions. The player is      
       from my old school, so no registers are pushed I'm afraid. Do it      
       yourself. Here is a list of the functions currently available in      
       this version of the player.                                           
                                                                             
                                                                             
       MAIN RESET      AH      00h                                           
                       BX:CX   Segment:offset of ".D00" data #1              
                       ES:DI   Segment:offset of ".D00" data #2              
                                                                             
       Initializes the soundcard, clears variables and resets constants      
       as well as informing the player of the location of the tune. The      
       ES:DI pair is normally  not of any interest  to you. It was used      
       in games  such as "Lollypop" to split up musics and SFX into two      
       parts; one for general stuff and one for level-specific stuff.        
                                                                             
                                                                             
       RESET           AH      01h                                           
                                                                             
       Use this function whenever you want to stop the player. Eg, when      
       quitting to DOS and stuff like that. Clears all variables too.        
                                                                             
                                                                             
       START           AH      02h                                           
                       BX      Tune number (Usually 0000h)                   
                                                                             
       Actually starts the tune. In BX more than one piece of music can      
       be triggered, something that was useful in games. However, EdLib      
       does not know how to pack more than one tune at this moment - so      
       I guess you have to tap a 0000h there, no matter what.                
                                                                             
                                                                             
       PLAY            AH      03h                                           
                                                                             
       This is the function that goes into the timer interrupt or maybe      
       the vertical retrace. Whatever. Just as long as you update it as      
       many times as  the 8th byte  in the ".D00" file is set to. EdLib      
       sets this byte to 70 (46h) as default.                                
                                                                             
                                                                             
       TOGGLE          AH      04h                                           
                       BX      Tune number (Usually 0000h)                   
                                                                             
       Pauses the music instantly. This feature is very useful in games      
       when the pause button is pressed. Calling it once more continues      
       the music to the best of its abilities; notes falling in quickly      
       makes the continuation faultless. But if the notes were long...       
                                                                             
                                                                             
       MAINVOL         AH      05h                                           
                       BL      Main volume for part one                      
                       BH      Main volume for part two                      
                       CL      Dividing line                                 
                                                                             
       This main volume is a little more complicated than a normal main      
       volume routine. Using values of 00h-3Fh  in BL or/and BH you can      
       split the main volume up into certain voice parts. Knowing  that      
       AdLib has 9 voices, a value of 04h in CL splits up the two reg's      
       into  voices 0-3 and 4-8. In  games such  as "Lollypop" this was      
       very useful when seperating main volumes for music or SFX, since      
       the SFX used voices 0-3 and the music voices 4-8. NOTE: AdLib is      
       upside down concerning level (volume) values; use 3Fh as silent.      
                                                                             
                                                                             
       SCAN            AH      06h                                           
                                                                             
                       CF=0    If the card was detected                      
                                                                             
       Tries to detect the OPL2 chip (standard AdLib FM chip) using the      
       AdLib timer method. If it fails, the carry is set. NOTE: In some      
       occasions the detection will fail if there is both a GUS (Gravis      
       Ultrasound) and an OPL2 based soundcard in the computer at once.      
       It is recommended that you make it possible to override it. Make      
       a switch on the commandline or something like that.                   
                                                                             
                                                                             
       BREAK/CONTINUE  AH      07h                                           
                       BL=0    Break, otherwise (if BL<>0) continue          
                                                                             
       This is not a function I can imagine you're ever going to use. I      
       made it to make it possible to  break the tune, "remember" where      
       it came and start another tune (going into a sublevel). When the      
       sublevel was over, this function would then continue on the song      
       it "remembered". Since EdLib does not allow more  than one piece      
       of music in a ".D00" file, it is not of much use to you! :(           
                                                                             
                                                                             
       REQUEST         AH      08h                                           
                       BX      Tune number (Usually 0000h)                   
                                                                             
                       CF=1    If it is still running                        
                                                                             
       Simply checks if a tune or SFX ends. Needless to say it requires      
       that you use the "FFFExxxx" endmarks in all of the tracks! It is      
       not of much use to you, but in games it was worth every penny.        
                                                                             
                                                                             
       PLAYER HEADER VARIABLES                                               
                                                      
                                                                             
       From offset 0000h in the player I have put certain constants and      
       variables at places that will stay the same in every player that      
       may be developed for EdLib. These may come in handy if  creating      
       some sort of ".D00" shell which loads the player.                     
                                                                             
                                                                             
       Offset          Description                                           
                                                            
                                                                             
       0000h-0002h     JMP to all functions which ends with RETF             
                                                                             
       0003h-0008h     Detection bytes ('JCH',26h,02h,66h)                   
                                                                             
       0009h-000ah     Current card player version (0400h)                   
                                                                             
       000bh           Indicates normal OPL2 player (00h)                    
                                                                             
       000ch           Number of voices supported (09h)                      
                                                                             
       000dh-002ch     32 bytes card name ('AdLib     ')                     
                                                                             
       002dh-002eh     Pointer to "Inst" variables                           
                                                                             
       002fh           Indicates that "Inst" is WORD-based (01h)             
                                                                             
       0030h-0031h     Pointer to "Dur" variables                            
                                                                             
       0032h           Indicates that "Dur" is WORD-based (01h)              
                                                                             
       0033h-0034h     Pointer to "SeqPoi" variables                         
                                                                             
       0035h           Indicates that "SeqPoi" is WORD-based (01h)           
                                                                             
       0036h-0037h     Pointer to "TrackPoi" variables                       
                                                                             
       0038h           Indicates that "TrackPoi" is WORD-based (01h)         
                                                                             
       0039h-003ah     Pointer to "Freq" variables                           
                                                                             
       003bh           Indicates that "Freq" is WORD-based (01h)             
                                                                             
       003ch-003dh     Pointer to "Spedr" variables                          
                                                                             
       003eh           Indicates that "Spedr" is BYTE-based (00h)            
                                                                             
       003fh-0040h     Pointer to "Gate" variables                           
                                                                             
       0041h           Indicates that "Gate" is BYTE-based (00h)             
                                                                             
       0042h-0043h     Pointer to "Nog" variables                            
                                                                             
       0044h           Indicates that "Nog" is BYTE-based (00h)              
                                                                             
       0045h-0046h     Pointer to "Note" variables                           
                                                                             
       0047h           Indicates that "Note" is BYTE-based (00h)             
                                                                             
       0048h-0067h     32 bytes reserved for future expansion                
                                                                             
       0068h-0070h     ON/OFF flags for all 9 voices (00h=Off)               
                                                                             
       0071h-????h     Copyright string, and rest of player                  
                                                                             
                                                                             
       Some notes about the information above may be necessary.              
                                                                             
       The JMP at position 0000h makes it  possible to turn  the player      
       into a BIN-file and just call the player from offset 0000h.           
                                                                             
       You may wonder about the detection bytes. The 'JCH' is of course      
       my initials. 26h,02h,66h is my birthdate; 26th of february 1966.      
                                                                             
       Offset 000bh-002ch was made to identify this player from players      
       written for other soundcards. I soon burried this idea.               
                                                                             
       All the variables pointers each points to nine bytes or words in      
       which you may find valuable information for shell programs. Here      
       is a deeper explanation of these variables...                         
                                                                             
                                                                             
       "Inst"          9 WORDS         Current instrument played             
                                                                             
       "Dur"           9 WORDS         Realtime note duration counters       
                                                                             
       "SeqPoi"        9 WORDS         Realtime sequence position            
                                                                             
       "TrackPoi"      9 WORDS         Realtime track position               
                                                                             
       "Freq"          9 WORDS         Actual raw frequency played           
                                                                             
       "Spedr"         9 BYTES         Current speed of the tune             
                                                                             
       "Gate"          9 BYTES         Key ON/OFF flags (+++/---)            
                                                                             
       "Nog"           9 BYTES         Tienote indicator flags               
                                                                             
       "Note"          9 BYTES         Current note including transp.        
                                                                             
                                                                             
       Note that the variables offered in the header of the player will      
       also be available though the "GlOBALS.INC" file when linking. It      
       is recommended that you fetch the variables that way if you only      
       plan on LINKING with the player.                                      
                                                                             
       There are more variables in the "GLOBALS.INC" file, but since it      
       is beyond the scope of this DOC to describe them I will leave it      
       up to you if you want to figure them all out! ;)                      
                                                                             
                                                                             
       THE ".D00" FORMAT                                                     
                                                            
                                                                             
       Here comes an extensive description of the ".D00" files. With it      
       you can make support for ".D00" files in your commandline player      
       if you're working on such a program.                                  
                                                                             
                                                                             
       Offset          Description                                           
                                                            
                                                                             
       0000h-0005h     Detection bytes ('JCH',26h,02h,66h)                   
                                                                             
       0006h           Block type (00h for music data)                       
                                                                             
       0007h           Player version required (Usually 04h)                 
                                                                             
       0008h           Timer speed for the block (Usually 46h)               
                                                                             
       0009h           Number of music and SFX (Usually 01h)                 
                                                                             
       000ah           Soundcard (Usually 00h for AdLib)                     
                                                                             
       000bh-002ah     32 bytes name of the music                            
                                                                             
       002bh-004ah     32 bytes name of composer                             
                                                                             
       004bh-006ah     32 bytes reserved for future expansion                
                                                                             
       006bh-006ch     Pointer to "Tpoin" tables                             
                                                                             
       006dh-006eh     Pointer to "SeqPointer" tables                        
                                                                             
       006fh-0070h     Pointer to "Instrument" tables                        
                                                                             
       0071h-0072h     Pointer to "DataInfo" text                            
                                                                             
       0073h-0074h     Pointer to "Special" tables (SpFX)                    
                                                                             
       0075h           Endmark (FFFFh)                                       
                                                                             
                                                                             
       Again, some notes about the information above may be necessary.       
                                                                             
       Offset 0006h is always 00h. It was made to tell music data apart      
       from sample data. EdLib of course always sets this to 00h.            
                                                                             
       Some years ago I spread some old ".D00" music files which I made      
       in old AdLib players (v02.00 and below). Some of  this music may      
       not sound too good in player v04.00. Check if this byte contains      
       04h. If it doesn't, you better avoid playing it.                      
                                                                             
       When using the AdLib player you should always check offset 0008h      
       to see how many times a second the player should be called.           
                                                                             
       EdLib always sets offset 0009h to 01h. You cannot make more than      
       one piece of music at a time in the editor.                           
                                                                             
       Offset 000ah is always set to 00h in EdLib. If you encounter any      
       strange ".D00" files containing any other value you better avoid      
       playing it.                                                           
                                                                             
       Even though the ".D00" format allows 32 bytes for both the music      
       name and the composer name, EdLib only accepts 20 characters.         
                                                                             
       The pointers to various tables is really  not of any interest to      
       you, except "DataInfo" which in old songs occasionally contained      
       additional text about the song. Tables  such as "Instrument" may      
       be useful to know in case you want to edit the ".D00" file! ;)        
                                                                             
                                                                             
       LAST WORDS                                                            
                                                                   
                                                                             
       You may wonder why it takes so much  time to play a pesky little      
       AdLib tune. After all, the player is not mixing like MOD players      
       so what the hell is going on here? Bad programming? No!! It is a      
       sad fact but true nonetheless; When outputting a value to the FM      
       chip like OPL2 I must wait 6 "IN" instructions after the reg has      
       been output, and 35 (!) "IN" instructions after the value itself      
       has been sent. If I try to decrease the  number of instructions,      
       some computers begins to play wrong; notes start falling out and      
       play false. There ARE alternatives to using the "IN" method, one      
       of the  best is to use the "timer tick" method - but there is an      
       even better method.                                                   
                                                                             
       One of my friends who is working on an editor for OPL3 (the four      
       operator chip on SB Pro II and SB 16 to mention a few) found out      
       that this chip has been optimized so much, that instead of 6 and      
       35 "IN's" it only requires 1 and 0 "IN's" !! I tried it on quite      
       a lot of computers, it actually works! If the OPL3 exists it may      
       play well in OPL2 mode with  a very small CPU usage. In fact, it      
       takes as little time as a native GUS player! :)                       
                                                                             
       Only one problem arises however. I have not made a detection for      
       the OPL3 chip. I haven't  even  tried to, but if I find a way to      
       do it, I may very well implement it in the next player update. I      
       need some response on this however. If you think AdLib sucks and      
       it doesn't make any difference, well - TUFF!                          
                                                                             
       If you want to contact me, look in the DOC file for EdLib itself      
       for a snail mail or FidoNet address.                                  
                                                                             
       This OBJ and the editor is freeware and may  be used in programs      
       that does not earn  you any money, for free. If you  are working      
       on one of those commandline players for MOD, S3M, MTM  (you name      
       it), why not  make  support for the ".D00" format?  After all, I      
       have done most of the work for you already! :)                        
                                                                             
                                                                             
       THE BORING STUFF                                                      
                                                             
                                                                             
       All files in the archive should be distributed in their original      
       form - it is forbidden to modify anything. The player may not be      
       used commercially in any way without permission from the author.      
                                                                             
       The names Vibrants, the SirFace System and EdLib  are trademarks      
       of Jens-Christian Huus. Other product and  company names are the      
       trademarks of their respective owners.                                
                                                                             
       All warranties are disclaimed, including damage to your hardware      
       and/or software from use of this product.  In no event will I be      
       liable to you for any damages - including any lost profits, lost      
       savings or other incidental or consequential damages arising out      
       of your use or inability to use the  program, or any other claim      
       by any other party.                                                   
                                                                             
                                                                             

