GSX - Die Graphische System eXtension

Die GSX ist eine graphische Bibliothek, portabel entwickelt für CP/M und CPM 86. Diese Doku — basierend auf www.seasip.info — stellt eine Übersicht der verfügbaren Systemaufrufe dar, Details finden sich im Handbuch von 1983.
Zu dem Thema wurden u.a. zwei Artikel veröffentlicht:
  1. GSX ohne Geheimnisse
  2. Grafik für Joyce
Das übliche GSX-System besteht aus drei Teilen:
  • GSX.SYS / GENGRAF.COM enthalten den Geräte unabhängigen Teil von GSX (das GDOS). Dieser gehört üblicherweise bei der Auslieferung zu GSX nutzenden Programmen dazu;
  • ASSIGN.SYS ist eine Textdatei, die eine Liste der Gerätetreiber des Systems beinhaltet;
  • DD*.PRL sind die aktuellen Gerätetreiber (das GIOS).
JOYCE nahm einen GSX Treiber auf, der CP/M Programmen die Nutzung von 800x600 Grafiken erlaubte.

Der Zugriff auf GSX erfolgt mit einem BDOS Aufruf - Nummer 115. Aufruf mit C=73h (115) und DE=Adresse eines Parameterblocks. Bei Rückkehr sind die durch den Parameterblock angegebene Werte in den Datenfeldern verändert.

Der Parameterblock hat folgende Gestalt: 
        DEFW    CONTRL  ;Adresse des Kontrollfeldes
        DEFW    INTIN   ;Adresse des Eingabefeldes von Ganzzahlen
        DEFW    PTSIN   ;Adresse des Eingabefeldes von Bildpunkten
        DEFW    INTOUT  ;Adresse des Ausgabefeldes von Ganzzahlen
        DEFW    PTSOUT  ;Adresse des Ausgabefeldes von Bildpunkten

Das Kontrollfeld hat folgende Gestalt: 
CONTRL: DEFW    Funktion ;Eingabe: GSX Funktion, 1-33
        DEFW    #ptsin   ;Eingabe: Anzahl von Punkten im Feld PTSIN.
        DEFW    #ptsout  ;Ausgabe: Anzahl von Punkten im Feld PTSOUT.
        DEFW    #intin   ;Eingabe: Anzahl von Ganzzahlen im Feld INTIN.
        DEFW    #intout  ;Ausgabe: Anzahl von Ganzzahlen im Feld INTOUT.
XCTRL:  DEFW    Spezial  ;Eingabe: Für besondere Aufgaben.
Die Koordinaten in PTSIN und PTSOUT sind 16-Bit Ganzzahlen mit Vorzeichen, 0-7FFFh. Der X-Wert kommt als erstes. Gelegentlich erfolgt ein Hinweis auf Geräteeinheiten (device units); dies sind die aktuell vom Bildschirm, Drucker, Plotter usw. genutzten Bildpunkte.

Funktionsübersicht
[1] Arbeitsstation öffnen [2] Arbeitsstation schließen [3] Bild löschen [4] Graphik ausgeben [5] Escape [6] Polyline zeichen [7] Markergruppe eintragen
[8] Text zeichnen [9] Gefülltes Polygon zeichnen [10] Farbindex-Feld ausgeben [11] Allgemeine Zeichengrundfunktion (GDP) [12] Textgröße festlegen [13] Textrichtung festlegen [14] Farbindex festlegen
[15] Linienart festlegen [16] Linienbreite festlegen [17] Linienfarbe festlegen [18] Art des Markers festlegen [19] Höhe des Markers festlegen [20] Markerfarbe festlegen [21] Zeichensatz festlegen
[22] Schriftfarbe festlegen [23] Füllschraffierung festlegen [24] Füllmuster festlegen [25] Füllfarbe festlegen [26] Farbdarstellung abfragen [27] Zellenfeld abfragen [28] Positionsgeber lesen
  [29] Wertgeber lesen [30] Auswahl lesen [31] Zeichenfolge lesen [32] Schreibmodus vorgeben [33] Eingabemodus setzen  

Funktion 1 - Arbeitsstation öffnen

Aufruf mit: 
     Funktion=1;
     #ptsin=0;
     #intin=10;
     INTIN enthält Anfangseinstellung.
