

                         AUDIOFUN V1.1


1. ALLGEMEINES
--------------

   Mit dem  Programm  AUDIOFUN  knnen  Sie  den Soundchip (PSG)
programmieren.   Interessant  ist  es  vor  allem fr Leute, die
Spiele  programmieren,  fr  diese  aber  keine  digitalisierten
Soundeffekte  benutzen wollen oder knnen - z.B. wegen Verbrauch
von  Speicherplatz  und/oder Rechenzeit. Der PSG ist aber leider
trotz vorhandenen Hllkurvengenerator keine Ohrenweide.
   Dieses Manko   soll   dieses   Programm  zumindest  zum  Teil
beseitigen.  Fr  jeden der drei Kanle ist nun eine eigene (und
echte!)  ADSR-Hllkurve  sowie  diverse Effekte verfgbar. Jeder
Kanal  ist  unabhngig und kann beliebig gestartet oder gestoppt
werden.  Es ist allerdings nicht mglich, ellenlanges Gedudel zu
erzeugen.  Vielmehr  kann  zu  Situationen  (Ball berhrt Bande,
Game   over   etc.)  ein  entsprechender  akustischer  Kommentar
gegeben werden.



1.1. Hardware

   Entwickelt habe  ich  dieses  Programm auf einem 1040 STE mit
Farbmonitor.   Da  es  aber  vollstndig in GEM eingebunden ist,
sollte  es  mit smtlichen Auflsungen ab 320x200 zurechtkommen,
egal ob bunt oder monochrom.
   Mit dem  Rechnermodell  sollte  es  eigentlich  ebenso  sein.
Voraussetzung  ist, da sowohl der TIMER_A und natrlich der PSG
vorhanden sind.
   Der Speicherbedarf  von  AUDIOFUN  ist gering und luft daher
auch auf kleinsten Modellen.



1.2. Public Domain

   AUDIOFUN ist  ffentliches Gut! Das bedeutet fr Sie, da Sie
dieses  Programm  kostenlos  benutzen,  kopieren und verschenken
knnen  und  sollen. Wird dieses Programm verkauft, so darf sich
der  Preis  nur  aus  dem  Kopieraufwand,  Porto  und Verpackung
zusammensetzen!
   Trotz sorgfltiger  Programmierung  sind  natrlich  Bugs nie
auszuschlieen.   Sollten  also  wider  erwarten  Fehlfunktionen
auftreten,  bin  ich  fr  eine  kurze  schriftliche  Mitteilung
dankbar.  Aber  auch wenn Ihnen dieses Programm nur gefllt oder
Sie  einen  Verbesserungsvorschlag  haben,  drfen (und sollten)
Sie mir eine (Ansichts-) Karte schicken! Meine Adresse lautet:

                        Harald Frster
                         Tnkenhagen 1
                         23552 Lbeck



                             - 1 -


                         AUDIOFUN V1.1


1.3. Zwei in Einem

   Dieses Programm  besteht  eigentlich  aus zwei Programmen. Zu
einem   ist   da  natrlich  AUDIOFUN,  welches  mit  Sozobon  C
geschrieben  wurde. Hiermit knnen Sie Ihre Sounddaten eingeben,
testen  und  bei  Bedarf ndern usw. Die fertige Datei wird dann
auf Massenspeicher gesichert.
   Das zweite     Programm     ist    der    SOUNDWORKER,    der
Ausfhrgeschwindigkeit  zuliebe  mit TurboAss entwickelt. Dieses
Programm  ist  in  der von Ihnen gesicherten Datei enthalten und
kann  nun zu Ihrem Programm geladen werden, wobei es keine Rolle
spielt,    welche    Programmiersprache   Sie   verwenden.   Der
SOUNDWORKER  wird alle 20ms gestartet (Interrupt), berechnet die
Sounddaten und schreibt sie in den PSG.
   Da beide  Programme  also  unterschiedliche  Aufgaben  haben,
wird  die  Beschreibung  getrennt erfolgen: erst AUDIOFUN, damit
Sie  wissen,  wie  Sie Klnge einstellen und danach SOUNDWORKER,
damit Sie diese Klnge auch ins eigene Programm bekommen.





2. AUDIOFUN
-----------

   Nach starten    des   Programms   sollten   Sie   am   oberen
Bildschirmrand eine Menzeile sehen.



2.1. Audiofun

   Wie beim   Desktop   Zugriff   auf   die   Info-Box  und  den
Accessories.



2.2. File

   Ebenfalls kaum  ein  Unterschied  zu  anderen GEM-Programmen,
trotzdem einige Erluterungen.


2.2.1. New

   Es wird  eine  im Speicher stehende Datei kommplett gelscht.
Sollte  diese  noch  ungesichert  sein,  erscheint  vorher  eine
Warnung.  Diese  Funktion  ist  nur  mglich,  wenn  es etwas zu
lschen gibt!




                             - 2 -


                         AUDIOFUN V1.1


2.2.2. Load...

   Eine vorher  gesicherte Datei kann wieder geladen werden. Als
