This is an old version from the tos.hyp. The new is on GitHub!

HomeVDIInput functionsColour table functions

7.8 Escape functions

This library contains functions to take advantage of special features of a graphic device. For this purpose the following function groups are available:

See also: VDI workstations   Style guidelines

7.8.1 Special graphic functions

This library contains functions to output data on a printer, for controlling the colour calibration, and many others. In all, the following routines are available:

v_bit_image Outputs image data on a printer
v_clear_disp_list Clears printer buffer
v_copies Sets number of copies
v_dspcur Displays graphic cursor at given position
v_form_adv Executes form-feed on a printer
v_hardcopy Outputs hardcopy on a printer
v_orient Sets output format
v_output_window Outputs part of screen area on a printer
v_page_size Sets page format
v_rmcur Clears last graphic cursor
v_tray Selects tray for paper feed-in/out
v_xbit_image Outputs image data on a printer
vq_calibrate Tests colour calibration
vq_margins Inquires printer margins
vq_page_name Gets name and size of a page format
vq_prn_scaling Gets scaling of the printer driver
vq_scan Gets printer parameters
vq_tabstatus Inquires availability of graphics tablet, mouse...
vq_tray_names Gets name of paper tray/output slot
vs_calibrate Tests colour calibration
vs_document_info Sets document specifications for print monitor
vs_palette Selects the colour palette

See also: VDI workstations   Style guidelines

7.8.1.1 vq_calibrate

Name: »Inquire calibration« - Test colour calibration.
Opcode: 5 (Escape 77)
Syntax: int16_t vq_calibrate ( int16_t handle, int16_t *flag );
Description: The call vq_calibrate tests whether functions for calibration are present, and if these are switched on. The following apply:
Parameter Meaning
   
handle Workstation identifier
flag Calibration:
0 = is off
1 = is on
Return value: The function returns the value 1 if functions for calibration are present, else the value 0.
Availability:
Group: Special graphic functions
See also: Binding   vs_calibrate

7.8.1.2 Bindings for vq_calibrate