Rückgabe: 
     #ptsout=6;
     #intout=45;
     INTOUT enthält Daten des Gerätes.
Ein Gerätetreiber wird geladen und das Gerät voreingestellt. Gültige Nummern für den Gerätetreiber stehen wie folgt in der Datei ASSIGN.SYS: 
 1- 9: Bildschirm
11-19: Plotter
21-29: Drucker
31-39: Metafile.
Das Format des Feldes INTIN ist: 
INTIN:  DEFW    Gerätenummer
        DEFW    Linienart
        DEFW    Linienfarbe
        DEFW    Markertype
        DEFW    Markerfarbe
        DEFW    Schriftart
        DEFW    Schriftfarbe
        DEFW    Füllschraffierung
        DEFW    Füllmuster
        DEFW    Füllfarbe
Das Feld INTOUT gibt zurück: 
INTOUT: DEFW    X-Koordinaten, in Geräteeinheiten
        DEFW    Y-Koordinaten, in Geräteeinheiten
        DEFW    0 bei Drucker, 1 bei Sichtgerät
        DEFW    Pixelbreite in Mikrorometer.
        DEFW    Pixelhöhe in Mikrorometer.
        DEFW    Zahl der Zeichengrößen, 0 für stufenlose Skalierung.
        DEFW    Zahl der Linienarten.
        DEFW    Zahl der Linienbreiten.
        DEFW    Zahl der Markertypen.
        DEFW    Zahl der Markergrößen.
        DEFW    Zahl der Schriftarten.
        DEFW    Zahl der Muster.
        DEFW    Zahl der Schraffurmuster.
        DEFW    Gleichzeitig darstellbare Farben.
        DEFW    Zahl der GDPs ("General Drawing Primitives", allgemeine Zeichengrundfunktionen)
        DEFS    20      ;GDP Nummern.
                        ;-1 => Ende der Liste
                        ; 1 => Balken
                        ; 2 => Kreisbogen
                        ; 3 => Tortenstück
                        ; 4 => Kreis
                        ; 5 => Linierte Zeichen
        DEFS    20      ;GDP Merkmale
                        ;-1 => Ende der Liste
                        ; 0 => Polyline
                        ; 1 => Polymarker
                        ; 2 => Text
                        ; 3 => Gefüllte Fläche
                        ; 4 => Keins
        DEFW    0 für Schwarz/Weiß, 1 für Farbe.
        DEFW    0 wenn keine Drehung des Textes möglich ist, 1 falls ja.
        DEFW    0 wenn keine gefüllte Fläche möglich sind, 1 falls ja.
        DEFW    0 wenn Zelleninhalt nicht gelesen werden kan, 1 falls ja.
        DEFW    Zahl der verfügbaren Farben.
                        ; 0 => Mehr als 32767
                        ; 2 => Schwarzweiß
        DEFW    Anzahl der Positionsgeber (Maus, Tablett, Lichtgriffel)
        DEFW    Anzahl der Wertgeber
        DEFW    Anzahl der Auswahlgeräte
        DEFW    Anzahl der Zeichengeräte
        DEFW    Workstationtyp
                        ; 0 => Nur Ausgabe
                        ; 1 => Nur Eingabe
                        ; 2 => Eingabe und Ausgabe
                        ; 3 => Segmentierte Speicherung
                        ; 4 => GKS Metafile Ausgabe.
Erklärung
Polyline: Ein aus einem oder mehreren Liniensegmenten oder Kreisbögen bestehendes geometrisches Objekt, das trotz seiner verschiedenen Bestandteile von Grafikprogrammen wie ein einziges Objekt behandelt wird.
Polymarker: Statt Ausgabe von Liniensegmenten werden lediglich die Punkte markiert.
Metafile: Eine codierte, sequentielle Datei, die aus einer Folge von festgelegten Einzelinformationen zur Beschreibung einer Zeichnung besteht.
Das Feld PTSOUT gibt zurück: 
        DEFW    Immer 0
        DEFW    ?, Minimale Zeichengröße, in Geräteeinheiten
        DEFW    Immer 0
        DEFW    ?, Maximale Zeichengröße, in Geräteeinheiten
        DEFW    ?, Kleinste Linienbreite, in Geräteeinheiten
        DEFW    Immer 0
        DEFW    ?, Größte Linienbreite, in Geräteeinheiten
        DEFW    Immer 0
        DEFW    Immer 0
        DEFW    ?, Minimale Markerhöhe, in Geräteeinheiten
        DEFW    Immer 0
        DEFW    ?, Maximale Markerhöhe, in Geräteeinheiten.
