GEM pages
Home -> GEM -> VDI -> Escapes

The Virtual Device Interface: Escapes

The following functions ("escapes") are all accessed through VDI function 5. The function number is given in the special member of the CONTRL array.

Different drivers support different ranges of escape functions. Escapes 1-19 and 60-69 apply only to video drivers, while numbers 20-29 are usually limited to printers and plotters.

[!] Escapes 1 and 4-19 are not implemented in most GEM drivers; you can only be sure of having them in the original GEM/1.1 set. Adding support back is a matter of setting "ibmvdi" to 1 rather than 0 and recompiling the affected driver.

1. void vq_chcells(WORD handle, WORD *rows, WORD *columns);

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. If the device doesn't have a text screen (such as a printer) then this will return (-1, -1).

2. void v_exit_cur(WORD handle)

Exit text mode (and enter graphics mode).

3. void v_enter_cur(WORD handle)

Enter text mode.

4. void v_curup(WORD handle)

Text cursor up.

5. void v_curdown(WORD handle)

Text cursor down.

6. void v_curright(WORD handle)

Text cursor right.

7. void v_curleft(WORD handle)

Text cursor left.

8. void v_curhome(WORD handle)

Clear text screen, home cursor.

9. void v_eeos(WORD handle)

Clear from text cursor to end of screen.

10. void v_eeol(WORD handle)

Clear from text cursor to end of line.

11. void vs_curaddress(WORD handle, WORD row, WORD column)

Move text cursor to coordinates given in INTIN. Therefore this should be entered with #intin=2.

12. void v_curtext(WORD handle, BYTE *string)

Print (to the text screen) a string whose characters are stored in INTIN (one character to each word). #intin = length of string.

13. void v_rvon(WORD handle)

Select reverse video.

14. void v_rvoff(WORD handle)

Cancel reverse video.

15. void vq_curaddress(WORD handle, WORD *row, WORD *column );

Return the coordinates of the text cursor in the first two words of INTOUT. Note: At least one driver implements this by moving the cursor to the top left hand corner of the screen and always returning (1,1).

16. WORD vq_tabstatus(WORD handle)

Is a tablet (or mouse etc.) available? Returns the first word of INTOUT as 0 if no, 1 if yes.

17. void v_hardcopy(WORD handle)

Dump the current screen to the printer.

18. void v_dspcur(WORD handle, WORD x, WORD y)

Place a graphic cursor (a mouse pointer or similar). Its coordinates are given in PTSIN, so enter with #ptsin=1.

19. void v_rmcur(WORD handle)

Remove the graphic cursor.

20. void v_form_adv(WORD handle)

Form advance - throw a page on a printer device.

21. void v_output_window (WORD handle, WORD xy[])

As v_updwk() - Print the page, but clipped within the rectangle given by the two points xy[]. Used on printers and other devices where drawing isn't immediate.

22. void v_clear_disp_list(WORD handle)

For a printer - discard any output for this page that has not been printed (ie, any output received since the last v_updwk() or v_output_window() ).

23. void v_bit_image(WORD handle, BYTE *filename, WORD aspect, WORD x_scale, WORD y_scale, WORD h_align, WORD v_align, WORD xy[])

Draw an image from a disc file onto the current device. Passed #ptsin=2, #intin=5 + length of filename. INTIN holds:

24. void vq_scan( WORD handle, WORD *g_height, WORD *g_slice, WORD *a_height, WORD *a_slice, WORD *factor )

Return printer "scan heights". Returns 5 values in INTOUT:

    DEFW    g_height    ;Height of a graphics slice
    DEFW    g_slice     ;No. of graphics slices per page
    DEFW    a_height    ;Height of a text slice
    DEFW    a_slice     ;No. of text slices per page
    DEFW    factor      ;?

25. void v_alpha_text( WORD handle, BYTE *string )

Output text directly to printer. Entered with #intin = no. of characters; string in INTIN, one character per word.

27. void v_orient(WORD handle, WORD orientation)

[!] (GEM/3 and later) Set page orientation. Passed #intin = 1; INTIN[0] is 0 for portrait, 1 for landscape.

28. void v_copies(WORD handle, WORD count)

[!] (GEM/3 and later) Set number of copies to print. Passed #intin = 1; INTIN[0] is number of copies.

29. void v_tray(WORD handle, WORD tray)

[!] (GEM/3 and later) Set paper tray to use. Passed #intin = 1; INTIN[0] is the tray number.

