                                                            04/12/94

                DSPMOD User's Manual
                ====================
                      written by bITmASTER of TCE


Hi Freaks,

ich hasse es, irgendwelche Dokumentationen zu schreiben. Da aber der
DSPMOD immer umfangreicher wird, geht es nicht mehr ohne.

DSPMOD ist ein Modulereplayer fr den Falcon 030. Er wurde speziell
fr Demos konzepiert. DSPMOD hat folgende Eigenschaften:

- Replay fr 4-Kanal-MOD's oder 8 Kanal-MOD's ( Octalizer )
- Replay fr 4-Kanal-MOD's und 4 Kanle fr FX ( Gerusche, z.B. fr
  Games )
- verbraucht wenig 68030er-Rechenzeit
- lt sich einfach einbinden
- die Frequenz des Interrupts ist ziemlich egal ( 50...70 Hz )
  ( also einfach den VBL verwenden )
- vblank-Speed und BPM-Speed wird untersttzt
- Surround-Effekt
- Interpolation

DSPMOD ist kein PD oder Shareware sondern No-Profit-Ware. Das bedeutet:

- DSPMOD kann beliebig kopiert werden, aber nur ohne Profit-Absicht,
  d.h. DSPMOD darf nicht auf kommerziellen PD-Disk's, Coverdisk's oder
  CD's verkauft werden

- DSPMOD kann ber Mailboxen verbreitet werden

- DSPMOD kann in jeden nichtkommerziellen Programm ( Freeware )
  verwendet werden ( z.B. Demos )

- wer DSPMOD in Sharewareprogrammen ( z.B. Games ) verwenden will,
  mu mir dies mitteilen.

- kommerzielle Nutzung ist nur mit mein vorheriges Einverstndnis
  mglich

Die DSPMOD-Funktionen:

Offset  Funktion
 28	init
 32 	off
 36	PlayerOn
 40	PlayerOff
 44	PlayMusic
 48	PlayTime
 52	ModType
 56	fx
 60	not used
 61	Flags
 62	SurroundDelay
 64	DspTracks
 66	PlayInfos
 70	SampleSets

init
====

Assembler:

bsr DSPMOD+28
in:	-
out:   	a0: Zeiger auf Version-String

C:

char *init( void );

Diese Funktion mu immer zuerst aufgerufen werden.
u.a. wird die Soundmatrix initialisiert. Es wird der DSP-Output
mit den Codec ( DA-Wandler ) verbunden.
Da ich selbst keinen richtigen berblick ber die Versionen des
DSPMOD's habe, ist jetzt im Versionsstring das Datum der letzten
Assemblierung enthalten. Daran kann man sicher die neuste Version
erkennen.

off
===

Assembler:

bsr DSPMOD+32
in:	-
out:	-

C:

void off( void )

Deinstalliert DSPMOD. Die Matrix wird wieder auf den alten Zustand
zurckgesetzt. Diese Funktion mu bei beenden des Programm's, welches
DSPMOD benutzt, ausgefhrt werden.

PlayerOn
========

Assembler:

bsr DSPMOD+36
in:	a0: Zeiger auf Modul, a1: Zeiger auf VolumeTab
out:	-

C:

void PlayerOn( char *mod, int *vol_tab )

Spiel ein Modul ab. Die Volume-Tabelle besteht aus 8 Words, welche die
SampleMainVol's festlegen. Zur Bestimmung der Volumes siehe "Volume-
Calculation".

PlayerOff
=========

Assembler:

bsr DSPMOD+40
in:	-
out:	-

C:

void PlayerOn( void )

Stoppt das Abspielen des Modules. Nach PlayerOff() kann mit PlayerOn()
ein neues Modul gestartet werden.



PlayMusic
=========

Assembler:

bsr DSPMOD+44
in:	-
out:	-

C:

void PlayMusic( void )

PlayMusic ist die Interruptroutine, sie mu regelmig aufgerufen
werden. Die Interruptfrequenz kann zwischen 50...70 Hz liegen.
Die Inhalter der Register d0-a6 werden dabei verndert !


PlayTime
========

Assembler:

bsr DSPMOD+48
in:	a0: Zeiger auf Modul
out:	d0: Playtime in BCD, z.B. $1234 = 12 Min, 34 Sek

C:

int PlayTime( char *mod )

Ermittelt die Spieldauer eine Modules.

ModType
=======

Assembler:

bsr DSPMOD+52
in:	a0: Zeiger auf Modul
out:	d0: Anzahl der Tracks ( 4 oder 8 ), 0 bei unbekannten MOD

C:

int ModType( char *mod )

Es werden Module mit folgenden Magic erkannt:
"M.K."
"FLT4"
"CD8 "
"CD81"
"FA08"
Achtung: ein altes 15er Module wird nicht erkannt ( d0 = 0 ) !

