The Virtual Device Interface
In this document, I list assembly language and C interfaces to the VDI. The C prototypes are similar to those provided by the GEM Developer's Kit, version 3.0. Most of the C interfaces are declared to return WORDs, but in practice only a few of them return meaningful values. The symbol indicates that a function behaves differently in different GEM versions.
Many of the low-numbered functions (eg: the "Cell array" functions, and the "locator/valuator/choice" input devices) are not implemented in most GEM drivers; they are relics of GSX and GKS.
This is still a work in progress. Some information is missing or requires additional explanation.
The VDI is used by GEM to communicate with its graphics drivers. It is used for all drawing functions.
The VDI is a superset of the Graphics System eXtension interface. GEM/2 for the PC provides a GSX interface; GEM/3 does not. It is made up of the GDOS, which loads drivers and performs Bezier drawing functions and coordinate transformations, and the drivers. Nearly all VDI functions passed to the drivers.
The GDOS lives in the file GEMVDI.EXE (in ViewMAX, VIEWMAX.EXE). GEM (but not ViewMAX) allows the VDI to use alternative AES modules:
GEMVDI /aesfileThis can be used to load the VDI without the AES:
GEMVDI /C:\COMMAND.COMwill load COMMAND.COM and wait until it terminates (ie, EXIT is typed).
The VDI is accessed by using INT 0EFh with CX=0473h and DS:DX=address of parameter block. The value in CX is not checked by the VDI, but should be used to ensure that the AES - or any other program chaining this interrupt - does not attempt to handle the call.
The parameter block format is:
DD CONTRL ;Address of control array DD INTIN ;Address of integer input array DD PTSIN ;Address of pixel input array DD INTOUT ;Address of integer output array DD PTSOUT ;Address of pixel output array
The control array is:
CONTRL: DEFW function ;Input: Function number 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. DEFW handle ;GEM driver handle DD ptr1 ;First far pointer value DD ptr2 ;Second far pointer value
GEM/5 copies an additional word from CONTRL. I do not know which, if any, function uses this.
The coordinates used in PTSIN and PTSOUT are signed 16-bit integer values, 0-7FFFh - The x value comes first. Normally these are device units - the actual pixels on the screen, printer etc. GEM can also be set to scale the coordinates, so that 0-7FFFh is the full height or width of the screen (as in GSX).In all calls except those where it is explicitly stated otherwise, handle is passed to the VDI on entry. If values for #ptsin and #intin are not supplied, these should be set to 0 on entry.
Function 1 - Open workstation
C Interface:- WORD v_opnwk(WORD work_in[], WORD *handle, WORD work_out[]);
- function=1;
- #ptsin=0;
- #intin=11;
- INTIN contains initial settings.
Note: The supplied bindings set #intin to 103. But the sample programs only supply 11 values.
Returns:
- #ptsout= 6;
- #intout= 45;
- handle = device handle, 0 if none available.
- INTOUT and PTSOUT contain device data (in the C interface, the INTOUT data appear at work_out[0] and the PTSOUT data at work_out[45]).
This loads a device driver and initialises it. Valid device driver numbers are found in the ASSIGN.SYS file (GEM/1 or 2; they are assigned automatically in GEM/3 and later), and follow this pattern:
1- 9: Screen 11-19: Plotter 21-29: Printer 31-39: GEM 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 DEFW pixel_mode ;1 to use NDCs, 2 to use pixelsThe INTOUT return array gives:
INTOUT: DEFW [0] Screen width, device units DEFW [1] Screen height, device units DEFW [2] 0 if device can produce a precisely scaled image, 1 if it can't DEFW [3] Width of a pixel, in thousandths of a millimetre. DEFW [4] Height of a pixel, in thousandths of a millimetre. DEFW [5] Number of character sizes, 0 for continuous sizing. DEFW [6] Number of line styles. DEFW [7] Number of line widths, 0 for continuous scaling. DEFW [8] Number of marker styles. DEFW [9] Number of marker sizes, 0 for continuous scaling. DEFW [10] Number of fonts. DEFW [11] Number of patterns. DEFW [12] Number of hatch styles. DEFW [13] Number of colours displayable at once. DEFW [14] Number of General Drawing Primitives DEFS [15] 20 ;General Drawing Primitive list. ;-1 => End of list ; 1 => Bar ; 2 => Arc ; 3 => Pie slice ; 4 => Circle ; 5 => Ellipse ; 6 => Elliptical arc ; 7 => Elliptical pie slice ; 8 => Rounded rectangle ; 9 => Filled rounded rectangle ;10 => Justified graphic text DEFS [25] 20 ;General Drawing Primitive attributes ;-1 => End of list ; 0 => Polyline ; 1 => Polymarker ; 2 => Text ; 3 => Filled area ; 4 => None DEFW [35] 0 for black/white, 1 for colour. DEFW [36] 0 if text rotation is not possible, 1 if it is. DEFW [37] 0 if filled areas are not possible, 1 if they are. DEFW [38] 0 if cannot read cell array, 1 if can. DEFW [39] Number of colours in the palette. ; 0 => More than 32767 ; 2 => Black and white DEFW [40] Number of locator devices (mice, tablets, lightpens) DEFW [41] Number of valuator devices (eg: a joystick throttle) DEFW [42] Number of choice devices (eg: function keys on a keyboard) DEFW [43] Number of string devices (ie: keyboards) DEFW [44] Workstation type ; 0 => Output only ; 1 => Input only ; 2 => Input and output ; 3 => Segment storage ; 4 => GEM metafile output.The PTSOUT return array gives:
DEFW minimum character width, minimum character height DEFW maximum character width, maximum character height DEFW minimum line width,0 DEFW maximum line width,0 DEFW minimum marker width, minimum marker height DEFW maximum marker width, maximum marker height.
(trust marker and character heights rather than widths).
Function 2 - Close workstation
C Interface:- void v_clswk(WORD handle);
- function = 2;
- handle = handle to close.
- #intout=0.
Function 3 - Clear picture
C Interface:- void v_clrwk(WORD handle);
- function=3;
Empties the buffer containing the current picture. This may be the screen, or buffered data for something like a printer.
Function 4 - Output graphics
C Interface:- void v_updwk(WORD handle);
- function=4;
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:- function=5;
- special=escape number;
- Other values as required by the escape.
Escapes are described in their own listing.
Function 6 - Draw a polyline
C Interface:- void v_pline(WORD handle, WORD count, WORD xy[]);
- function=6;
- #ptsin=no. of points in polyline;
- PTSIN contains the coordinates.
This draws a sequence of lines on the current device. It does not join the first and last point.
Function 7 - Plot a group of markers
C Interface:- void v_pmarker(WORD handle, WORD count, WORD xy[]);
- function=7;
- #ptsin=no. of markers;
- PTSIN contains the coordinates.
Function 8 - Draw text
C Interface:- void v_gtext(WORD handle, WORD x, WORD y, BYTE *string);
- function=8;
- #ptsin=1;
- #intin=length of text;
- PTSIN contains the coordinates at which to start drawing;
- INTIN contains the text, one character per word.
Function 9 - Draw a filled polygon.
C Interface:- void v_fillarea(WORD handle, WORD count, WORD points[]);
- function=9;
- #ptsin=number of vertices;
- Coordinates of vertices in PTSIN.
This function does join the first and last points it is given (unlike the polyline).
Function 10 - Output colour index array.
C Interface:- void v_cellarray( WORD handle, WORD xy[4], WORD row_length, WORD el_per_row, WORD num_rows, WORD wr_mode, WORD *colors );
- function=10;
- #ptsin=2;
- #intin=length of array;
- Array in INTIN;
- Coordinates in PTSIN for bottom left and top right corners;
The ptr1 and ptr2 areas of CONTRL hold: DEFW length of each row DEFW number of elements used in each row DEFW number of rows DEFW modeMode is:
- replace
- OR
- XOR
- erase
This function is not implemented in any of the GEM drivers I have seen.
Function 11 - General Drawing Primitive
Entered with:- function=11;
- special=primitive ID
- #ptsin, #intin, PTSIN, INTIN vary.
General Drawing Primitives are operations such as ellipses and rectangles.
- ID=1: void v_bar(WORD handle, WORD xy[4]);
- Filled bar. #ptsin=2; PTSIN gives diagonally opposite corners.
- ID=2: void v_arc(WORD handle, WORD xc, WORD yc, WORD radius, WORD start_angle, WORD end_angle);
- Arc. #ptsin=4, #intin=2. INTIN holds start angle and end angle in 10ths of a degree; PTSIN[0-1] holds coords of centre; PTSIN[6-7] holds (radius, 0). PTSIN[2-5] are zero.
- ID=3: void v_pieslice(WORD handle, WORD xc, WORD yc, WORD radius, WORD start_angle, WORD end_angle);
- Pie slice. As for arc.
- ID=4: WORD v_circle(WORD handle, WORD xc, WORD yc, WORD radius)
- Filled circle. #ptsin=3; PTSIN[0-1] hold coordinates of the centre; PTSIN[4-5] hold (radius, 0). PTSIN[2-3] hold (0,0).
- ID=5: WORD v_ellipse(WORD handle, WORD xc, WORD yc, WORD xrad, WORD yrad);
- Draw ellipse. #ptsin=2; PTSIN[0-1] hold coordinates of the centre, and PTSIN[2-3] holds (xradius, yradius).
- ID=6: WORD v_ellarc(WORD handle, WORD xc, WORD yc, WORD xrad, WORD yrad, WORD sang, WORD eang);
- Draw elliptical arc segment. As for the ellipse above, except that INTIN[0] holds start angle and INTIN[1] holds end angle.
- ID=7: WORD v_ellpie(WORD handle, WORD xc, WORD yc, WORD xrad, WORD yrad, WORD sang, WORD eang);
- Draw elliptical pie slice. Parameters as for the elliptical arc segment.
- ID=8: void v_rbox( WORD handle, WORD xy[4]);
- Rectangle with rounded corners. #ptsin=2; PTSIN gives diagonally opposite corners.
- ID=9: void v_rfbox( WORD handle, WORD xy[4]);
- Filled rectangle with rounded corners. #ptsin=2; PTSIN gives diagonally opposite corners.
- ID=10: void v_justified( WORD handle, WORD x, WORD y, BYTE *string, WORD length, WORD word_space, WORD char_space)
- Justified text.
- PTSIN[0-1] = coordinates at which to draw text
- PTSIN[2-3] = (desired width, 0).
- INTIN[0]: Set to 1 to allow word spacing to be varied.
- INTIN[1]: Set to 1 to allow character spacing to be varied.
- INTIN[2+] hold the text, one character per word.
Thus #ptsin=2 and #intin = 2 + length of text.
In GEM/3, if the top bit of INTIN[0] is set, INTOUT will be populated with the adjusted width (in pixels) of each character. In addition, if the top bit of INTIN[1] is set, the calculation will be performed but nothing will be drawn.
- ID=11: void v_etext( WORD handle, WORD x, WORD y, BYTE *string, offsets)
- Exact parameters and effects are not known.
- ID=12:
- Non-filled bezier.
- ID=13:
- Enable/disable Beziers (v_bez_on() / v_bez_off()).
If #ptsin = 0, disable Bezier functions; else enable.
Function 12 - Set text size
C Interface:- void vst_height( WORD handle, WORD height, WORD *char_width, WORD *char_height, WORD *cell_width, WORD *cell_height );
- 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
C Interface:- void vst_rotation( WORD handle, WORD angle);
- function=13;
- #intin=1
- INTIN[0] = Angle to turn through in tenths of a degree (anticlockwise, 0 = normal)
In practice many drivers only like their text at right-angles.
Function 14 - Set colour index (palette registers)
C Interface:- void vs_color( WORD handle, WORD colno, WORD *rgb);
- 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
On Atari systems with more than 8 bits colour depth, this will update the colours used for future drawing operations but not affect colours already onscreen. Colour number should be 0-255.
Function 15 - Set line style
C interface:- WORD vsl_type( WORD handle, WORD style);
- function=15;
- #intin=1;
- INTIN[0]=style.
- INTOUT[0] = style actually selected [The C binding returns this value].
Function 16 - Set line width
C interface:- WORD vsl_width( WORD handle, WORD width);
- function=16;
- #ptsin=1;
- PTSIN[0]=(width,0)
- PTSOUT[0] = (actual width, 0) [the C binding returns actual width].
Function 17 - Set line colour
C interface:- WORD vsl_color( WORD handle, WORD colour);
- function=17;
- #intin=1;
- INTIN[0]=colour.
- INTOUT[0] = actual colour [The C binding returns this value].
Function 18 - Set marker type
C interface:- WORD vsm_type( WORD handle, WORD type);
- function=18;
- #intin=1;
- INTIN[0]=type.
- INTOUT[0] = actual type [The C binding returns this value].
Function 19 - Set marker height
C interface:- WORD vsm_height WORD handle, WORD height);
- function=19;
- #ptsin=1;
- PTSIN[0]=(0, height)
- PTSOUT[0] = (0, actual height) [The C binding returns actual height].
Function 20 - Set marker colour
C interface:- WORD vsm_color( WORD handle, WORD colour);
- function=20;
- #intin=1;
- INTIN[0]=colour.
- INTOUT[0] = actual colour [The C binding returns this value].
Function 21 - Set text font
C interface:- WORD vst_font( WORD handle, WORD font);
- function=21;
- #intin=1;
- INTIN[0]=font.
- INTOUT[0] = font selected [The C binding returns this value].
Function 22 - Set text colour
C interface:- WORD vst_color( WORD handle, WORD colour);
- function=22;
- #intin=1;
- INTIN[0]=colour.
- INTOUT[0] = actual colour [The C binding returns this value].
Function 23 - Set fill style
C interface:- WORD vsf_interior( WORD handle, WORD style);
- function=23;
- #intin=1;
- INTIN[0]=style.
- INTOUT[0] = actual style [The C binding returns this value].
Function 24 - Set fill index
C interface:- WORD vsf_style( WORD handle, WORD index);
- function=24;
- #intin=1;
- INTIN[0]=fill index.
- INTOUT[0] = actual index [The C binding returns this value].
The fill index is used only with styles 2 & 3. Most GEM drivers support 12 hatches (1-12) and 24 patterns (1-24).
Function 25 - Set fill colour
C interface:- WORD vsf_color( WORD handle, WORD colour);
- function=25;
- #intin=1;
- INTIN[0]=colour.
- INTOUT[0] = actual colour [The C binding returns this value].
Function 26 - Inquire colour representation (read palette)
C interface:- WORD vq_color( WORD handle, WORD index, WORD set_flag, WORD rgb[] )
- function=26;
- #intin=2;
- INTIN[0]=colour no.;
- INTIN[1]=0 to request return values (ie, those set by the program).
- INTIN[1]=1 to request real values (ie, those actually used by the VDI).
Returns INTOUT[0]=Colour value, INTOUT[1-3]=RGB values 0-1000. The C binding stores the three RGB values in rgb[0-2].
Function 27 - Inquire cell array
C interface:- WORD vq_cellarray( WORD handle, WORD xy[4], WORD row_len, WORD num_rows, WORD *el_used, WORD *rows_used, WORD *stat, LONG colors )
- function=27;
- #ptsin=2;
- #intin=maximum length of colour index array;
- CONTRL[7]=length of each row;
- CONTRL[8]=number of rows.
- PTSIN holds coordinates of bottom LH and top RH corners of array.
Returns:
- CONTRL[9]=no. elements used in each row. [C stores this in *el_used]
- CONTRL[10]=no. rows used. [C stores this in *rows_used]
- CONTRL[11]=error flag (0=OK 1=error). [C stores this in *stat]
- Array in INTOUT. [C stores this in the array "colors" - the value passed in is a far pointer cast to long].
The next few functions can be operated in Request mode or Sample mode. The information given for them is rather hypothetical, as GEM drivers don't tend to implement these calls (except for the String input, which is used to read the keyboard).
Function 28 - Read locator (eg tablet or mouse)
In Request mode:
C interface:- WORD vrq_locator( WORD handle, WORD initx, WORD inity, WORD *xout, WORD *yout, WORD *term )
- function=28;
- #ptsin=1;
- #intin=1;
- INTIN[0]=locator number (normally 1 for keyboard, 2 for mouse etc.);
- PTSIN gives initial coordinates
Returns:
- PTSOUT=coordinates when key/button pressed [C returns this in *xout, *yout];
- INTOUT[0]=terminator (key pressed, or mouse button +20h); #intout=0 if error [C returns this in *term].
In Sample mode:
C interface:- WORD vsm_locator( WORD handle, WORD initx, WORD inity, WORD *xout, WORD *yout, WORD *term )
- function=28;
- #intin=1;
- INTIN[0]=locator number (normally 1 for keyboard, 2 for mouse etc.);
Returns:
- If coordinates changed:
- #ptsout=1 if coordinates changed; new coordinates in PTSOUT[0] [C returns this in *xout, *yout];
- If key or button pressed:
- #intout=1 if key or button pressed; and key or button in INTOUT[0] [C returns this in *term].
Function 29 - Read valuator
A valuator is a device like a mouse, except that it only operates in one dimension - for example, a volume control or a throttle.
In Request mode:
C interface:- WORD vrq_valuator( WORD handle, WORD val_in, WORD *val_out, WORD *term )
- function=29;
- #intin=2;
- INTIN[0]=valuator number.
- INTIN[1]=initial value.
- INTOUT[0]=final value when key/button pressed; [C returns this in *val_out]
- INTOUT[1]=terminator (key pressed, or button + 20h); #intout=0 if error. [C returns this in *term]
In Sample mode:
C interface:- WORD vsm_valuator( WORD handle, WORD val_in, WORD *val_out, WORD *term, WORD *status )
- 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 C binding returns INTOUT[0] in *val_out, INTOUT[1] in *term, and #intout in *status.
Function 30 - Read choice
In Request mode:
C interface:- WORD vrq_choice( WORD handle, WORD in_choice, WORD *out_choice )
- function=30;
- #intin=1;
- INTIN[0]=choice number (1=function keys on keyboard).
Returns #intout=1, INTOUT[0]=choice (1-n) [C stores this in *out_choice].
In Sample mode:
C interface:- WORD vsm_choice( WORD handle, WORD *choice )
- 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]).
The C binding returns #intout, and sets *choice to INTOUT[0].
Function 31 - Read string
In Request mode:
C interface:- WORD vrq_string( WORD handle, WORD length, WORD echo_mode, WORD echo_xy[], BYTE *string)
- function=31;
- #ptsin=1 if echoing, 0 if not;
- #intin=2;
- INTIN[0]=maximum length;
- INTIN[1]=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.
The C binding returns the string as series of bytes, 0-terminated, at "string".
In GEM, if the device number is negative, then keyboard scancodes are returned as well as ASCII. In each INTOUT word, the high byte is the scancode and the low byte is the ASCII value.
In Sample mode:
C interface:- WORD vsm_string( WORD handle, WORD length, WORD echo_mode, WORD echo_xy[], BYTE *string )
- function=31;
- #ptsin=1 if echoing, 0 if not;
- #intin=2;
- INTIN[0]=maximum length.
- INTIN[1]=echo mode.
- If echoing is on, PTSIN[0] gives coordinates of where to echo the string.
Returns #intout=length of string returned, string in INTOUT. The C binding returns a 0-terminated string at "string", and its length as a word.
In GEM, if the device number is negative, then keyboard scancodes are returned as well as ASCII. In each INTOUT word, the high byte is the scancode and the low byte is the ASCII value.
Function 32 - Set writing mode
C interface:- WORD vswr_mode( WORD handle, WORD 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:
- Replace. "Foreground" and "background" areas are replaced ("background" areas with colour 0).
- Transparent. "Foreground" areas are replaced but "background" areas stay the same.
- XOR. "Foreground" areas are XOR'ed with previous colour; "background" areas stay the same.
- Erase. "Foreground" areas are written in GSX colour 0; "background" areas stay the same.
Function 33 - Set input mode
C interface:- WORD vsin_mode( WORD handle, WORD dev_type, WORD mode )
- function=33;
- #intin=2;
- INTIN[0]=device type (1=locator, 2=valuator, 3=choice, 4=string).
- INTIN[1]=mode (1=Request, 2=Sample).
GSX stopped here. Calls from here are only present in the VDI, though the next few calls can be accessed from the GSX-86 interface present in GEM/1 and GEM/2.
Function 34
This function is a no-op in all GEM drivers that I have examined.
Function 35 - Get line attributes
C interface:- VOID vql_attributes( WORD handle, WORD attributes[] )
- function=35
- INTOUT[0] = Line style
- INTOUT[1] = Line colour
- INTOUT[2] = Drawing mode
- INTOUT[3] = Line start style [Not in GEM 1.1]
- INTOUT[4] = Line end style [Not in GEM 1.1]
- PTSOUT[0] = line width
[The C binding returns these values in
attributes[]
, with line width in
attributes[3]
. You would need to write a modified
binding to get at the line start and end styles.]
Function 36 - Get marker attributes
C interface:- VOID vqm_attributes( WORD handle, WORD attributes[] )
- function=36
- INTOUT[0] = Marker style
- INTOUT[1] = Marker colour
- INTOUT[2] = Drawing mode
- PTSOUT[1] = Marker height
[The C binding returns these values in
attributes[]
, with marker height in
attributes[3]
].
Function 37 - Get fill attributes
C interface:- VOID vqf_attributes( WORD handle, WORD attributes[] )
- function=37
- INTOUT[0] = Fill style
- INTOUT[1] = Fill index
- INTOUT[2] = Fill colour
- INTOUT[3] = Drawing mode
- INTOUT[4] = Outline flag
[The C binding returns these values in
attributes[]
.]
Function 38 - Get text attributes
C interface:- VOID vqt_attributes( WORD handle, WORD attributes[] )
- function=38
- INTOUT[0] = Text style
- INTOUT[1] = Text colour
- INTOUT[2] = Text direction
- INTOUT[3] = Justify H mode
- INTOUT[4] = Justify V mode
- INTOUT[5] = Drawing mode
- PTSOUT[1] = Minimum character height
- PTSOUT[3] = Maximum character height
[The C binding returns these values in
attributes[]
, with the minimum and maximum character
sizes in attributes[7]
and attributes[9]
respectively.]
The ViewMAX VGA driver does not support this call; you can check for this by seeing if it returned any integers. The normal call returns 6 integers but ViewMAX returns 0. This missing call will cause some programs (eg: RCS.APP) to crash with Divide by Zero errors when the ViewMAX driver is used.
Function 39 - Set text alignment
C interface:- VOID vst_alignment( WORD handle, WORD hor_in, WORD vert_in, WORD *hor_out, WORD *vert_out);
- function=39
- #intin=2
- INTIN[0] = horizontal alignment
- INTIN[1] = vertical alignment
- INTOUT[0] = actual horizontal alignment
- INTOUT[1] = actual vertical alignment
VDI calls after this point should not be accessed from the GSX-86 interface (INT E0). The VDI interface (INT EF) should be used.
Function 100 - Open virtual workstation
C Interface:- WORD v_opnvwk(WORD work_in[], WORD *handle, WORD work_out[]);
- function=100;
- #ptsin=0;
- #intin=11;
- handle=handle of currently open workstation (returned by function 1).
- INTIN contains initial settings, as in function 1.
Returns:
- #ptsout= 6;
- #intout= 45;
- handle = new handle, 0 if none available.
- INTOUT and PTSOUT contain the device data, as in function 1.
This is used to create a second and subsequent graphics context for an already- open driver. Typically, GEM will open the screen device using function 1, and the applications and desk accessories running under it will use this function to have their own graphics context for the display.
Current VDIs allow eight graphics contexts to be open at a time.
Virtual workstations opened with this call must be closed using function 101.
Function 101 - Close virtual workstation
C Interface:- void v_clsvwk(WORD handle);
- function = 101;
- handle = handle to close.
- #intout=0.
Function 102 - Query extended information
C Interface:- void vq_extnd(WORD handle, WORD owflag, WORD work_out[]);
- function = 102;
- #intin = 1;
- INTIN[0] = 0 (read startup information) or 1 (read extra information)
- Up to 45 words in INTIN
- Up to 12 words in PTSIN
If INTIN[0] was 0, this returns the same data as function 1. If INTIN[0] was 1, it returns a different set of data:
INTOUT: DEFW Type of alpha/graphic controllers 0 => Not a screen 1 => Separate text/graphic controllers and separate screens (eg: CGA+MDA dualhead) 2 => Separate controllers, common screen 3 => One controller, separate screen buffers 4 => One controller, one screen buffer DEFW No. of background colours (always 1?) DEFW Text styles supported (0Fh for printers, 1 for screen) DEFW 1 if can scale rasters, else 0 DEFW No. of planes DEFW 1 if palette based, 0 if true colour DEFW Number of 16x16 raster operations per second DEFW 1 if v_contourfill() is provided, else 0 DEFW Character rotation capability 0 => No 1 => 90 degree angles only 2 => Any angle DEFW No. of writing modes DEFW Highest input mode 0 => No input 1 => Request only 2 => Request and sample DEFW 1 if text alignment is possible, else 0 DEFW 1 if device can ink, else 0 DEFW Rubber banding 0 => No rubberbanding 1 => Lines only 2 => Lines and rectangles DEFW Maximum size of PTSIN (in vertices); -1 for unlimited DEFW Max size of INTIN (in words); -1 for unlimited DEFW No. of buttons on mouse DEFW 1 if styles are available for wide lines DEFW 1 if writing modes are available for wide lines DEFW 1 if clip rectangle set, else 0 DEFW ? ;[20] Unknown DEFW ? ;[21] Unknown DEFW ? ;[22] Unknown DEFW ? ;[23] Unknown DEFW ? ;[24] Unknown DEFW ? ;[25] Unknown DD Size of offscreen backing buffer. If this is nonzero, then the graphics card is assumed to have a buffer outside conventional memory, which can be used by vro_cpyfm(). The GEM 3.x AES supports this buffer mechanism and will use it in preference to allocating a buffer in main memory. ; PTSOUT: DEFW x,y ;Top left-hand corner of clip rectangle DEFW x,y ;Bottom right-hand corner of clip rectangle
Function 103 - Contour fill
C Interface:- void v_contourfill(WORD handle, WORD x, WORD y, WORD index);
- function=103;
- #ptsin=1;
- #intin=1;
- PTSIN contains the coordinates at which to start drawing;
- INTIN contains the fill index to use.
This function is not implemented in any of the GEM/3 screen or printer drivers.
Function 104 - Enable/disable fill perimeter
C Interface:- void vsf_perimeter(WORD handle, WORD per_vis);
- function=104;
- #intin=1;
- INTIN contains 1 to draw a perimeter round filled areas, 0 not to.
Function 105 - Get pixel value
C Interface:- BOOLEAN v_get_pixel(WORD handle, WORD x, WORD y, WORD *pel, WORD *index);
- function=105;
- #ptsin=1;
- PTSIN contains the point to read.
- If successful, #intout=2. INTOUT[0] is "pel" and INTOUT[1] is "index".
- If not successful #intout=0.
This function is not implemented in any of the GEM/3 screen or printer drivers.
Function 106 - Set text effects
C Interface:- WORD vst_effects(WORD handle, WORD effect);
- function=106;
- #intin=1;
- INTIN contains a bitmapped effect:
Bit 0: Bold Bit 1: Light Bit 2: Skew Bit 3: Underline Bit 4: Outline Bit 5: Shadow Bits 6-7: Rotate (0=normal, 1=90 degrees, 2=180 degrees, 3=270 degrees) Bit 8: Scale
Function 107 - Set text size in points
C Interface:- void vst_point( WORD handle, WORD point, WORD *char_width, WORD *char_height, WORD *cell_width, WORD *cell_height );
- function=107;
- #intin=1
- INTIN holds height in points.
- PTSOUT[0]=(width,height) of a W
- PTSOUT[1]=(width,height) of a cell
Function 108 - Set line end style
C Interface:- VOID vsl_ends( WORD handle, WORD beg_style, WORD end_style);
- function=108;
- #intin=2
- INTIN holds beginning & end style, in that order.
Styles should be 0 (square), 1 (arrow) or 2 (circle).
Function 109 - Copy raster opaque
C Interface: Entered with:- function=109;
- #ptsin=4
- #intin=1
- ptr1 and ptr2 point at the source and destination MFDBs.
- INTIN holds the writing mode. This is not the same as in other
functions; it specifies how the source and destination pixels will be
combined.
- 0: All result pixels 0
- 1: Source AND destination
- 2: Source AND NOT destination
- 3: Source
- 4: Destination AND NOT source
- 5: Destination unchanged
- 6: Source XOR destination
- 7: Source OR destination
- 8-15: As 7-0, but NOT applied to result.
- The first two points in PTSIN are opposite corners of a rectangle in the source bitmap; the second two are opposite corners of a rectangle in the destination bitmap.
This will copy a rectangular area from the source bitmap to the destination bitmap. It should be used for copying between bitmaps with the same colour depth.
Function 110 - Transform bitmap
C Interface: Entered with:- function=110;
- ptr1 and ptr2 point at the source and destination MFDBs.
This will transform a bitmap from device-independent format to device - dependent, or vice versa.
Function 111 - Set cursor shape
C Interface:- VOID vsc_form( WORD handle, WORD form[37]);
- function=111;
- #intin=37;
- INTIN holds a cursor shape:
DEFW hot spot X DEFW hot spot Y DEFW plct ;No. of planes in mouse defn. Always 1. DEFW ci_mask ;Colour index for mask DEFW ci_data ;Colour index for pointer DEFS 32 ;Mouse pointer mask DEFS 32 ;Mouse pointer bitmap
Function 112 - Create user-defined pattern
C Interface:- VOID vsf_udpat( WORD handle, WORD *pattern, WORD planes);
- function=112;
- #intin=16 * no. of planes in pattern;
- INTIN holds 16 words for each plane in the pattern.
Function 113 - Create user-defined line style
C Interface:- VOID vsl_udsty( WORD handle, WORD pattern);
- function=113;
- #intin = 1;
- INTIN[0] is the pattern to use.
Function 114 - Draw a filled rectangle
C Interface:- VOID vr_recfl( WORD handle, WORD *xy);
- function=114;
- #ptsin = 2;
- PTSIN holds opposite corners of the rectangle.
No border will be drawn round the rectangle.
Function 115 - Query input mode
C Interface:- VOID vqin_mode( WORD handle, WORD dev_type, WORD *mode);
- function=115;
- #intin = 1;
- INTIN[0] = device type (1=locator 2=valuator 3=choice 4=string)
Function 116 - Get text extent
C Interface:- VOID vqt_extent( WORD handle, BYTE *string, WORD *extent);
- function=116;
- #intin = length of string;
- INTIN contains the string; each word holds one character.
Function 117 - Get character size
C Interface:- WORD vqt_width( WORD handle, BYTE character, WORD *cell_width, WORD *left_delta, WORD *right_delta )
- function=117;
- #intin = 1;
- INTIN[0] = character.
- PTSOUT[0] = (cell width, ?)
- PTSOUT[1] = (left delta, ?)
- PTSOUT[2] = (right delta, ?)
- INTOUT[0] = -1 if no bitmap for character in font; else character.
Function 118 - Exchange timer vector
C Interface:- VOID vex_timv( WORD handle, VOID FAR *tim_addr, VOID FAR *old_addr, WORD *scale);
- function=118;
- ptr1 = address of new timer code.
- ptr2 = address of old timer code
- INTOUT[0] = timer tick count in milliseconds (ie, milliseconds per tick)
On a PC, this sets the INT 0x1C handler.
Function 119 - Load fonts
C Interface:- VOID vst_load_fonts(WORD handle, WORD select);
- function=119.
- INTOUT[0] = number of fonts loaded.
The "Select" parameter to the C interface does not appear to be used.
The VDI passes the following extra parameters in CONTRL to the driver when making this call:
- CONTRL[5] = segment of font manager.
- CONTRL[7] = segment of newly loaded font chain.
- CONTRL[8] = segment of text scratch buffer.
- CONTRL[9] = length of text scratch buffer.
- CONTRL[10] = offset of font manager.
The font manager is used to swap fonts in and out of memory. If a font is paged out (indicated by bit 4 of its flags being set), a far call will be made to the font manager with BX:AX pointing to the font header to swap in.
Function 120 - Unload fonts
C Interface:- VOID vst_unload_fonts(WORD handle, WORD select);
- function=120.
The VDI passes the following extra parameters in CONTRL to the driver when making this call:
- CONTRL[7] = segment of font chain being freed.
Function 121 - Copy raster transparent
C Interface:- VOID vrt_cpyfm( WORD handle, WORD wr_mode, WORD xy[], MFDB *srcMFDB, MFDB *desMFDB, WORD fg, WORD bg );
- function=121;
- #ptsin=4
- #intin=3
- ptr1 and ptr2 point at the source and destination MFDBs.
- INTIN holds the writing mode and the
foreground and background colours in which the monochrome bitmap is
to be painted. The writing mode is similar to the one used in
vswr_mode:
- 1: Background pixels drawn, foreground pixels drawn.
- 2: Background pixels not drawn, foreground pixels drawn.
- 3: Background pixels not drawn, foreground pixels inverted.
- 4: Background pixels drawn, foreground pixels not drawn.
- The first two points in PTSIN are opposite corners of a rectangle in the source bitmap; the second two are opposite corners of a rectangle in the destination bitmap.
This will copy a rectangular area from the source (mono) bitmap to the destination bitmap, drawing it in the colours provided.
Function 122 - Show mouse pointer
C Interface:- VOID v_show_c (WORD handle, WORD reset)
- function=122;
- #intin=1;
- INTIN[0] = reset flag.
If the "reset flag" is nonzero, displays the cursor and sets the "hide count" to 0. If not, decrements the "hide count" and if it is 0, shows the cursor.
Function 123 - Hide mouse pointer
C Interface:- VOID v_hide_c (WORD handle)
- function=123.
Hides the cursor and increases the "hide count".
Function 124 - Get mouse position
C Interface:- VOID vq_mouse (WORD handle, WORD *status, WORD *px, WORD *py)
- function=124.
- INTOUT[0] = mouse button status. Bit 0 = left button, bit 1 = right button, bit 2 = middle button.
- PTSOUT[0] = mouse cursor coordinates.
Function 125 - Exchange button vector
C Interface:- VOID vex_butv( WORD handle, VOID FAR *btn_addr, VOID FAR *old_addr);
- function=125;
- ptr1 = address of new button code.
- ptr2 = address of old button code.
The button code will be called when a mouse button is clicked. The mouse button status is passed to it in AX (x86) / D0 (680x0); Bit 0 for the left button, bit 1 for the right, bit 2 for the middle.
Function 126 - Exchange motion vector
C Interface:- VOID vex_motv( WORD handle, VOID FAR *mot_addr, VOID FAR *old_addr);
- function=126;
- ptr1 = address of new mouse movement code.
- ptr2 = address of old mouse movement code.
The code will be called when the mouse pointer is moved. It is entered with BX = mouse X-coordinate and CX = mouse Y-coordinate (D0 and D1 for 680x0).
Function 127 - Exchange cursor draw vector
C Interface:- VOID vex_curv( WORD handle, VOID FAR *cur_addr, VOID FAR *old_addr);
- function=127;
- ptr1 = address of new mouse pointer draw code.
- ptr2 = address of old mouse pointer draw code.
The code is entered with BX = mouse X-coordinate and CX = mouse Y-coordinate (D0 and D1 for 680x0).
Function 128 - Get keyboard shift state
C Interface:- VOID vq_key_s(WORD handle, WORD *status);
- function=128.
- INTOUT[0] = status (bit 0 = Shift, bit 1 = Ctrl, bit 2 = Alt)
Function 129 - Set clipping rectangle
C Interface:- VOID vs_clip(WORD handle, WORD clip_flag, WORD xy[]);
- function=129;
- #ptsin=2;
- #intin=1;
- PTSIN holds coordinates of opposite corners of the rectangle;
- INTIN[0] is 0 to turn off clipping, 1 to turn it on.
Function 130 - Get font name
C Interface:- WORD vqt_name( WORD handle, WORD element_num, BYTE name[] )
- function=130;
- #intin=1;
- INTIN[0] is index of font (1=first, 2=second...)
- #intout=33;
- INTOUT[0] = font ID (eg: 2 for serif, 14 for sans-serif)
- INTOUT[1-32] = font name, each word is one character.
In GEM/5, this function returns nothing
for font index 0 or 1; for other indices, the font scaler is used
to return data. A good test for a GEM/5 VDI would be to do a
vqt_name()
on font 1, and see if it returned any
values - if it did not, GEM/5 is running.
Function 131 - Get font info
C Interface:- BOOLEAN vqt_font_info( WORD handle, WORD *minADE, WORD *maxADE, WORD distances[], WORD *maxwidth, WORD effects[] )
- function=131.
- #intout=2 if successful, 0 if failed;
- #ptsout=5 if successful, 0 if failed;
- INTOUT[0] = first character in font (minADE);
- INTOUT[1] = last character in font (maxADE;
- PTSOUT[0] = (max cell width, bottom);
- PTSOUT[1] = (weight, descent);
- PTSOUT[2] = (left offset, half);
- PTSOUT[3] = (right offset, ascent);
- PTSOUT[4] = (?, top).
This returns information for the currently selected font.
"weight" (in PTSOUT[1]) is 0 if the font is not monospaced.
"left offset" and "right offset" are the amounts the character slants when it is skewed.
The C binding returns distances[] = {bottom, descent, half, ascent, top} and effects[] = {weight, left offset, right offset}.
Function 132 - Get offsets for justified text
C Interface:- WORD vqt_justified( WORD handle, WORD x, WORD y, BYTE string[], WORD length, WORD word_space, WORD char_space, WORD *offsets)
- function=132;
- #ptsin=2;
- #intin=2 + no. of bytes in string;
- PTSIN[0] = (x, y) to draw string at;
- PTSIN[1] = (width, 0) of area string should occupy;
- INTIN[0] = nonzero to adjust word spaces;
- INTIN[1] = nonzero to adjust character spaces;
- INTIN[2..] = string, one byte in each word.
- #ptsout=length of string;
- PTSOUT = coordinates of each character in the string (only X-coordinates text output is horizontal, only Y-coordinates if text output is vertical).
This function, at least in the GEM/2.0 and GEM/3.x drivers that I have examined, does not give the same character positions as sd_justified.
Functions 133-135
These functions exist in the GEM/4 screen driver, but have no effect.
Function 136
GEM/4: Based on v_pline() but takes extra integer parameters.
Function 137
GEM/4: Based on v_fillarea() but takes extra integer parameters.
Function 142
GEM/4: Takes an integer parameter.
Function 143
GEM/4: Takes an integer parameter that is at most 100.
Function -1 - GDOS escape
These are functions handled by the GDOS, where no driver handle is required.
Entered with:
- function=-1;
- special= subfunction.
GEM/2 only provides subfunction 1.
Subfunctions are
- Page out GEM to run a DOS (or CP/M-86) program. Only a stub of
the VDI will remain in memory, and no VDI or AES functions will be
available.
Entered with INTIN[0-1] = far pointer to INT 21/AX=4B00 parameter block and INTIN[2-3] = address of 0-terminated error message. - Font extension. Entered with 3 words in INTIN, which are the file type to use for fonts (normally 'F','N','T').
- PD list. Returns path to GDOS in INTOUT and driver paths at ptr1.
- Driver list. Enter with INTIN[0] = device ID and INTIN[1] =
information requested:
- Full driver filename including path
- Short driver description
- Long driver description
- Driver font search path
- Driver patch bytes
C interface: v_get_driver_info(WORD device_id, WORD info_select, BYTE *info_string);
Returns information in INTOUT, and #intout set accordingly.
- Get font info. Returns INTOUT[0] = segment of font buffer and INTOUT[1] = size of font buffer in bytes.
- Set App buffer address and size. Entered with INTIN[0-1] = far pointer to buffer and INTIN[2] = buffer size in paragraphs. Used in GEM/3 for beziers.
- (GEM/4) Fill INTOUT with a 0-terminated ASCII string.
- (GEM/4) Fill INTOUT with a 0-terminated ASCII version number (for GEM/4, this is "3.91".