Multichannel ayFX replayer using asMSX syntax

code: SapphiRe
source: http://www.z80st.es

Version History
---------------
04-05-2020 v2.1M     Multichannel ayFX replayer with PT3 replayer support
02-04-2018 v2.0M     Multichannel ayFX replayer

What is it?
-----------
This replayer allows to use ayFX samples on your MSX games. It allows to play up
to three ayFX samples simultaneously (one on each PSG channel).

Also each sample can be played with a different priority (from 0 to 15).  Higher
values  result in less priority.  If all the channels are busy playing a sample,
the  replayer removes the one with lower priority if  the new sample  has higher
priority.

How can I write ayFX samples?
-----------------------------
You can use the ayFX editor made by shiru for Windows. Download it from:

                          http://shiru.untergrund.net

You you  must save the samples as a bank,  using the  "Save bank" or  "Save bank
w/o names"  options  to  save  a multisound  bank.  The only  difference between
these two options is that "Save bank" will also save the names of the samples.

A bank can contain up to 256 ayFX samples.

How to use
----------

There are three main routines on the player: setup a bank, init a new sample and
play a frame of all the samples.

-Bank setup:

First  of all,  you need  to call  the ayFX_SETUP  procedure to  initialize  the
correct values of  the replayer. When  calling ayFX_SETUP you must set on hl the
address of the sound bank you want to use.

-Init a sample:

When you want to play an ayFX sample,  you need to put on register A (from  0 to
255) the index of the sample in the bank, and  in register C the priority of the
sample, and  call to  ayFX_INIT procedure.  Legal sample  priorities are  from 0
(highest  priority)  to 15  (lowest  priority). Higher  values  may cause  wrong
results.

The ayFX_INIT procedure returns a value on register A for debugging purposes:

0: no errors, the new sample has been correctly initialized
1: priority error, all channels are playing samples with higher priority
2: index error, the current bank don't have a sample with such index

-Play a frame of the samples:

To play a frame of the streams, just call to ayFX_PLAY. The replayer will search
an empty  channel or will remove  the lower priority  sample if the  new one has
higher priority.

The suggested calling sequence is:

HALT (or any equivalent vblank sinchronization)
...
(a routine that copy ayFX_REGS ram zone on PSG registers)
...
call ayFX_PLAY
...

Contact
-------
For any comments, bugs or suggestions, send an email to

                            z80st.software@gmail.com
