7.8 Escape functions

7.8.1.2 Bindings for vq_bit_image

int16_t vq_bit_image( int16_t handle, int16_t *ver, int16_t *maximg, int16_t *form );

Binding:

int16_t  vq_bit_image( int16_t handle, int16_t *ver,
                  int16_t *maximg,
                  int16_t *form )
{
   intout[0] = 0;

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

   vdi ();

   *ver    = intout[1];
   *maximg = intout[2];
   *form   = intout[3];

  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]	4 # Entry in intout
contrl+10	contrl[5]	2102 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intout	intout[0]	Return Value
intout+2	intout[1]	ver
intout+4	intout[2]	maximg
intout+6	intout[3]	form

7.8.1.3 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

Note for TC-VDI: Syntax is vq_calibrate(handle) and the function returns intout[0] instead of contrl[4] which is always set to 1.

Return value:

The function returns the value 1 if functions for calibration are present, else the value 0.

Availability:

NVDI (depends on the driver), MATRIX TC-VDI

Group:

See also:

Binding vs_calibrate

7.8.1.4 Bindings for vq_calibrate

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] = 0;
   contrl[5] = 77;
   contrl[6] = handle;

   vdi ();

   *flag = 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]	0 # Entry in intin
contrl+8	contrl[4]	n # 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.5 vq_driver_info

Name:

»Inquire driver info« - Obtain information about a printer driver.

Opcode:

5 (Escape 2101)

Syntax:

int16_t vq_driver_info ( int16_t handle, int16_t *lib, int16_t *drv, int16_t *plane, int16 *attr, int8_t *name );

Description:

The call vq_driver_info returns information about a printer driver and available features of the current library. The following apply:

Parameter

Meaning

handle

Workstation identifier

lib

Library version number

drv

Driver version number

plane

Number of planes

1	-	Monochrome
3	-	CMY
4	-	CMYK

attr

Supported attributes

Bit 0:

Four color

Bit 1:

Negative

Bit 2:

Mirror

Bit 3 & 4:

Multiple copies

0	-	No
1	-	Hardware
2	-	Software
3	-	Reserved

Bit 5:

Landscape

Bit 6..15:

Reserved

name

Name of the driver as up to 27 characters (26 + NULL)

Note: This function allows to determine if the new vq_margin and vq_bit_image functions (Escape >= 2100) are available.

Return value:

0: Function does not exist.

Availability:

Available with new drivers from Thierry Rodolfo.

Group:

See also:

Binding vq_margin vq_bit_image

7.8.1.6 Bindings for vq_driver_info

int16_t vq_driver_info ( int16_t handle, int16_t *lib, int16_t *drv, int16_t *plane, int16_t *attr, int8_t *name );

Binding:

int16_t vq_driver_info (int16_t handle, int16_t *lib, int16_t *drv,
                  int16_t *plane, int16_t *attr, int8_t *name )
{
   int16_t tmp;

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

   vdi ();

   *lib   = intout[1];
   *drv   = intout[2];
   *plane = intout[3];
   *attr  = intout[4];
   for (tmp = 0; tmp < 26; tmp++)
     name[tmp] = intout[tmp+5];
   name[26] = 0;

   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]	32 # Entry in intout
contrl+10	contrl[5]	2101 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intout	intout[0]	Return Value
intout+2	intout[1]	lib
intout+4	intout[2]	drv
intout+6	intout[3]	plane
intout+8	intout[4]	attr
intout+10	intout[5..31]	name[0..26]

7.8.1.7 vq_driver_name

Name:

»Inquire driver name« - Obtain name of a driver.

Opcode:

5 (Escape 2108)

Syntax:

int16_t vq_driver_name ( int16_t handle, int8_t *name );

Description:

The call vq_driver_name returns the name of a driver. The following apply:

Parameter	Meaning

handle	Workstation identifier
name	Name of the driver as up to 27 characters (26 + NULL)

Return value:

0: Function does not exist.

Availability:

Available with new drivers from Thierry Rodolfo.

Group:

See also:

Binding vq_driver_info

7.8.1.8 Bindings for vq_driver_name

int16_t vq_driver_name ( int16_t handle, int8_t *name );

Binding:

int16_t vq_driver_name (int16_t handle, int8_t *name )
{
   int16_t tmp;

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

   vdi ();

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

   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]	27 # Entry in intout
contrl+10	contrl[5]	2108 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intout	intout[0..26]	name

7.8.1.9 vq_image_type

Name:

»Inquire image type« - Obtain type of a bitmap file.

Opcode:

5 (Escape 2105)

Syntax:

