home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / may94 / mus / play / delitracker.lha / DeliTracker / Files / developer.lha / Developer / Developer.dok < prev    next >
Text File  |  1994-04-17  |  36KB  |  829 lines
  1.  
  2.  
  3.                  $VER: Developer.dok V2.00 (13.04.1994)
  4.                    Copyright 1994 by Delirium Softdesign
  5.                       (Peter Kunath and Frank Riffel)
  6.  
  7.                   DeliTracker Development Documentation
  8.  
  9.  
  10.   1.ÜBERBLICK
  11.  
  12.   2.PLAYER
  13.    2.1 Normale Player
  14.    2.2 Custom Module
  15.    2.3 Interrupts
  16.  
  17.   3.GENIES
  18.    3.1 Generic Kind
  19.    3.2 Converter
  20.    3.3 Decruncher
  21.    3.4 NotePlayer
  22.  
  23.   4.TAGS
  24.  
  25.   5.DELITRACKER SUPPORT FUNKTIONEN
  26.  
  27.  
  28.   1.ÜBERBLICK
  29.  
  30.   DeliTracker kann mit externen Programmodulen erweitert werden. Diese
  31.   sehen vom DOS aus betrachtet genauso aus wie normale Objectfiles, mit
  32.   dem Unterschied allerdings, daß sie am Anfang des ersten Hunks eine
  33.   spezielle Struktur besitzen. Wenn DeliTracker ein solches Programmodul
  34.   nachlädt, wertet er diese Struktur aus. Sie besteht aus drei Teilen:
  35.   Einem Longword mit Code, zwei Longwords als Identifier und als letztes
  36.   einem Pointer auf ein Tagarray. Das erste Longword enthält normalerweise
  37.   moveq #-1,d0 gefolgt von einem rts Befehl. Dies soll einen Absturz
  38.   verhindern, wenn ein Player oder Genie irrtümlich vom Benutzer gestartet
  39.   wird. Um ein Programm zu erzeugen, das auch ohne DeliTracker lauffähig
  40.   ist, muß in das erste Longword in einen bra.w geändert werden, der dann
  41.   den eigentlichen Startupcode anspringt. Um die charakteristische Struktur
  42.   zu erzeugen sollte das PLAYERHEADER Macro aus 'deliplayer.i' verwendet
  43.   werden. Es hat zwei Parameter: einen Pointer auf ein Tagarray und
  44.   optional einen Pointer auf den Startupcode.
  45.  
  46.     PLAYERHEADER <tagarray>,[startup]
  47.  
  48.         tagarray        Pointer auf ein Tag Array, das mit TAG_DONE
  49.                         abgeschlossen sein muß.
  50.         startup         Pointer auf einen optionalen Startupcode. Nur
  51.                         notwendig, wenn das Programmodul auch ohne
  52.                         DeliTracker lauffähig sein soll.
  53.                         Bemerkung: Wenn der Startupcode angesprungen
  54.                         wird, muß die gesamte Initialisierung etc. ohne
  55.                         DeliTracker durchgeführt werden. In den meisten
  56.                         Fällen macht die Startup Option wenig Sinn und
  57.                         wird deshalb auch kaum benutzt.
  58.  
  59.   Die Tagliste enthält dabei alle Informationen, die DeliTracker wissen
  60.   muß. Wir verwenden ein Tagarray deshalb, weil es sehr flexibel und leicht
  61.   erweiterbar ist. Zusätzlich können die externen Programmodule noch die
  62.   GlobalStructure sowie die eingebauten Supportfunktionen benutzen. Im
  63.   Moment unterscheidet DeliTracker zwei verschiedene Typen von externen
  64.   Programmodulen:
  65.  
  66.         1) Player, um Module zu identifizieren und zu spielen
  67.  
  68.         2) Genies können viele andere Dinge machen. Unter anderem Module
  69.            konvertieren, Dateien entpacken oder Informationen anzeigen.
  70.  
  71.   Beide Arten können synchron oder asynchron laufen. Unter synchron
  72.   versteht man, daß der Player oder das Genie nicht als eigener Prozess
  73.   läuft. DeliTracker benutzt in diesem Fall echte Funktionsaufrufe (jsr)
  74.   zur Kommunikation. Im asynchronen Modus startet DeliTracker den Player
  75.   oder das Genie als eigenen Prozess und verwendet dann Messages um
  76.   Funktionen der externen Programmodule aufzurufen. Im allgemeinen laufen
  77.   Genies asynchron und Player synchron. Wenn ein Player oder ein Genie
  78.   asynchron läuft, dann muss man es durch Senden eines CTRL-C Signals an
  79.   den Prozeß beenden können. Offensichtlich sind DeliPlayer und DeliGenies
  80.   also sehr ähnlich. Sie werden von DeliTracker auch ziemlich gleich
  81.   verwaltet, wenn auch in zwei verschiedenen Listen. Jedes externe
  82.   Programmodul bei dem ein DTP_CustomPlayer, DTP_Check1 oder DTP_Check2
  83.   Tag benutzt wird, ist ein Player. Der Rest sind Genies.
  84.  
  85.   Wenn eine GUI vorhanden ist, sollten normalerweise folgende Menüpunkte
  86.   zur Verfügung stehen:
  87.  
  88.         Project
  89.                 About      A ?  Kurzinformation über das Programmodul
  90.                 ==============
  91.                 Save Prefs A S  Speichern der aktuellen Einstellungen
  92.                 ==============
  93.                 Hide       A H  GUI verbergen
  94.                 ==============
  95.                 Quit       A Q  Genie beenden (ebenso wie CTRL-C)
  96.  
  97.         Settings
  98.                 Activate   A A  Aktiviert das Fenster beim Öffnen des GUI
  99.                 Popup      A P  Öffnet das GUI nach dem Laden
  100.                 ==============
  101.                 Other settings  Hier können je nach Bedarf weitere
  102.                 ··············  Einstellungen folgen.
  103.  
  104.   Ein paar Anmerkungen:
  105.  
  106.   Bevor man einen DeliPlayer schreibt, sollte man sich die migelieferten
  107.   Beispielsourcen genau durchlesen. Um einen besseren Überblick davon zu
  108.   bekommen, wann und in welcher Reihenfolge DeliTracker die Funktionen des
  109.   Players aufruft, kann man den 'Testplayer.s' Source benutzen. Wenn eine
  110.   Konfigurationsdatei abgespeichert werden kann, sollte sie nicht nach
  111.   ENV:, sondern in das DeliTracker Konfiguartionsverzeichnis abgespeichert
  112.   werden. Der Pfad des Konfiguartionsverzeichnisses kann steht in der ENV-
  113.   Vaiable 'DeliConfig'. Falls diese nicht vorhanden ist, sollte stattdessen
  114.   'PROGDIR:DeliConfig' zum Abspeichern benutzt werden. Ein Player sollte
  115.   außerdem den Zustand der LED (Lowpass-Filter) unbeeinflußt lassen, da im
  116.   Optionfenster eine entsprechende Funktion existiert. Wenn von DeliTracker
  117.   eine Funktion des Players aufgerufen wird (außer bei den Interrupt-
  118.   Funktionen DTP_Interrupt und DTP_NoteSignal), enthält das Register a5
  119.   einen Pointer auf die Globale Struktur (Base). Da DeliTracker vor Aufruf
  120.   einer Routine (außer bei DTP_Interrupt und DTP_NoteSignal) alle Register
  121.   sichert, dürfen diese verändert werden.
  122.  
  123.  
  124.   2.PLAYERS
  125.  
  126.   Es ist relativ einfach, eine Replayroutine an DeliTracker anzupassen.
  127.   Alles was Sie tun müssen ist ein wenig Interfacecode zu schreiben. Dies
  128.   ist im allgemeinen recht einfach, denn DeliTracker stellt ihnen viele
  129.   hilfreiche Routinen zur Verfügung. Um ein neues Soundsystem anzupassen,
  130.   benötigen Sie zum einen den Quellcode oder ein linkbares Objektfile der
  131.   Replayroutine, zum anderen sollten mindestens ca. 5 Module zum Testen der
  132.   Funktionstüchtigkeit des Players vorhanden sein. Ganz am Anfang eines
  133.   Players muß sie charakteristische Struktur stehen. DeliTracker unter-
  134.   scheidet dann zwei Arten von Playern: normale Player und Custom Module.
  135.  
  136.     2.1 Normale Player
  137.  
  138.     Normale Player identifizieren und spielen Module. Sie müssen immer eine
  139.     Check Routine besitzen. Der schematische Aufbau eines normalen Players
  140.     ist folgendermassen:
  141.  
  142.         { Playerheader  }       Kennzeichnet das Object als Player.
  143.         { TagArray      }       Beschreibung, was der Player kann.
  144.         { Interfacecode }       Playername/Registerumsetzung/Checkcode u.ä.
  145.         { Replaycode    }       Eigentlicher Musikabspielcode.
  146.         { evtl. Daten   }       und Daten
  147.  
  148.     Damit der Player die einzelnen Module unterscheiden kann, befindet sich
  149.     in jedem Player eine Erkennungsroutine, die auf ein zugehöriges Modul
  150.     testet und DeliTracker mitteilt, ob der Player dieses Modul spielen
  151.     kann oder nicht. Diese Routine prüft auf Stellen im Modul, die bei allen
  152.     Modulen eines Formats gleich sind. So z.B. auf 'M.K.' bei Offset $438
  153.     in ProTracker-Modulen. Nur auf einige wenige Sprungbefehle zu Prüfen
  154.     reicht im allgemeinen nicht aus, da viele Modulformate mit eingebauter
  155.     Abspielroutine Sprungbefehle am Anfang haben und der Player möglicher-
  156.     weise das falsche Modul erkennen könnte, was in den meisten Fällen zum
  157.     Absturz führt! Deshalb sollte die Check Routine auch eingehend getestet
  158.     werden. Es gibt zwei Typen von Check Funktionen, genau eine davon muß
  159.     der Player verwenden.
  160.  
  161.     a) DTP_Check1: Diese Check Funktion wird aufgerufen, wenn DeliTracker
  162.     1K des Files geladen hat. Der Vorteil ist daß sich auch Player
  163.     realisieren lassen, die das Modul selbst nachladen. Der Nachteil ist,
  164.     daß der Player dann nicht von den Entpackroutinen in DeliTracker
  165.     profitiert. Meistens ist es deshalb schwerer, einen solchen Player zu
  166.     schreiben. Man sollte diesen Typ nur für Härtefälle verwenden, z.B.
  167.     wenn das Modul vom Player selbst geladen werden muß.
  168.  
  169.