*
* S F X for the NGPC.
*        by 
*  Ivan Mackintosh 
*    28 July 2001
*

1. ARCHIVE CONTENTS
----------------------------------------------------------------
The archive contains:
   readme.txt  - instructions
   sfx.ngp     - a sound generator program
   sfxdriv.z80 - the sound driver code itself
   sfxlib.inc  - a helper library of the sound calls
   example code


2. INTRODUCTION
----------------------------------------------------------------
This archive and instructions provides you with everything you
will need to integrate the SFX driver into your NGPC project 
and get up and running with sound effects in minutes!


3. FIRST CREATE YOUR SOUND EFFECTS
----------------------------------------------------------------
* Load up sfx.ngp either on NGPocket emulator or a real NGPC.

* Fiddle about with the numbers until you get the sound you like
(these values are described below)

* Write down the hex values. Note that when writing down the two
byte values you will have to reverse them. e.g If INIT TONE = 03FF
then write down FF 03

* Repeat steps 2 and 3 for all of your sound effects.


4. SFX.NGP VARIABLES DESCRIBED
----------------------------------------------------------------
When you run SFX.NGP the screen will show a list of variables that
can be altered to make your sound effect.

These are as follows:

CHANNEL - values: 00 - 04
Specifies which sound channel the effect will play on. Channels 1,2,
and 3 are pure tone channels whereas 0 and 4 are white noise. 0 and 4
are actually the same channel and therefore cannot be played 
simultaneously. The difference is the type of white noise. 4 has
feedback.

LENGTH - values: 00 - FF
How long the sound effect should last in 60ths second.

REPEATS - values: 00 - FF
How many times the sound effect should repeat (FF = infinite)

INIT TONE - values: 0000 - 03FF
The initial tone. 0 = high pitched, 3FF = low pitched. If a noise channel
is used then the scales is 0 to somewhere around 0080.

STEP - values: 0000 - 03FF
If speed is set to >0 then the step value is added to the initial tone.
So setting speed to 1 and step to 1 will cause a sliding sound.
The step is added to the initial tone and then logically anded with 03FF
this means that a value of 03FF actually represents -1, 03FE = -2 etc.

SPEED - values: 00 - FF
The speed of change in 60ths seconds.
If this value is >0 then when this timer is reached the step value will
be added to the initial tone.

OFF/W/B - values: 00 - 02
00 = OFF, 01 = (W)RAP, 02 = (B)OUNCE
This enables the Low and Upper limits and instructs what to do when a 
limit is reached. E.g. if the upper limit is reached and wrap is set then
the sound tone will wrap back to the lower limit. If bounce is set then
the slide is reverse and the tone bounces between the two limits.
This setting only takes affect if speed and step are used.

LOW LIMIT - values: 0000 - 03FF
The lower tone limit for the OFF/W/B setting.

UPR LIMIT - values: 0000 - 03FF
The upper tone limit for the OFF/W/B setting.

INIT VOL - values: 00 - 0F
The initial volume of the sound effect. 00 = off (quiet), 0F = loudest

STEP - values: 00 - 0F
If speed is set to >0 then the step value is added to the initial vol.
So setting speed to 1 and step to 1 will cause a effect that will get 
louder.
The step is added to the initial volume and then logically anded with 0F
this means that a value of 0F actually represents -1, 0E = -2 etc.

SPEED - values 00 - FF
The speed of change in 60ths seconds.
If this value is >0 then when this timer is reached the step value will
be added to the initial volume.

OFF/W/B - values: 00 - 02
00 = OFF, 01 = (W)RAP, 02 = (B)OUNCE
This enables the Low and Upper limits and instructs what to do when a 
limit is reached. E.g. if the upper limit is reached and wrap is set then
the sound volume will wrap back to the lower limit. If bounce is set then
the slide is reverse and the volume bounces between the two limits.
This setting only takes affect if speed and step are used.

LOW LIMIT - values: 0000 - 03FF
The lower volume limit for the OFF/W/B setting.

UPR LIMIT - values: 0000 - 03FF
The upper volume limit for the OFF/W/B setting.


5. ADDING SOUNDS TO YOUR PROJECT
----------------------------------------------------------------
Use Example.asm as a reference. There are only a few things to do.

* include "sfxlib.inc" at the end of your program. This provides 
all of the helper functions you will need like SFX_PlaySound

* in your VB interrupt code add a call to SFX_VBTimer

* in your initialisation code make a call to SFX_Initialise. This
has 2 parameters. The 'c' register must be set to say how many
sound effects you have. (1-31)
The 'xix' register must point to the sound effect data as taken from
the SFX.NGP program e.g.
    ld c, 2                   ; I have 2 sound effects
    ld xix, MySoundEffects    ; and here they are.
    calr SFX_Initialise

* to play a sound effect simple call SFX_PlaySound setting the 'c'
register to the sound effect number you wish to play.
e.g.
    ld c, 2                   ; play sound 2
    call SFX_PlaySound

* a call to SFX_Quiet can be made if you wish to turn off all of the
sound effects.

And that is it!!! 