int16_t vq_image_type ( int16_t handle, int8_t *filename, BIT_IMAGE *image )

Description:

The call vq_image_type obtains the image type of the file whose full pathname is specified by filename, and writes information into the structure pointed to by image if its type is supported by v_bit_image. The following apply:

Parameter	Meaning

handle	Workstation identifier
filename	Pointer to the name
image	Pointer to a BIT_IMAGE structure

Note: Currently the returned type is based on the file extension.

Return value:

The function can return the following values:

0 :	Unknown
1 :	IMG
2 :	TGA

Availability:

Available with new drivers from Thierry Rodolfo.

Group:

See also:

Binding v_bit_image vq_bit_image vq_driver_info

7.8.1.10 Bindings for vq_image_type

int16_t vq_image_type ( int16_t handle, int8_t *filename, BIT_IMAGE *image )

Binding:

int16_t vq_image_type ( int16_t handle,
   int8_t *filename, BIT_IMAGE *image )
{
   int16_t tmp;

   ptsin[0..1] = image;

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

   contrl[0] = 5;
   contrl[1] = 1;
   contrl[3] = tmp;
   contrl[5] = 2105;
   contrl[6] = handle;

   vdi ();

   return ( intout[1] );
}

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]	n+1 # Entry in intin
contrl+8	contrl[4]	2 # Entry in intout
contrl+10	contrl[5]	2105 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0..n]	filename with NULL-byte
ptsin	ptsin[0..1]	image
intout	intout[0]	Availability
intout+2	intout[1]	Return Value

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

7.8.1.11 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:

See also:

Binding

7.8.1.12 Bindings for vq_margins

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.13 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:

See also:

Binding v_opnwk vq_extnd

7.8.1.14 Bindings for vq_page_name

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.15 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:

See also:

Binding

7.8.1.16 Bindings for vq_prn_scaling

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.17 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:

See also:

Binding

7.8.1.18 Bindings for vq_scan

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.19 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.20 Bindings for vq_tabstatus

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.21 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:

See also:

Binding v_tray v_copies v_orient

7.8.1.22 Bindings for vq_tray_names

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

Note for TC-VDI: Syntax is vs_calibrate(handle, rgb, flag) however intin entries are assigned to the same values in both cases.

Return value:

The function returns the value 0 if the calibration is switched off, or the value 1 if this is switched on.

Availability:

NVDI (depends on the driver), MATRIX TC-VDI.

Group:

See also:

Binding vq_calibrate

7.8.1.24 Bindings for vs_calibrate

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.25 vs_crop

Name:

»Set crop marks« - Sets a cropping rectangle on a document.

Opcode:

5 (Escape 2104)

Syntax:

int16_t vs_crop ( int16_t handle, int16_t ltx1, int16_t lty1, int16_t ltx2, int16_t lty2, int16_t ltlen, int16_t ltoffset );

Description:

The call vs_crop sets a cropping rectangle to print cutting lines on a document. The following apply:

Parameter	Meaning

handle	Workstation identifier
ltx1	X-coordinate, and
lty1	Y-coordinate of top left corner point
ltx2	X-coordinate, and
lty2	Y-coordinate of bottom right corner point
ltlen	Length of the cutting lines
ltoffset	Position of cutting lines relative to coordinates

To remove the crop marks, set all parameters to 0.

Return value:

0: Function does not exist.

Availability:

Available with new drivers from Thierry Rodolfo.

Group:

See also:

Binding

7.8.1.26 Bindings for vs_crop

int16_t vs_crop ( int16_t handle, int16_t ltx1, int16_t lty1, int16_t ltx2, int16_t lty2, int16_t ltlen, int16_t ltoffset );

Binding:

int16_t vs_crop (int16_t handle, int16_t ltx1, int16_t lty1,
            int16_t ltx2, int16_t lty2, int16_t ltlen, int16_t ltoffset)
{
   intin[0] = ltx1;
   intin[1] = lty1;
   intin[2] = ltx2;
   intin[3] = lty2;
   intin[4] = ltlen;
   intin[5] = ltoffset;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 6;
   contrl[5] = 2104;
   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]	6 # entry in intin
contrl+8	contrl[4]	1 # entry in intout
contrl+10	contrl[5]	2104 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0]	ltx1
intin+2	intin[1]	lty1
intin+4	intin[2]	ltx2
intin+6	intin[3]	lty2
intin+8	intin[4]	ltlen
intin+10	intin[5]	ltoffset
intout	intout[0]	Return value

7.8.1.27 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

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:

See also:

Binding

