GFXCTL -- Graphics Control Extension


	1) GFXCTL Usage

	| OBJECT gfx[GFXCTL];

	The GFX extension provides access to a virtual, vector-based
	black and white graphics device which is mapped to the user's
	graphics terminal screen. The virtual graphics device has a
	layout with the origin at the center of the screen and a
	resolution of 32000 x 32000 points. This layout is mapped
	to the physical graphics device by the GFX driver.

	The layout of the virtual GFX device is illustrated in the
	following figure:

	| +---------------------------------------+
	| | \                                   / |
	| |  -16000,-16000          16000,-16000  |
	| |                                       |
	| |                                       |
	| |                  0,0                  |
	| |                   +                   |
	| |                 Origin                |
	| |                                       |
	| |                                       |
	| |  -16000,16000            16000,16000  |
	| | /                                   \ |
	| +---------------------------------------+

	Besides access to the virtual graphics device, the GFX
	extension also provides access to the keyboard and pointing
	device (mouse, trackball, touchpad, etc) of the associated
	physical graphics device.


	2) Methods


	2.1 GFX.BOX(X,Y,DX,DY,MODE)

	| Number X,Y,DX,DY
	| Number MODE

	Draw a solid box with its upper left corner at (X,Y) and its
	lower right corner at (DX,DY). Use the specified MODE for
	drawing the box.


	2.2 GFX.CLEAR(MODE)

	| Number MODE

	Clear the graphics device using the specified MODE.


	2.3 GFX.COPYFONT(A,B)

	| Vector A,B

	Copy the vector font structure which has been loaded during
	initialization into the buffer B. A will be initialized with
	indices into the font buffer so that each A[I] represents the
	font information associated with the I'th character in the
	ASCII alphabet. The information contained in each @B::A[I] for
	I={0,...,127} is suitable for passing it to GFX.PUTV().

	When a null argument is supplied for either A or B, no data
	will be transferred by the procedure, but in either case, the
	number of bytes required to store the font information in B
	will be returned.


	2.4 GFX.FINI()

	Shut down the graphics extension. If a new window has been
	opened by GFX.INIT(), this routine closes it. If the TTY mode
	had to be changed when initializing the graphics routines,
	GFX.FINI() restores it. No meaningful value is returned.


	2.5 GFX.EVENT(E,B)

	| Event E
	| Number B

	Wait for an event to occur or poll the event handler (*4). B is
	the `blocking' flag. If B=0, GFX.EVENT() polls the event
	handler and returns immediately. In this case, the return value
	indicates whether something has happened: 0=no event, -1=an
	event took place. If B\=0, the routine waits until an event
	happens. In this case, of course, it returns always -1. In any
	case, GFX.EVENT() fills the event structure E which has the
	following layout:

	| STRUCT event = e_x, e_y, e_buttons, e_key;

	The members E_X and E_Y which contain the current position of
	the mouse cursor will always be updated, even if no event
	occured. E_BUTTONS holds a bitmask indicating whether buttons
	on the pointing device have been pressed:

	| 1=button#1, 2=button#2, 4=button#3.

	E_KEY holds the ASCII value of the key pressed, if any. B=1
	implies GFX.SYNC().

	When GFX.EVENT() is called with the blocking flag set, the
	following events will cause it to return:

	- Pointer button presses
	- Pointer button releases
	- Key presses
	- Reshape events (window moves or resizes).


	2.6 GFX.FONTSIZE(SC,V)

	| Number SC
	| Vector V[2]

	Examine the number of points a character will
	occupy on the virtual graphics device when using a given scaling
	factor. SC is the desired scale. V is a vector of the length 2.
	The size of a character in the X (V[0]) and Y (V[1]) direction
	will be stored in this vector when the procedure returns. These
	values can be used to position characters on the display
	screen. Subsequently,

	| 32000 / V[0]

	gives the number of columns and

	| 32000 / V[1]

	gives the number of rows available for text output.
	GFX.FONTSIZE() returns nothing.


	2.7 GFX.INIT()

	Initialize the graphics extension. Return nothing. Initializing
	the extension includes the following steps: On systems where
	applications usually create new windows (like X11), a new
	window is created and cleared with the default background color
	(GCLEAR). On systems where applications run in the same window
	as the command shell (like Plan9 and DOS), only the window is
	cleared.

	GFX.INIT() also initializes the pointing device where
	necessary. Finally, GFX.INIT() attempts to load the `system'
	font. It searches the file `system.vf' first in the current
	directory and then in a path which has been configured when the
	graphics package has been compiled. When either the hardware
	graphics device could not be accessed, or no pointing device is
	found, GFX.INIT() prints a message and terminates the calling
	program.


	2.8 GFX.LINE(X,Y,DX,DY,MODE)

	| Number X,Y,DX,DY
	| Number MODE

	Draw a line segment from the origin (X,Y) up to and including
	the position (DX,DY). Draw the line segment using the specified
	MODE.


	2.9 GFX.POINT(X,Y,MODE)

	| Number X,Y
	| Number MODE

	Place a single point at the virtual position specified by the
	coordinates X and Y. Use mode MODE for drawing the point.


	2.10 GFX.PUTC(X,Y,SC,M,C)

	| Number X,Y
	| Number SC,M
	| Number C

	Draw the printable ASCII character C with its lower left edge
	at position (X,Y) in mode M. GFX.PUTC() uses the vector font
	stored in the file `system.vf' to draw the character C. Because
	of their vector structure, the same amount of characters always
	fits in the display window, no matter what size it has.

	SC gives the scaling factor for drawing the vectorized
	characters. It must be >=1. When SC=1, all characters are
	displayed in their original size. When SC=N (N>1), the size of
	the character will be increased by the factor N. Unprintable
	characters will display as blanks. GFX.PUTC() returns nothing.


	2.11 GFX.PUTS(X,Y,SC,M,P)

	| Number X,Y
	| Number SC,M
	| Pstring P

	Draw the packed string P by sending each character to
	GFX.PUTC(). The spacing used to separate the single characters
	in the string is taken from the vector font file. When a string
	extends past the right border or the top of the screen, it will
	be clipped. See also GFX.PUTC().


	2.12 GFX.PUTV(X,Y,SC,M,B)

	| Number X,Y
	| Number SC,M
	| Bytevector B

	GFX.PUTV() is a generalization of GFX.PUTC(). It draws the
	figure which is stored in the byte vector B starting at
	position (X,Y) using the given MODE and scaling factor. The
	format of the figure is as follows: The first byte of B
	contains the number of bytes (N) describing the vector image
	itself. The subsequent N bytes contain the vectors the figure
	consists of. A bit map is used to represent each vector:

	| P D D D L L L L

	where

	| P is the pen position (0=up, 1=down).
	| D is the direction.
	| L is the length of the vector (0...15).

	The direction bits are interpreted as follows:

	|       0
	|   7   |   1
	|     \ | /
	| 6 ---- ---- 2
	|     / | \
	|   5   |   3
	|       4


	2.13 GFX.RESHAPED()

	Return a flag that indicates whether the window the graphics
	device is mapped to has been moved or reshaped since the last
	call to GFX.INIT() or GFX.RESHAPED(). When this procedure
	returns a non- zero value, the content of the window may not
	reflect the actual content of the virtual graphics device and
	therefore should be redrawn. When a size change has occured,
	GFX.RESHAPED() recomputes the scale of the loaded system font
	and the scaling factor used to translate virtual point
	addresses into hardware addresses.


	2.14 GFX.SYNC()

	On systems which cache graphics operations, commit all pending
	requests. Thereby, the contents of the virtual graphics device
	and the hardware screen get synchronized. GFX.SYNC() does not
	return any meaningful value.


	2.15 GFX.WAIT(MS)

	| Number MS

	Sleep (idle) for at least MS milliseconds.


	2.16 Drawing Modes

	The following modes are available for drawing:

	Mode	Description
	GCLEAR	Use the background color.
	GSET	Use the foreground color.
	GOR	OR the foreground color with each background pixel.
	.	Since the graphics extension is a monochrome system,
	.	this is the same as GSET.
	GXOR	XOR the foreground color with each background pixel.
	.	(Revert the color of each pixel touched by the drawn
	.	figure).

	NOTE: Using this mode when drawing vector figures will lead to
	strange results, because the connections of each two line
	segments will be drawn twice.


	2.17 Vector Fonts

	The vector font format is described in the default font source
	file 'sys6x12.vfd'.

	The default font may be changed by placing a vector font file
	called `system.vf' in the directory the graphics application is
	started from. See also GFX.INIT().