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:

• GSX.SYS / GENGRAF.COM contain the device-independent portion of GSX (the GDOS). This is normally added to GSX-aware programs when they are distributed;
• ASSIGN.SYS is a text file listing the device drivers on a system;
• DD*.PRL are the actual device drivers (the GIOS).

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

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.

Function 1 - Open workstation

• function=1;
• #ptsin=0;
• #intin=10;
• INTIN contains initial settings.

• #ptsout=6;
• #intout=45;
• INTOUT contains device data.

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.

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

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.

	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

• function=2;
• #intin=0.

• #intout=0.

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

Function 3 - Clear picture

• function=3;
• #intin=0.

• #intout=0.

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

Function 4 - Output graphics

• function=4;
• #intin=0.

• #intout=0.

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

• function=5;
• special=escape number;
• Other values as required by the escape.

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.

Function 6 - Draw a polyline

• function=6;
• #ptsin=number of points;
• Coordinates of points in PTSIN.

Function 7 - Plot a group of markers

• function=7;
• #ptsin=number of markers;
• Coordinates of markers in PTSIN.

Function 8 - Draw text

• function=8;
• #intin=number of characters;
• #ptsin=1.
• Coordinates of text in PTSIN.
• Text in INTIN.

Function 9 - Draw a filled polygon.

• function=9;
• #ptsin=number of vertices;
• Coordinates of vertices in PTSIN.

Function 10 - Output colour index array.

• function=10;
• #ptsin=2;
• #intin=length of array;
• Array in INTIN;
• Coordinates in PTSIN for bottom left and top right corners;

XCTRL: DEFW    length of each row
                DEFW    number of elements used in each row
                DEFW    number of rows
                DEFW    mode

1. replace
2. OR
3. XOR
4. erase

Function 11 - General Drawing Primitive

• function=11;
• special=primitive ID
• #ptsin, #intin, PTSIN, INTIN vary.

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

• function=12;
• #ptsin=1
• PTSIN holds (0, height)

• PTSOUT[0]=(width,height) of a W
• PTSOUT[1]=(width,height) of a cell

Function 13 - Set text direction

• function=13;
• #intin=3
• INTIN holds:
  • INTIN[0] = Angle to turn through in tenths of a degree (anticlockwise, 0 = normal)
  • INTIN[1] = 100 cos (angle)
  • INTIN[2] = 100 sin (angle)

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

Function 14 - Set colour index (palette registers)

• function=14;
• #intin=4;
• INTIN holds:
  • INTIN[0] = Colour number
  • INTIN[1] = Red 0-1000
  • INTIN[2] = Green 0-1000
  • INTIN[3] = Blue 0-1000

Function 15 - Set line style

• function=15;
• #intin=1;
• INTIN[0]=style.

Function 16 - Set line width

• function=16;
• #ptsin=1;
• PTSIN[0]=(width,0)

Function 17 - Set line colour

• function=17;
• #intin=1;
• INTIN[0]=colour.

Function 18 - Set marker type

• function=18;
• #intin=1;
• INTIN[0]=type.

Function 19 - Set marker height

• function=19;
• #ptsin=1;
• PTSIN[0]=(0, height)

Function 20 - Set marker colour

• function=20;
• #intin=1;
• INTIN[0]=colour.

Function 21 - Set text font

• function=21;
• #intin=1;
• INTIN[0]=font.

Function 22 - Set text colour

• function=22;
• #intin=1;
• INTIN[0]=colour.

Function 23 - Set fill style

• function=23;
• #intin=1;
• INTIN[0]=style.

Function 24 - Set fill index

• function=24;
• #intin=1;
• INTIN[0]=fill index.

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

Function 25 - Set fill colour

• function=25;
• #intin=1;
• INTIN[0]=colour.

Function 26 - Inquire colour representation (read palette)

• function=26;
• #intin=2;
• INTIN[0]=style;
  • INTIN[1]=0 to request return values.
  • INTIN[1]=1 to request real values.

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

Function 27 - Inquire cell array

• function=27;
• #ptsin=2;
• #intin=maximum length of colour index array;
• CONTRL[5]=length of each row;
• CONTRL[6]=number of rows.
• PTSIN holds coordinates of bottom LH and top RH corners of array.

Returns:

• CONTRL[7]=no. elements used in each row.
• CONTRL[8]=no. rows used.
• CONTRL[9]=error flag (0=OK 1=error).
• Array in INTOUT.

Function 28 - Read locator (eg tablet or mouse)

In Request mode:

• function=28;
• #ptsin=1;
• #intin=1;
• INTIN[0]=locator number (normally 1 for keyboard, 2 for mouse or tablet);
• PTSIN gives initial coordinates

Returns:

• PTSOUT=coordinates when key/button pressed;
• INTOUT[0]=terminator (key pressed, or mouse button +20h); #intout=0 if error.

In Sample mode:

• function=28;
• #intin=1;
• INTIN[0]=locator number (normally 1 for keyboard, 2 for mouse etc.);

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:

• function=29;
• #intin=2;
• INTIN[0]=valuator number.
• INTIN[1]=initial value.

• INTOUT[0]=final value when key/button pressed;
• INTOUT[1]=terminator (key pressed, or button + 20h); #intout=0 if error.

In Sample mode:

• function=29;
• #intin=1;
• INTIN[0]=valuator number.

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:

• function=30;
• #intin=1;
• INTIN[0]=choice number (1=function keys on keyboard).

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

In Sample mode:

• function=30;
• #intin=1;
• INTIN[0]=choice number (1=function keys on keyboard).

Returns:

• #intout=0 if nothing happened;
• #intout=1 if choice (choice in INTOUT[0]);
• #intout=2 if non-choice key (choice in INTOUI[0], key in INTOUT[1]).

Function 31 - Read string

In Request mode:

• function=31;
• #ptsin=INTIN[2];
• #intin=3;
• INTIN[0]=device number;
• INTIN[1]=maximum length;
• INTIN[2]=1 to echo, 0 not to.
• If echoing is on, PTSIN[0] gives coordinates of where to echo the string.

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

In Sample mode:

• function=31;
• #ptsin=0;
• #intin=2;
• INTIN[0]=device number;
• INTIN[1]=maximum length.

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

Function 32 - Set writing mode

• function=32;
• #intin=1;
• INTIN[0]=mode.

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

• function=33;
• #intin=2;
• INTIN[0]=device type (1=locator, 2=valuator, 3=choice, 4=string).
• INTIN[1]=mode (1=Request, 2=Sample).

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

• function=104;
• #intin=1;
• INTIN[0]=perimeter (1 to give filled shapes a perimeter, 0 not to).

Return to archive listing