7.8.1.28 Bindings for vs_document_info

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.29 vs_load_disp_list

Name:

»Load display list« - Load the printer buffer list.

Opcode:

5 (Escape 2107)

Syntax:

int16_t vs_load_disp_list ( int16_t handle, int8_t *name );

Description:

The call vs_load_disp_list loads the printer buffer with the contents of a file. It can be used to load master documents for example and provides huge time savings during printing.

Parameter	Meaning

handle	Workstation identifier
name	Pointer to the name of the file

Return value:

Return value of the function is unknown at present.

Availability:

The function is only present if intout[0] is non-zero.

Group:

7.8.1.30 Bindings for vs_load_disp_list

int16_t vs_load_disp_list ( int16_t handle, int8_t *name );

Binding:

int16_t vs_load_disp_list ( int16_t handle, int8_t *name )
{
   intin[0..1] = name;

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

   vdi ();

   return ( 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]	2107 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0..1]	name
intout	intout[0]	Availability
intout+2	intout[1]	Return value

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

7.8.1.31 vs_page_info

Name:

»Set page info« - Set document specifications for print monitor.

Opcode:

5 (Escape 2103)

Syntax:

int16_t vs_page_info( int16_t handle, int16_t type, int8_t *s );

Description:

The call vs_page_info allows a program to set 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

Pointer to the string (8 bits per character) which will be written character by character into 16-bit entries of intin, including the NULL-byte.

Return value:

0: Function not present
1: All OK

Availability:

Available with new drivers from Thierry Rodolfo.

Group:

See also:

Binding vs_document_info

7.8.1.32 Bindings for vs_page_info

int16_t vs_page_info( int16_t handle, int16_t type, int8_t *s );

Binding:

int16_t  vs_page_info( int16_t handle, int16_t type,
                           int8_t *s )
{
   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.33 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:

See also:

Binding

7.8.1.34 Bindings for vs_palette

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.35 vs_save_disp_list

Name:

»Save display list« - Save the printer buffer list.

Opcode:

5 (Escape 2106)

Syntax:

int16_t vs_save_disp_list ( int16_t handle, int8_t *name );

Description:

The call vs_save_disp_list saves the printer buffer to a file. It can be used to save master documents for example and provides huge time savings during printing.

Parameter	Meaning

handle	Workstation identifier
name	Pointer to the name of the file

Return value:

Return value of the function is unknown at present.

Availability:

The function is only present if intout[0] is non-zero.

Group:

7.8.1.36 Bindings for vs_save_disp_list

int16_t vs_save_disp_list ( int16_t handle, int8_t *name );

Binding:

int16_t vs_save_disp_list ( int16_t handle, int8_t *name )
{
   intin[0..1] = name;

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

   vdi ();

   return ( 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]	2106 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0..1]	name
intout	intout[0]	Availability
intout+2	intout[1]	Return value

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

7.8.1.37 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:

See also:

Binding v_xbit_image GDOS XIMG format

7.8.1.38 Bindings for v_bit_image

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.39 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.40 Bindings for v_clear_disp_list

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.41 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:

See also:

Binding v_orient v_tray

7.8.1.42 Bindings for v_copies

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.43 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:

See also:

Binding

7.8.1.44 Bindings for v_dspcur

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.45 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.46 Bindings for v_form_adv

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.47 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.48 Bindings for v_hardcopy

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.49 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:

See also:

Binding v_copies v_tray

7.8.1.50 Bindings for v_orient

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.51 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:

See also:

Binding v_updwk

7.8.1.52 Bindings for v_output_window

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.53 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:

See also:

Binding v_opnwk vq_extnd

7.8.1.54 Bindings for v_page_size

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.55 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.56 Bindings for v_rmcur

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.57 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. In GEM/3 this function is called v_tray, and has only 1 parameter.

Group:

See also:

Binding vq_tray_names v_copies v_orient

7.8.1.58 Bindings for v_tray

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.59 v_xbit_image

Opcode:	5 (Escape 101)
Syntax:	void v_xbit_image(int16_t handle, const char *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

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:

See also:

Binding GDOS vq_tabstatus vt_alignment vt_resolution vt_axis vt_origin

7.8.2.2 Bindings for vq_tdimensions

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:

See also:

Binding GDOS vq_tabstatus vq_tdimensions vt_resolution vt_axis vt_origin

7.8.2.4 Bindings for vt_alignment

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:

See also:

Binding GDOS vq_tabstatus vt_alignment vt_resolution vt_origin vq_tdimensions

7.8.2.6 Bindings for vt_axis

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:

See also:

Binding GDOS vq_tabstatus vt_alignment vt_resolution vt_axis vq_tdimensions

7.8.2.8 Bindings for vt_origin

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:

See also:

Binding GDOS vq_tabstatus vt_alignment vt_axis vt_origin vq_tdimensions

7.8.2.10 Bindings for vt_resolution

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:

7.8.3.2 Bindings for vm_coords

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:

See also:

Binding GDOS v_opnwk Metafile format sub-opcodes

7.8.3.4 Bindings for vm_filename

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:

7.8.3.6 Bindings for vm_pagesize

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 right 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:

See also:

Binding GDOS vm_filename v_write_meta Metafile format

7.8.3.8 Bindings for v_meta_extents

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:

See also:

Binding GDOS v_meta_extents Metafile format sub-opcodes

7.8.3.10 Bindings for v_write_meta

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.

7.8.4.1 vqp_error

Name:

»Polaroid 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:

See also:

Binding GDOS

7.8.4.2 Bindings for vqp_error

int16_t vqp_error ( int16_t handle );

Binding:

int16_t vqp_error ( int16_t handle );
{
   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:

See also:

Binding GDOS

7.8.4.4 Bindings for vqp_filmname

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 polaroid 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:

See also:

GDOS

7.8.4.6 vqp_state

Name:

»Inquire polaroid 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:

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:

See also:

Binding GDOS vsp_save vqp_state vsp_state vqp_films vsp_message

7.8.4.8 Bindings for vsc_expose

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:

See also:

Binding GDOS

7.8.4.10 Bindings for vsp_film

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 polaroid 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 polaroid 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 polaroid 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:

See also:

GDOS vsc_expose vqp_state vsp_save vsp_message vqp_films

7.8.5 Sound functions

This library contains functions for audio playback through supported sound system; the following routines are available for this purpose:

• vmid_load	Loads a MIDI file
• vmid_play	Plays a MIDI file
• vmid_unload	Releases memory occupied by a MIDI file
• vqspl_position_d2d	Gets current position when playing through D2D
• vqspl_position_dma	Gets current position when playing through DMA
• vqspl_status_d2d	Gets current D2D status
• vqspl_status_dma	Gets current DMA status
• vqspl_time_left_d2d	Gets remaining time when playing through D2D
• vspl_load_d2d	Loads an audio file for playing through D2D
• vspl_load_sample	Loads a sample for DMA playback
• vspl_make_d2d	Continues D2D playback
• vspl_pause_d2d	Suspends D2D playback
• vspl_pause_dma	Suspends DMA playback
• vspl_play	Plays an audio file
• vspl_play_d2d	Starts playback of an audio file through D2D
• vspl_play_dma	Plays a sample through DMA
• vspl_stop_d2d	Stops D2D playback
• vspl_stop_dma	Stops DMA playback
• vspl_unload_d2d	Releases memory allocated for the D2D playback
• vspl_unload_sample	Releases memory occupied by a sample
• vsspl_monitor_off	Disables monitoring
• vsspl_monitor_on	Enables monitoring

Note: Currently the unit of time for the start position and for the returned remaining time is unknown. The purpose of monitoring is also unknown.

7.8.5.1 vmid_load

Name:	»Load Midifile« - Loads a MIDI file
Opcode:	5 (Escape 4000)
Syntax:	int16_t vmid_load( int16_t handle, int8_t *fname, uint32_t position );
Description:	The call vmid_load loads the MIDI file fname from the position position into memory.
Return value:	An error has arisen only if the value 0 is returned.
Availability:	SpeedoGDOS with MIDI sound driver.
Group:	Sound functions
See also:	Binding vmid_play vmid_unload

7.8.5.1.1 Bindings for vmid_load

int16_t vmid_load( int16_t handle, int8_t *fname, uint32_t position );

Binding:

int16_t vmid_load (int16_t handle, int8_t *fname, uint32_t position)
{
   int16_t tmp;

   intin[0..1] = position;

   tmp = 2;
   while (intin[tmp++] = *fname++)
      ;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = --tmp;
   contrl[5] = 4000;
   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]	4000 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0..1]	position
intin+4	intin[2..n-1]	fname
intout	intout[0]	Return value

7.8.5.2 vmid_play

Name:	»Play Midifile« - Replay a MIDI file
Opcode:	5 (Escape 4002)
Syntax:	void vmid_play( int16_t handle );
Description:	The call vmid_play starts the playback of a MIDI file loaded previously with vmid_load.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with a sound driver that supports MIDI files.
Group:	Sound functions
See also:	Binding vmid_load vmid_unload

7.8.5.2.1 Bindings for vmid_play

void vmid_play( int16_t handle );

Binding:

void vmid_play (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 4002;
   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]	4002 # Escape/Sub-opcode
contrl+12	contrl[6]	handle

7.8.5.3 vmid_unload

Name:	»Unload Midifile« - Unload a MIDI file
Opcode:	5 (Escape 4001)
Syntax:	void vmid_unload( int16_t handle );
Description:	The call vmid_unload releases the memory allocated for MIDI playback.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with a sound driver that supports MIDI files.
Group:	Sound functions
See also:	Binding vmid_load vmid_play

7.8.5.3.1 Bindings for vmid_unload

void vmid_unload( int16_t handle );

Binding:

void vmid_unload (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 4001;
   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]	4001 # Escape/Sub-opcode
contrl+12	contrl[6]	handle

7.8.5.4 vqspl_position_d2d

Name:	»Inquire D2D position« - Gets the current D2D playback position
Opcode:	5 (Escape 3017)
Syntax:	uint32_t vqspl_position_d2d( int16_t handle );
Description:	The call vqspl_position_d2d returns the current position of the audio file being played through D2D.
Return value:	This function returns the current position.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_status_d2d vqspl_time_left_d2d vspl_load_d2d vspl_make_d2d vspl_pause_d2d vspl_play_d2d vspl_stop_d2d vspl_unload_d2d

7.8.5.4.1 Bindings for vqspl_position_d2d

uint32_t vqspl_position_d2d( int16_t handle );

Binding:

uint32_t vqspl_position_d2d (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 3017;
   contrl[6] = handle;

   vdi();

   return intout[0..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]	3017 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intout	intout[0..1]	Return value

7.8.5.5 vqspl_position_dma

Name:	»Inquire DMA position« - Gets the DMA position
Opcode:	5 (Escape 3006)
Syntax:	uint32_t vqspl_position_dma( int16_t handle, int16_t id );
Description:	The call vqspl_position_dma obtains the current DMA playback position for the sample identified by id.
Return value:	This function returns the sample DMA position.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_status_dma vspl_load_sample vspl_pause_dma vspl_play_dma vspl_stop_dma vspl_unload_sample

7.8.5.5.1 Bindings for vqspl_position_dma

uint32_t vqspl_position_dma( int16_t handle, int16_t id );

Binding:

uint32_t vqspl_position_dma (int16_t handle, int16_t id)
{
   intin[0] = id;

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

   vdi();

   return ( intout[0..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]	1 # Entry in intin
contrl+8	contrl[4]	2 # Entry in intout
contrl+10	contrl[5]	3006 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0]	id
intout	intout[0..1]	Return value

7.8.5.6 vqspl_status_d2d

Name:	»Inquire D2D status« - Gets the current status of the D2D audio system
Opcode:	5 (Escape 3016)
Syntax:	int16_t vqspl_status_d2d( int16_t handle );
Description:	The call vqspl_status_d2d returns the current status of the D2D audio system.
Return value:	This function returns the current status. If nonzero, the D2D audio system is ready to process the next audio data from disk through a call to vspl_make_d2d.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_d2d vqspl_time_left_d2d vspl_load_d2d vspl_make_d2d vspl_pause_d2d vspl_play_d2d vspl_stop_d2d vspl_unload_d2d

7.8.5.6.1 Bindings for vqspl_status_d2d

int16_t vqspl_status_d2d( int16_t handle );

Binding:

int16_t vqspl_status_d2d (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 3016;
   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]	3016 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intout	intout[0]	Return value

7.8.5.7 vqspl_status_dma

Name:	»Inquire DMA status« - Gets the current DMA status
Opcode:	5 (Escape 3005)
Syntax:	int16_t vqspl_status_dma( int16_t handle, int16_t id );
Description:	The call vqspl_status_dma obtains the current DMA playback status for the sample identified by id.
Return value:	This function returns the sample DMA status (sound currently playing if bit 0 = 1).
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_dma vspl_load_sample vspl_pause_dma vspl_play_dma vspl_stop_dma vspl_unload_sample

7.8.5.7.1 Bindings for vqspl_status_dma

int16_t vqspl_status_dma( int16_t handle, int16_t id );

Binding:

int16_t vqspl_status_dma (int16_t handle, int16_t id)
{
   intin[0] = id;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 3005;
   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]	3005 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0]	id
intout	intout[0]	Return value

7.8.5.8 vqspl_time_left_d2d

Name:	»Inquire D2D remaining time« - Gets the D2D remaining playing time
Opcode:	5 (Escape 3018)
Syntax:	int16_t vqspl_time_left_d2d( int16_t handle );
Description:	The call vqspl_time_left_d2d returns the remaining playing time on the D2D audio system.
Return value:	This function returns the remaining playing time.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_d2d vqspl_status_d2d vspl_load_d2d vspl_make_d2d vspl_pause_d2d vspl_play_d2d vspl_stop_d2d vspl_unload_d2d

7.8.5.8.1 Bindings for vqspl_time_left_d2d

int16_t vqspl_time_left_d2d( int16_t handle );

Binding:

int16_t vqspl_time_left_d2d (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 3018;
   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]	3018 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intout	intout[0]	Return value

7.8.5.9 vspl_load_d2d

Name:	»Prepare D2D playback« - Loads an audio file
Opcode:	5 (Escape 3011)
Syntax:	int16_t vspl_load_d2d( int16_t handle, int8_t *fname, uint32_t position );
Description:	The call vspl_load_d2d loads the file fname from the position position into memory for D2D playback.
Return value:	An error has arisen only if the value 0 is returned.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_d2d vqspl_status_d2d vqspl_time_left_d2d vspl_make_d2d vspl_pause_d2d vspl_play_d2d vspl_stop_d2d vspl_unload_d2d

7.8.5.9.1 Bindings for vspl_load_d2d

int16_t vspl_load_d2d( int16_t handle, int8_t *fname, uint32_t position );

Binding:

int16_t vspl_load_d2d (int16_t handle, int8_t *fname, uint32_t position)
{
   int16_t tmp;

   intin[0..1] = position;

   tmp = 2;
   while (intin[tmp++] = *fname++)
      ;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = --tmp;
   contrl[5] = 3011;
   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]	3011 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0..1]	position
intin+4	intin[2..n-1]	fname
intout	intout[0]	Return value

7.8.5.10 vspl_load_sample

Name:	»Load sample« - Loads an audio file
Opcode:	5 (Escape 3001)
Syntax:	int16_t vspl_load_sample( int16_t handle, int8_t *fname, uint32_t position );
Description:	The call vspl_load_sample loads the file fname from the position position into memory. Multiple samples can be loaded into a single workstation, each sample is identified by an index.
Return value:	This function returns the corresponding sample index.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_dma vqspl_status_dma vspl_pause_dma vspl_play_dma vspl_stop_dma vspl_unload_sample

7.8.5.10.1 Bindings for vspl_load_sample

int16_t vspl_load_sample( int16_t handle, int8_t *fname, uint32_t position );

Binding:

int16_t vspl_load_sample (int16_t handle, int8_t *fname, uint32_t position)
{
   int16_t tmp;

   intin[0..1] = position;

   tmp = 2;
   while (intin[tmp++] = *fname++)
      ;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = --tmp;
   contrl[5] = 3001;
   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]	3001 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0..1]	position
intin+4	intin[2..n-1]	fname
intout	intout[0]	Return value

7.8.5.11 vspl_make_d2d

Name:	»Make D2D playback« - Continues D2D playback
Opcode:	5 (Escape 3020)
Syntax:	void vspl_make_d2d( int16_t handle );
Description:	The call vspl_make_d2d continues the D2D playback of the file previously started with vspl_play_d2d. The D2D status should be checked regularly with vqspl_status_d2d in order to call vspl_make_d2d whenever the system is ready. During this loop, buffoper(-1) has the bit 0 set to 1 throughout the playback. buffoper(-1) returns a value with bit 0 set to 0 at the end of the playback.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_d2d vqspl_status_d2d vqspl_time_left_d2d vspl_load_d2d vspl_pause_d2d vspl_play_d2d vspl_stop_d2d vspl_unload_d2d

7.8.5.11.1 Bindings for vspl_make_d2d

void vspl_make_d2d( int16_t handle );

Binding:

void vspl_make_d2d (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 3020;
   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]	3020 # Escape/Sub-opcode
contrl+12	contrl[6]	handle

7.8.5.12 vspl_pause_d2d

Name:	»Pause D2D playback« - Suspends the D2D audio playback
Opcode:	5 (Escape 3014)
Syntax:	void vspl_pause_d2d( int16_t handle );
Description:	The call vspl_pause_d2d suspends the D2D playback of the file previously loaded with vspl_load_d2d.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_d2d vqspl_status_d2d vqspl_time_left_d2d vspl_load_d2d vspl_make_d2d vspl_play_d2d vspl_stop_d2d vspl_unload_d2d

7.8.5.12.1 Bindings for vspl_pause_d2d

void vspl_pause_d2d( int16_t handle );

Binding:

void vspl_pause_d2d (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 3014;
   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]	3014 # Escape/Sub-opcode
contrl+12	contrl[6]	handle

7.8.5.13 vspl_pause_dma

Name:	»Pause DMA playback« - Suspends the DMA playback of a sample
Opcode:	5 (Escape 3007)
Syntax:	void vspl_pause_dma( int16_t handle, int16_t id );
Description:	The call vspl_pause_dma suspends the DMA playback of the sample identified by id.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_dma vqspl_status_dma vspl_load_sample vspl_play_dma vspl_stop_dma vspl_unload_sample

7.8.5.13.1 Bindings for vspl_pause_dma

void vspl_pause_dma( int16_t handle, int16_t id );

Binding:

void vspl_pause_dma (int16_t handle, int16_t id)
{
   intin[0] = id;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 3007;
   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]	3007 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0]	id

