The Graphics System eXtension

The GSX is a graphics library, for CP/M and CP/M-86, designed to be portable. This document gives details of the system calls it uses.

A conventional GSX system comes in three parts:

GSX went on to become the Virtual Device Interface of the GEM environment. At least some versions of GEM support the GSX-86-type calls, though ViewMAX does not.

JOYCE incorporates a GSX driver allowing CP/M programs to use 800x600 colour graphics.

GSX is accessed using one BDOS call - number 115. It is entered with C=73h (115) and DE=address of parameter block. On exit, values in the arrays indicated by the parameter block are changed.

The parameter block format is:

	DEFW	CONTRL	;Address of control array
	DEFW	INTIN	;Address of integer input array
	DEFW	PTSIN	;Address of pixel input array
	DEFW	INTOUT	;Address of integer output array
	DEFW	PTSOUT	;Address of pixel output array
(in CP/M-86, these are 4-byte segment/offset addresses). GSX-86 and GEM obey this call if CX=0473h and DS:DX->parameter block.

The control array is:

CONTRL:	DEFW	function ;Input:  GSX function, 1-33
	DEFW	#ptsin   ;Input:  Number of points in PTSIN array.
	DEFW	#ptsout  ;Output: Number of points in PTSOUT array.
	DEFW	#intin   ;Input:  Number of integers in INTIN array.
	DEFW	#intout  ;Output: Number of integers in INTOUT array.
XCTRL:	DEFW	special  ;Input:  For special uses.
The coordinates used in PTSIN and PTSOUT are signed 16-bit integer values, 0-7FFFh. The x value comes first. Occasionally, reference is made to device units; these are the actual pixels used on the screen, printer, plotter etc.

Function 1 - Open workstation

Entered with: Returns:

This loads a device driver and initialises it. Valid device driver numbers are found in the ASSIGN.SYS file, and follow this pattern:

 1- 9: Screen
11-19: Plotter
21-29: Printer
31-39: GKS metafile.
The format of the INTIN array is:
INTIN:	DEFW	device_number
	DEFW	line_style
	DEFW	line_colour
	DEFW	marker_style
	DEFW	marker_colour
	DEFW	text_style
	DEFW	text_colour
	DEFW	fill_style
	DEFW	fill_index
	DEFW	fill_colour
The INTOUT return array gives:
INTOUT:	DEFW	Screen width, device units
	DEFW	Screen height, device units
	DEFW	0 if device is a printer, 1 if it is a CRT
	DEFW	Width of a pixel, in thousandths of a millimetre.
	DEFW	Height of a pixel, in thousandths of a millimetre.
 	DEFW	Number of character sizes, 0 for continuous sizing.
	DEFW	Number of line styles.
	DEFW	Number of line widths.
	DEFW	Number of marker styles.
	DEFW	Number of marker sizes.
	DEFW	Number of fonts.
	DEFW	Number of patterns.
	DEFW	Number of hatch styles.
	DEFW	Number of colours displayable at once.
	DEFW	Number of General Drawing Primitives
	DEFS	20	;General Drawing Primitive numbers.
			;-1 => End of list
			; 1 => Bar
			; 2 => Arc
			; 3 => Pie slice
			; 4 => Circle
			; 5 => Ruling characters
	DEFS	20	;General Drawing Primitive attributes
			;-1 => End of list
			; 0 => Polyline
			; 1 => Polymarker
			; 2 => Text
			; 3 => Filled area
			; 4 => None
	DEFW	0 for black/white, 1 for colour.
	DEFW	0 if text rotation is not possible, 1 if it is.
	DEFW	0 if filled areas are not possible, 1 if they are.
	DEFW	0 if cannot read cell array, 1 if can.
	DEFW	Number of colours in the palette.
			; 0 => More than 32767
			; 2 => Black and white
	DEFW	Number of locator devices (mice, tablets, lightpens)
	DEFW	Number of valuator devices
	DEFW	Number of choice devices
	DEFW	Workstation type
			; 0 => Output only
			; 1 => Input only
			; 2 => Input and output
			; 3 => Segment storage
			; 4 => GKS metafile output.
The PTSOUT return array gives:
	DEFW	?, minimum character height
	DEFW	?, maximum character height
	DEFW	minimum line width,?
	DEFW	maximum line width,?
	DEFW	?, minimum marker height
	DEFW	?, maximum marker height.

Function 2 - Close workstation

Entered with: Returns:

GSX can only use one device at a time. When you have finished with a device, close it.


Function 3 - Clear picture

Entered with: Returns:

Empties the buffer containing the current picture. This may be the screen, or buffered data for something like a printer.


Function 4 - Output graphics

Entered with: Returns:

Ensures that all graphics have been displayed which should be displayed. On a device such as a printer, this will cause the picture to be printed.


Function 5 - Escape

Entered with: Returns: values vary.

The escapes are:

  1. Get text screen size in characters. The first two words of INTOUT will hold the height and the width respectively, and this will therefore return #intout=2.
  2. Enter graphics mode.
  3. Enter text mode.
  4. Text cursor up.
  5. Text cursor down.
  6. Text cursor left.
  7. Text cursor right.
  8. Clear text screen.
  9. Clear from text cursor to end of screen.
  10. Clear from text cursor to end of line.
  11. Move text cursor to coordinates given in INTIN. Therefore this should be entered with #intin=2.
  12. Print (to the text screen) a string whose characters are stored in INTIN (one character to each word). #intin = length of string.
  13. Select reverse video.
  14. Cancel reverse video.
  15. Return the coordinates of the text cursor in the first two words of INTOUT.
  16. Is a tablet (or mouse etc.) available? Returns the first word of INTOUT as 0 if no, 1 if yes.
  17. Dump the current screen to the printer.
  18. Place a graphic cursor (a mouse pointer or similar). Its coordinates are given in PTSIN, so enter with #ptsin=1.
  19. Remove the graphic cursor.