Funktion 2 - Arbeitsstation schließen

Aufruf mit: 
     Funktion=2;
     #intin=0.
Rückgabe: 
     #intout=0.
GSX erlaubt nur ein geöffnetes Gerät zur Zeit. Wenn die Arbeit an einem Gerät beendet ist, sollte es geschlossen werden.
Funktion 3 - Bild löschen

Aufruf mit: 
     Funktion=3;
     #intin=0.
Rückgabe: 
     #intout=0.
Leert den Puffer, der das aktuelle Bild beinhaltet. Das kann der Bildschirm sein oder gepufferte Daten wie für einen Drucker.
Funktion 4 - Graphik ausgeben

Aufruf mit: 
     Funktion=4;
     #intin=0.
Rückgabe: 
     #intout=0.
Stellt sicher, das alle vorhandene Grafik angezeigt wird. Beim Drucker wird das Bild entsprechend gedruckt.
Funktion 5 - Escape

Aufruf mit: 
     Funktion=5;
     Spezial=Escape-Nummer;
     Weitere Werte, bestimmt durch die Escape-Funktion.
Rückgabe:

Werte variieren.

Die Escape-Funktion sind:
  1. Bildschirmgröße in Zeilen und Spalten erfragen. Die ersten beiden Worte von INTOUT beinhalten jeweils die Höhe und Breite, womit #intout=2 zurückgegeben wird.
  2. Grafikmodus einschalten.
  3. Textmodus einschalten.
  4. Text-Cursor nach oben bewegen.
  5. Text-Cursor nach unten bewegen.
  6. Text-Cursor nach rechts bewegen.
  7. Text-Cursor nach links bewegen.
  8. Bildschirm löschen und Text-Cursor in die linke obere Eecke stellen.
  9. Von der Position des Text-Cursors bis zum Bildschirmende löschen.
  10. Von der Cursor-Position bis zum Zeilenende löschen.
  11. Cursor in Zeile und Spalte absolut positionieren. Setzt den Cursor auf die Koordinaten von INTIN. Der Aufruf muss deshalb erfolgen mit #intin=2.
  12. Text an der Stelle des Text-Cursors ausgeben, dessen Zeichen in INTIN abgelegt sind. Jedes Wort entspricht einem Zeichen. #intin = Länge des Textes.
  13. Inverse Darstellung einschalten.
  14. Inverse Darstellung ausschalten.
  15. Aktuelle Cursor-Position erfragen. Die Rückgabe erfolgt in den ersten beiden Worten von INTOUT.
  16. Zustand des Joysticks oder der Maus erfragen. Gibt im ersten Wort von INTOUT 0 an, wenn das Gerät nicht zur Verfügung steht oder 1 falls ja.
  17. Bildschirm-Hardcopy ausdrucken.
  18. Grafik-Cursor an einer Stelle positionieren. Die Koordinaten liegen in PTSIN, der Aufruf erfolgt mit #ptsin=1.
  19. Grafik-Cursor unsichtbar machen.
Die meisten dieser Funktionen stehen bei den Treibern, die mit dem GEM geliefert werden, nicht zur Verfügung (GEM = Graphics Environment Manager, eine von Digital Research entwickelte Graphische Oberfläche).
Funktion 6 - Polyline zeichen
(Eine Polyline ist eine Linie durch mehere Koordinatenpunkte)

Aufruf mit: 
     Funktion=6;
     #ptsin=Anzahl der Punkte;
     Koordinaten der Punkte in PTSIN.
Rückgabe: Entfällt.
Funktion 7 - Markergruppe eintragen

Aufruf mit: 
     Funktion=7;
     #ptsin=Anzahl der Marker;
     Koordinaten der Marker in PTSIN.
Rückgabe: Entfällt.
Funktion 8 - Text zeichnen