Extension  habe  ich "FUN" gewhlt, kann von Ihnen aber gendert
werden.


2.2.3. Save

   Eine Datei  wird  gesichert. Diese Funktion ist erst mglich,
wenn  ein gltiger Dateiname existiert, also nach Load oder Save
as.


2.2.4. Save as...

   Wie bei  Save  wird eine Datei gesichert, nur knnen Sie hier
ein  anderes Laufwerk auswhlen und der Datei einen Namen geben.
Diese Funktion ist erst mglich, wenn es etwas zu sichern gibt!
   Whlen Sie  eine  schon  vorhandene  Datei,  die  nichts  mit
AUDIOFUN   zu   tun   hat  (z.B.  DESKTOP.INF),  erscheint  eine
Fehlermeldung.


2.2.5. Save DRI

   Diese Funktion  ist  fr  Sie  interessant, wenn Ihr Compiler
das  Linkformat  von  Digital  Research  versteht.  Es  wird ein
Objekt-File  gesichert,  da Sie direkt zu Ihrem Programm linken
knnen.
   Eine so gesicherte Datei kann nicht mehr geladen werden!


2.2.6. Quit

   Das Programm  wird  verlassen.  Eine Rckfrage gibt es nicht,
wohl aber eine Warnung im Falle einer ungesicherten Datei.



2.3. Edit

   Unter diesem  Titel  befinden  sich  alle Eintrge, die etwas
mit  dem  PSG  zu tun haben. Tatschlich dienen sie aber nur zum
ffnen  der  entsprechenden  Fenster.   Pro Eintrag kann nur ein
Fenster  geffnet  werden.  Jedes  kann  getoppt, verschoben und
geschlossen werden.
   Die Einstellungen  selbst  werden  immer  im obersten Fenster
vorgenommen.  Um  etwas zu ndern, bewegt Sie den Mauscursor auf
einen  der  Pfeile  und  bettigen  die linke Maustaste. Je nach
Richtung  des  Pfeils wird nun der Wert erhht bzw.  erniedrigt.
Bei  Zahlen mit mehr als zwei Stellen kann auch die rechte Taste


                             - 3 -


                         AUDIOFUN V1.1


benutzt  werden,  wobei statt 1 dann 10 addiert oder subtrahiert
werden.
   Bei der  Erklrung  der  einzelnen  Parameter  werde  ich die
mglichen  Werte  in  eckigen Klammern angeben. Es bedeutet dann
also  [1...999],  da  smtliche  Einstellungen  von  1  bis 999
mglich sind.



2.3.1. Frequency

   Dieses Fenster  ist  nach  Programmstart  schon  geffnet und
eben fr die Frequenzen zustndig.


2.3.1.1. Channel [A...C]

   Einer der drei Kanle A, B oder C kann gewhlt werden.


2.3.1.2. Part [1...8]

   Zu jedem  Kanal  gehren  acht  Parts mit eigenen Frequenzen,
Hllkurven  und Effekten, wobei natrlich pro Kanal nur ein Part
zur  Zeit gespielt werden kann. Sie knnen also bis zu 24 Klnge
bzw. kurze Melodien eingeben.


2.3.1.3. Tempo [1...2000]

   Dieser Wert   bestimmt   die  Zeitdauer  eines  Taktes.  Jede
Einheit einer Zeitangabe hat immer die Lnge von 20ms.
   Wenn bei  Tempo  z.B. ein Wert von 50 steht, hat ein Takt die
Lnge von 50*20ms, also einer Sekunde.


2.3.1.4. Test

   Der eingestellte  Kanal wird gestartet und der Part gespielt.
Wenn  Sie  den Test vorzeitig abbrechen wollen, so verlassen Sie
mit dem Mauspfeil das Testfeld.


2.3.1.5. Sound [0 - 30...4095]

   Jeder Part  ist  maximal  16  Takte lang (Time 0 bis Time F).
Ein  Takt kann die Eintrge 30 (hchster Ton) bis 4095 (tiefster
Ton) annehmen.
   Die 0  hat  hierbei eine besondere Bedeutung. Einerseits wird
berhaupt  kein  Ton  gespielt.  Zum anderen kann man erreichen,
da  ein Ton mehrere Takte lang ist.  Wenn Sie zum Beispiel 100,
200,  0, 0, 100 eingeben, hat der erste Ton die Lnge von Tempo,


                             - 4 -


                         AUDIOFUN V1.1


der  zweite  dagegen  die dreifache. Geben Sie nun 0, 200, 0, 0,
100  ein,  so  ist der Unterschied zum vorigen Beispiel der, da
im ersten Takt kein Ton zu hren ist.


2.3.1.6. Noise [0...32]

   Im Prinzip  genau  das  gleiche  wie  bei  Sound. Der Wert 32
entspricht  hier  dem  physikalischen  Wert  0 des PSG (hchstes
Rauschen).
   Einen wichtigen  Unterschied  gibt  es  aber doch: da der PSG
nur  einen  Rauschgenerator  besitzt,  habe  ich  diesen fest an
Kanal  A  gebunden.  Mit  anderen  Worten:  Rauschen ist auf den
Kanlen B und C nicht mglich!
   Deshalb knnen  Sie  die Noise-Werte auch nur verndern, wenn
