CP/M pages
Home -> CP/M -> GSX

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:

Under CP/M-86, the files are:

GSX went on to become the Virtual Device Interface of the GEM environment. GEM versions 1 and 2 support the GSX API as well as the GEM one.

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.

In CP/M-86, GSX should be invoked with CX=0473h and DS:DX giving the address of the parameter block. If CH has a value other than 4, it will invoke one of the GDOS internal functions.

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).

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 capable of continuous scaling (eg a printer),
		1 if it is not (eg 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.

Not all drivers can support filled polygons; usually, the fallback position is to draw the outline of the polygon.


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 support text rotations of 0, 90, 180 and 270 degrees.


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.

On a two-head system with separate text and graphics screens, the input text may be echoed on the text screen, not the graphics one.

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:

GDOS internal functions

In GSX-86, the function passed in CX to INT 0E0h is interpreted as follows:

CL = 73h
CH low nibble  = function, 0-7
CH high nibble = layer number, 0-14

('Layer' is the index into the internal driver table).

Functions are:

Function=0: KillLayer

Unbind any driver in the specified layer.

Function=1: BindIndirect

Load a driver into the specified layer by ASSIGN.SYS ID (1-9 for screen, 10-19 for plotter, etc.)

Pass DX = ASSIGN.SYS ID. If succeeded returns AL=0. If failed returns AL=0FFh, AH = error number.

Function=2: BindFCB

Load a driver into the specified layer by FCB. DS:DX = FCB address.

Function=3: BindDirect

Map an already-loaded driver into the specified layer. DS:DX = address of entry point.

Function=4: InvokeDriver

The public GSX API, as described above.

Function=5: PassThrough

Call the entry point of the driver in the specified layer with all caller registers as passed to GSX-86. No coordinate scaling will be done on entry or exit.

Function=6: ReturnPtr

Return ES:BX = address within the GDOS of a table describing the specified layer:

00:	DB	HowBound
			0FFh: Driver not loaded
			000h: Driver loaded by BindIndirect
			001h: Driver loaded by BindFCB
			002h: Driver loaded by BindDirect
01:	DD	ProcPtr	
			Far address of driver entry point
05:	DW	BasePageSegment
			Segment of driver's base page [data segment]
07:	DW	ModuleSize
			Number of paragraphs allocated to this driver
09:	DW	ProcId
			ASSIGN.SYS device ID of this driver
0B:	DW	XPixels
			Device resolution, horizontal	
0D:	DW	YPixels
			Device resolution, vertical
0F:	DB	0
			Filler byte
Function=7: ReturnMaxProc

Returns AX = 0Fh (maximum number of layers)

The API design suggests that GSX-86 was designed to be able to cope with multiple concurrently-loaded drivers, using the layer number to distinguish them (ie, calling GSX with CX=0473h, CX=1473h, CX=2473h etc.). In the current GSX-86, only layers 0 and 1 have meaning. Layer 0 is for the current graphics driver, and layer 1 is for character I/O.

GDOS character I/O

GSX-86 device drivers are expected to do keyboard and screen I/O using layer 1 functions. The example in the GDOS source suggests calling INT 0E0h / CX=1573h (PassThrough to layer 1). The GSX 1.1 drivers do it a bit differently, by using INT 0E0h / CX=1673h to get the address of the driver definition, and extracting its entry point (ProcPtr).

The entry point is called with:

BH = function:
	0 = Reset channel
	1 = Get input status, return status in AX
	2 = Wait for input, return input status in AX, input in DX
	3 = Poll input, return input status in AX, input (if any) in DX
	4 = Reserved
	5 = Get output status, return status in AX
	6 = Wait for output ready, then send character in DX. Returns 
	    status in AX.
	7 = If output is ready, send character in DX. Returns status in AX.
	8 = Line input, DS:DX as for BDOS function 0Ah.
BL = channel number:
	0 = CON: (screen / keyboard)
	1 = AUX: (serial)
	2 = LST: (printer)
	3 = CON: (graphics)
	4 = AUX: (sgraphics)
	5 = LST: (graphics)
	6,7 not assigned
DX = data, if appropriate

Status returned in AX:

Bit 0:  On receive: Parity error
Bit 1:  On receive: Overrun error
Bit 2:  On receive: Framing error
Bit 13: On receive: End of file. On send: Channel has hardware queue, data
        queued and being sent.
Bit 14: No connection to channel
Bit 15: Ready

Return to archive listing