######### gra-ext v1.31  2019-10-31 #########


*** Befehle:


&P x,y
	Plot: setzt/löscht/invertiert Pixel an Position x,y
	0<=x<=319
	0<=y<=199

&M x,y
	Move: Der unsichtbare Pixel-Cursor wird nach Position x,y bewegt.
	x,y siehe Plot.

&G 0
&G 1,fg,bg
&G 2,fg,bg
&G 3
&G 4
	Graphic mode: Grafik ein-/ausschalten
	0 ausschalten (ohne weitere Parameter)
	1 Grafik aktivieren mit Vordergrundfarbe fg, Hintergrundfarbe bg
	2 wie 1, aber ohne Löschen der Bitmap (setzt nur die
          Vordergrund- und Hintergrundfarbe)
	3 einschalten ohne Bildschirm zu löschen
	4 nur den Bildschirm löschen
	Farbwertbereich:
		0<=fg<=15
		0<=bg<=15

&L x0,y0,x1,y1
	Line: zieht Linie von absoluter Position 0 zu absoluter Position 1.
	x0,y0 und x1,y1 sind Koordinaten wie bei Plot beschrieben.

&H x,y,xl[,yl]
	Horizontal line or block: zieht eine horizontale Linie von Position x,y
	xl Pixel nach rechts (Endposition ist x+xl).
	Mit dem optionalen yl, der die "Dicke" der Linie angibt kann ein
	rechteckiger Block beginnend bei x,y mit Breite xl nach rechts
	und Höhe yl nach unten (zu y+yl) erstellt werden.

&V x,y,yl
	Vertical line: zeichnet eine vertikale Linie von Position x,y yl Pixel
	nach unten. Endposition ist y+yl.

&B x,y,xl,yl
	Box: zeichnet einen rechteckigen Rahmen beginnend bei x,y xl nach rechts
        und yl nach unten. Die untere, rechte Ecke hat die Koordinaten x+xl,y+yl.
	Der graphische Cursor wird auf x,y gesetzt.

&S m
	Set mode: Legt den Operationsmodus für alle Zeichenbefehle fest
		oder setzt den Modus für die Fehlerbehandlung bei Koordinatenüberlauf.
	m=0 Grafikmodus: Pixel löschen (auf Hintergrundfarbe setzen)
	m=1 Grafikmodus: Pixel setzen (auf Vordergrundfarbe setzen)
	m=2 Grafikmodus: Pixel invertieren
	m=3 Fehlerbehandlung bei Koordinatenüberlauf: Befehl abbrechen.
	m=4 Fehlerbehandlung bei Koordinatenüberlauf: Programm mit 
	    "illegal quantity error" beenden.
	m=5 Fehlerbehandlung bei Koordinatenüberlauf: Wieder zum Aufrufer zurück 
	    (Wert entsprechend beschränken).

&C cx,cy,string

	Character: Schreibt Textzeichen in die Grafik auf entsprechende Textmodes-
        Positionen.
	
	string Zeichenkettenausdruck
	cx,cy Textmodus Zeichposition (keine Pixel-Position!)
	0<=cx<=39
	0<=cy<=24

&T x,y [TO x,y [TO x,y ...]]
	Line to: zieht eine Linie von der Pixel-Cursor-Position zur
	absoluten Koordinate x,y.
	Mehrere Koordinaten können optional getrennt mit TO angegeben werden.

&R dx,dy [TO dx,dy [TO dx,dy ...]]
	Line to relative: zieht eine Linie der Pixel-Cursor-Position zur
	Position dx,dy relativ zur Pixel-Cursor-Position.
	Mehrere relative Koordinaten können optional getrennt mit TO angegeben 
	werden.

&F x,y
	Fill: Flächenfüllen beginnend bei x,y mit dem aktuellen Modus.
	Dieser Befehl verwendet den freien BASIC-Speicher als
	temporären Grafikstapelspeicher.

&U
	Unnew: Stellt ein noch im Speicher befindliches BASIC-Program nach einem
	Warmstart oder Reset wieder her.




*** Funktionen:


&X
	Get X position: ermittelt die aktuelle Grafik-Cursor-Position in X-Richtung.

&Y
	Get Y position: ermittelt die aktuelle Grafik-Cursor-Position in Y-Richtung.

&Z(x,y)
	Get pixel status: gibt den Pixelstatus an Position x,y zurück:
	Wert 1, wenn der Pixel gesetzt ist, sonst 0.



**** Benutzungshinweise und technische Parameter


Achtung! Diese Erweiterung muss zu Beginn mit folgendem Befehl initialisiert werden:
	SYS 49152

Der Speicher der Bitmap startet bei $E000 (57344) und braucht 8000 Bytes
(für Hardcopy-Programme).

Wenn ein GRA-EXT-Befehl einem "THEN" folgt, dann muss ein extra ":" eingefügt
werden. Andernfalls bricht das Programm mit SYNTAX ERROR ab.

Die Farbinformation für den Hires-Schirm liegt bei $CC00 (52224) und umfasst
1000 Bytes.

Die Erweiterung liegt im Bereich von $C000 bis $CAA1 (49152 bis 51873).


**** Laufzeitverhalten

Es existieren am Markt bereits Unmengen von Grafikerweiterungen, doch schleppen
diese oft einen sehr großen Befehlsvorrat mit sich herum (bis zu 100 Befehle 
und mehr), wobei fÜr eine Grafikanwendung vielleicht nur 10 oder weniger 
Befehle benötigt werden.  Ausserdem ist  es nicht sonderlich angenehm vor 
jedem Start einer Grafikerweiterung diese zu laden, wenn sie einen umfang von 
rund 70 Blöcke aufweist.

Diese Nachteile hat GRA-EXT nicht, denn diese Erweiterung ist ziemlich kompakt,
kann nachgeladen werden, ohne das Hauptprogramm zu zerstören.

Außerdem ist diese Grafikerweiterung sehr schnell (ca. 4-5 mal so schnell wie 
Simon's BASIC, ca. 2-3 mal schneller als die meisten anderen Erweiterungen.
Das liegt zu meinen daran, dass sich die Fähigkeiten auf den Hires-Modus 
beschränken und die Grafikroutinen dahingehend optimiert sind. Außerdem kommen
schnelle Algorithmen, wie etwa das Bresenham-Verfahren zum Zeichnen einer Linie
zum Einsatz. Alle Operationen arbeiten dabei immer direkt in der Bitmap statt 
ständig punktweise mit Koordinaten zu hantieren.


**** Autor

Johann Klasek

http://klasek.at/c64/gra-ext

johann (at) klasek (dot) at