60. WORD vs_palette( WORD handle, WORD palette )

Select a predefined palette. Passed #intin = 1, INTIN[0] holds the zero-based palette number. Returns the selected palette number in INTOUT[0]. This is intended for systems like the CGA (in low-resolution mode) or "Plantronics" 640x200 mode, which have a number of fixed palettes. Digital Research drivers known to implement this include the Apricot F-Series drivers, which have two palettes: the usual black on white, and yellow on blue.

Has no effect in most GEM drivers, though there's a case to be made that calling vs_palette(handle, 0) ought to reset all colours to the default palette.

61. void v_sound(WORD handle, WORD frequency, WORD duration)

Play a sound on the beeper. Passed #intin = 2; INTIN holds the frequency and duration in that order.

62. WORD vs_mute(WORD handle, WORD action)

Enable / disable sound. Entered with #intin = 1, INTIN[0] holds -1, 0 or 1. If INTIN[0] is:

Returns the current status in INTOUT[0].
Sound is enabled.
Sound is disabled

81. void vt_resolution(WORD handle, WORD xres, WORD yres, WORD *xset, WORD *yset)

? Passed two words in INTIN (xres and yres); returns xset and yset in INTOUT. Used in GEM 2.2 with tablet input devices; functions 81-85 are not exposed in GEM 3+, though the code to implement them is still present.

82. void vt_axis(WORD handle, WORD xres, WORD yres, WORD *xset, WORD *yset)

? Passed two words in INTIN (xres and yres); returns xset and yset in INTOUT.

83. void vt_origin(WORD handle, WORD x, WORD y)

? Passed two words in INTIN (x and y).

84. void vq_tdimensions(WORD handle, WORD *xdim, WORD *ydim)

? Get two dimensions in INTOUT (x and y).

85. void vt_alignment( WORD handle, WORD dx, WORD dy )

? Set two words in INTIN (dx and dy).

91.void vsp_film( WORD handle, WORD index, WORD lightness )

? Set the film parameters for a camera. The two words go to INTIN[0] and INTIN[1] respectively, so this is called with #intin = 2.

92. BOOLEAN vqp_filmname( WORD handle, WORD index, BYTE *name )

? Get the name of film number "index". Passed one word in INTIN; returns #intout is the length of the name, which is stored in INTOUT (one character per word). If #intout is 0, then the C binding returns FALSE; else TRUE.

93. void vsc_expose( WORD handle, WORD state )

? Passed one word in INTIN, but for some reason the standard binding sets #intin to 2. This may be a bug.

98. void v_meta_extents( WORD handle, WORD min_x, WORD min_y, WORD max_x, WORD max_y )

Set the size of the drawing area when writing a metafile. The parameters are passed as the first two points in PTSIN (min then max), so the call is made with #ptsin equal to 2.

99. Metafile functions

Escape 99 is used to perform functions that only have effect in a metafile. INTIN[0] holds the "sub-opcode" number. Sub-opcode numbers 0-100 are reserved for the GEM system; other sub-opcodes can be used by users.

99. void v_write_meta( WORD handle, WORD num_ints, WORD *ints, WORD num_pts, WORD pts )

Write out a "user-defined" metafile record. The INTIN and PTSIN arrays can be any size (though the INTIN array must contain at least one element - the sub-opcode).

The subfunctions 99/0 and 99/1 do not actually add records to the metafile; rather, they set values in the metafile header.

99/0. void vm_pagesize(WORD handle, WORD width, WORD height)

Set the size of the page used by the metafile being written, in tenths of millimetres:

99/1. void vm_coords(WORD handle, WORD llx, WORD lly, WORD urx, WORD ury)

Set the lower left and upper right corners of the coordinate system used by the metafile being written.

99/32. WORD v_bez_qual( WORD handle, WORD prcnt)

Set Bezier curve quality.

100. void vm_filename(WORD handle, BYTE *filename)

? Set the metafile filename. The filename is passed in INTIN, one character per word, with #intin being its length.

101. void v_xbit_image(WORD handle, BYTE *filename, WORD aspect, WORD x_scale, WORD y_scale, WORD h_align, WORD v_align, WORD rotation, WORD foreground, WORD background, WORD xy[])

[!] (GEM/3 and later) Draw an image from a disc file onto the current device - with rotation and colouring. Passed #ptsin=2, #intin=8 + length of filename. INTIN holds:

Back to VDI listing