Aufruf mit: 
     Funktion=8;
     #intin=Anzahl der Zeichen;
     #ptsin=1.
     Koordinaten des Textes in PTSIN.
     Text in INTIN.
Rückgabe: Entfällt.
Funktion 9 - Gefülltes Polygon zeichnen.

Aufruf mit: 
     Funktion=9;
     #ptsin=Anzahl der Eckpunkte;
     Koordinaten der Eckpunkte in PTSIN.
Rückgabe: Entfällt.
Funktion 10 - Farbindex-Feld ausgeben.

Aufruf mit: 
     Funktion=10;
     #ptsin=2;
     #intin=Länge des Feldes;
     Feld in INTIN;
     Koordinaten in PTSIN für untere linke und obere rechte Ecken;

XCTRL: DEFW    Länge jeder Reihe
       DEFW    Anzahl der genutzten Elemente used in jeder Reihe
       DEFW    Anzahl der Reihen
       DEFW    Verfahren
Verfahren is:
  1. ersetzen
  2. OR
  3. XOR
  4. löschen

Rückgabe: Entfällt.
Funktion 11 - Allgemeine Zeichengrundfunktion (General Drawing Primitive GDP)

Aufruf mit: 
     Funktion=11;
     Spezial=Grundfunktions-ID
     #ptsin, #intin, PTSIN, INTIN variieren.
General Drawing Primitives stehen u.U. nicht auf allen Systemen zur Verfügung; sie werden normalerweise unterstützt, wenn die Hardware eine dieser Operationen schneller ausführen kann als die allgemeinen GSX-Funktionen. Beispielsweise können viele Rastergrafik-Systeme einen ausgefüllten Balken sehr schnell zeichnen, weil sich das mit der Zeilenausgabe deckt.

ID=1Gefüllter Balken. #ptsin=2; PTSIN gibt die Diagonalen in den gegenüberliegenden Ecken an.
ID=2Kreisbogen. #ptsin=4, #intin=2. INTIN enthält den Anfangs- und Endwinkel in 1/360 Grad; PTSIN beinhaltet die Koordinaten für den Mittel-, Start-, Endpunkt und (Radius,0).
ID=3Tortenstück. Parameter wie für den Kreisbogen.
ID=4Gefüllter Kreis. #ptsin=3; PTSIN hält die Koordinaten des Mittelpunktes, einen Punkt auf dem Kreisumfang und (Radius,0).
ID=5Text zeichnen. #ptsin=1; #intin=Anzahl Zeichen. PTSIN hält die Textkoordinaten; INTIN hält Zeichen als 16-Bit
ID=6-7Reserviert.
ID=8-10Steht dem Implementierer zur Verfügung (wird in GEM benutzt).
Funktion 12 - Textgröße festlegen

Aufruf mit: 
     Funktion=12;
     #ptsin=1
     PTSIN hält (0, Höhe)
Rückgabe: 
     PTSOUT[0]=(Breite,Höhe) eines Zeichens
     PTSOUT[1]=(Breite,Höhe) einer Zelle
Funktion 13 - Textrichtung festlegen

Aufruf mit: 
     Funktion=13;
     #intin=3
     INTIN beinhaltet:
          INTIN[0] = Winkel zum Drehen in 1/10 Graden (gegen den Uhrzeigersinn, 0 = normal)
          INTIN[1] = 100 cos (Winkel)
          INTIN[2] = 100 sin (Winkel)
In der Praxis unterstützen viele Treiber das Drehen nur im rechten Winkel.
Funktion 14 - Farbindex festlegen (Register für Farbpalette)

Aufruf mit: 
     Funktion=14;
     #intin=4;
     INTIN beinhaltet:
          INTIN[0] = Farbnummer
          INTIN[1] = Rot 0-1000
          INTIN[2] = Grün 0-1000
          INTIN[3] = Blau 0-1000
Funktion 15 - Linienart festlegen

Aufruf mit: 
     Funktion=15;
     #intin=1;
     INTIN[0]=Art.
Funktion 16 - Linienbreite festlegen

Aufruf mit: 
     Funktion=16;
     #ptsin=1;
     PTSIN[0]=(Breite,0)
