* **********************************************************************
* **                                                                  **
* **   DOKUMENTATION ZUR MODULSCHNITTSTELLE VON ESCAPE PAINT V.0.5.   **
* **      (diesmal in Deutsch; keine Lust zu Englisch heute...)       **
* **                                                                  **
* **********************************************************************
*
* Escape Paint stellt eine einfache, kleine Modulschnittstelle zur Ver-
* fgung. Diese hat den Sinn, dass jeder (Assembler-) Programmierer sich
* eigene Werkzeuge oder Filter...oder was weis ich was...selber schreib-
* en kann und diese Routinen von EP (Escape Paint) aus benutzen kann.
*
*   ALLGEMEINER AUFBAU
*   
* Ein EPM (Escape Paint Module) besteht aus zwei Teilen: Einem Script-
* file, welches einige wichtige Informationen zum Modul enthlt und einem
* Objektfile, welches die eigentliche Routine enthlt. Das Scriptfile
* wird dann spter von EP aus angewhlt. Es stellt also fr den Endver-
* braucher die einzig wichtige Datei dar.
*
*   DAS SCRIPTFILE
*   
* Ein EPM-Scriptfile wird mit einem normalen ASCII Editor, wie Qed z.B.
* erstellt. In der Datei wird der Name des Modules, der Name des Autors,
* die Version des Modules, das Entstehungsdatum, der Modultyp und der
* Pfad des Objektfiles festgelegt. Dies geschieht immer ber einen 
* Grobuchstaben am Anfang einer Zeile, gefolgt von einem '='. Alle
* brigen Zeichen knnen als Kommentare verwendet werden. Es ist jedoch
* sinnvoll nur Sonderzeichen und nicht Buchstaben als Kommentare zu
* benutzen. (eventuell sptere Erweiterungen der Schnittstelle)
* Das Scriptfile kann so auch fr eine Kurzbeschreibung des Modules
* genutzt werden. Am einfachsten ist es, die Scriptdatei (*.EPM)
* des Beispielmodules zu verwenden und nur die Werte auszutauschen.
* Ein Beispiel fr ein Scriptfile knnte so aussehen:
*
* ############################
* # SCRIPTFILE FUER EP-MODUL #
* ############################
* 
* # MODUL(N)AME
* N=Testmodul
*
* # MODUL(V)ERSION
* V=1.00
*
* # ENTSTEHUNGS(D)ATUM
* D=11.11.99
*
* # (A)UTOR
* A=Hans Meier
*
* # MODUL(T)YP:
* # TYP 1: START DES MODULES OHNE WECHSEL IN DEN ARBEITSBILDSCHIRM
* # TYP 2: AKTIVIERUNG NACH DEM WECHSEL IN DEN ARBEITSBILDCHIRM
* # TYP 3: ERST NACH MAUSTASTENDRUCK IM ARBEITSBILDSCHIRM STARTEN
* # TYP 4: ES WIRD VOR DEM START EINE RUBBERBOX AUFGEZOGEN
* T=1
*
* # OBJEKT(P)FAD/NAME
* P=TEST.O
*
* ############################
*
*
*   DAS OBJEKTFILE
*   
* Die Modulschnittstelle untersttzt zunchst einmal die Objekt-
* files, die bei der Assemblierung mit "PASM" (Pure Assembler von
* Application Systems Heidelberg) erzeugt werden. Diese bestehen
* standartmig aus einem Header, der jedoch von EP nicht ausge-
* wertet wird.
* Die Routine wird mittels 'JSR 32(a1)' angesprungen, wobei der
* Offset 32 den "Header"-offset darstellt. Es ist mglich SmallDRI
* Objektfiles zu benutzen indem man einfach am Anfang der Routine
* 32 Bytes Speicher reserviert. ('DS.B 32')
* Generell wird in A0.l eine Adresse auf eine Struktur bergeben.
* Die Struktur enthlt alle wichtigen Stati und Routinenadressen,
* die vom Modul aus genutzt werden knnen. Eine Beschreibung der
* Struktur erfolgt spter.
*
*   GRUNDLEGENDES
*   
* EP arbeitet niemals im Bild direkt, sondern in einem extra Bild-
* speicher ('Screen'). Am Anfang (nach dem Wechsel vom Men ins Bild)
* wird der Bildinhalt in den 'Screen' kopiert und im Folgendem nur
* der Screeninhalt verndert. Vor der Anwendung einer Zeichenfunktion
* wird der 'Screen'inhalt in das Bild zurckkopiert. Die 'UNDO' Funktion
* kommt dann einem Kopieren des Bildes in den 'Screen' gleich. Mit
* diesem Verfahren ist es mglich, die letzte Zeichenaktionen rck-
* gngig zu machen. Es ist am besten, auch die Module auf diese Weise
* arbeiten zu lassen. (also niemals direkt im Bild, sondern im 'Screen'
* - der Arbeitsflche)
*
*   MODULTYPEN
*   
* Es sind fr verschiedene Anwendungen verschiedene Modultypen vorge-
* sehen, die jeweils fr ein Anwendungsgebiet besonders geeignet sind.
* Module werden generell (ab EP Version 0.5.) im Supervisormode aufge-
* rufen.
* Der Modultyp 1 wird direkt nach dem Druck auf den Modulbutton ge-
* startet. Dabei wird weder die Auflsung, noch die Bildschirmspeicher-
* adresse verndert. Der Modultyp ist demnach nicht fr Zeichenfunk-
* tionen geeignet. Die Anwendung liegt im Schreiben kleiner Tools in
* Verbindung mit dem Men. (Modplayer, Statusanzeigen oder sowas)
* Eventuell wird der Modtyp1 in spteren Programmversionen auch als
* Datei Im/Export Modul arbeiten knnen.
* Die Anwendung des zweiten Modultypes liegt in der Programmierung
* "eines Programmes im Programm", also Spriteeditoren, neue Zoomscreens,
* Spiele oder hnlich komplexe Sachen. Vor dem Aufruf des Modules wird
* in die Auflsung 320x240 in 16Bit Farbtiefe geschaltet. Die Bild-
* schirmadresse wird auf den 'Screen' (s.o.) gesetzt. Man hat also
* nicht das Bild vor sich, sondern kann seinen eigenen Arbeitsbild-
* schirm gestalten.
* Zur einfachen und schnellen Realisierung von neuen Zeichenwerkzeugen
* wird Modultyp 3 zur Verfgung gestellt. Hierbei finden vor dem eigent-
* lichen Aufruf der Routine einige komplexere Aktionen statt. Zunchst
* wird wie bei Modtyp 2 in den 'Screen' gewechselt. Anschlieend wird
* das aktuelle Bild in den 'Screen' kopiert. Nach dem Anschalten des
* Mauscursors wird solange gewartet, bis die linke Maustaste gedrckt
* wird. In diesem Falle wird der Mauscursor abgeschaltet und der 'Screen'
* in den aktuellen Bildspeicher kopiert. Danach wird die Routine
* aufgerufen. Nach dem Beenden der Routine wird die Maus wieder ange-
* schaltet und die Routine kann von neuem gestartet werden.
* Zur schnelleren Programmierung von Modulen wird die aktuelle Mauspos-
* ition in D0.l (x) und D1.l (y) bergeben. 
* Fr Filtermodule ist es praktisch, einen Wirkungsbereich whlen zu
* knnen. Diese Funktion bietet Modtyp 4. Der Ablauf ist im Grunde der
* gleiche, wie bei Modtyp 3. Hier wird lediglich gewartet bis der Be-
* nutzer mittels einer Rubberbox einen Bildbereich gewhlt hat. Die
* Eckpunktkoordinaten der Rubberbox werden dann dem Modul in den Re-
* gistern D0.l (x1), D1.l (y1), D2.l (x2) und D3.l (y2) bergeben. Dabei
* kann der Modulprogrammierer davon ausgehen, dass x1<=x2 und y1<=y2
* ist. Das eventuelle Tauschen der Koordinaten bernimmt EP.
*
*   DIE PROGRAMMSTRUKTUR
*   
* In A0.l wird ein Zeiger auf eine Struktur geliefert, die fr die
* Programmierung sinnvoller Module ntig ist. Der Zugriff auf die
* Strukturelemente erfolgt mittels Offsets (Bsp.: 'movea.l 52(A0), A1').
* Die Arbeit mit Zeigern auf Variablen hat gegenber der bergabe
* von konkreten Werten, den groen Vorteil, da die ensprechenden
* Werte global (im ganzen Programm) vom Modul aus verndert werden
* knnen. 
* 
*   Offset  |  Funktion
* |
*    0      |  'Screen'-Adresse
*    4      |  Zeiger auf eine Tabelle der X-Bildauflsungen
*           |  Alle Tabelleneintrge sind Longwords.
*           |  Werte knnen nicht verndert werden
*    8      |  Zeiger auf eine Tabelle der Y-Bildauflsungen
*           |  Werte knnen nicht verndert werden
*   12      |  Zeiger auf die aktuelle Bildnummer (Long)
*           |  Wert sollte nicht verndert werden
*   16      |  Zeiger auf eine Tabelle der Bildadressen. 
*   20      |  Zeiger auf eine Speicherbereich, der vom Modul be-
*           |  nutzt werden kann. (ca.300000 Bytes)
*   24      |  Zeiger auf die Palettendaten (Die Paletten stehen hinter-
*           |  einander im Speicher. Jede Palette ist 256 Words lang)
*   28      |  Adresse einer Speicherkopierroutine
*           |   -BERGABE:  D0.l: Anzahl der zu kopierenden Longwords
*           |               A0.l: Quelladresse
*           |               A1.l: Zieladresse
*           |   -ZERSTRT:  D0,A0,A1
*   32      |  Adresse einer Speicherlschroutine
*           |   -BERGABE:  D0.l: Anzahl der zu lschenden Longwords
*           |               A0.l: Zieladresse
*           |   -ZERSTRT:  D0,A0
*   36      |  Adresse einer Speichertauschroutine
*           |   -BERGABE:  D0.l: Anzahl der zu vertauschenden Longwords
*           |               A0.l: Adresse eines Speicherbereiches
*           |               A1.l: Adresse eines anderen Speicherbereiches
*           |   -ZERSTRT:  D0,D1,A0,A1
*   40      |  Adresse einer Pixelzeichenroutine
*           |   -BERGABE:  D0.l: x
*           |               D1.l: y
*           |               D2.l: x-Auflsung
*           |            4(sp).l: Farbe
*           |   -ZERSTRT:  D1,D3
*   44      |  Adresse einer Routine zum Ermitteln einer Pixelfarbe
*           |   -BERGABE:  D0.l: x
*           |               D1.l: y
*           |               D2.l: horiz. Auflsung
*           |               A0.l: Bildschirmadresse
*           |   -RCKGABE:  D0.l: Pixelfarbe
*           |   -ZERSTRT:  D1
*   48      |  Adresse einer Linienroutine (nur 320 Pixel horiz.Aufl.)
*           |   -BERGABE:  D0.l: x1
*           |               D1.l: y1
*           |               D2.l: x2
*           |            4(sp).l: y2
*           |            8(sp).l: Farbe (-1 -> negativ)
*           |               A0.l: Bildschirmadresse
*           |   -ZERSTRT:  D0-D7,A0-A5
*   52      |  Adresse einer Routine zum Zeichnen einer Rubberbox
*           |  fr eine horiz.Auflsung von 320 Pixeln
*           |   -BERGABE:  D0.l: x1
*           |               D1.l: y1
*           |               D2.l: x2
*           |            4(sp).l: y2
*           |               A0.l: Bildschirmadresse
*   56      |  Adresse einer Kreisroutine (nur 320 Pixel horiz.Aufl.)
*           |   -BERGABE:  D0.l: Mittelpunkt x
*           |               D1.l: Mittelpunkt y
*           |               D2.l: Radius
*           |            4(sp).l: Farbe
*           |            8(sp).l: Zeichenmodus (0...normal,
*           |                                   1...negativ,
*           |                                   2...transparent 50%,
*           |                                   3...bitweises And,
*           |                                   4...bitweises Or,
*           |                                   5...Farbaddition,
*           |                                   6...Farbsubtraktion)
*           |               A0.l: Bildschirmadresse
*           |   -ZERSTRT:  D0-D6,A0-A1
*   60      |  Adresse einer Floodfillroutine fr eine Auflsung von
*           |  320 Pixeln. Zum Zeichnen wird der eingestellte Zeichen-
*           |  modus benutzt.
*           |   -BERGABE:  D0.l: x-Startkoordinate
*           |               D1.l: y-Startkoordinate
*           |               D2.l: Farbe
*           |               A0.l: Bildschirmadresse
*           |   -ZERSTRT:  D0-D7,A0-A5
*   64      |  Adresse einer Routine zum Zeichnen eines gefllten
*           |  Rechteckes bei horizontaler Auflsung von 320 Pixeln
*           |   -BERGABE:  D0.l: Farbe (akt.Zeichenmodus)
*           |               D1.l: x1
*           |               D2.l: y1
*           |            4(sp).l: x2
*           |            8(sp).l: y2
*           |               A0.l: Bildschirmadresse
*           |   -ZERSTRT:  D1-D7,A0
*   68      |  Adresse einer Block-Ausschneideroutine fr horiz.
*           |  Auflsung von 320 Pixeln
*           |  Block: 1 Word Breite, 1 Word Hhe, Pixeldaten
*           |   -BERGABE:  D0.l: x1
*           |               D1.l: y1
*           |               D2.l: x2
*           |            4(sp).l: y2
*           |               A0.l: Quellbild
*           |               A1.l: Blockbuffer
*           |   -ZERSTRT:  D0-D5,A0-A1
*   72      |  Adresse einer Block-Einfgeroutine
*           |  (verwendet aktuellen Block-Einfgemodus)
*           |   -BERGABE:  D0.l: x-Zielkoordinate (l.o.Ecke)
*           |               D1.l: y-Zielkoordinate (l.o.Ecke)
*           |               A0.l: Blockbuffer
*           |               A1.l: Zielbild (320 Pix.hor.Auflsung)
*   76      |  Adresse einer Routine zum Ermitteln der Blockbreite
*           |   -BERGABE:  A0.l: Blockbuffer
*           |   -RCKGABE:  D0.l: Blockbreite
*   80      |  Adresse einer Routine zum Ermitteln der Blockhhe
*           |   -BERGABE:  A0.l: Blockbuffer
*           |   -RCKGABE:  D0.l: Blockhhe
*   84      |  Adresse einer Routine zum Herstellen des Blockhinter-
*           |  grundes. (nur 320 Pixel hor.Auflsung)
*           |   -BERGABE:  D0.l: x-Position der l.o.Ecke
*           |               D1.l: y-Position der l.o.Ecke
*           |               A0.l: Blockbuffer
*           |               A1.l: Bildschirmadresse
*           |            4(sp).l: Bildadresse (Hintergrund)
*           |   -ZERSTRT:  D0-D6,A0-A2
*   88      |  Zeiger auf Blockflag (1..EP: Block vorhanden) (long)
*   92      |  Adresse einer Routine zum zeichnen eines Fadenkreuzes
*           |  bei horiz.Auflsung von 320 Pixeln
*           |   -BERGABE:  D0.l: x
*           |               D1.l: y
*           |               A0.l: Bildschirmadresse
*           |   -ZERSTRT:  D0-D2,A0-A1
*   96      |  Adresse der Mauscursor Anschaltroutine
*           |   -ZERSTRT:  D0-D7,A0-A6
*  100      |  Adresse der Mauscursor Abschaltroutine
*           |   -ZERSTRT:  D0-D7,A0-A6
*  104      |  Adresse einer Routine zum Setzen der Mausposition
*           |   -BERGABE:  D0.l: neue x-Position der Maus
*           |               D1.l: neue y-Position der Maus
*           |   -ZERSTRT:  D0-D7,A0-A6
*  108      |  Adresse einer Routine zum Setzen eines neuen Maus-
*           |  cursors (16x16 Pixel, 16Bit Pixel)
*           |   -BERGABE:  A0.l: Adresse des neuen Mauscursors
*           |   -ZERSTRT:  D0,A0,A1
*  112      |  Adresse einer x-Mausposition Abfrageroutine
*           |   -RCKGABE:  D0.l: x-Mausposition
*           |   -ZERSTRT:  D1
*  116      |  Adresse einer y-Mausposition Abfrageroutine
*           |   -RCKGABE:  D0.l: y-Mausposition
*           |   -ZERSTRT:  D1
*  120      |  Adresse einer Routine zum Abfragen der Mausbuttons
*           |   -RCKGABE:  Mausstatus (Bit1: linke Maustaste
*           |                           Bit2: rechte Maustaste)
*  124      |  Adresse der Ice-Entpackroutine
*           |   -BERGABE:  A0.l: Adresse der gepackten Daten
*           |   -ZERSTRT:  ne ganze Menge
*  128      |  Zeiger auf aktuelle Zeichenfarbe (long)
*  132      |  Zeiger auf aktuelle Werkzeugnummer (long)
*           |  Wert sollte nicht verndert werden
*  136      |  Zeiger auf aktuellen Zeichenmodus
*           |  Wert sollte nicht verndert werden
*  140      |  Zeiger auf aktuellen Monitortyp (->XBIOS)
*  144      |  Zeiger auf aktuellen Palettenindex
* 
*
* Man kann ja einfach mal einen Blick in die Sourcen des Beispiels
* riskieren. (Dank an Andreas John!)
*
*   DAS WARS SCHON
*   
* Das sind soweit die wichtigsten Informationen zur Programmierung
* eigener EP-Module. Wenn noch Fragen auftauchen knnt Ihr mich ja
* noch kontaktieren. (Abba nich wegen jedem Mll, Bitte!)
*
* Viel Spa beim programmieren. Wenn irgendwas vernnftiges oder un-
* vernnftiges Zustande kommt, wre es schn wenn ich das auch in
* die Finger kriege. (event. Release mit EP zusammen ? Hm?)
*
* Schreibt mal:              Norman Feske
*                        Cmmerswalder Str.19
*                           01189 Dresden
*                               Germany
*
* oder Emailt mal...:    norman@iee.et.tu-dresden.de
*            ...oder:    htw824@rob.rz.htw-dresden.de
*
*
*
*                                                     (NO/Escape) 07'96
*