7.8.5.14 vspl_play

Name:	»Play sample« - Plays an audio file
Opcode:	5 (Escape 3000)
Syntax:	void vspl_play( int16_t handle, int8_t *fname, uint32_t position );
Description:	The call vspl_play starts the playback of the file fname from the position position.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding

7.8.5.14.1 Bindings for vspl_play

void vspl_play( int16_t handle, int8_t *fname, uint32_t position );

Binding:

void vspl_play (int16_t handle, int8_t *fname, uint32_t position)
{
   int16_t tmp;

   intin[0..1] = position;

   tmp = 2;
   while (intin[tmp++] = *fname++)
      ;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = --tmp;
   contrl[5] = 3000;
   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]	3000 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0..1]	position
intin+4	intin[2..n-1]	fname

7.8.5.15 vspl_play_d2d

Name:	»Start D2D playback« - Plays an audio file through the D2D sound system
Opcode:	5 (Escape 3013)
Syntax:	void vspl_play_d2d( int16_t handle );
Description:	The call vspl_play_d2d starts the D2D playback of the file previously loaded with vspl_load_d2d. After calling this function, the D2D status should be checked regularly with vqspl_status_d2d in order to call vspl_make_d2d whenever the system is ready. During this loop, buffoper(-1) has the bit 0 set to 1 throughout the playback. buffoper(-1) returns a value with bit 0 set to 0 at the end of the playback.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_d2d vqspl_status_d2d vqspl_time_left_d2d vspl_load_d2d vspl_make_d2d vspl_pause_d2d vspl_stop_d2d vspl_unload_d2d