der Kanal A eingestellt ist.


2.3.1.7. Hinweise zu Frequency

   berlegen Sie,  welche  Klnge kein Rauschen bentigen. Diese
legen Sie vorrangig auf die Kanle B und C.
   Da bis  zu  drei  Gerusche  gleichzeitig  erklingen  knnen,
verteilen  Sie  diese, die tatschlich gleichzeitg oder zeitlich
kurz aufeinander vorkommen knnen, auf A, B und C.
   Die Ereignisse,  die  nie gleichzeitig auftreten knnen (z.B.
Spielstart,  neues  Level  und Game over) gehren alle auf einen
Kanal (etwa Part 1 bis 3 auf C).



2.3.2. Envelope

   Mit einer  Hllkurve  wird  der Lautstrkeverlauf eines Tones
festgelegt.  Aufgrund  der  wenigen  Hllkurven des PSG habe ich
per  Software  eine  komplette  und relativ frei programmierbare
ADSR-Hllkurve  realisiert.  Im  Gegensatz zum PSG hat nun jeder
Kanal  seinen  eigenen Generator, wodurch alle Kanle vollkommen
unabhngig voneinander werden.


2.3.2.1. Rand

   Dieses Feld   ist   fast   identisch  mit  dem  Testfeld.  Im
Unterschied  dazu  werden aber nicht die programmierten, sondern
zufllige   Frequenzen   gespielt.  Rauschen  und  alle  anderen
Parameter bleiben unverndert.







                             - 5 -


                         AUDIOFUN V1.1


2.3.2.2. Attack

   Der Beginn  einer  Hllkurve  ist  immer Attack. Dabei bewegt
sich  die  Lautstrke  von  0 auf Maximum. Je nachdem, ob dieser
Anstieg  schnell  oder  langsam  abluft, kann man z.B Zupf- von
Streichinstrumenten unterscheiden.


2.3.2.2.1. Length [1...999]

   Die Zeit,  nach  der  die maximale Lautstrke erreicht werden
soll.


2.3.2.2.2. Volume [1...15]

   Die Lautstrke,  die  nach  Beendigung  von  Attack  erreicht
werden soll.


2.3.2.3. Decay

   Wenn Sie   eine   Klaviertaste  drcken  und  diese  gedrckt
halten,  wird  der  Ton  recht  schnell  die  grte  Lautstrke
erreichen   (Attack),   um   anschlieend  langsam  abzuklingen.
Hierfr ist Decay zustndig.


2.3.2.3.1. Length [0...999]

   Lnge der  Decay-Phase.  Ist  dieser  Wert 0, wird kein Decay
ausgefhrt.


2.3.2.3.2. Volume [0...15]

   Lautstrke, die  nach  Ablauf von Decay erreicht werden soll.
Beachten  Sie, da im Gegensatz zu natrlichen Instrumenten hier
die  Decay-Lautstrke  auch  grer  oder  gleich der von Attack
sein kann.
   Ist die Decay-Dauer 0, wird die Lautstrke nicht beachtet.


2.3.2.4. Sustain

   Drcken Sie  statt  einer  Klavier-  eine  Orgeltaste, ergibt
sich   ein   anderer   Lautstrkeverlauf.   Nach  erreichen  der
maximalen  Lautstrke bleibt diese nun nun solange konstant, bis
die Taste losgelassen wird.





                             - 6 -


                         AUDIOFUN V1.1


2.3.2.4.1. Length [0...999]

   Angabe, wie  lange  die  Lautstrke  von  Attack  oder  Decay
gehalten  werden  soll.  Ist  dieser  Wert 0, wird Sustain nicht
ausgefhrt.


2.3.2.5. Release

   Noch einmal   zum   Klavier.  Wenn  Sie  diesmal  eine  Taste
drcken,  diese  aber  nach  einer kurzen Zeit wieder loslassen,
ergibt  sich  folgender  Hllkurvenverlauf:  Nach Attack beginnt
die  Decay-Phase,  wird  aber  mit dem loslassen der Taste durch
Release  ersetzt. Die Folge ist, da der Ton nicht mehr langsam,
sondern recht schnell ausklingt.


2.3.2.5.1. Length [0...999]

   Dauer, bis  die  Attack- oder Decaylautstrke 0 erreicht. Ist
der Wert von Release 0, wird diese Funktion nicht ausgefhrt.


2.3.2.6. Hinweise zu Envelope

   Wie Sie  gesehen  haben,  lassen  sich  Hllkurventeile  auch
ausblenden.  Dadurch  mu  nicht  eine  komplette ADSR-Hllkurve
programmiert  werden,  mglich sind auerdem: A, AD, AS, AR, ADS
sowie ADR.
   Ist die  Gesamtdauer  der Hllkurve (also A+D+S+R) lnger als
ein  Takt,  so  gehen  die Tne ineinander ber. Ist dagegen der
Takt lnger, klingt das ganze abgehackt (staccato).
   Wenn ein   Ton  mehrere  Takte  hrbar  sein  soll,  mu  die