Funktion 17 - Linienfarbe festlegen

Aufruf mit: 
     Funktion=17;
     #intin=1;
     INTIN[0]=Farbe.
Funktion 18 - Art des Markers festlegen

Aufruf mit: 
     Funktion=18;
     #intin=1;
     INTIN[0]=Art.
Funktion 19 - Höhe des Markers festlegen

Aufruf mit: 
     Funktion=19;
     #ptsin=1;
     PTSIN[0]=(0, Höhe)
Funktion 20 - Markerfarbe festlegen

Aufruf mit: 
     Funktion=20;
     #intin=1;
     INTIN[0]=Farbe.
Funktion 21 - Zeichensatz festlegen

Aufruf mit: 
     Funktion=21;
     #intin=1;
     INTIN[0]=Zeichensatz.
Funktion 22 - Schriftfarbe festlegen

Aufruf mit: 
     Funktion=22;
     #intin=1;
     INTIN[0]=Farbe.
Funktion 23 - Füllschraffierung festlegen

Aufruf mit: 
     Funktion=23;
     #intin=1;
     INTIN[0]=Schraffurart.
Füllschraffierung ist 0-3: 0=transparent, 1=ganz, 2=Muster, 3=Schraffur.
Funktion 24 - Füllmuster festlegen

Aufruf mit: 
     Funktion=24;
     #intin=1;
     INTIN[0]=Füllmuster.
Das Füllmuster ist nur gesetzt bei Schraffurart 2 & 3.
Funktion 25 - Füllfarbe festlegen

Aufruf mit: 
     Funktion=25;
     #intin=1;
     INTIN[0]=Farbe.
Funktion 26 - Farbdarstellung abfragen (Farbpalette lesen)

Aufruf mit: 
     Funktion=26;
     #intin=2;
     INTIN[0]=Ausführung;
          INTIN[1]=0 Abfrage der Rückgabewerte.
          INTIN[1]=1 Abfrage der echten Werte.
Rückgabe 
INTOUT[0]=Farbwert, INTOUT[1-3]=RGB Werte 0-1000.
Funktion 27 - Zellenfeld abfragen

Aufruf mit: 
     Funktion=27;
     #ptsin=2;
     #intin=maximale Länge des Farbindexfeldes;
     CONTRL[5]=Länge jeder Reihe;
     CONTRL[6]=Anzahl Reihen.
     PTSIN hält Koordinaten der Ecken links unten und rechts oben des Feldes.
Rückgabe: 
     CONTRL[7]=Anzahl Elemente in jeder Reihe.
     CONTRL[8]=Anzahl genutzter Reihen.
     CONTRL[9]=Fehlermarke (0=OK 1=Fehler).
     Array in INTOUT.
Falls INTOUT[x]=-1 ist, dann konnte das dazugehörige Bildelement nicht ermittelt werden.
Die nächsten wenigen Funktionen können im Abfrage- oder Abtastmodus betrieben werden:
Funktion 28 - Positionsgeber lesen (z.B. Tablett oder Maus)
Im Abfragemodus:

Aufruf mit: 

     Funktion=28;
     #ptsin=1;
     #intin=1;
     INTIN[0]=Nummer des Positionsgebers (normalerweise 1 für Tastatur, 2 für Maus usw.);
     PTSIN ergibt Anfangskoordinaten
Rückgabe: 
     PTSOUT=Koordinaten bei Betätigung von Taste/Schalter;
     INTOUT[0]=Abschluss (Taste betätigt oder Mausschalter +20h); #intout=0 im Fehlerfall.
Im Abtastmodus:

Aufruf mit: 

     Funktion=28;
     #intin=1;
     INTIN[0]=Nummer des Positionsgebers (normalerweise 1 für Tastatur, 2 für Maus usw.);
Rückgabe:

Falls Koordinaten geändert wurden:
#ptsout=1 falls Koordinaten geändert wurden; neue Koordinaten in PTSOUT[0];
Falls Taste oder Schalter betätigt:
#intout=1 falls Taste oder Schalter betätigt; und Taste oder Schalter in INTOUT[0].
Funktion 29 - Wertgeber lesen
Im Abfragemodus:

Aufruf mit: 

     Funktion=29;
     #intin=2;
     INTIN[0]=Nummer des Wertgebers.
     INTIN[1]=Anfangswert.
Rückgabe: 
     INTOUT[0]=Endwert falls Taste/Schalter betätigt;
     INTOUT[1]=Abschluss (Taste betätigt, oder Schalter + 20h); #intout=0 im Fehlerfall.
Im Abtastmodus:

Aufruf mit: 

     Funktion=29;
     #intin=1;
     INTIN[0]=Nummer des Wertgebers.
Rückgabe:

Falls Wert geändert wurde:
#intout=1; neuer Wert in INTOUT[0].
Falls Taste oder Schalter betätigt:
#intout=2 falls Taste oder Schalter betätigt; Endwert in INTOUT[0] und Taste oder Schalter in INTOUT[1].

Der Wertgeber der Tastatur (Nr. 1) bewegt sich in 10er Schritten bei Betätigung der Cursortaste, oder 1 bei Tastenkombination SHIFT+Cursor.
Funktion 30 - Auswahl lesen
Im Abfragemodus:

Aufruf mit: 

     Funktion=30;
     #intin=1;
     INTIN[0]=Auswahlnummer (1=Funktionstaste auf der Tastatur).
Rückgabe #intout=1, INTOUT[0]=Auswahl (1-n).

Im Abtastmodus:

Aufruf mit: 

     Funktion=30;
     #intin=1;
     INTIN[0]=Auswahlnummer (1=Funktionstaste auf der Tastatur).
Rückgabe: 
     #intout=0 ohne Aktivität;
     #intout=1 bei Auswahl (Auswahl in INTOUT[0]);
     #intout=2 falls keine Auswahl Taste (Auswahl in INTOUI[0], Taste in INTOUT[1]).
Funktion 31 - Zeichenfolge lesen
Im Abfragemodus:

Aufruf mit: 

     Funktion=31;
     #ptsin=INTIN[2];
     #intin=3;
     INTIN[0]=Gerätenummer;
     INTIN[1]=maximale Länge;
     INTIN[2]=1 für Wiedergabe, 0 falls nicht.
     Wenn die Wiedergabe gewählt wurde, dann gibt PTSIN[0] die Koordinaten vor, wo die Zeichenfolge wiedergegeben werden soll.
Rückgabe #intout=Rückgabe der Länge der Zeichenfolge, Zeichenfolge in INTOUT.

Im Abtastmodus:

Aufruf mit: 

     Funktion=31;
     #ptsin=0;
     #intin=2;
     INTIN[0]=Gerätenummer;
     INTIN[1]=maximale Länge.
Rückgabe #intout=Rückgabe der Länge der Zeichenfolge, Zeichenfolge in INTOUT.
Funktion 32 - Schreibmodus vorgeben

Aufruf mit: 

     Funktion=32;
     #intin=1;
     INTIN[0]=Modus.
Hinweis:
"Hintergrund" ist die zweite Farbe, benutzt in Strichlinien usw. Wenn eine solche Linie gezeichnet wird, werden die Strichelungen als "Vordergrund"- und die Lücken als "Hintergrund"-Bereiche gezeichnet.

Die Modi sind:
  1. Austausch (Replace). "Vordergrund"- und "Hintergrund"-Bereiche werden getauscht ("Hintergrund"-Bereiche mit GSX Farbe 0).
  2. Transparent. "Vordergrund"-Bereiche werden getauscht aber die "Hintergrund"-Bereiche bleiben gleich.
  3. XOR. "Vordergrund"-Bereiche werden mit der vorigen Farbe mit XOR verknüpft; die "Hintergrund"-Bereiche bleiben gleich.
  4. Löschen (Erase). "Vordergrund"-Bereiche werden in der GSX Farbe 0 geschrieben; die "Hintergrund"-Bereiche bleiben gleich.
Funktion 33 - Eingabemodus setzen

Aufruf mit: 

     Funktion=33;
     #intin=2;
     INTIN[0]=Gerätetyp (1=Positionsgeber, 2=Wertgeber, 3=Auswahl, 4=Zeichenfolge).
     INTIN[1]=Modus (1=Abfrage, 2=Abtastung).
Letzte Änderung: 27.Oktober 2014