7.8.5.15.1 Bindings for vspl_play_d2d

void vspl_play_d2d( int16_t handle );

Binding:

void vspl_play_d2d (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 3013;
   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]	3013 # Escape/Sub-opcode
contrl+12	contrl[6]	handle

7.8.5.16 vspl_play_dma

Name:	»Start DMA playback« - Plays a sample through the DMA sound system
Opcode:	5 (Escape 3003)
Syntax:	void vspl_play_dma( int16_t handle, int16_t id );
Description:	The call vspl_play_dma starts the DMA playback of the sample identified by id.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_dma vqspl_status_dma vspl_load_sample vspl_pause_dma vspl_stop_dma vspl_unload_sample

7.8.5.16.1 Bindings for vspl_play_dma

void vspl_play_dma( int16_t handle, int16_t id );

Binding:

void vspl_play_dma (int16_t handle, int16_t id)
{
   intin[0] = id;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 3003;
   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]	3003 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0]	id

7.8.5.17 vspl_stop_d2d

Name:	»Stop D2D playback« - Stops the D2D audio playback
Opcode:	5 (Escape 3015)
Syntax:	void vspl_stop_d2d( int16_t handle );
Description:	The call vspl_stop_d2d stops the D2D playback of the file previously loaded with vspl_load_d2d.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_d2d vqspl_status_d2d vqspl_time_left_d2d vspl_load_d2d vspl_make_d2d vspl_pause_d2d vspl_play_d2d vspl_unload_d2d