Gesamtdauer der Hllkurve ein vielfaches von Tempo sein.
   Beim letzten  Ton  hngt  die Taktlnge nicht mehr von Tempo,
sondern von der Hllkurve ab.



2.3.3. Effects

   Auch mit  einer ADSR-Hllkurve klingt der Sound vom PSG immer
noch    recht    langweilig.    Um    diesen    lebendiger   und
abwechslungsreicher  zu gestalten, stehen Ihnen hier noch einige
Effekte zur Verfgung.


2.3.3.1. Tremolo

   Die Hllkurve  wird  amplitudenmoduliert,  d.h.  der Ton wird
abwechselnd lauter und leiser.



                             - 7 -


                         AUDIOFUN V1.1


2.3.3.1.1. Speed [1...15]

   Dieser Wert      bestimmt      die     Geschwindikeit     des
Lautstrkewechsels,  wobei  die  Werte  8  bis 14 aber identisch
sind.


2.3.3.1.2. Delay [1...2000]

   Mit dieser  Zeitangabe  knnen  Sie  den Einsatz des Effektes
verzgern.  Die Angabe mu aber kleiner als Tempo sein, da sonst
der  Effekt  nicht  ausgefhrt  wird.  Wenn sich der Ton und der
Effekt  ber  mehrere  Takte erstreckt, wird die Verzgerung nur
im ersten Takt beachtet.


2.3.3.1.3. FEDCBA9876543210

   Die Effekte  knnen  Sie  fr  jeden  Takt freigeben (1) oder
sperren  (0).  Diese Zeile gibt die Taktnummern an, in der Zeile
darunter  befinden  sich die dazugehrigen Schalter. Bewegen Sie
den  Mauspfeil  auf  die  entsprechende Ziffer und bettigen die
linke Taste. Aus einer 0 wird dann eine 1 und umgekehrt.


2.3.3.2. Sound Vibtrato

   Der Ton  wird  frequenzmoduliert. Hierbei pendelt die Tonhhe
periodisch um die Grunfrequenz.


2.3.3.2.1. Add [1...4095]

   Dieser Betrag wird in jedem Interrupt zur Frequenz addiert.


2.3.3.2.2. Count [1...2000]

   Ein Zhler,  der  die  Vibratofrequenz  bestimmt.  Je  grer
dieser Wert ist, desto geringer die Frequenz.
   Add und  Count  stehen  in  einem engen Zusammenhang. Add=100
und  Count=1  ergeben  den  gleichen  Frequenzhub wie Add=25 und
Count=4, nur die Vibratofrequenz ist unterschiedlich.


2.3.3.3. Noise Vibrato

   Vibrato fr   den  Rauschgenerator.  Vernderungen  sind  nur
mglich, wenn Kanal A eingestellt ist.





                             - 8 -


                         AUDIOFUN V1.1


2.3.3.3.1. Add [1...31]

   Gleiche Bedeutung wie bei Sound Vibrato.


2.3.3.3.2. Count [1...2000]

   Da der  Rauschgenerator im PSG nur 5 bit schmal ist, bestimmt
dieser  Eintrag nicht wie bei Sound Vibrato zusammen mit Add den
Hub.  In  diesem  Fall  wird  nur  die  Rauschfrequenz  fr  die
angegebene Zeit gehalten.


2.3.3.4. Sound Pitch Bend

   Whrend beim  Vibrato  die Frequenz um den Grundton schwankt,
biegt dieser Effekt den Ton in nur eine Richtung.


2.3.3.4.1. Add [1...4095]

   Bestimmt, wieviel  in  jedem  Interrupt  zur Frequenz addiert
wird.  Angaben  bis  2047 ziehen den Ton nach unten, die darber
nach oben.


2.3.3.5. Noise Pitch Bend

   Pitch Bend  fr  den  Rauschgenerator.  Kann ebenfalls nur im
Kanal A verndert werden.


2.3.3.5.1. Add [1...31]

   Bis 15 wird das Rauschen tiefer, sonst hher.


2.3.3.6. Sound Legato

   Dieser letzte  Effekte ist ebenfalls zur Frequenzbeinflussung
gedacht.  Die  Tonhhe  wird  dabei  auf die des folgenden Tones
gezogen.  Bekannt  drfte  solches  von  der Geige, Posaune oder
Hawaiigitarre sein.
   Zu beachten    ist    hier,    da    dieser   Effekt   immer
zusammenhngend  durchgefhrt  wird.   Wenn  ein  Ton  z.B. drei
Takte    dauert,   gibt   es   mehrere   Mglichkeiten,   Legato
einzusetzen.  Es kann nur im ersten Takt erlaubt sein, wobei die
folgenden  beiden  dann  schon  die Frequenz des folgenden Tones
haben.  Auch  kann  Legato  bei  allen  drei  Takten freigegeben
werden,  dann  ist  die  nderung  langsamer.  Fast alle anderen
Kombinationen sind ebenfalls mglich.
   Nur eines  funktioniert  in  diesem  Beispiel  nicht: Legato,


                             - 9 -


                         AUDIOFUN V1.1