Most of these escapes are not supported by the drivers supplied with GEM.

Function 6 - Draw a polyline

Entered with: Returns: Nothing.

Function 7 - Plot a group of markers

Entered with: Returns: Nothing.

Function 8 - Draw text

Entered with: Returns: Nothing.

Function 9 - Draw a filled polygon.

Entered with: Returns: Nothing.

Function 10 - Output colour index array.

Entered with:
XCTRL: DEFW    length of each row
                DEFW    number of elements used in each row
                DEFW    number of rows
                DEFW    mode
Mode is:
  1. replace
  2. OR
  3. XOR
  4. erase
Returns: Nothing.

Function 11 - General Drawing Primitive

Entered with:

General Drawing Primitives may not be present on all systems; they are normally provided if the hardware can do one of these operations faster than the generic GSX functions. For example, many raster graphic systems can draw a filled bar very quickly since it aligns with the scan lines.

ID=1
Filled bar. #ptsin=2; PTSIN gives diagonally opposite corners.
ID=2
Arc. #ptsin=4, #intin=2. INTIN holds start angle and end angle in 360ths of a degree; PTSIN holds coords of centre, start point, end point and (radius,0).
ID=3
Pie slice. As for arc.
ID=4
Filled circle. #ptsin=3; PTSIN holds coordinates of the centre, a point on the circumference and (radius,0).
ID=5
Draw text. #ptsin=1; #intin=no. chars. PTSIN holds text coordinates; INTIN holds 16-bit characters
ID=6-7
Reserved.
ID=8-10
Available to implementor (used in GEM).

Function 12 - Set text size

Entered with: Returns:

Function 13 - Set text direction

Entered with:

In practice many drivers only like their text at right-angles.


Function 14 - Set colour index (palette registers)

Entered with:

Function 15 - Set line style

Entered with:

Function 16 - Set line width

Entered with:

Function 17 - Set line colour

Entered with:

Function 18 - Set marker type

Entered with:

Function 19 - Set marker height

Entered with:

Function 20 - Set marker colour

Entered with:

Function 21 - Set text font

Entered with:

Function 22 - Set text colour

Entered with:

Function 23 - Set fill style

Entered with: Fill style is 0-3: 0=transparent, 1=solid, 2=Pattern, 3=Hatch.

Function 24 - Set fill index

Entered with:

The fill index is used only with styles 2 & 3.


Function 25 - Set fill colour

Entered with:

Function 26 - Inquire colour representation (read palette)

Entered with:

Returns INTOUT[0]=Colour value, INTOUT[1-3]=RGB values 0-1000.


Function 27 - Inquire cell array

Entered with:

Returns:

If INTOUT[x]=-1, the corresponding pixel could not be read.
The next few functions can be operated in Request mode or Sample mode:

Function 28 - Read locator (eg tablet or mouse)

In Request mode:

Entered with:

Returns:

In Sample mode:

Entered with:

Returns:

If coordinates changed:
#ptsout=1 to indicate coordinates changed; new coordinates in PTSOUT[0];
If key or button pressed:
#intout=1 to indicate key/button pressed; and key or button in INTOUT[0].

If you are developing a GSX driver, note that some programs (including DR DRAW) only check for button presses if there are no new coordinates.


Function 29 - Read valuator

In Request mode:

Entered with: Returns:

In Sample mode:

Entered with:

Returns:

If value changed:
#intout=1; new value in INTOUT[0].
If key or button pressed:
#intout=2 if key or button pressed; final value in INTOUT[0] and key or button in INTOUT[1].

The keyboard valuator (no. 1) moves in steps of 10 using the cursor keys, or 1 using SHIFT+cursor keys.


Function 30 - Read choice

In Request mode:

Entered with:

Returns #intout=1, INTOUT[0]=choice (1-n).

In Sample mode:

Entered with:

Returns:


Function 31 - Read string

In Request mode:

Entered with:

Returns #intout=length of string returned, string in INTOUT.

In Sample mode:

Entered with:

Returns #intout=length of string returned, string in INTOUT.


Function 32 - Set writing mode

Entered with:

Note: "background" is the second colour used in dashed lines etc. When such a line is being drawn, the dashes are drawn as "foreground" areas and the gaps as "background" areas. Modes are:

  1. Replace. "Foreground" and "background" areas are replaced ("background" areas with GSX colour 0).
  2. Transparent. "Foreground" areas are replaced but "background" areas stay the same.
  3. XOR. "Foreground" areas are XOR'ed with previous colour; "background" areas stay the same.
  4. Erase. "Foreground" areas are written in GSX colour 0; "background" areas stay the same.

Function 33 - Set input mode

Entered with:

Activity extensions

The 'Activity' GUI on the Apricot PC range uses GSX video drivers, with the admixture of some extensions. The numbering scheme used by the extra functions seems to match the GEM VDI, but the parameters often differ.


Function 104 - Set Perimeter

Entered with:

Return to archive listing