How to use the MB1.4 BASIC driver
=================================

This BASIC driver is spread as a binary file for BASIC programmers. This text
will explain how to use this driver for BASIC programmers.

The driver supports:
- DOS1 and DOS2 memory usage
- DOS1 and DOS2 file access
- Z80 and R800

Also, the BASIC driver now returns BASIC errors when something went wrong for
whatever reason.



BASIC
-----

To load the driver use BLOAD"BASIC.BIN",R after protecting the driver area
from being overwritten by BASIC with CLEAR 200,&HDA00.

Below is a short overview of all new BASIC commands:

_MBVER
Displays the version message.

_MBCHIP(chips)
This will select which soundchip will be used to play the music. Setting 0
will select MSX-AUDIO. Setting 1 will select MSX-MUSIC. Setting 2 or higher
will play the song on both.

_MBADDR(address)
This sets the current load/play address. To allow loading inside the mapper
bank the address should be between &H8000 and &HC000. When the driver is
first installed the address will be &H8000.

_MBBANK(bank)
This sets the current load/play mapper bank. After first installation the
bank will be 3. It's possible to use up to 4 more mapper banks by allocating
extra banks. The bank is verified and will raise an error if it's outside
boundaries. Bank 3 is the lowest possible bank and can be up to 7 depending
on the number of additional banks allocated. This can be done with _MBALLOC.

_MBKLOAD("filename")
This will load a samplekit with the name "filename". It uses the current bank
set by _MBBANK as a buffer to move the data to Sample RAM. "Filename" can
also include a pathname. _MBKLOAD will only actually load if there is sample
RAM.

_MBMLOAD("filename")
This will load a songfile with the name "filename" in the current bank at the
current address. "Filename" can unclude a pathname.

_MBPLAY
Starts playing of a song using current address and current bank. Samples will
only actually play if there is sample RAM.

_MBSTOP
Stops playing.

_MBHALT
Pauses music.

_MBCONT
Continues music after _MBHALT.

_MBFADE(speed)
The music will fade out at the given speed. The lowest possible value is 1 and
the highest possible value is 255.

_MBEQUAL(switch)
This will force the music to play at 50Hz at all time. You can switch it off
and on. Setting 0 will disable the feature. Music will play faster on 60Hz.
Setting 1 or higher will enable the feature.

_MBALLOC(number of extra banks)
If you need more than just 16K (see _MBBANK) use this command. Note that the
driver will try to allocate the number of free memory. It's possible to use
_MBALLOC more than once, up to the 4 extra allocated blocks. If there are 4
banks allocated or no more free banks to allocate the command will raise an
error.

_MBFREE(number of extra banks to free)
This will free the given number of banks allocated with _MBALLOC. Especially
for DOS2 usage it's very important that this is always done before you return
to the system. If you forget this the allocated banks will be wasted until the
computer is restarted. When music is playing in one of the extra banks, it'll
be stopped and both _MBBANK and _MBADDR will be restored to their initial
values.

_Z80, _R800
MSXturboR users can use these commands to change the current CPU.


POSSIBLE ERRORS
---------------

(5) Illegal function call
- Occurs when you try to select a bank with _MBBANK that isn't allocated yet.
  To solve this, use _MBALLOC to allocated additional banks.
- Occurs when you try to allocate or free less than 1 or more than 4
  additional banks.
(7) Out of memory
- Occurs when you try to allocate extra banks with _MBALLOC while the maximum
  number of banks is already allocated. The BASIC replayer can only allocate
  up to 4 extra banks.

(53) File not found
(69) Disk I/O error
- Possible disk errors which can occur with _MBKLOAD or _MBMLOAD.


READABLE VARIABLES
------------------

The BASIC programmer can read several variables with the PEEK command from the
following table:

&HDA00	0 = MSX-AUDIO, 1 = MSX-MUSIC, 2 = both
&HDA01	0 = not playing, 255 = playing
&HDA02	mapperbank with songdata
&HDA03	address of song data
&HDA05	current position
&HDA06	current step
&HDA07	status byte #1 (0 = off)
&HDA08	status byte #2 (0 = off)
&HDA09	status byte #3 (0 = off)
&HDA0A	song data that will be played the next interrupt
&HDA1B	number of extra allocated banks

Do not POKE in this table, this may give unexpected results!


CHANGES
-------

- fixed lock-up in sample ram detection
- fixed bug disallowing filenames without extensions in DOS1


CREDITS
-------

The MB1.4 BASIC driver is written by Remco Schrijvers. Due to lack of sources
reverse engineered, after a request by Near Dark, by BiFi 2012.
Adaptions by BiFi / The New Image 2012/2015.

Comments, bug reports or feature requests:
e-mail: bifi@msxnet.org
IRC:    BiFi in #msxdev@Rizon