kein  Legato,  Legato!  Nachdem im ersten Takt Legato ausgefhrt
wurde,  hat  der  zweite  Takt  schon  die Frequenz des nchsten
Tones.  Im  dritten  Takt  kann also kein Legato mehr ausgefhrt
werden.
   Eine Mglichkeit  gibt  es  aber  doch.  Wenn  Sie  zu obigen
Beispiel  zustzlich  kein  Pitch  Bend,  Pitch Bend, kein Pitch
Bend  eingeben,  klappt  es.  Nach  dem  ersten  Legato  wird im
zweiten  Takt der Ton verbogen, im dritten Takt kann also erneut
Legato erfolgen.
   Zu guter  letzt:  beim  letzten Ton ist natrlich kein Legato
mglich!


2.3.3.7. Hinweise zu Effects

   Alle Effekte  sind  auch  untereinander  mischbar. Allerdings
sollten  Sie  es  nicht bertreiben: Legato zusammen mit Vibrato
und Pitch Bend ist des Guten zuviel!



2.3.4. Test all

   In diesem  Fenster  knnen Sie alle Kanle und Parts parallel
testen.  Gestartet  wird  ein  Part, indem der Mauspfeil auf das
entsprechende  Feld  bewegt  und  die linke Taste gedrckt wird.
Mchten  Sie  den Part vorzeitig stoppen, drcken Sie die rechte
Taste.
   Sie knnen  auch  -  whrend  ein  Part  abgearbeitet  wird -
diesen  erneut  oder  einen  anderen  starten.  Dadurch  hat Ihr
Programm   die   Mglichkeit,  immer  die  aktuellen  Ereignisse
akustisch wiederzugeben.
   Whrend eines  Lade  -oder  Speichervorganges  wird der Sound
abgestellt.   Anschlieend  knnen  Sie  aber wie gewohnt weiter
testen.





3. SOUNDWORKER
--------------

   Nachdem Sie   mhsam  Ihre  Sounddaten  zusammengestellt  und
abgespeichert  haben,  sollen  Sie  jetzt erfahren, wie Sie eine
solche   Datei  in  Ihr  Programm  bekommen  und  von  dort  aus
ansprechen knnen.







                             - 10 -


                         AUDIOFUN V1.1


3.1. Binding

   Fr Omikron.Basic  und  Sozobon  C  habe  ich  je ein Binding
geschrieben.  Sollten  Sie  mit einer anderen Programmiersprache
arbeiten,  ist  dieses  kein  Problem.   Schreiben  Sie sich ein
eigenes Binding oder verzichten Sie vllig auf ein Binding.
   Herr Peter   Vogel   aus   Heide   schrieb  ein  Binding  fr
GFA-Basic,   welches  er  mir  freundlicherweise  zur  Verfgung
stellte  und  sich  nun  ebenfalls  auf dieser Diskette befinden
sollte.
   Da Omikron.Basic   auf  Zeilennummern  besteht,  beginnt  das
Binding  bei  63000. Wenn eine Biblothek ebenfalls diese Nummern
benutzt, mssen Sie das Binding umnummerieren.



3.2. Funktionen und ihre Aufrufe

   Mit den  folgenden  Funktionen knnen Sie den SOUNDWORKER aus
Ihrem  Programm  ansprechen.  Es  kann  sein, da Sie nicht alle
Mglichkeiten  nutzen.  In  diesem Fall streichen Sie alle nicht
bentigten Funktionen im Binding.
   Fr Sozobon  C  ist  zustzlich  ein Archiv vorhanden, in dem
sich  alle  Funktionen  assembler-optimiert  befinden.  Wenn Sie
dieses  benutzten,  sollten  Sie  die Datei "SWK_LIB.H" in Ihren
Quelltext einbinden.


3.2.1. Load

   Eine Datei   wird   zum   Programm   geladen.  Der  bentigte
Speicherplatz wird dabei reserviert.

    GFA-Basic:   lret& = FN swk_load(filename$)
Omikron-Basic:   Lret% = FN Swk_Load%(Filename$)
    Sozobon C:   int lret = swk_load(char *filename);

  Parameter:   Dateiname

   Rckgabe:       0:  alles OK
               sonst:  Gemdos-Fehlermeldung oder falsche Datei


   Den Rckgabewert  sollten  Sie  auf  jeden  Fall abfragen. Es
knnte  ja sein, da die Datei nicht gefunden wurde oder es sich
um  eine  fremde  Datei  handelt.  In diesem Fall mssen Sie Ihr
Programm mit einer Fehlermeldung abbrechen!
   Wenn Sie  Ihre Sounddatei mit Save DRI gesichert und zu Ihrem
Programm  gelinkt  haben, knnen Sie diese Funktion natrlich im
Binding streichen.




                             - 11 -


                         AUDIOFUN V1.1


3.2.2. Start

   Timer_A wird  gestartet.  Bevor  irgendwelche  Daten  an  den
SOUNDWORKER  bergeben  werden,  mu  diese  Funktion aufgerufen
werden!

    GFA-Basic:   swk_start