7.8.5.17.1 Bindings for vspl_stop_d2d

void vspl_stop_d2d( int16_t handle );

Binding:

void vspl_stop_d2d (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 3015;
   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]	3015 # Escape/Sub-opcode
contrl+12	contrl[6]	handle

7.8.5.18 vspl_stop_dma

Name:	»Stop DMA playback« - Stops the DMA playback of a sample
Opcode:	5 (Escape 3004)
Syntax:	void vspl_stop_dma( int16_t handle, int16_t id );
Description:	The call vspl_stop_dma stops the DMA playback of the sample identified by id.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_dma vqspl_status_dma vspl_load_sample vspl_pause_dma vspl_play_dma vspl_unload_sample

7.8.5.18.1 Bindings for vspl_stop_dma

void vspl_stop_dma( int16_t handle, int16_t id );

Binding:

void vspl_stop_dma (int16_t handle, int16_t id)
{
   intin[0] = id;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 3004;
   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]	3004 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0]	id

7.8.5.19 vspl_unload_d2d

Name:	»Unload D2D sample« - Unload an audio file
Opcode:	5 (Escape 3012)
Syntax:	void vspl_unload_d2d( int16_t handle );
Description:	The call vspl_unload_d2d releases the memory allocated with vspl_load_d2d for D2D playback.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with driver.
Group:	Sound functions
See also:	Binding vqspl_position_d2d vqspl_status_d2d vqspl_time_left_d2d vspl_load_d2d vspl_make_d2d vspl_pause_d2d vspl_play_d2d vspl_stop_d2d

