MSX Village forum

 
How to use the MBWAVE BASIC driver 1.13
=======================================
 
This BASIC driver is spread as a binary file for BASIC programmers
and as a source file for ML programmers. The first part of this
text will explain how to use this driver for BASIC programmers. The
second part is meant for ML programmers.
 
The driver supports:
- MoonBlaster for MoonSound Wave songs from version 0.90 to 1.12.
- DOS1 and DOS2
- Z80,Z80H and R800 (three different drivers)
 
For 7MHz Users is now a special version available (WAVDRV7.BIN). This version
is  mutch faster because (for 7Mhz that is) the wait for the Turbo R is:
 
PUSH BC
POP  BC  (This is a total of 21 cycles for the Z80)
 
In the 7Mhz version this is replayced by:
 
NOP (only 4 Cycles)
 
This means 17 cycles faster by almost each OUT or IN. And there are a lot of
those.
 
 
BASIC
-----
To load the driver type BLOAD"WAVEDRVx.BIN",R and then protect the
upper memory from BASIC with CLEAR 200,&HDA00.
 
Below is a short overview of all new BASIC commands:
 
_MBVER
Displays version number
 
_MBINIT
It is very important that this call is done first! This will initialise
the mapper routines and allocate the first 4 mapper banks.
 
_MBADDR(load address)
This sets the current load/play address.
 
_MBBANK1(bank)
_MBBANK2(bank)
_MBBANK3(bank)
These routines set the current load/play mapper bank. In theory a Wave
song can be slightly larger than 32KB. Therefore 3 mapper banks may be
neccessary. However, in practice songs abover 16K will be very rare and
it will suffice to set only _MBBANK1. Note that with songs > 16K MBBANK1
is always used as the first bank to fill and only when the song is too
big to fit MBBANK2 and 3 will be used.
 
In theory you can use 64K after a MBINIT command (bank 0-3). But unfortunately
you cannot use bank 0 (system page), 2 (replayer page) and you can only
use bank 1 if you move the BASIC start address to &HC000. So only bank 3
is available most of the time unless you use the MBALLOC command.
 
_MWKLOAD("filename")
This will load a wavekit with name "filename". It uses MBBANK1 as a
buffer to move the data to Sample RAM. Do not forget to load a wavekit
before playing a song. The replayer may crash if you try to play a song
that uses a wavekit when no wavekit was loaded!
 
_MWMLOAD("filename")
This will load a wave song with name "filename" in the current bank at
the current address.
 
_MBPLAY
Starts playing of a song using current address and current bank.
 
_MBSTOP
Stops playing.
 
_MBHALT
Pauses music.
 
_MBCONT
Continues music after MBHALT.
 
_MBFADE(speed)
The music will fade out at the given speed.
 
_MBALLOC(extra banks)
If you need more than the first 64K (see MBBANK) use this command. Note that
the driver will NOT check if enough free memory is available. The programmer
needs to do that himself! You can only use MBALLOC once. If you need more,
use MBFREE first and then MBALLOC again. MBALLOC will only allocate *extra*
segments. E.g. with MBALLOC(4) you will have 4 + 4 = 8 banks (128K) available.
 
_MBFREE
This will free all segments that were allocated with MBALLOC. Especially
for DOS2 usage it is VERY important that this is always done before you return
to the system. If you forget this the allocated segments will be wasted untill
the computer is restarted!!
 
_Z80, _R800
Turbo-R users can use these commands to change the current CPU. Great care
must be taken however because it is impossible to use the Z80 version of the
replayer in R800 speed and vice versa!
 
The BASIC programmer can read several variables with the PEEK command from
the following table:
 
&HDA000 = not playing, 255 = playing
&HDA011st mapperbank with song data
&HDA022nd mapperbank with song data
&HDA033rd mapperbank with song data
&HDA04address of song data
&HDA06current position
&HDA07current step
&HDA083 status bytes (0 = off)
&HDA0Bsong data that will be played the next interrupt
 
&HDA26Available free segments. This is only valid in DOS2! It can
be used to check if enough memory is available for the MBALLOC
command. Note that it is not updated after an MBALLOC command.
 
Do not POKE in this table, this may give unexpected results!
 
 
ML programmers
--------------
ML programmers will find most of the explanation they need in the BASIC text
above and in the source. Some additional notes are given here.
 
- The source uses a lot of conditional assembly. You can select the following:
  1. Assemble it for R800,Z80H or Z80
  2. Include the FADE
  3. Include a speed test
  4. Disable RAM headers for extra speed (try to avoid this!)
 
- The replayer is using routines called selbank_FE and curbank_FE to select
  or to read the current mapper bank from 08000h - 0BFFFh. You may wish to
  replace these with your own routines.
 
- Read the comment at the MWM loading routine. It is possible to simplify this
  routine, but take care doing so!
 
- The MWK loading routine needs several variables in the replayer bank. It
  may be convenient to place the loader in the same bank as the replayer but
  do not forget that the FCB cannot be in the page 04000h-07FFFh unless you
  are in MSX-DOS!!! Some MSX computers can handle this, but most of them
  cannot!
 
- Note that the R800 version will not crash in Z80 mode on a MSX2 but it is
  strongly advised to use the Z80 version! Using the R800 version on Z80 will
  slow the replayer down incredibly and it will crash on a Turbo-R in Z80 mode!
 
- The replayer is now on the Hook #FD9A, because it uses the OPL4 interrupt
  now.(So no difference between 50/60Hz anymore!)