Omikron-Basic:   Swk_Start
    Sozobon C:   void swk_start()

  Parameter:   keine

   Rckgabe:   keine



3.2.3. Stop

   Timer_A wird   gestoppt.   Diese   Funktion   mu  immer  vor
Programmende oder laden einer anderen Datei aufgerufen werden!

    GFA-Basic:   swk_stop
Omikron-Basic:   Swk_Stop
    Sozobon C:   void swk_stop();

  Parameter:   keine

   Rckgabe:   keine



3.2.4. Play

   Ein Kanal wird gestartet und der gewnschte Part gespielt.

    GFA-Basic:   swk_play(channel&, part&)
Omikron-Basic:   Swk_Play(Channel%, Part%)
    Sozobon C:   void swk_play(int channel, int part);

  Parameter:   Kanalnummer 0 bis 2 fr Kanle A bis C
               Partnummer +/- 1 bis 8 (negativ fr zufllige
                                                 Frequenzen)

   Rckgabe:   keine

   Bei einer    ungltigen    Partnummer    wird    der    Kanal
stummgeschaltet.







                             - 12 -


                         AUDIOFUN V1.1


3.2.5. Till

   Nicht immer   mchte   man   alle   Takte   hren.   Bei  den
Zufallsfrequenzen  werden z.B.  immer alle 16 Takte benutzt. Mit
dieser  Funktion  knnen  Sie die Anzahl der zu spielenden Takte
vermindern.  Im  Unterschied  zum AUDIOFUN zhlt der SOUNDWORKER
die  Takte  von  1  bis  16.  Dieser  Aufruf  mu immer vor Play
erfolgen!

    GFA-Basic:   swk_till(channel&, last&)
Omikron-Basic:   Swk_Till(Channel%, Last%)
    Sozobon C:   void swk_till(int channel, int last);

  Parameter:   Kanalnummer 0 bis 2 fr Kanle A bis C
               Nummer des letzten zu spielenden Taktes

   Rckgabe:   keine


3.2.6. Exec

   In bestimmten  Situationen  kann  es sinnvoll sein, zu Beginn
eines   Taktes  eine  Aktion  auszulsen,  z.B.  den  Bildschirm
invertieren.
   Mit diesem   Aufruf   knnen   Sie   die  Startadresse  einer
(kurzen!)   Routine   bergeben,   die   dieses  oder  hnliches
ausfhrt.  Die  Routine  wird im Supervisor-Modus ausgefhrt und
mu   mit   einem   RTS   abgeschlossen  sein.  Sie  knnen  die
XBIOS-Funktionen,   die   mit   dem  Bildschirm  zu  tun  haben,
benutzen.  Die  Aufrufe  sollten  Sie  (Sozobon  C Programmierer
mssen,  also  auf  gar  keinen Fall OSBIND.H benutzen!) aber in
Assembler schreiben.
   Exec mu  vor  Play aufgerufen werden. Ihre Routine kann dann
aber  wieder  Exec  aufrufen. Sie knnten so z.B. den Bildschirm
invertieren  und  nach  einigen Takten wieder normal darstellen.
Wahlweise knnen Sie auch Till aufrufen.

    GFA-Basic:   swk_exec(channel&, begin&, routine%)
Omikron-Basic:   Swk_Exec(Channel%, Begin%, Routine%L)
    Sozobon C:   void swk_exec(int channel, int begin, long routine);

  Parameter:   Kanalnummer 0 bis 2 fr Kanle A bis C
               Nummer des Taktes, bei dem die Routine
                  gestartet werden soll. Bei einer  0
                  wird die Routine am Ende  des Parts
                  ausgefhrt.
               Startadresse der Routine.

   Rckgabe:   keine





                             - 13 -


                         AUDIOFUN V1.1


3.2.7. Time

   Diese Funktion  liefert  die  Nummer  des momentan gespielten
Taktes.

    GFA-Basic:   tret& = FN swk_time(channel&)
Omikron-Basic:   Tret% = FN Swk_Time%(Channel%)
    Sozobon C:   int tret = swk_time(int channel);

  Parameter:   Kanalnummer 0 bis 2 fr Kanle A bis C

   Rckgabe:   Momentane Taktnummer oder 0, wenn Kanal
                  inaktiv. -1: falsche Kanalnummer

   Wenn Sie  gleich  nach  Play  diese Funktion aufrufen, werden
Sie  aller  Wahrscheinlichkeit nach die Partnummer erhalten, die
Sie  eben  mit  Play  bergeben  haben. Abhilfe: mindestens 20ms
warten oder folgenden Aufruf vorschalten!


3.2.8. Part

   Diese Funktion  liefert  die  Nummer  des momentan gespielten
Parts.

    GFA-Basic:   pret& = FN swk_part(channel&)
Omikron-Basic:   Pret% = FN Swk_Part%(Channel%)
    Sozobon C:   int pret = swk_part(int channel);

  Parameter:   Kanalnummer 0 bis 2 fr Kanle A bis C

   Rckgabe:   Momentane Partnummer oder 0, wenn Kanal
                  inaktiv. -1: falsche Kanalnummer

   Part sollten  Sie  immer  vor  Time  verwenden,  um sicher zu