C: int16_t vq_calibrate ( int16_t handle, int16_t *flag );
Binding:
int16_t vq_calibrate (int16_t handle, int16_t *flag)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 77;
   contrl[6] = handle;

   vdi ();

   *flags = intout[0];
   return (  contrl[4] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+10 contrl[5] 77 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intout intout[0] flag


Note: n specifies the number of entries in the intout field. If contrl[4] contains the value 0, calibration is not supported.

7.8.1.3 vq_margins

Name: »Inquire printer margins«
Opcode: 5 (Escape 2100)
Syntax: int16_t vq_margins( int16_t handle, int16_t *top_margin, int16_t *bottom_margin, int16_t *left_margin, int16_t *right_margin, int16_t *hdpi, int16_t *vdpi );
Description: The call vq_margins obtains the printer margins. The following apply:
Parameter Meaning
   
handle Workstation identifier
top_margin Top margin in pixels
bottom_margin Bottom margin in pixels
left_margin Left margin in pixels
right_margin Right margin in pixels
hdpi Horizontal dpi resolution
vdpi Vertical dpi resolution
Return value: 0: Function does not exist
Availability: As of NVDI 5.00.
Group: Special graphic functions
See also: Binding

7.8.1.4 Bindings for vq_margins

C: int16_t vq_margins( int16_t handle, int16_t *top_margin, int16_t *bottom_margin, int16_t *left_margin, int16_t *right_margin, int16_t *hdpi, int16_t *vdpi );
Binding:
int16_t  vq_margins( int16_t handle, int16_t *top_margin,
                  int16_t *bottom_margin, int16_t *left_margin,
                  int16_t *right_margin, int16_t *hdpi,
                  int16_t *vdpi )
{
   intout[0] = 0;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 2100;
   contrl[6] = handle;

   vdi ();

   *top_margin    = intout[1];
   *bottom_margin = intout[2];
   *left_margin   = intout[3];
   *right_margin  = intout[4];
   *hdpi          = intout[5];
   *vdpi          = intout[6];

  return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 7 # Entry in intout
contrl+10 contrl[5] 2100 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intout intout[0] Return Value
intout+2 intout[1] top_margin
intout+4 intout[2] bottom_margin
intout+6 intout[3] left_margin
intout+8 intout[4] right_margin
intout+10 intout[5] hdpi
intout+12 intout[6] vdpi

7.8.1.5 vq_page_name

Name: »Inquire page name« - Obtain name and size of a page format.
Opcode: 5 (Escape 38)
Syntax: int16_t vq_page_name ( int16_t handle, int16_t page_id, int8_t *page_name, int32_t *page_width, int32_t *page_height )
Description: The call vq_page_name obtains the name and the physical size of a page format. The following apply:
Parameter Meaning
   
handle Workstation identifier
page_id Paper format
page_name Pointer to the name, or NULL
page_width Page width in microns (1/1000 mm)
page_height Page height in microns (1/1000 mm)


Note: The data for the paper size include also the non-printable margins.
Return value: The function returns the current paper format. A value of -1 means that the specified page format is not known to the driver; in that case no values will be returned in page_width or page_height.
Availability: The function is only present if contrl[4] has a non-zero value.
Group: Special graphic functions
See also: Binding   v_opnwk   vq_extnd

7.8.1.6 Bindings for vq_page_name

C: int16_t vq_page_name ( int16_t handle, int16_t page_id, int8_t *page_name, int32_t *page_width, int32_t *page_height )
Binding:
int16_t vq_page_name ( int16_t handle, int16_t page_id, int8_t *page_name,
                    int32_t *page_width, int32_t *page_height )
{
   intin[0] = page_id;
   intin[1..2] = page_name;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 3;
   contrl[5] = 38;
   contrl[6] = handle;

   vdi ();

   *page_width  = intout[1..2];
   *page_height = intout[3..4];

   return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 3 # Entry in intin
contrl+8 contrl[4] 5 # Entry in intout
contrl+10 contrl[5] 38 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] page_id
intin+2 intin[1..2] page_name
intout intout[0] Return Value
intout+2 intout[1..2] page_width
intout+6 intout[3..4] page_height


Note: If contrl[4] contains the value 0, the function is not available.

7.8.1.7 vq_prn_scaling

Name: »Inquire printer scaling« - Obtain scaling of the printer driver.
Opcode: 5 (Escape 39)
Syntax: fixed vq_prn_scaling( int16_t handle );
Description: The call vq_prn_scaling returns information whether the printer driver takes heed of the scaling passed in the PRN_SETTINGS. If the driver does not support the function (i.e. an old driver), the binding returns -1 for the scaling. If we are dealing with a new driver that supports the function but does not scale, then this returns -1.

If the driver performs the scaling, then the set scaling factor will be returned (0x10000L corresponds to 100 %).
Parameter Meaning
   
handle Workstation identifier
Return value: -1 if an old driver or scaling did not take place, else the set scaling factor (0x10000L corresponds to 100%).
Availability: As of NVDI 5.00.
Group: Special graphic functions
See also: Binding

7.8.1.8 Bindings for vq_prn_scaling

C: fixed vq_prn_scaling( int16_t handle );
Binding:
fixed vq_prn_scaling( int16_t handle )
{
   intin[0] = -1;
   intin[1] = -1;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 3;
   contrl[5] = 39;
   contrl[6] = handle;

   vdi ();

   return ( *(fixed *) intout );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 3 # Entry in intin
contrl+8 contrl[4] 2 # Entry in intout
contrl+10 contrl[5] 39 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] -1
intin+2 intin[1] -1
intout intout[0..1] Return Value


Note: If contrl[4] contains the value 0, the function is not available.

7.8.1.9 vq_scan

Name: »Inquire printer scan« - Obtain parameters relating to printer banding.
Opcode: 5 (Escape 24)
Syntax: void vq_scan ( int16_t handle, int16_t *g_slice, int16_t *g_page, int16_t *a_slice, int16_t *a_page, int16_t *div_fac );
Description: The call vq_scan permits inquiry of various printer-specific parameters related to the number of graphic passes per printer page. The following apply:
Parameter Meaning
   
handle Workstation identifier
g_slice Pixel height of a band
g_page Number of bands into which the printer subdivides a page
a_slice Height of an alpha text line in pixels
a_page Alpha text lines per page
div_fac Factor by which the other values may have to be divided


Notes: One can calculate the number of graphics scan lines per pass from the formula g_slice/div_fac and the number of scan lines per alpha text line from a_slice/div_fac.

This call has been previously mis-documented.
Return value: The function does not return a result.
Availability: Supported by all printer drivers.
Group: Special graphic functions
See also: Binding

7.8.1.10 Bindings for vq_scan

C: void vq_scan ( int16_t handle, int16_t *g_slice, int16_t *g_page, int16_t *a_slice, int16_t *a_page, int16_t *div_fac );
Binding:
void vq_scan (int16_t handle, int16_t *g_slice,
              int16_t *g_page, int16_t *a_slice,
              int16_t *a_page, int16_t *div_fac)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 24;
   contrl[6] = handle;

   vdi ();

   *g_slice = intout[0];
   *g_page  = intout[1];
   *a_slice = intout[2];
   *a_page  = intout[3];
   *div_fac = intout[4];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 5 # Entry in intout
contrl+10 contrl[5] 24 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intout intout[0] g_slice
intout+2 intout[1] g_page
intout+4 intout[2] a_slice
intout+6 intout[3] a_page
intout+8 intout[4] div_fac

7.8.1.11 vq_tabstatus

Name: »Inquire tablet status« - Obtain availability of a specialized input device.
Opcode: 5 (Escape 16)
Syntax: int16_t vq_tabstatus ( int16_t handle );
Description: The call vq_tabstatus checks on the workstation with the ID handle for the availability of a graphics tablet, of a mouse, a joystick or a similar device.
Return value: The function returns the value 1 if a corresponding device is available, else the value 0 if this is not the case.
Availability: Supported by all screen drivers.
Group: Special graphic functions
See also: Binding

7.8.1.12 Bindings for vq_tabstatus

C: int16_t vq_tabstatus ( int16_t handle );
Binding:
int16_t vq_tabstatus (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 16;
   contrl[6] = handle;

   vdi ();

   return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+10 contrl[5] 16 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intout intout[0] Return Value

7.8.1.13 vq_tray_names

Name: »Inquire tray names« - Obtain name of the paper feed-in or feed-out tray.
Opcode: 5 (Escape 36)
Syntax: void vq_tray_names ( int16_t handle, int8_t *input_name, int8_t *output_name, int16_t *input, int16_t *output );
Description: The call vq_tray_names obtains the name of the current feed-in or feed-out tray.
Parameter Meaning
   
handle Workstation identifier
input_name Pointer to the name of the input tray
output_name Pointer to the name of the output tray
input Number of the input tray
output Number of the output tray


Note: If the parameters input_name or output_name are NULL-pointers, they will not be returned.
Return value: The function returns no direct result.
Availability: The function is only present if contrl[4] is non-zero.
Group: Special graphic functions
See also: Binding   v_tray   v_copies   v_orient

7.8.1.14 Bindings for vq_tray_names

C: void vq_tray_names ( int16_t handle, int8_t *input_name, int8_t *output_name, int16_t *input, int16_t *output );
Binding:
void vq_tray_names ( int16_t handle, int8_t *input_name,
                     int8_t *output_name, int16_t *input,
                     int16_t *output )
{
   intin[0..1] = input_name;
   intin[2..3] = output_name;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 4;
   contrl[5] = 36;
   contrl[6] = handle;

   vdi ();

   *input  = intout[0];
   *output = intout[1];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 4 # Entry in intin
contrl+8 contrl[4] 2 # Entry in intout
contrl+10 contrl[5] 36 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0..1] input_name
intin+4 intin[2..3] output_name
intout intout[0] input
intout+2 intout[1] output


Note: If contrl[4] contains the value 0, the function is not available.

7.8.1.15 vs_calibrate

Name: »Set calibration« - Set colour calibration.
Opcode: 5 (Escape 76)
Syntax: int16_t vs_calibrate ( int16_t handle, int16_t flag, int16_t *rgb );
Description: The call vs_calibrate switches colour calibration on or off and can be used to set a calibration table.
Parameter Meaning
   
handle Workstation identifier
flag Calibration:
0 = Turn off
1 = Turn on
rgb Pointer to calibration table, or NULL


Note: A calibration table consists of 1001 RGB entries, that allocate for the value range 0- to 1000- thousandths of each input value a corrected thousandth value. Before calling this function, one should use vq_calibrate to check whether it is even present.

The colour calibration is valid for the whole system for the driver identified by handle. Hence it should not be set by individual applications, but only with a CPX module or a desk accessory.
Return value: The function returns the value 0 if the calibration is switched off, or the value 1 if this is switched on.
Availability: No information to hand.
Group: Special graphic functions
See also: Binding   vq_calibrate

7.8.1.16 Bindings for vs_calibrate

C: int16_t vs_calibrate ( int16_t handle, int16_t flag, int16_t *rgb );
Binding:
int16_t vs_calibrate (int16_t handle, int16_t flag,
                      int16_t *rgb)
{
   intin[0..1] = rgb;
   intin[2] = flag;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 3;
   contrl[5] = 76;
   contrl[6] = handle;

   vdi ();

   return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 3 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+10 contrl[5] 76 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0..1] rgb
intin+4 intin[2] flag
intout intout[0] Return Value

7.8.1.17 vs_document_info

Name: »Set document info« - Set document specifications for print monitor.
Opcode: 5 (Escape 2103)
Syntax: int16_t vs_document_info( int16_t handle, int16_t type, void *s, int16_t wchar );
Description: The call vs_document_info passes to a program various specifications about a document that the print monitor displays during printout.
Parameter Meaning
   
handle Workstation identifier
type
0 = Name of the application
1 = Name of the document
2 = Name of the originator/editor
3 = Comment
4 = Filename of the document
s Pointer to the string
wchar 0: 8 bits per character
1: 16 bits per character
Return value: 0: Function not present
1: All OK
Availability: As of NVDI 5.00.
Group: Special graphic functions
See also: Binding

7.8.1.18 Bindings for vs_document_info

C: int16_t vs_document_info( int16_t handle, int16_t type, void *s, int16_t wchar );
Binding:
int16_t  vs_document_info( int16_t handle, int16_t type,
                           void *s, int16_t wchar )
{
   intin[0] = type;
   intin[1..n-1] = s

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = n;
   contrl[5] = 2103;
   contrl[6] = handle;

   vdi ();

   return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] n # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+10 contrl[5] 2103 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] type
intin+2 intin[1..n-1] s
intout intout[0] Return Value

7.8.1.19 vs_palette

Name: »Select palette« - Select a colour palette.
Opcode: 5 (Escape 60)
Syntax: int16_t vs_palette ( int16_t handle, int16_t palette );
Description: The call vs_palette permits the selection of the colour palette on an IBM CGA graphics card in medium resolution. The following apply:
Parameter Meaning
   
handle Workstation identifier
palette Colour palette
0 = Red, Green, Blue
1 = Cyan, Magenta, White
Return value: The function returns the selected palette.
Availability: This call was originally designed for use on IBM CGA-based computers. Its usefulness and availability are not guaranteed under any driver, so it should be avoided.
Group: Special graphic functions
See also: Binding

7.8.1.20 Bindings for vs_palette

C: int16_t vs_palette ( int16_t handle, int16_t palette );
Binding:
int16_t vs_palette (int16_t handle, int16_t palette)
{
   intin[0] = palette;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 60;
   contrl[6] = handle;

   vdi ();

   return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+10 contrl[5] 60 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] palette
intout intout[0] Return Value

7.8.1.21 v_bit_image

Name: »Output bit image file« - Output a bit image file on the printer.
Opcode: 5 (Escape 23)
Syntax: void v_bit_image ( int16_t handle, CONST int8_t *filename, int16_t aspect, int16_t x_scale, int16_t y_scale, int16_t h_align, int16_t v_align, int16_t *xyarray );
Description: The call v_bit_image permits print output of the image data stored in a bit-Image (IMG) file. The following apply:
Parameter Meaning
   
handle Workstation identifier
filename Pointer to filename
aspect Aspect ratio:
0 = Ignore aspect ratio
1 = Respect pixel aspect ratio
x_scale Scaling of the X-axis, and
y_scale Scaling of the Y-axis, for both of which the following apply:
0 = Rational (exact)
1 = Integer
h_align Horizontal alignment:
0 = Left
1 = Center
2 = Right
v_align Vertical alignment:
0 = Top
1 = Middle
2 = Bottom
xyarray[0] X-coordinate, and
xyarray[1] Y-coordinate of top left corner of the output rectangle
xyarray[2] X-coordinate, and
xyarray[3] Y-coordinate of the bottom right corner of the output recangle


Notes: If the aspect ratio in aspect is honoured, then circles will appear as circles, squares as squares etc. The image will then be stretched correspondingly on the output device. In some circumstances this can look bad when, say, fine dot rasters are stretched or compressed. If the ratio is ignored, it is possible that circles will become ellipses etc.

If rational scaling is used, the image will appear at the coordinates given by the VDI format rectangle pointed to by xyarray; if integer scaling is used, the image will be displayed as large as possible within the given coordinates, using h_align and v_align for justifying the image.
Return value: The function does not return a result.
Availability: Supported by all printer, metafile, and memory drivers.
Group: Special graphic functions
See also: Binding   v_xbit_image   GDOS   XIMG format

7.8.1.22 Bindings for v_bit_image

C: void v_bit_image ( int16_t handle, CONST int8_t *filename, int16_t aspect, int16_t x_scale, int16_t y_scale, int16_t h_align, int16_t v_align, int16_t *xyarray );
Binding:
void v_bit_image (int16_t handle, CONST int8_t *filename,
                  int16_t aspect, int16_t x_scale,
                  int16_t y_scale, int16_t h_align,
                  int16_t v_align, int16_t *xyarray)
{
   int16_t tmp;

   ptsin[0..3] = xyarray[0..3];
   intin[0] = aspect;
   intin[1] = x_scale;
   intin[2] = y_scale;
   intin[3] = h_align;
   intin[4] = v_align;

   tmp = 5;
   while (intin[tmp++] = *filename++)
      ;

   contrl[0] = 5;
   contrl[1] = 2;
   contrl[3] = --tmp;
   contrl[5] = 23;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 2 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] n+5 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 23 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] aspect
intin+2 intin[1] x_scale
intin+4 intin[2] y_scale
intin+6 intin[3] h_align
intin+8 intin[4] v_align
intin+10 intin[5..n+4] filename[0..n-1]
ptsin ptsin[0..3] xyarray[0..3]

7.8.1.23 v_clear_disp_list

Name: »Clear display list« - Clear the printer buffer list.
Opcode: 5 (Escape 22)
Syntax: void v_clear_disp_list ( int16_t handle );
Description: The call v_clear_disp_list clears the printer buffer on the workstation with the ID handle.

Note: A form-feed will not be performed by the call. The function should be called, say, if the user wants to cancel graphic output before the printout starts.
Return value: The function does not return a result.
Availability: Supported by all printer, plotter, camera, metafile and memory drivers.
Group: Special graphic functions
See also: Binding   GDOS   v_clrwk

7.8.1.24 Bindings for v_clear_disp_list

C: void v_clear_disp_list ( int16_t handle );
Binding:
void v_clear_disp_list (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 22;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function Opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 22 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.1.25 v_copies

Name: »Set number of copies« - Set number of copies of page to be printed.
Opcode: 5 (Escape 28)
Syntax: int16_t v_copies ( int16_t handle, int16_t count );
Description: The call v_copies determines the number of copies of the page to be printed. The following apply:
Parameter Meaning
   
handle Workstation identifier
count Number of copies (1 = normal), or -1 to obtain the number of copies set


Note: All pages up to the closing or the output device will be printed in the specified quantity.
Return value: The function returns the number of copies set.
Availability: GEM/3 Release 3.1, and otherwise only if contrl[4] contains a non-zero value.
Group: Special graphic functions
See also: Binding   v_orient   v_tray

7.8.1.26 Bindings for v_copies

C: int16_t v_copies ( int16_t handle, int16_t count );
Binding:
int16_t v_copies ( int16_t handle, int16_t count )
{
   intin[0] = count;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 28;
   contrl[6] = handle;

   vdi ();

   return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+10 contrl[5] 28 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] count
intout intout[0] Return Value


Note: If contrl[4] contains the value 0, the function is not available.

7.8.1.27 v_dspcur

Name: »Place graphic cursor at location« - Position the graphic cursor at the specified position.
Opcode: 5 (Escape 18)
Syntax: void v_dspcur ( int16_t handle, int16_t x, int16_t y );
Description: The call v_dspcur sets the graphic cursor (mouse pointer) at a specified position. The following apply:
Parameter Meaning
   
handle Workstation identifier
x New X-coordinate for mouse pointer
y New Y-coordinate for mouse pointer


Note: The function is only available on devices that permit position input, such as mouse, joystick or trackball, for instance.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Special graphic functions
See also: Binding

7.8.1.28 Bindings for v_dspcur

C: void v_dspcur ( int16_t handle, int16_t x, int16_t y );
Binding:
void v_dspcur (int16_t handle, int16_t x, int16_t y)
{
   ptsin[0] = x;
   ptsin[1] = y;

   contrl[0] = 5;
   contrl[1] = 1;
   contrl[3] = 0;
   contrl[5] = 18;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 1 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 18 # Escape/Sub-opcode
contrl+12 contrl[6] handle
ptsin ptsin[0] x
ptsin+2 ptsin[1] y

7.8.1.29 v_form_adv

Name: »Form advance« - Create a form-feed.
Opcode: 5 (Escape 20)
Syntax: void v_form_adv ( int16_t handle );
Description: The call v_form_adv creates a form-feed on the workstation with the ID handle.

Note: The data buffer and display list are not cleared by this; with a metafile a corresponding entry will be made in the file.
Return value: The function does not return a result.
Availability: Supported by all drivers.
Group: Special graphic functions
See also: Binding   v_clrwk

7.8.1.30 Bindings for v_form_adv

C: void v_form_adv ( int16_t handle );
Binding:
void v_form_adv (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 20;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 20 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.1.31 v_hardcopy

Name: »Hardcopy« - Create a hardcopy of the screen.
Opcode: 5 (Escape 17)
Syntax: void v_hardcopy ( int16_t handle );
Description: The call v_hardcopy invokes the ALT-HELP screen dump to create a hardcopy on the workstation with the ID handle (a printer or a similar device).

Note: This is a function of the screen driver, which accesses the XBIOS for this.
Return value: The function does not return a result.
Availability: Supported by screen drivers running under ST compatible resolutions.
Group: Special graphic functions
See also: Binding

7.8.1.32 Bindings for v_hardcopy

C: void v_hardcopy ( int16_t handle );
Binding:
void v_hardcopy (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 17;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 17 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.1.33 v_orient

Name: »Set orientation for output«
Opcode: 5 (Escape 27)
Syntax: int16_t v_orient ( int16_t handle, int16_t orientation );
Description: The call v_orient sets the output orientation for a device. The following apply:
Parameter Meaning
   
handle Workstation identifier
orientation Format:
-1 = Just return orientation
0 = Set to portrait
1 = Set to landscape


Note: The desired setting must be performed before any output is actioned.

If there is insufficient memory free to alter the orientation, the function returns the value -1; in that case the printer workstation must be closed with v_clswk.
Return value: The function returns the set output orientation, or -1 in case of error.
Availability: GEM/3 Release 3.1 and otherwise only if contrl[4] has a non-zero value.
Group: Special graphic functions
See also: Binding   v_copies   v_tray

7.8.1.34 Bindings for v_orient

C: int16_t v_orient ( int16_t handle, int16_t orientation );
Binding:
int16_t v_orient ( int16_t handle, int16_t orientation )
{
   intin[0] = orientation;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 27;
   contrl[6] = handle;

   vdi ();

   return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+10 contrl[5] 27 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] orientation
intout intout[0] Return Value


Note: If contrl[4] contains the value 0, the function is not available.

7.8.1.35 v_output_window

Name: »Output window« - Output window contents on the printer.
Opcode: 5 (Escape 21)
Syntax: void v_output_window ( int16_t handle, int16_t *xyarray );
Description: The call v_output_window outputs a specified portion of the current page, and permits a picture to be printed split up between various sheets. The following apply:
Parameter Meaning
   
handle Workstation identifier
xyarray[0] X-coordinate, and
xyarray[1] Y-coordinate of a corner of the output rectangle
xyarray[2] X-coordinate, and
xyarray[3] Y-coordinate of the diagonally opposite corner point


Notes: The difference to v_updwk consists of the fact that a section can be selected using the coordinate system of the printer.

Some printer drivers ignore the sides of the bounding box and print the entire width of the page.
Return value: The function does not return a result.
Availability: Supported by all printer and metafile drivers under any type of GDOS.
Group: Special graphic functions
See also: Binding   v_updwk

7.8.1.36 Bindings for v_output_window

C: void v_output_window ( int16_t handle, int16_t *xyarray );
Binding:
void v_output_window (int16_t handle, int16_t *xyarray)
{
   ptsin[0..3] = xyarray[0..3];

   contrl[0] = 5;
   contrl[1] = 2;
   contrl[3] = 0;
   contrl[5] = 21;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 2 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 21 # Escape/Sub-opcode
contrl+12 contrl[6] handle
ptsin ptsin[0..3] xyarray[0..3]

7.8.1.37 v_page_size

Name: »Set page size«
Opcode: 5 (Escape 37)
Syntax: int16_t v_page_size ( int16_t handle, int16_t page_id );
Description: The call v_page_size enables one to set the page format for an output device. The following apply:
Parameter Meaning
   
handle Workstation identifier
page_id Desired paper format:
0 = Default setting
1 = DIN A3
2 = DIN A4
3 = DIN A5
4 = DIN B5
16 = Letter size
17 = Half size
18 = Legal size
19 = Double size
20 = Broadsheet size


Note: If the requested size does not exist, the default setting will be used.
Return value: The function returns the set paper format. For a return value of -1 the workstation has to be closed, as insufficient free memory is available.
Availability: The function is only present of contrl[4] contains a non-zero value.
Group: Special graphic functions
See also: Binding   v_opnwk   vq_extnd

7.8.1.38 Bindings for v_page_size

C: int16_t v_page_size ( int16_t handle, int16_t page_id );
Binding:
int16_t v_page_size ( int16_t handle, int16_t page_id )
{
   intin[0] = page_id;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 37;
   contrl[6] = handle;

   vdi ();

   return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+10 contrl[5] 37 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] page_id
intout intout[0] Return Value


Note: If contrl[4] contains the value 0, the function is not available.

7.8.1.39 v_rmcur

Name: »Remove last graphic cursor«
Opcode: 5 (Escape 19)
Syntax: void v_rmcur ( int16_t handle );
Description: The call v_rmcur removes the last mouse cursor displayed on the workstation with the ID handle.

Note: This function should only be used in conjunction with v_dspcur when the mouse is moved manually. graf_mouse or v_hide_c should be used unless this is your intention.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Special graphic functions
See also: Binding

7.8.1.40 Bindings for v_rmcur

C: void v_rmcur ( int16_t handle );
Binding:
void v_rmcur (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 19;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 19 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.1.41 v_tray

Name: »Set input and output tray« - Set input and output tray of the printer.
Opcode: 5 (Escape 29)
Syntax: void v_tray ( int16_t handle, int16_t input, int16_t output, int16_t *set_input, int16_t *set_output );
Description: The call v_tray determines the printer slot or tray for the paper feed-in and feed-out. The following apply:
Parameter Meaning
   
handle Workstation identifier
input Paper feed:
-1 = Manual input
0 = Default input (tray 1)
1 = Tray 2
n = n-th optional tray or slot
output Paper output:
0 = Standard output (usually front)
1 = Output 2
n = n-th optional slot or tray
set_input Actually selected feed-in
set_output Actually set feed-out slot or tray


Note: If the requested tray does not exist, the standard tray will be selected (input 0 and output 0). The names of the input and output trays/slots can be determined with vq_tray_names.
Return value: The function does not return a result.
Availability: GEM/3 Release 3.1 and otherwise only if contrl[4] has a non-zero value. In NVDI this function is called v_trays.
Group: Special graphic functions
See also: Binding   vq_tray_names   v_copies   v_orient

7.8.1.42 Bindings for v_tray

C: void v_tray ( int16_t handle, int16_t input, int16_t output, int16_t *set_input, int16_t *set_output );
Binding:
void v_tray ( int16_t handle, int16_t input, int16_t output,
               int16_t *set_input, int16_t *set_output )
{
   intin[0] = input;
   intin[1] = output;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 2;
   contrl[5] = 29;
   contrl[6] = handle;

   vdi ();

   *set_input  = intout[0];
   *set_output = intout[1];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] 2 # Entry in intout
contrl+10 contrl[5] 29 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] input
intin+2 intin[1] output
intout intout[0] set_input
intout+2 intout[1] set_output

7.8.1.43 v_xbit_image

Opcode: 5 (Escape 101)
Syntax: void v_xbit_image(int16_t handle, BYTE *filename, int16_t aspect, int16_t x_scale, int16_t y_scale, int16_t h_align, int16_t v_align, int16_t rotation, int16_t foreground, int16_t background, int16_t xy[])
Description: The call v_xbit_image draws an image from a disk file onto the current device - with rotation and colouring.

Passed #ptsin=2, #intin=8 + length of filename.

INTIN holds:
  • 0 to ignore aspect ratio, 1 to preserve it
  • X axis scaling: 0 = fractional, 1 = integer
  • Y axis scaling: 0 = fractional, 1 = integer
  • Horizontal alignment: 0=left 1=centre 2=right
  • Vertical alignment: 0=top 1=centre 2=bottom
  • Rotation angle, 0 - 3600 in 1/10th degrees
  • Foreground colour if drawing a monochrome image on a colour device
  • Background colour
  • Filename, one character per word
Availability: GEM/3 and later
Group: Special graphic functions

7.8.2 Graphics tablet functions

This library contains functions to access a graphics tablet in an optimum manner. The following routines are available for this purpose:

vq_tdimensions Gets dimensions of the graphics tablet in 1/10 inch
vt_alignment Sets offsets to graphics tablet coordinate system
vt_axis Sets resolution of the graphics tablet
vt_origin Sets coordinate origin for graphics tablet
vt_resolution Sets resolution of the graphics tablet

See also: VDI workstations   Style guidelines

7.8.2.1 vq_tdimensions

Name: »Return tablet x and y dimensions« - Dimensions of the graphics tablets in 1/10-inch.
Opcode: 5 (Escape 84)
Syntax: void vq_tdimensions ( int16_t handle, int16_t *xdimension, int16_t *ydimension );
Description: The call vq_tdimensions returns the scanning dimensions of an attached graphics tablet in 1/10 inch. The following apply:
Parameter Meaning
   
handle Workstation identifier
xdimension Width in 1/10 inch on exit
ydimension Height in 1/10 inch on exit
Return value: The function does not return a result.
Availability: Supported by all tablet drivers.
Group: Graphics tablet functions
See also: Binding   GDOS   vq_tabstatus   vt_alignment   vt_resolution   vt_axis   vt_origin

7.8.2.2 Bindings for vq_tdimensions

C: void vq_tdimensions ( int16_t handle, int16_t *xdimension, int16_t *ydimension );
Binding:
void vq_tdimensions (int16_t handle, int16_t *xdimension,
                     int16_t *ydimension)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 84;
   contrl[6] = handle;

   vdi ();

   *xdimension = intout[0];
   *ydimension = intout[1];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 2 # Entry in intout
contrl+10 contrl[5] 84 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intout intout[0] xdimension
intout+2 intout[1] ydimension

7.8.2.3 vt_alignment

Name: »Set tablet alignment« - Align coordinate system of the graphics tablet.
Opcode: 5 (Escape 85)
Syntax: void vt_alignment ( int16_t handle, int16_t dx, int16_t dy );
Description: The call vt_alignment allows the specification of an offset to be applied to all coordinates output from a connected graphics tablet. The following apply:
Parameter Meaning
   
handle Workstation identifier
dx X-offset from origin
dy Y-offset from origin
Return value: The function does not return a result.
Availability: Supported by all tablet drivers.
Group: Graphics tablet functions
See also: Binding   GDOS   vq_tabstatus   vq_tdimensions   vt_resolution   vt_axis   vt_origin

7.8.2.4 Bindings for vt_alignment

C: void vt_alignment ( int16_t handle, int16_t dx, int16_t dy );
Binding:
void vt_alignment (int16_t handle, int16_t dx, int16_t dy)
{
   intin[0] = dx;
   intin[1] = dy;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 2;
   contrl[5] = 85;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 85 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] dx
intin+2 intin[1] dy

7.8.2.5 vt_axis

Name: »Set tablet axis resolution in lines« - Set the resolution of the graphics tablet in lines.
Opcode: 5 (Escape 82)
Syntax: void vt_axis ( int16_t handle, int16_t xres, int16_t yres, int16_t *xset, int16_t *yset );
Description: The call vt_axis sets the horizontal and vertical resolution for an attached graphics tablet in lines. The following apply:
Parameter Meaning
   
handle Workstation identifier
xres Desired resolution in lines in X-direction,
yres and in Y-direction
xset Actual resolution in lines in X-direction,
yset and in Y-direction
Return value: The function does not return a result.
Availability: Supported by all tablet drivers.
Group: Graphics tablet functions
See also: Binding   GDOS   vq_tabstatus   vt_alignment   vt_resolution   vt_origin   vq_tdimensions

7.8.2.6 Bindings for vt_axis

C: void vt_axis ( int16_t handle, int16_t xres, int16_t yres, int16_t *xset, int16_t *yset );
Binding:
void vt_axis (int16_t handle, int16_t xres, int16_t yres,
              int16_t *xset, int16_t *yset)
{
   intin[0] = xres;
   intin[1] = yres;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 2;
   contrl[5] = 82;
   contrl[6] = handle;

   vdi ();

   *xset = intout[0];
   *yset = intout[1];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] 2 # Entry in intout
contrl+10 contrl[5] 82 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] xres
intin+2 intin[1] yres
intout intout[0] xset
intout+2 intout[1] yset

7.8.2.7 vt_origin

Name: »Set tablet X and Y origin« - Set coordinate origin for graphics tablet.
Opcode: 5 (Escape 83)
Syntax: void vt_origin ( int16_t handle, int16_t xorigin, int16_t yorigin );
Description: The call vt_origin sets the point of origin for the coordinate system (top left corner) of an attached graphics tablet. The following apply:
Parameter Meaning
   
handle Workstation identifier
xorigin X-coordinate, and
yorigin Y-coordinate of the top left corner
Return value: The function does not return a result.
Availability: Supported by all tablet drivers.
Group: Graphics tablet functions
See also: Binding   GDOS   vq_tabstatus   vt_alignment   vt_resolution   vt_axis   vq_tdimensions

7.8.2.8 Bindings for vt_origin

C: void vt_origin ( int16_t handle, int16_t xorigin, int16_t yorigin );
Binding:
void vt_origin (int16_t handle, int16_t xorigin,
                int16_t yorigin)
{
   intin[0] = xorigin;
   intin[1] = yorigin;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 2;
   contrl[5] = 83;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] 2 # Entry in intout
contrl+10 contrl[5] 83 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] xorigin
intin+2 intin[1] yorigin

7.8.2.9 vt_resolution

Name: »Set tablet axis resolution in lines/inch« - Set the resolution of the graphics tablet in lines per inch.
Opcode: 5 (Escape 81)
Syntax: void vt_resolution ( int16_t handle, int16_t xres, int16_t yres, int16_t *xset, int16_t *yset );
Description: The call vt_resolution sets the horizontal and vertical resolution on an attached graphics tablet in lines per inch. The following apply:
Parameter Meaning
   
handle Workstation identifier
xres Resolution in lines per inch (lpi) in X-direction, and in
yres Y-direction
xset Actually set resolution in X-direction, and
yset Y-direction
Return value: The function does not return a result.
Availability: Supported by all tablet drivers.
Group: Graphics tablet functions
See also: Binding   GDOS   vq_tabstatus   vt_alignment   vt_axis   vt_origin   vq_tdimensions

7.8.2.10 Bindings for vt_resolution

C: void vt_resolution ( int16_t handle, int16_t xres, int16_t yres, int16_t *xset, int16_t *yset );
Binding:
void vt_resolution (int16_t handle, int16_t xres, int16_t yres,
                    int16_t *xset, int16_t *yset)
{
   intin[0] = xres;
   intin[1] = yres;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 2;
   contrl[5] = 81;
   contrl[6] = handle;

   vdi ();

   *xset = intout[0];
   *yset = intout[1];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] 2 # Entry in intout
contrl+10 contrl[5] 81 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] xres
intin+2 intin[1] yres
intout intout[0] xset
intout+2 intout[1] yset

7.8.3 Metafile functions

This library contains functions that are indispensable for creating metafiles. In all, the following routines are available:

v_meta_extents Calculates dimensions of a metafile
v_write_meta Stores graphic primitives in a metafile
vm_coords Sets new coordinate system for a metafile
vm_filename Renames a metafile
vm_pagesize Sets physical page size for a metafile

Note: The main purpose of a metafile lies in standardized data exchange between various GEM systems.

See also:
Metafile format   VDI workstations   Style guidelines   VDI fundamentals

7.8.3.1 vm_coords

Name: »VDI metafile coordinates« - Custom coordinate system for metafiles.
Opcode: 5 (Escape 99, Opcode 1)
Syntax: void vm_coords ( int16_t handle, int16_t llx, int16_t lly, int16_t urx, int16_t ury );
Description: The call vm_coords sets the coordinate system used for the page of a metafile. The following apply:
Parameter Meaning
   
handle Workstation identifier
llx X-coordinate, and
lly Y-coordinate (lower left)
urx X-coordinate, and
ury Y-coordinate (upper right)


Notes: With this function one must note in which coordinate type (NDC or RC) the metafile was opened, and if necessary the Y-values have to be adapted.

This function permits use of almost any coordinate system with limit of (-32768, -32768), (32767, 32767).
Return value: The function does not return a result.
Availability: Supported by all metafile drivers.
Group: Metafile functions
See also: Binding   v_write_meta   Metafile format   sub-opcodes

7.8.3.2 Bindings for vm_coords

C: void vm_coords ( int16_t handle, int16_t llx, int16_t lly, int16_t urx, int16_t ury );
Binding:
void vm_coords (int16_t handle, int16_t llx, int16_t lly,
                int16_t urx, int16_t ury)
{
   intin[0] = 1;
   intin[1] = llx;
   intin[2] = lly;
   intin[3] = urx;
   intin[4] = ury;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 5;
   contrl[5] = 99;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 5 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 99
contrl+12 contrl[6] handle
intin intin[0] 1 # Sub-opcode
intin+2 intin[1] llx
intin+4 intin[2] lly
intin+6 intin[3] urx
intin+8 intin[4] ury

7.8.3.3 vm_filename

Name: »Change GEM VDI file name« - Change the name of a metafile.
Opcode: 5 (Escape 100)
Syntax: void vm_filename ( int16_t handle, CONST int8_t *filename );
Description: The call vm_filename renames a metafile from the default GEMFILE.GEM to another name while retaining the extension GEM. The following apply:
Parameter Meaning
   
handle Workstation identifier
filename New name of the metafile (NULL-terminated)


Note: The parameter filename can also contain a path name with drive identifier. If the function is not called immediately after an v_opnwk call, then it will have no effect. A possibly opened metafile will be closed.

As older metafile drivers (in contrast to NVDI drivers) may not delete the source file "GEMFILE.GEM" which is created in the current directory, the application should take over this task itself.
Return value: The function does not return a result.
Availability: Supported by all metafile drivers.
Group: Metafile functions
See also: Binding   GDOS   v_opnwk   Metafile format   sub-opcodes

7.8.3.4 Bindings for vm_filename

C: void vm_filename ( int16_t handle, CONST int8_t *filename );
Binding:
void vm_filename (int16_t handle, CONST int8_t *filename)
{
   int16_t *tmp;

   tmp = intin;
   while (*tmp++ = *filename++)
      ;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = ((int16_t) (tmp-intin)-1);
   contrl[5] = 100;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] n # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 100 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0..n-1] filename[0..n-1]

7.8.3.5 vm_pagesize

Name: »VDI page size« - Set the physical page size for metafiles.
Opcode: 5 (Escape 99, Opcode 0)
Syntax: void vm_pagesize ( int16_t handle, int16_t pgwidth, int16_t pgheight );
Description: The call vm_pagesize sets the metafile's source page size in 1/10 mm. The following apply:
Parameter Meaning
   
handle Workstation identifier
pgwidth Page width in 1/10 mm
pgheight Page height in 1/10 mm


Note: As the width and height of a page may be set separately, it is also possible to create graphics in landscape format (width greater than the height).
Return value: The function does not return a result.
Availability: Supported by all metafile drivers.
Group: Metafile functions
See also: Binding   v_write_meta   Metafile format   sub-opcodes

7.8.3.6 Bindings for vm_pagesize

C: void vm_pagesize ( int16_t handle, int16_t pgwidth, int16_t pgheight );
Binding:
void vm_pagesize (int16_t handle, int16_t pgwidth,
                  int16_t pgheight)
{
   intin[0] = 0;
   intin[1] = pgwidth;
   intin[2] = pgheight;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 3;
   contrl[5] = 99;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 3 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 99
contrl+12 contrl[6] handle
intin intin[0] 0 # Sub-opcode
intin+2 intin[1] pgwidth
intin+4 intin[2] pgheight

7.8.3.7 v_meta_extents

Name: »Update metafile extents« - Update the size information for a metafile.
Opcode: 5 (Escape 98)
Syntax: void v_meta_extents ( int16_t handle, int16_t min_x, int16_t min_y, int16_t max_x, int16_t max_y );
Description: The call v_meta_extents updates the size information in the header of a metafile. The following apply:
Parameter Meaning
   
handle Workstation identifier
min_x Minimum X-value, and
min_y Minimum Y-value of the smallest bounding box (the top left corner)
max_x Maximum X-value, and
max_y Maximum Y-value of the smallest bounding box (the bottom left corner)


Notes: The size information can be used to obtain quickly the minimum or maximum dimensions of all the primitives stored in the metafile.

The parameters sent to this call should be specified in whatever coordinate system the metafile is using at the time.
Return value: The function does not return a result.
Availability: Supported by all metafile drivers.
Group: Metafile functions
See also: Binding   GDOS   vm_filename   v_write_meta   Metafile format

7.8.3.8 Bindings for v_meta_extents

C: void v_meta_extents ( int16_t handle, int16_t min_x, int16_t min_y, int16_t max_x, int16_t max_y );
Binding:
void v_meta_extents (int16_t handle, int16_t min_x,
                     int16_t min_y, int16_t max_x, int16_t max_y)
{
   ptsin[0] = min_x;
   ptsin[1] = min_y;
   ptsin[2] = max_x;
   ptsin[3] = max_y;

   contrl[0] = 5;
   contrl[1] = 2;
   contrl[3] = 0;
   contrl[5] = 98;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 2 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 98 # Escape/Sub-opcode
contrl+12 contrl[6] handle
ptsin ptsin[0] min_x
ptsin+2 ptsin[1] min_y
ptsin+4 ptsin[2] max_x
ptsin+6 ptsin[3] max_y

7.8.3.9 v_write_meta

Name: »Write metafile item« - Write an object to a metafile.
Opcode: 5 (Escape 99)
Syntax: void v_write_meta ( int16_t handle, int16_t num_intin, int16_t *a_intin, int16_t num_ptsin, int16_t *a_ptsin );
Description: The call v_write_meta permits the marking of a parameter written to a metafile with an opcode as a user-defined graphic object. The following apply:
Parameter Meaning
   
handle Workstation identifier
num_intin Number of values in intin array (0 - 127)
num_ptsin Number of values in ptsin array(0 - 127)
a_intin[0] Sub-opcode (user-defined)
a_intin[1]  
:  
:  
a_intin[num_intin-1] User-defined information
a_ptsin[0]  
:  
:  
a_ptsin[num_ptsin-1] User-defined information


Note: Sub-opcodes 0 to 100 are reserved; some have been pre-defined:

a_intin Meaning
10 Start group
11 End group
49 Set no line style
50 Set attribute shadow on
51 Set attribute shadow off
80 Start draw area type primitive
81 End draw area type primitive
Return value: The function does not return a result.
Availability: Supported by all metafile drivers.
Group: Metafile functions
See also: Binding   GDOS   v_meta_extents   Metafile format   sub-opcodes

7.8.3.10 Bindings for v_write_meta

C: void v_write_meta ( int16_t handle, int16_t num_intin, int16_t *a_intin, int16_t num_ptsin, int16_t *a_ptsin );
Binding:
void v_write_meta (int16_t handle, int16_t num_intin,
                   int16_t *a_intin, int16_t num_ptsin,
                   int16_t *a_ptsin)
{
   intin[0..num_intin-1] = a_intin[0..num_intin-1];
   ptsin[0..num_ptsin-1] = a_ptsin[0..num_ptsin-1];

   contrl[0] = 5;
   contrl[1] = num_ptsin;
   contrl[3] = num_intin;
   contrl[5] = 99;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] num_ptsin # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] num_intin # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 99 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] User-defined sub-opcode
intin+2 intin[1..n] User-defined information
ptsin ptsin[0..m] User-defined information

7.8.4 Polaroid functions

This library contains functions to access a Polaroid image recorder. The following routines are available for this purpose:

vqp_error Gets error codes of the Polaroid driver
vqp_filmname Gets name from a film number
vqp_films Gets available film types
vqp_state Gets status of the Polaroid driver
vsc_expose Switches on/off preview option for camera
vsp_film Sets film type and exposure time
vsp_message Suppresses or permits error-messages of the Polaroid driver
vsp_save Saves settings of the Polaroid driver
vsp_state Resets Polaroid driver

Note: Drivers for the Polaroid palette are non-existent at the time of writing. The functions vsp_film, vqp_filmname and vsc_expose were introduced with PC-GEM Version 2.0, and replace the other six routines from GEM 1.x.

See also: VDI workstations   Style guidelines

7.8.4.1 vqp_error

Name: »Palette error inquire« - Return the number of an error that has occurred.
Opcode: 5 (Escape 96)
Syntax: int16_t vqp_error ( int16_t handle );
Description: The call vqp_error obtains the last error occurring in connection with the Polaroid image recorder with the ID handle.
Return value: The function returns:
Value Meaning
   
0 No error
1 Shutter open
2 No port selected
3 Palette not available at chosen port
4 Connection broken off
5 Operating system does not allow memory allocation
6 Insuficient buffer memory
7 No free memory
8 Workstation driver file missing
9 Workstation driver file has an invalid format
10 Film at end
Availability: This function is no longer available from PC-GEM Version 2.0 onwards.
Group: Polaroid functions
See also: Binding   GDOS

7.8.4.2 Bindings for vqp_error

C: int16_t vqp_error ( int16_t handle );
Binding:
int16_t vqp_error ( int16_t handle );
{
   intin[0] = palette;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 96;
   contrl[6] = handle;

   vdi ();

   return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+10 contrl[5] 96 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intout intout[0] Return Value

7.8.4.3 vqp_filmname

Name: »Inquire camera film name« - Obtain the name of a given film number.
Opcode: 5 (Escape 92)
Syntax: int16_t vqp_filmname ( int16_t handle, int16_t index, int8_t *name );
Description: The call vqp_filmname returns the corresponding name belonging to a film number. The following apply:
Parameter Meaning
   
handle Workstation identifier
index Number of the film type
name Name of the film (NULL-terminated)


Note: With an invalid film number the return will be a NULL-string.
Return value: The function returns the value 0 if an invalid film number was passed.
Availability: The function is available only from PC-GEM Version 2.0 onwards.
Group: Polaroid functions
See also: Binding   GDOS

7.8.4.4 Bindings for vqp_filmname

C: int16_t vqp_filmname ( int16_t handle, int16_t index, int8_t *name );
Binding:
int16_t vqp_filmname (int16_t handle, int16_t index,
                      int8_t *name)
{
   int16_t tmp;

   intin[0] = index;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 92;
   contrl[6] = handle;

   vdi ();

   for (tmp = 0; tmp < contrl[4]; tmp++)
      name[tmp] = intout[tmp];

   return ( contrl[4] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] status # Entry in intout
contrl+10 contrl[5] 92 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] index
intout intout[0..24] name[0..24]

7.8.4.5 vqp_films

Name: »Inquire palette film types« - Obtain information about a film.
Opcode: 5 (Escape 91)
Syntax: void vqp_films ( int16_t handle, int8_t *film_names );
Description: The call vqp_films obtains information about a film. The following apply:
Parameter Meaning
   
handle Workstation identifier
film_names Name, manufacturer and sensitivity of the film


Note: The parameter film_names should point to a 126 byte sized buffer in which 5 entries of 25 characters each are stored.
Return value: The function does not return a result.
Availability: This function is no longer available from PC-GEM Version 2.0 onwards.
Group: Polaroid functions
See also: GDOS

7.8.4.6 vqp_state

Name: »Inquire palette driver state« - Obtain the device state of the Polaroid image recorder.
Syntax: void vqp_state ( int16_t handle, int16_t *port, int8_t *film_name, int16_t *lightness, int16_t *interlace, int16_t *planes, int16_t *indexes );
Description: The call vqp_state obtains the status of a Polaroid image recorder. The following apply:
Parameter Meaning
   
handle Workstation identifier
port Number of the port (0 = first port)
film_name Number of the film name (0 to 4)
lightness Brightness (-3 to 3, where each step corresponds to a third of a stop)
interlace Image is scanned with (1) or without (0) interlace
planes Number of colours = 2^planes, where planes lies between 1 and 4
indexes Specifies the colours of the colour palette. 16 bytes of memory space is required. Each colour is identified by a number (for the rows of the colour matrix) and a letter between A and H (for the column of the colour matrix).
Return value: The function does not return a result.
Availability: This function is no longer available from PC-GEM Version 2.0 onwards.
Group: Polaroid functions
See also: GDOS   vsp_state   vsp_save   vsp_message   vqp_films

7.8.4.7 vsc_expose

Name: »Disable or enable film exposure for frame preview« - Switch on/off exposure for previews with an image recorder camera.
Opcode: 5 (Escape 93)
Syntax: void vsc_expose ( int16_t handle, int16_t state );
Description: The call vsc_expose permits switching on/off the exposure for image recorders with a preview option. The following apply:
Parameter Meaning
   
handle Workstation identifier
state Exposure:
0 = Switch off
<> 0 = Switch on
Return value: The function does not return a result.
Availability: This function is only available from PC-GEM Version 2.0 onwards.
Group: Polaroid functions
See also: Binding   GDOS   vsp_save   vqp_state   vsp_state   vqp_films   vsp_message

7.8.4.8 Bindings for vsc_expose

C: void vsc_expose ( int16_t handle, int16_t state );
Binding:
void vsc_expose (int16_t handle, int16_t state)
{
   intin[0] = state;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 93;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 93 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] state

7.8.4.9 vsp_film

Name: »Set camera film type and exposure time«
Opcode: 5 (Escape 91)
Syntax: void vsp_film ( int16_t handle, int16_t index, int16_t lightness );
Description: The call vsp_film specifies the film type and the exposure time for the image recorder. The following apply:
Parameter Meaning
   
handle Workstation identifier
index Number of the film type
lightness Exposure time:
-3 = Half
0 = Normal
3 = Double


Note: With increasing value of the parameter lightness the exposure is increased by one third of a stop. The valid indices for index can be obtained with vqp_filmname.
Return value: The function does not return a result.
Availability: The function is only available from PC-GEM Version 2.0 onwards.
Group: Polaroid functions
See also: Binding   GDOS

7.8.4.10 Bindings for vsp_film

C: void vsp_film ( int16_t handle, int16_t index, int16_t lightness );
Binding:
void vsp_film (int16_t handle, int16_t index,
               int16_t lightness)
{
   intin[0] = index;
   intin[1] = lightenss;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 2;
   contrl[5] = 91;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 91 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] index
intin+2 intin[1] lightness

7.8.4.11 vsp_message

Name: »Suppress palette message« - Suppress error-messages of the Polaroid image recorder.
Syntax: void vsp_message ( int16_t handle );
Description: The call vsp_message suppresses error-messages of the Polaroid image recorder with the ID handle.
Return value: The function does not return a result.
Availability: The function is available only from PC-GEM Version 2.0 onwards.
Group: Polaroid functions
See also: GDOS   vqp_error

7.8.4.12 vsp_save

Name: »Save palette driver state« - Save the device state of the Polaroid image recorder.
Syntax: void vsp_save ( int16_t handle );
Description: The call vsp_save saves the status of a Polaroid image recorder with the ID handle.
Return value: The function does not return a result.
Availability: This function is no longer available from PC-GEM Version 2.0 onwards.
Group: Polaroid functions
See also: GDOS   vqp_state   vsp_state   vsp_message   vqp_films   vsc_expose

7.8.4.13 vsp_state

Name: »Set palette driver state« - Set the state of the Polaroid recorder.
Syntax: void vsp_state ( int16_t handle, int16_t port, int16_t film_num, int16_t lightness, int16_t interlace, int16_t planes, int16_t *indexes );
Description: The call vsp_state sets the output status of a Polaroid image recorder. The following apply:
Parameter Meaning
   
handle Workstation identifier
port Number of the port (0 = first port)
film_num Number of the film name (0 to 4)
lightness Brightness (-3 to 3, where each step corresponds to a third of a stop)
interlace Image is scanned with (1) or without (0) interlace
planes Number of colours = 2^planes, where planes lies between 1 and 4
indexes Specifies the colours of the colour palette. 16 bytes of memory space is required. Each colour is identified by a number (for the rows of the colour matrix) and a letter between A and H (for the column of the colour matrix).
Return value: The function does not return a result.
Availability: This function is no longer available from PC-GEM Version 2.0 onwards.
Group: Polaroid functions
See also: GDOS   vsc_expose   vqp_state   vsp_save   vsp_message   vqp_films

7.8.5 Special functions

This library contains functions for some special purposes that cannot be assigned to any of the other groups of Escape functions. The following routines are available:

v_escape2000 Special function for the ATARI page-printer
v_fontinit Selects custom system font
v_offset Sets offset to top screen edge
v_sound Generates a tone
vs_mute Switches tone generation on/off

See also: VDI workstations   Style guidelines

7.8.5.1 v_escape2000

Name: »Escape 2000« - Special function for ATARI page-printer.
Opcode: 5 (Escape 2000)
Syntax: void v_escape2000 ( int16_t handle, int16_t times );
Description: The call v_escape2000 prints any number of extra copies of the current page. The following apply:
Parameter Meaning
   
handle Workstation identifier
times Number of additional copies


Note: The function works only in connection with the Atari SLM laser printers; therefore it is better to fall back to the function v_copies.
Return value: The function does not return a result.
Availability: Supported only with some laser printer drivers (for instance the Atari SLM laser printer driver) under some forms of GDOS.
Group: Special functions
See also: Binding   GDOS

7.8.5.2 Bindings for v_escape2000

C: void v_escape2000 ( int16_t handle, int16_t times );
Binding:
void v_escape2000 (int16_t handle, int16_t times)
{
   intin[0] = times;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 2000;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 2000 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] times

7.8.5.3 v_fontinit

Name: »Init system font« - Initializes a system font.
Opcode: 5 (Escape 102)
Syntax: void v_fontinit ( int16_t handle, int16_t fh_high, int16_t fh_low );
Description: The call v_fontinit installs a specified font as the system font. The following apply:
Parameter Meaning
   
handle Workstation identifier
fh_high Address of the font header (high)
fh_low Address of the font header (low)


Note: The function is described in no official documentation - use it at your own risk! Some attempts have shown that the character width has to be a constant eight pixels and the font must be in the Motorola (big-endian) format.
Return value: The function does not return a result.
Availability: All TOS versions; ROM screen driver.
Group: Special functions
See also: Binding   Header for bitmap GDOS fonts

7.8.5.4 Bindings for v_fontinit

C: void v_fontinit ( int16_t handle, int16_t fh_high, int16_t fh_low );
Binding:
void v_fontinit (int16_t handle, int16_t fh_high,
                 int16_t fh_low)
{
   intin[0] = fh_high;
   intin[1] = fh_low;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 2;
   contrl[5] = 102;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 102 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] fh_high
intin+2 intin[1] fh_low


Note: The pointer to the font header will be stored in the fields intin[0..1] here.

7.8.5.5 v_offset

Name: »Set screen offset« - Set the top screen margin.
Opcode: 5 (Escape 101)
Syntax: void v_offset ( int16_t handle, int16_t offset );
Description: The call v_offset sets the offset in raster lines to the start of the logical screen. The following apply:
Parameter Meaning
   
handle Workstation identifier
offset Number of raster lines below the top screen edge up to the start of the logical screen


Note: The function is described in no official documentation - use it at your own risk!
Return value: The function does not return a result.
Availability: ROM screen driver.
Group: Special functions
See also: Binding

7.8.5.6 Bindings for v_offset

C: void v_offset ( int16_t handle, int16_t offset );
Binding:
void v_offset (int16_t handle, int16_t offset)
{
   intin[0] = offset;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 101;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 101 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] offset

7.8.5.7 v_sound

Name: »Generate specified tone«
Opcode: 5 (Escape 61)
Syntax: void v_sound ( int16_t handle, int16_t frequency, int16_t duration );
Description: The call v_sound generates a tone of a specified length and frequency. The following apply:
Parameter Meaning
   
handle Workstation identifier
frequency Tone frequency in Hertz
duration Tone length in timer ticks
Return value: The function does not return a result.
Availability: The function is only available under PC-GEM as of Version 2.0.
Group: Special functions
See also: Binding   GDOS   vs_mute

7.8.5.8 Bindings for v_sound

C: void v_sound ( int16_t handle, int16_t frequency, int16_t duration );
Binding:
void v_sound (int16_t handle, int16_t frequency,
              int16_t duration)
{
   intin[0] = frequency;
   intin[1] = duration;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 2;
   contrl[5] = 61;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 61 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] frequency
intin+2 intin[1] duration

7.8.5.9 vs_mute

Name: »Set/clear tone muting flag«
Opcode: 5 (Escape 62)
Syntax: int16_t vs_mute ( int16_t handle, int16_t action );
Description: The call vs_mute sets or clears the tone flag, or returns it status. The following apply:
Parameter Meaning
   
handle Workstation identifier
action Desired action:
-1 = Inquire status
 0 = Tone generation on
 1 = Tone generation off
Return value: The function returns the status of the tone generation.
Availability: The function is available only under PC-GEM as of Version 2.0.
Group: Special functions
See also: Binding   GDOS   v_sound

7.8.5.10 Bindings for vs_mute

C: int16_t vs_mute ( int16_t handle, int16_t action );
Binding:
int16_t vs_mute (int16_t handle, int16_t action)
{
   intin[0] = action;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 62;
   contrl[6] = handle;

   vdi ();

   return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 62 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] action
intout intout[0] Return Value

7.8.6 Text functions

This library contains functions for control of the alphanumeric screen; the following routines are available for this purpose:

v_alpha_text Outputs text in text mode to printer or metafile
v_curdown Moves text cursor one row down
v_curhome Moves text cursor to top left corner
v_curleft Moves text cursor one column left
v_curright Moves text cursor one column right
v_curtext Outputs text to screen from text cursor position on
v_curup Moves text cursor one row up
v_eeol Clears screen from text cursor to end of line
v_eeos Clears screen from text cursor to end of screen
v_enter_cur Switches on text mode
v_exit_cur Exits text mode
v_rvoff Switches off inverse video
v_rvon Switches on inverse video
vq_chcells Gets number of rows and columns of the text screen
vq_curaddress Gets row and column of current text cursor
vs_curaddress Positions text cursor at given row and column

See also: VDI workstations   Style guidelines

7.8.6.1 vq_chcells

Name: »Inquire addressable alpha character cells« - Obtain the number of rows and columns of a workstation.
Opcode: 5 (Escape 1)
Syntax: void vq_chcells ( int16_t handle, int16_t *rows, int16_t *columns );
Description: The call vq_chcells obtains the number of rows and columns that can be accessed with the alpha cursor. The following apply:
Parameter Meaning
   
handle Workstation identifier
rows Number of rows
columns Number of columns


Note: A value of 0 in the parameters rows or columns means that addressing is not possible.
Return value: The function does not return a result.
Availability: Supported by all screen and printer drivers.
Group: Text functions
See also: Binding   v_enter_cur

7.8.6.2 Bindings for vq_chcells

C: void vq_chcells ( int16_t handle, int16_t *rows, int16_t *columns );
Binding:
void vq_chcells (int16_t handle, int16_t *rows,
                 int16_t *columns)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 1;
   contrl[6] = handle;

   vdi ();

   *rows    = intout[0];
   *columns = intout[1];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 2 # Entry in intout
contrl+10 contrl[5] 1 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intout intout[0] rows
intout+2 intout[1] columns

7.8.6.3 vq_curaddress

Name: »Inquire current alpha cursor address«
Opcode: 5 (Escape 15)
Syntax: void vq_curaddress ( int16_t handle, int16_t *row, int16_t *column );
Description: The call vq_curaddress obtains the current alpha text cursor position.
Parameter Meaning
   
handle Workstation identifier
row Row number (1 to the maximum number of rows)
column Column number (1 to the maximum number of columns)
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur

7.8.6.4 Bindings for vq_curaddress

C: void vq_curaddress ( int16_t handle, int16_t *row, int16_t *column );
Binding:
void vq_curaddress (int16_t handle, int16_t *row,
                    int16_t *column)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 15;
   contrl[6] = handle;

   vdi ();

   *row    = intout[0];
   *column = intout[1];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 2 # Entry in intout
contrl+10 contrl[5] 15 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intout intout[0] row
intout+2 intout[1] column

7.8.6.5 v_alpha_text

Name: »Output alpha text« - Output a line of alpha text in text mode to a printer or metafile.
Opcode: 5 (Escape 25)
Syntax: void v_alpha_text ( int16_t handle, int8_t *string );
Description: The call v_alpha_text outputs a line of alpha text in text mode to a printer (or metafile) at the current position of the printhead. The following apply:
Parameter Meaning
   
handle Workstation identifier
string Address of text string (NULL-termminated)


Note: The output is not made in graphic mode. Two special BYTE codes may be embedded in the text for control functions that are standardized for all printers ('DC2' corresponds to ASCII 18):
Code Meaning
   
DC2 0 Enable bold print
DC2 1 Disable bold print
DC2 2 Enable italic print
DC2 3 Disable italic print
DC2 4 Enable underlining
DC2 5 Disable underlining
DC2 6 Enable superscript
DC2 7 Disable superscript
DC2 8 Enable subscript
DC2 9 Disable subscript
DC2 A Enable NLQ mode
DC2 B Disable NLQ mode
DC2 C Enable wide printing
DC2 D Disable wide printing
DC2 E Enable light printing
DC2 F Disable light printing
DC2 G  
:  
:  
DC2 V Reserved, will be ignored
DC2 W Switch to pica printing (10 cpi)
DC2 X Switch to elite printing (12 cpi)
DC2 Y Toggle compressed printing
DC2 Z Toggle proportional printing


In addition, form-feed with the ASCII value 12 is supported. Under PC-GEM, graphics can be taken into account as well; the syntax in this case is:

(ESC)(ESC)GEM,x,y,w,h,C:\pathname\filename.img

The parameters x, y, w and h for this are to be given in character units relative to the current cursor position.
Return value: The function does not return a result.
Availability: Supported by all printer and metafile drivers.
Group: Text functions
See also: Binding   OUT file format

7.8.6.6 Bindings for v_alpha_text

C: void v_alpha_text ( int16_t handle, int8_t *string );
Binding:
void v_alpha_text (int16_t handle, int8_t *string)
{
   int16_t *tmp;

   tmp = intin;
   while (*tmp++ = *string++)
      ;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = ((int16_t) (tmp-intin)-1);
   contrl[5] = 25;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] n # Entry in intin
contrl+8 contrl[4] 5 # Entry in intout
contrl+10 contrl[5] 25 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0..n-1] string[0..n-1]

7.8.6.7 v_curaddress

Name: »Direct alpha cursor address« - Set the alpha cursor to the specified position.
Opcode: 5 (Escape 11)
Syntax: void v_curaddress ( int16_t handle, int16_t row, int16_t column );
Description: The call v_curaddress moves the alpha cursor to a given column and row.
Parameter Meaning
   
handle Workstation identifier
row Row number (1 to maximum number of rows)
column Column number (1 to maximum number of columns)


Note: If addresses above the maximum limit are specified, the function will assume the nearest valid value.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur

7.8.6.8 Bindings for v_curaddress

C: void v_curaddress ( int16_t handle, int16_t row, int16_t column );
void vs_curaddress ( int16_t handle, int16_t row, int16_t column );
Binding:
void v_curaddress  (int16_t handle, int16_t row, int16_t column)
void vs_curaddress (int16_t handle, int16_t row, int16_t column)
{
   intin[0] = row;
   intin[1] = column;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 2;
   contrl[5] = 11;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 11 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] row
intin+2 intin[1] column

7.8.6.9 v_curdown

Name: »Alpha cursor down« - Move the alpha cursor down by one row.
Opcode: 5 (Escape 5)
Syntax: void v_curdown ( int16_t handle );
Description: The call v_curdown moves the alpha cursor on the workstation with the ID handle one row or line down.

Note: If the cursor is already in the last row, nothing happens.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur

7.8.6.10 Bindings for v_curdown

C: void v_curdown ( int16_t handle );
Binding:
void v_curdown (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 5;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 5 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.6.11 v_curhome

Name: »Home alpha cursor« - Move the alpha cursor to the
Opcode: 5 (Escape 8)
Syntax: void v_curhome ( int16_t handle );
Description: The call v_curhome moves the alpha cursor on the workstation with the ID handle to the 'home' position.

Note: The 'home' position normally means the position at the top left corner of the screen.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur

7.8.6.12 Bindings for v_curhome

C: void v_curhome ( int16_t handle );
Binding:
void v_curhome (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 8;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 8 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.6.13 v_curleft

Name: »Alpha cursor left« - Move the alpha cursor left by one character.
Opcode: 5 (Escape 7)
Syntax: void v_curleft ( int16_t handle );
Description: The call v_curleft moves the alpha cursor on the workstation with the ID handle one column to the left.

Note: If it is already in the first column, nothing happens.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur

7.8.6.14 Bindings for v_curleft

C: void v_curleft ( int16_t handle );
Binding:
void v_curleft (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 7;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 7 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.6.15 v_curright

Name: »Alpha cursor right« - Move the alpha cursor right by one character.
Opcode: 5 (Escape 6)
Syntax: void v_curright ( int16_t handle );
Description: The call moves v_curright the alpha cursor on the workstation with the ID handle one column to the right.

Note: If the cursor is already in the last column, nothing happens.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur

7.8.6.16 Bindings for v_curright

C: void v_curright ( int16_t handle );
Binding:
void v_curright (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 6;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 6 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.6.17 v_curtext

Name: »Output cursor addressable alpha text« - Output a line of text to the screen from the alpha cursor onwards.
Opcode: 5 (Escape 12)
Syntax: void v_curtext ( int16_t handle, int8_t *string );
Description: The call v_curtext outputs a line of text to the screen in text mode from the current cursor position onwards. The following apply:
Parameter Meaning
   
handle Workstation identifier
string Pointer to text string (max. 127 chars.)


The cursor is advanced by one position for each character output (alpha mode).

Note: Text output with this function can be faster than via GEMDOS.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur   v_curup   v_curdown   v_curright   v_curleft   v_curhome   vs_curaddress

7.8.6.18 Bindings for v_curtext

C: void v_curtext ( int16_t handle, int8_t *string );
Binding:
void v_curtext (int16_t handle, int8_t *string)
{
   int16_t *tmp;

   tmp = intin;
   while (*tmp++ = *string++)
      ;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = ((int16_t) (tmp-intin)-1);
   contrl[5] = 12;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] n # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 12 # Escape/Sub-opcode
contrl+12 contrl[6] handle
intin intin[0..n-1] string[0..n-1]

7.8.6.19 v_curup

Name: »Alpha cursor up« - Move the alpha cursor up by one row.
Opcode: 5 (Escape 4)
Syntax: void v_curup ( int16_t handle );
Description: The call v_curup moves the alpha cursor on the workstation with the ID handle one row or line upwards.

Note: If the cursor is already in the first row, nothing happens.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur

7.8.6.20 Bindings for v_curup

C: void v_curup ( int16_t handle );
Binding:
void v_curup (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 4;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 4 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.6.21 v_eeol

Name: »Erase to end of alpha text line« - Clear the text line from the alpha cursor onwards.
Opcode: 5 (Escape 10)
Syntax: void v_eeol ( int16_t handle );
Description: The call v_eeol clears the current text line from the current text cursor position rightwards on the workstation with the ID handle.

Note: The position of the cursor will not be altered by this.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur

7.8.6.22 Bindings for v_eeol

C: void v_eeol ( int16_t handle );
Binding:
void v_eeol (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 10;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 10 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.6.23 v_eeos

Name: »Erase to end of alpha screen« - Clear the screen of text from the alpha cursor onwards.
Opcode: 5 (Escape 9)
Syntax: void v_eeos ( int16_t handle );
Description: The call v_eeos clears the alphanumeric screen of text from the current cursor position onwards on the workstation with the ID handle.

Note: The position of the cursor will not be altered by this.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur

7.8.6.24 Bindings for v_eeos

C: void v_eeos ( int16_t handle );
Binding:
void v_eeos (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 9;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 9 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.6.25 v_enter_cur

Name: »Enter alpha mode« - Switch text mode on for screen or metafile.
Opcode: 5 (Escape 3)
Syntax: void v_enter_cur ( int16_t handle );
Description: The call v_enter_cur exits the graphic mode on the workstation with the ID handle (screen or metafile) if this is not identical to the alpha mode.

In addition the mouse pointer will be removed, the alpha cursor set to the top left character cell, and the alpha screen will be cleared (by setting it to the colour 0); with a metafile a corresponding entry will be made in the file.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_exit_cur

7.8.6.26 Bindings for v_enter_cur

C: void v_enter_cur ( int16_t handle );
Binding:
void v_enter_cur (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 3;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 3 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.6.27 v_exit_cur

Name: »Exit alpha mode« - Switch text mode off for screen or metafile.
Opcode: 5 (Escape 2)
Syntax: void v_exit_cur ( int16_t handle );
Description: The call v_exit_cur switches off the alpha mode on the workstation with the ID handle (screen or metafile) if the alpha and graphic modes are different.

The alpha mode is the normal text mode without any graphics, such as used by the desktop for depicting files and folders in windows set to 'Display > As Text' for instance.

Note: The function also clears the graphics screen and restores the mouse pointer (to completely restore the screen, you should call form_dial( FMD_FINISH sx, sy, sw, sh ) where sx, sy, sw, sh are the coordinates of the screen); with a metafile a corresponding entry is made in the file.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur

7.8.6.28 Bindings for v_exit_cur

C: void v_exit_cur ( int16_t handle );
Binding:
void v_exit_cur (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 2;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 2 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.6.29 v_rvoff

Name: »Reverse video off« - Switch off inverse video mode.
Opcode: 5 (Escape 14)
Syntax: void v_rvoff ( int16_t handle );
Description: The call v_rvoff switches off the inverse alpha text display (causing it to appear as normal video) on the workstation with the ID handle.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur   v_rvon

7.8.6.30 Bindings for v_rvoff

C: void v_rvoff ( int16_t handle );
Binding:
void v_rvoff (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 14;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 14 # Escape/Sub-opcode
contrl+12 contrl[6] handle

7.8.6.31 v_rvon

Name: »Reverse video on« - Switch on inverse video mode.
Opcode: 5 (Escape 13)
Syntax: void v_rvon ( int16_t handle );
Description: The call v_rvon activates the inverse alpha text display on the workstation with the ID handle.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Text functions
See also: Binding   v_enter_cur   v_rvoff

7.8.6.32 Bindings for v_rvon

C: void v_rvon ( int16_t handle );
Binding:
void v_rvon (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 13;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 5 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 13 # Escape/Sub-opcode
contrl+12 contrl[6] handle

HomeVDIInput functionsColour table functions