7.8.5.19.1 Bindings for vspl_unload_d2d

void vspl_unload_d2d( int16_t handle );

Binding:

void vspl_unload_d2d (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 3012;
   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]	3012 # Escape/Sub-opcode
contrl+12	contrl[6]	handle

7.8.5.20 vspl_unload_sample

Name:	»Unload sample« - Unloads a sample
Opcode:	5 (Escape 3002)
Syntax:	void vspl_unload_sample( int16_t handle, int16_t id );
Description:	The call vspl_unload_sample unloads the sample identified by id.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vqspl_position_dma vqspl_status_dma vspl_load_sample vspl_pause_dma vspl_play_dma vspl_stop_dma

7.8.5.20.1 Bindings for vspl_unload_sample

void vspl_unload_sample( int16_t handle, int16_t id );

Binding:

void vspl_unload_sample (int16_t handle, int16_t id)
{
   intin[0] = id;

   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[5] = 3002;
   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]	3002 # Escape/Sub-opcode
contrl+12	contrl[6]	handle
intin	intin[0]	id

7.8.5.21 vsspl_monitor_off

Name:	»Monitor off« - Disables monitoring
Opcode:	5 (Escape 3031)
Syntax:	void vsspl_monitor_off( int16_t handle );
Description:	The call vsspl_monitor_off disables the monitoring of the sound system. Note: What the monitoring actually does is currently unknown.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vsspl_monitor_on

7.8.5.21.1 Bindings for vsspl_monitor_off

void vsspl_monitor_off( int16_t handle );

Binding:

void vsspl_monitor_off (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 3031;
   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]	3031 # Escape/Sub-opcode
contrl+12	contrl[6]	handle

7.8.5.22 vsspl_monitor_on

Name:	»Monitor on« - Enables monitoring
Opcode:	5 (Escape 3030)
Syntax:	void vsspl_monitor_on( int16_t handle );
Description:	The call vsspl_monitor_on enables the monitoring of the sound system. Note: What the monitoring actually does is currently unknown.
Return value:	This function does not return a result.
Availability:	SpeedoGDOS with sound driver.
Group:	Sound functions
See also:	Binding vsspl_monitor_off

7.8.5.22.1 Bindings for vsspl_monitor_on

void vsspl_monitor_on( int16_t handle );

Binding:

void vsspl_monitor_on (int16_t handle)
{
   contrl[0] = 5;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[5] = 3030;
   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]	3030 # Escape/Sub-opcode
contrl+12	contrl[6]	handle

7.8.6 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

7.8.6.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:

See also:

Binding GDOS

7.8.6.2 Bindings for v_escape2000

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.6.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:

See also:

Binding Header for bitmap GDOS fonts

7.8.6.4 Bindings for v_fontinit

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.6.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:

See also:

Binding

7.8.6.6 Bindings for v_offset

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.6.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:

See also:

Binding GDOS vs_mute

7.8.6.8 Bindings for v_sound

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.6.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:

See also:

Binding GDOS v_sound

7.8.6.10 Bindings for vs_mute

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

7.8.7.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:

See also:

Binding v_enter_cur

7.8.7.2 Bindings for vq_chcells

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

See also:

Binding v_enter_cur

7.8.7.4 Bindings for vq_curaddress

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

See also:

Binding OUT file format

7.8.7.6 Bindings for v_alpha_text

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]	0 # 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.7.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:

See also:

Binding v_enter_cur

7.8.7.8 Bindings for v_curaddress

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.7.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.7.10 Bindings for v_curdown

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.7.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.7.12 Bindings for v_curhome

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.7.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.7.14 Bindings for v_curleft

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.7.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.7.16 Bindings for v_curright

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