stellen,  da  der  Wert, den Sie erhalten, auch gltig ist. Nur
wenn  es sich um eine Partnummer handelt, ist auf die Taktnummer
verlass.
   Einzige Ausnahme:  Sie  bergeben  bei  Play  eine  ungltige
Partnummer  grer  255  und  fragen anschlieend die Partnummer
ab!
   Die Funktionen  Time  und Part knnen Sie z.B. dazu benutzen,
da  Ihr Programm bis Erreichen eines bestimmten Taktes in einer
Leerschleife  verharrt  und  somit  der Programmablauf fr diese
Zeit gestoppt wird.


3.2.9. Joy_Start

   Im SOUNDWORKER  ist auch eine Joystickabfrage integriert, die
Sie,  falls  Ihr  Programm mit dem Joystick gesteuert wird, auch
benutzen  sollten.  Damit  stellen  Sie sicher, da Ihr Programm


                             - 14 -


                         AUDIOFUN V1.1


auch unter anderen TOS-Versionen luft!
   Dieser Aufruf   startet  die  Abfrage.  Dabei  gibt  es  zwei
Mglichkeiten:  entweder  es  werden  beide  Joysticks  oder nur
Joystick  1  abgefragt.  Im  letzteren  Fall ist die Mausabfrage
weiter   mglich,   dafr   aber  nicht  die  des  Feuerknopfes.
Abhilfe:  mit der AES-Funktion Graf_Mkstate die rechte Maustaste
abfragen.

    GFA-Basic:   joy_start(joy_mode&)
Omikron-Basic:   Joy_Start(joy_mode%)
    Sozobon C:   void joy_start(int joy_mode);

  Parameter:       0: nur Joystick 1
               sonst: joystick 0 und joystick 1

   Rckgabe:   keine


3.2.10. Joy_Stop

   Die Joystickabfrage  wird  beendet.  Diese  Funktion  mu auf
jeden   Fall   vor  Programmende  aufgerufen  werden,  wenn  die
Joystickabfrage benutzt wurde!

    GFA-Basic:   joy_stop
Omikron-Basic:   Joy_Stop
    Sozobon C:   void joy_stop();

  Parameter:   keine

   Rckgabe:   keine


3.2.11. Joy_Last

   Liefert den Wert des zuletzt bewegten Joysticks.

    GFA-Basic:   jlast& = FN joy_last
Omikron-Basic:   Jlast% = FN Joy_Last%
    Sozobon C:   int jlast = joy_last();

  Parameter:   keine

   Rckgabe:   254 fr Joystick 0 und 255 fr Joystick 1.
               Ist die Abfrage nicht eingeschaltet, erhalten
               Sie eine 0.


3.2.12. Joy_0

   Liefert momentane Stellung von Joystick 0.



                             - 15 -


                         AUDIOFUN V1.1


    GFA-Basic:   stick_0& = FN joy_0
Omikron-Basic:   Stick_0% = FN Joy_0%
    Sozobon C:   int stick_0 = joy_0();

  Parameter:   keine

   Rckgabe:   Wert fr Joystick 0. Bei gedrckter Feuertaste
               um 128 erhht.


3.2.13. Joy_1

   Liefert momentale Stellung von Joystick 1.

    GFA-Basic:   stick_1& = FN joy_1
Omikron-Basic:   Stick_1% = FN Joy_1%
    Sozobon C:   int stick_1 = joy_1();

  Parameter:   keine

   Rckgabe:   Wert fr Joystick 1. Bei gedrckter Feuertaste
               um 128 erhht (nicht bei Joy_Mode 0).



3.3. Andere Sprachen

   Damit Sie   sich  Ihr  eigenes  Binding  schreiben  oder  den
SOUNDWORKER  direkt  ansprechen  knnen,  werde  ich  jetzt  den
prinzipiellen Aufbau einer solchen Datei beschreiben.
   Zuerst mssen  Sie  in  Ihrem  Programm (oder Binding) ein 16
bit  Integerfeld  mit  2512  Elementen einrichten, also z.B. DIM
Feld%(2512).  Anschlieend  ermitteln Sie die Anfangsadresse des
Feldes und laden Ihre Sounddatei binr dorthin.
   Wenn Sie  die  Datei  zu Ihrem Programm gelinkt haben, mssen
Sie   dieses   Feld  (oder  besser  noch  Struktur)  als  extern
deklarieren.    Der   Feldname   ist   _swk,   wobei   zumindest
C-Programmierer   den   Unterstrich   weglassen  mssen  (extern
swk[2512]).
   Fr die   Kommunikation   mit  dem  SOUNDWORKER  sind  einige
Feldelemente  zustndig, die ich nun erklren werde. Dabei nehme
ich  an,  da  das  erste  Element  den Index 0 hat. Wenn in der
Sprache,  die  Sie verwenden, dieses der Index 1 ist, mssen Sie
zu den folgenden Feldangaben immer eine 1 addieren.


