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


*** Commands:


&P x,y
	Plot: set/reset/toggle pixel at position x,y
	0<=x<=319
	0<=y<=199

&M x,y
	Move: The unvisible pixel cursor is moved to position x,y
	x,y see plot.

&G 0
&G 1,fg,bg
&G 2,fg,bg
&G 3
&G 4
	Graphic mode: turn on/off graphic mode
	0 turn off (without further parameters)
	1 turn on with forground color fg, background color bg
	2 like 1, but without screen erasing (setups only
          the foreground and background color)
	3 graphic on without erase
	4 only erase graphic
	Color value:
		0<=fg<=15
		0<=bg<=15

&L x0,y0,x1,y1
	Line: draw a line from absolute position 0 to absolute position 1
	x0,y0 and x1,y1 coordinates as described at plot.

&H x,y,xl[,yl]
	Horizontal line or block: draw a horizontal line from position x,y
	with xl pixels to the right (endposition is x+xl).
	With optional yl the thickness of the line is given drawing a 
	rectangular box starting at x,y with width xl to the right
	and height yl downwards (down to y+yl).

&V x,y,yl
	Vertical line: draw a vertical line from position x,y yl pixels
	down. Endposition is y+yl.

&B x,y,xl,yl
	Box: draw a rectangular frame starting at x,y xl to the right and
	yl down. The lower right corner has the coordinates x+xl,y+yl.
	The graphic cursor is set to x,y.

&S m
	Set mode: defines operational mode for all drawing commands
		or setup mode for range error handling.
	m=0 graphic mode: reset pixel (to background color)
	m=1 graphic mode: set pixel (to foreground color)
	m=2 graphic mode: toggle pixel
	m=3 range error handling: abort command
	m=4 range error handling: terminate with illegal quantity error
	m=5 range error handling: back to call (clip value)

&C cx,cy,string

	Character: Write characters on the grafical screen at text mode
	positions. 
	string a string expression
	cx,cy text mode character position (not a pixel position!)
	0<=cx<=39
	0<=cy<=24

&T x,y [TO x,y [TO x,y ...]]
	Line to: draw a line from the pixel cursor position to the
	absolute coordinates x,y
	Multiple coordinates are optional separated by TO.

&R dx,dy [TO dx,dy [TO dx,dy ...]]
	Line to relative: draw a line from the pixel cursor position to
	the position dx,dy relative to the pixel cursor's position.
	Multiple relative coordinates are optional separated by TO.

&F x,y
	Flood fill the area starting at x,y in the current mode.
	This uses the free BASIC storage for a temporary graphic
	stack.
&U
	Unnew: Restore the last BASIC program after a warm start or reset.




*** Functions:


&X
	Get X position: get the current graphic cursor in X direction

&Y
	Get Y position: get the current graphic cursor in Y direction

&Z(x,y)
	Get pixel status: returns value 1 if the pixel is set, 0 otherwise.



**** Usage hints and technical parameters


Important! This extension has to be intialized by doing an initial
	SYS 49152

The bitmap memory range starts at $E000 (57344), taking 8000 bytes -
good to know if some hardcopy program needs access to the bitmap.

If a GRA-EXT command follows a "THEN", you have to insert an extra ":".
Otherwise a syntax error happens.

The color information for the hires screen is located at $CC00 (52224),
taking 1000 bytes.

The extension itself is located in the area from $C000 to $CAA1 (49152
to 51873).


**** Run-time behavior

Many basic extension do exist and a lot of them are carrying dozens of
other commands (well known ones up to over 100 additional commands).
Just for simple graphical usage with these extensions a user is burden
with to much overhead in memory consumption and loading time. It's
frustrating to load 70 blocks every time just to do some simple
graphical programming.

Such disadvantages prevents GRA-EXT. It is short and efficient. You may
chain load this extension without currupting the main program.

Compared to Simon's Basic up to 4-5 times faster, or 2-3 times faster
then the graphical command set provided by nearly any other extension.

The implemention is fast because its well optimized and limited to
the hires mode. All graphic routines use fast algorithms, like the fast
line drawing algorithm based on Bresenham. The main key is that all
operations are done directly in the bitmap without pointwise addressing
of single points (preventing the calculation of bitmap positions from
coordinates all the time).


**** Author

Johann Klasek

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

johann (at) klasek (dot) at