fx
==

Assembler:

bsr DSPMOD+56
in:	d0: fx-Channel ( 0 ... 3 )
	d1: Sample-Period
	d2: Sample-Volume
	d3: Sample-Position
	a0: Sample-Start	( Adresse )
	a1: Sample-Ende         ( Adresse )
	a2: Repeat-Start        ( Adresse )
	a3: Repeat-Lnge        ( Bytes )

out:	-

C:

void fx( int channel, int periode, int volume, int position,
         char *start, char *end, char *rep_start, long rep_len );

Alle Adressen und die Lnge mssen geradzahlig sein !

DSPMOD+60:	Kopierschutz-Byte ;-)

DSPMOD+61:	Flags
		b0: Surround an
		b1: Interpolation an

DSPMOD+62:	dc.w SurroundDelay
		1... SurroundDelay in 1/49170 s - Schritten


DSPMOD+64:	dc.w	DspTracks
Anzahl der Tracks, die der DSP verarbeitet. Wird automatisch je
nach Modul gesetzt ( 4 oder 8 Tracks ). Wenn bei einen 4-Kanal-Modul
fx ausgegeben werden soll, mu DspTracks je nach fx-Channels erhht
werden. z.B. 4 fx-Channels -> DspTracks = 8. Wenn fx nicht mehr
gebraucht wird, kann DspTracks wieder auf 4 zurckgesetzt werden
( spart Rechenzeit ).

DSPMOD+66:	dc.l	PlayInfos
Zeiger auf Variablen des MOD-Interpreters

DSPMOD+70 	Zeiger auf SampleSets[8]

Fr jeden Channel gibt es ein Sample-Set. In Assembler sieht
das so aus:

SampPtr:	ds.l 1		;aktuelle Sample-Position
SampEnd:  	ds.l 1		;Sample-Ende
RepStart:	ds.l 1          ;Repeat-Start
RepLen:		ds.l 1          ;Repeat-Lnge
SampPtrFrac:	ds.l 1		;aktuelle Sample-Position fractional
				;Part
SampPer:	ds.w 1          ;Periode, Amiga-kompatibel
  			   	;z.b. fr C-1: 856
SampVol:	ds.w 1          ;Volume, wird von der Replay-
  			   	;Routine gesetzt
  			   	;0 ( min ) ... 64 ( max )
SampMainVol:	ds.w 1          ;Volume, wird durch den User
  			   	;bestimmt werden
  			   	;0 ( min ) ... $7fff ( max )
SampPos:	ds.w 1          ;Stereopositon, wird durch User
		   		;festgelegt
  			   	;-63 ( links ) ... 63 ( rechts )

ein Sample-Set ist 28 Bytes gro.

In C sieht das so aus:

struct {
  	char *ptr;
  	char *end;
  	char *repstart;
  	long replen;
  	long frac_pos
  	int per;
  	int vol;
  	int main_vol;
  	int pos;
} SampSets[];


Volume-Calculation
==================

Die Lautstrke eines Samples wird durch 3 Faktoren bestimmt:

1:  SampVol, Volume von MOD-Interpreter
    0...64
    die Volumes werden als Festkomma-Zahl interpretiert:

    0   $00     0.00
    :    :       :
   32   $20     0.25
    :    :       :
   64   $40     0.50


2:  SampMainVol, wird von User festgelegt
    0...32767
    die Volumes werden als Festkomma-Zahl interpretiert:

       0   $0000     0.00
       :     :        :
   16384   $4000     0.25
       :     :        :
   32767   $7fff     0.99

3:  SampPos, wird von User festgelegt
      -63 ...  0  ... 63
    -0.492 ... 0 ... 0.492
    links    mitte   rechts

Die Lautstrke, mit der ein Sample links / rechts ausgegeben wird,
wird wie folgt berechnet:

Links  = SampVol * SampMainVol * ( 0.5 - SampPos )
Rechts = SampVol * SampMainVol * ( 0.5 + SampPos )

SampleMainVol mu so gewhlt werden, da keine bersteuerung auftritt.

z.B. 4-Kanal-MOD, 2 Kanle links, 2 Kanle rechts
     Maximalausteuerung = 0.99
     0.99 = 0.5 * SampMainVol * 0.92 * 2
     SampMainVol = 1.08
     SampMainVol kann aber nur max. 0.99 sein, also mu dieser Wert
     genommen werden

     8-Kanal-MOD, 4 Kanle links, 4 Kanle rechts
     Maximalausteuerung = 0.99
     0.99 = 0.5 * SampMainVol * 0.92 * 4
     SampMainVol <= 0.53

OK, das ist alles Theorie, man kann den maximalen Wert von SampleMainVol
auch einfach ausprobieren.


EOF ( ich bin eben schreibfaul )