3.3.1. ID [Index 0 bis 8]

   In den   ersten  18  Bytes  befindet  sich  die  Dateikennung
"SOUNDWORKER  V1.1"  (ohne  Gnsefchen),  mit  zwei  Nullbytes
abgeschlossen.



                             - 16 -


                         AUDIOFUN V1.1


3.3.2. Kanal A [Index 9]

   Um den  Kanal  A zu starten, schreiben Sie in dieses Feld die
Nummer  des  gewnschten  Parts. Ist dieser Wert negativ, werden
anstelle der programmierten zufllige Frequenzen gespielt.
   Erlaubt sind  die  Werte  +/-  1  bis  8.  Alle anderen Werte
schalten den Kanal stumm.
   Beim lesen  erhalten  Sie  im  oberen  Byte  die Part- und im
unteren  die  Taktnummer.   Sind  diese  Werte  0, ist der Kanal
inaktiv.

       Kanal B [Index 10]
       Kanal C [Index 11]


3.3.3. Begin/Last A [Index 12]

   Nummer, ab  welchen  Takt  eine Routine gestartet oder bis zu
welchem   Takt   ein   Part   gespielt   werden  soll.  Fr  die
Entscheidung,  welche  der  beiden Mglichkeiten gltig ist, ist
der folgende Eintrag zustndig.
   Dieser Wert   mu  schon  vorhanden  sein,  bevor  der  Kanal
gestartet  wird!  Bei einer 0, die nicht eingetragen werden mu,
wird der Part normal zu Ende gespielt.

       Begin/Last B [Index 13]
       Begin/Last C [Index 14]


3.3.4. Routine A [Index 15 und 16]

   Startadresse der   Routine.   Die   Routine  mu  eine  kurze
Ausfhrungszeit haben, da Sie im Interrupt aufgerufen wird!
   Steht hier  eine  0,die  Sie  nicht  hineinschreiben  mssen,
interpretiert der SOUNDWORKER Begin/Last als Last.
   Es wird  also  der Part bis zum angegebenen Takt gespielt und
keine Routine aufgerufen.
   Bei einem  Wert  ungleich  0 wird dieser als Startadresse der
Routine  gewertet.   Diese  wird bei Erreichen der Taktnummer in
Begin/Last aufgerufen.

       Routine B High-Word [Index 17]
       Routine B  Low-Word [Index 18]
       Routine C High-Word [Index 19]
       Routine C  Low-Word [Index 20]


3.3.5. Joy_Last [Index 21]

   Hier steht  der  Wert  fr den zuletzt bewegten Joystick. 254
bedeutet Joystick 0 und 255 Joystick 1.



                             - 17 -


                         AUDIOFUN V1.1


3.3.6. Joy_0 [Index 22]

   Stellung von  Joystick  0.  Bei  gedrckter Feuertaste um 128
erhht.


3.3.7. Joy_1 [Index 23]

   Stellung von  Joystick  1.  Bei  gedrckter Feuertaste um 128
erhht (nicht bei Joy_Mode 0).


3.3.8. Start/Stop

   Von den   vier   folgenden   Feldelementen   mssen  Sie  die
jeweiligen   Adressen   (also   die   absoluten   Adressen   der
Speicherpltze,  an denen sie sich befinden) ermitteln und diese
an Supexec (XBIOS 38) bergeben.
   Supexec ruft   eine  von  den  vier  Routinen  auf,  die  den
SOUNDWORKER  oder  die Joystickabfrage starten bzw. stoppen. Sie
sollten  diese  Routinen  nur  mit  Supexec  aufrufen, da einige
Registerinhalte   verndert  werden  und  die  Routinen  nur  im
Supervisor-Modus funktionieren!


3.3.8.1. Swk_Start [Index 24]

   Der Timer_A  wird  gestartet  und daduch der SOUNDWORKER alle
20ms   aufgerufen.    Bevor   Sie  also  irgend  etwas  mit  dem
SOUNDWORKER anfangen knnen, mu der TIMER gestartet werden!


3.3.8.2. Swk_Stop [Index 26]

   Der Timer  wird  gestoppt. Dieses mssen Sie vor Programmende
immer machen!


3.3.8.3. Joy_Start [Index 28]

   Die Joystickabfrage  wird  eingeschaltet. Vorher mu Joy_Mode
(kommt gleich) gesetzt werden.


3.3.8.4. Joy_Stop [Index 30]

   Die Joystickabfrage    wird   abgeschaltet.   Ebenfalls   vor
Programmende nicht vergessen!






                             - 18 -


                         AUDIOFUN V1.1


3.3.8.5. Joy_Mode [Index 32] (erst ab SOUNDWORKER V1.1!)

   Bei einer  0 wird nur Joystick 1 abgefragt. Da der Feuerknopf
nun  als  rechte  Maustaste  interpretiert wird, kann er nur mit
der AES-Funktion Graf_Mkstate abgefragt werden!
   Jeder andere  Wert sorgt dafr, da beide Joysticks - diesmal
mit Feuerknpfen - abgefragt werden.















































                             - 19 -

