{mplayer.txt - the document for mbplyer.inc }

 Turbo Pascal moonblaster dos player routines by Kari Lammassaari 1997.

 The source of mbplayer.mpc needed by this source is originally written
 by REMCO SCHRIJVER and later improvements are from Maarten ter Huurne alias
 KRYTEN/MAYHEM .

 The modifications I made, were msxdos2 support, better OPLL search (from
 library of MsxHandbook), mapper support routines and adaptation to operate
 under DOS.

REM !!! The MBPLAYER.MPC (MPC = MapperPageCode) is essential for the operation
of mbplayer.inc. This code is loaded to alocated mapper page and contains the
music interrupt, loader and init code for player code. It's a separate file 
to save the program memory for other purposes.
  
The mplayer.inc  contains following constants,variables,procedures and
functions:


Following constants contain entry adresses of mbplayer.mpc loaded at $4000.
(User don't need to know them. This is only for Your information)

Const 	StartMusic    = $4000;  {Entries to player code. Used internally }
        StopMusic     = $4003;
        PauseMusic    = $4006;  {Not used, same as StopMusic} 
	ContinueMusic = $4009; 
	SearchChips   = $400c;
        MbkLoad       = $400f; {Entry for MModule sample kit loader.}
        MbmLoad       = $4012; {Entry for Moonblaster MBM-file loader}
        MusicInt      = $4015; {Entry for music interrupt}
        ClearFIB      = $4018; {Clear internal FileInfoBlock}
	
	MusicFIB      = $4033; {Internal fib for loading MBM and MBK files}
        Chips         = $401b; {0=MsxAudio,1=MsxMusic,2=both}
        MusicPageNum  = $401D; {Contains the music page number}
        DosErrorFlag  = $4073; {Contains recent dos operation result,Not used.}
        MapperJumpTbl = $4074; {Updated with InitMbmPlayer.}
					 
        IntCode      :Array[0..17] Of Byte = ($f5,$db,$fd,$f5,$3e,0,$d3,$fd,
					      $cd,$15,$40,$f1,$d3,$fd,$f1,
					      $c3,0,0);
        (This code is actual interrupt code to access the mbplayer.mpc code
         on allocated mapper page in primary mapper. It is transferred to
	 $f6ca and patched with pagenumber and original dos interrupt address.
 	 User can ofcourse locate it elsewhere in page 3, if it's nexcessary.)

 	RedirectCode :Array[0..2] Of Byte = ($c3,$ca,$f6); 
 
         {Redirect $38 interrupt to $f6ca.This code is placed at $0038.}
      
        Const PlayerName = 'mbplayer.mpc'; {actual player file }

Var     
    PlayerPageID :Integer;                        
    MusicPageID  :Integer;                       

      {The page id of player/music page, initialized by InitMbmPlayer.
	Lo(PageId) = Slot ID of page, Hi(PageId) = page number  }

    NewHook	:Array[0..17] Of Byte Absolute $f6ca ;{Code to access player}
    z80int      :Array[0..2]  Of Byte Absolute $0038; {Original $38 interrupt}
    z80orig	:Array[0..20] Of Byte;                {Storage for $38 int vect}



Function InitMbmPlayer:Boolean; {True if succeeded ;}

  You need not to know this, but this is done by InitMbmPlayer:

  - Checks, that there is player code file 'mbplayer.mpc available, if not,
    halts with error message. So use this code before setting a graphic screen.
  - Checks, that there is mapper support.
  - Checks, that there are 2 free pages to allocate on primary mapper.
  - Allocates 2 pages as system pages for player code and music file.
  - Loads MBPLAYER.MPC into allocated page.
  - Updates MapperJumpTbl-address in mbplayer code for internal use.
  - Searches for music chips and updates Chips location in mbplayer code.
  - Updates MusicPageNum location in mbplayer code for music interrupt.

Procedure LoadMBKFile(FileName:StringType);

  - Loads MusicModule samplekit (created by Moonblaster) into Audio Ram.
  - The file extension of sample kit is normally .MBK  .
  - Corrupts Music Page, which is used as buffer. Load MBK first, then MBM.
  - If there is no MusicModule, does nothing.

Procedure LoadMBMFile(FileName:StringType);

  - Loads Moonblaster music file into MusicPage .
  - Normally file extension is .MBM .
  
Function GetMusicChips:Byte; {0=MsxAudio,1=MsxMusic,2=Both,255 = PSG}

  - Returns the code for the music chips available.

Procedure StartMbmPlay;

  - Redirects interrupt vector at $0038 and starts playing.
  - Does not check, that there is a valid music file loaded into music page,
    but plays, what ever there happens to be. System may crash.

Procedure StopMbmPlay;
 
  - Restores interrupt vector at $0038 and ... stops playing.

Procedure ContinueMbmPlay;

  - Redirects interrupt vector at $0038 and starts playing from the position,
    where the playing was stopped.

	
Function GetErrorCode:Byte; { The codes are normal msxdos2 error codes }

  - Returns after LoadMBK/MBMFile the result of loading process.
  - Zero = no errors , $DA = invalid filename, $$D7 = file not found etc.	
  - Does not detect corrupted files !