include "/var/www/banner.php"; ?>
This is an old version from the tos.hyp. The new is on GitHub!



7.8 Escape functions
This library contains functions to take advantage of special
features of a graphic device. For this purpose the following function
groups are available:
See also: VDI workstations Style guidelines
7.8.1 Special graphic functions
This library contains functions to output data on a printer, for
controlling the colour calibration, and many others. In all, the
following routines are available:
See also: VDI workstations Style guidelines
7.8.1.1 vq_calibrate
Name: |
»Inquire calibration« - Test colour calibration. |
Opcode: |
5 (Escape 77) |
Syntax: |
int16_t vq_calibrate ( int16_t handle, int16_t *flag ); |
Description: |
The call vq_calibrate tests whether functions for calibration
are present, and if these are switched on. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
flag |
Calibration:
|
|
Return value: |
The function returns the value 1 if functions for calibration
are present, else the value 0. |
Availability: |
|
Group: |
Special graphic functions |
See also: |
Binding vs_calibrate
|
7.8.1.2 Bindings for vq_calibrate
C: |
int16_t vq_calibrate ( int16_t handle, int16_t *flag ); |
Binding: |
int16_t vq_calibrate (int16_t handle, int16_t *flag)
{
contrl[0] = 5;
contrl[1] = 0;
contrl[3] = 1;
contrl[5] = 77;
contrl[6] = handle;
vdi ();
*flags = intout[0];
return ( contrl[4] );
}
|
GEM-Arrays: |
Note: n specifies the number of entries in the intout
field. If contrl[4] contains the value 0, calibration is not
supported.
|
7.8.1.3 vq_margins
Name: |
»Inquire printer margins« |
Opcode: |
5 (Escape 2100) |
Syntax: |
int16_t vq_margins( int16_t handle, int16_t *top_margin,
int16_t *bottom_margin, int16_t *left_margin, int16_t *right_margin,
int16_t *hdpi, int16_t *vdpi ); |
Description: |
The call vq_margins obtains the printer margins. The following
apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
top_margin |
Top margin in pixels |
bottom_margin |
Bottom margin in pixels |
left_margin |
Left margin in pixels |
right_margin |
Right margin in pixels |
hdpi |
Horizontal dpi resolution |
vdpi |
Vertical dpi resolution
|
|
Return value: |
0: Function does not exist |
Availability: |
As of NVDI 5.00. |
Group: |
Special graphic functions |
See also: |
Binding
|
7.8.1.4 Bindings for vq_margins
C: |
int16_t vq_margins( int16_t handle, int16_t *top_margin,
int16_t *bottom_margin, int16_t *left_margin, int16_t *right_margin,
int16_t *hdpi, int16_t *vdpi ); |
Binding: |
int16_t vq_margins( int16_t handle, int16_t *top_margin,
int16_t *bottom_margin, int16_t *left_margin,
int16_t *right_margin, int16_t *hdpi,
int16_t *vdpi )
{
intout[0] = 0;
contrl[0] = 5;
contrl[1] = 0;
contrl[3] = 0;
contrl[5] = 2100;
contrl[6] = handle;
vdi ();
*top_margin = intout[1];
*bottom_margin = intout[2];
*left_margin = intout[3];
*right_margin = intout[4];
*hdpi = intout[5];
*vdpi = intout[6];
return ( intout[0] );
}
|
GEM-Arrays: |
|
7.8.1.5 vq_page_name
Name: |
»Inquire page name« - Obtain name and size of a page format. |
Opcode: |
5 (Escape 38) |
Syntax: |
int16_t vq_page_name ( int16_t handle, int16_t page_id, int8_t
*page_name, int32_t *page_width, int32_t *page_height ) |
Description: |
The call vq_page_name obtains the name and the physical size of
a page format. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
page_id |
Paper format |
page_name |
Pointer to the name, or NULL |
page_width |
Page width in microns (1/1000 mm) |
page_height |
Page height in microns (1/1000 mm)
|
Note: The data for the paper size include also the
non-printable margins. |
Return value: |
The function returns the current paper format. A value of -1
means that the specified page format is not known to the driver; in
that case no values will be returned in page_width or
page_height. |
Availability: |
The function is only present if contrl[4] has a non-zero
value. |
Group: |
Special graphic functions |
See also: |
Binding v_opnwk vq_extnd
|
7.8.1.6 Bindings for vq_page_name
C: |
int16_t vq_page_name ( int16_t handle, int16_t page_id, int8_t
*page_name, int32_t *page_width, int32_t *page_height ) |
Binding: |
int16_t vq_page_name ( int16_t handle, int16_t page_id, int8_t *page_name,
int32_t *page_width, int32_t *page_height )
{
intin[0] = page_id;
intin[1..2] = page_name;
contrl[0] = 5;
contrl[1] = 0;
contrl[3] = 3;
contrl[5] = 38;
contrl[6] = handle;
vdi ();
*page_width = intout[1..2];
*page_height = intout[3..4];
return ( intout[0] );
}
|
GEM-Arrays: |
Note: If contrl[4] contains the value 0, the function is
not available.
|
7.8.1.7 vq_prn_scaling
Name: |
»Inquire printer scaling« - Obtain scaling of the printer
driver. |
Opcode: |
5 (Escape 39) |
Syntax: |
fixed vq_prn_scaling( int16_t handle ); |
Description: |
The call vq_prn_scaling returns information whether the printer
driver takes heed of the scaling passed in the PRN_SETTINGS. If the
driver does not support the function (i.e. an old driver), the binding
returns -1 for the scaling. If we are dealing with a new driver that
supports the function but does not scale, then this returns -1.
If the driver performs the scaling, then the set scaling factor
will be returned (0x10000L corresponds to 100 %).
Parameter |
Meaning |
|
|
handle |
Workstation identifier
|
|
Return value: |
-1 if an old driver or scaling did not take place, else the
set scaling factor (0x10000L corresponds to 100%). |
Availability: |
As of NVDI 5.00. |
Group: |
Special graphic functions |
See also: |
Binding
|
7.8.1.8 Bindings for vq_prn_scaling
7.8.1.9 vq_scan
Name: |
»Inquire printer scan« - Obtain parameters relating to printer
banding. |
Opcode: |
5 (Escape 24) |
Syntax: |
void vq_scan ( int16_t handle, int16_t *g_slice, int16_t
*g_page, int16_t *a_slice, int16_t *a_page, int16_t *div_fac ); |
Description: |
The call vq_scan permits inquiry of various printer-specific
parameters related to the number of graphic passes per printer page.
The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
g_slice |
Pixel height of a band |
g_page |
Number of bands into which the printer subdivides a page |
a_slice |
Height of an alpha text line in pixels |
a_page |
Alpha text lines per page |
div_fac |
Factor by which the other values may have to be divided
|
Notes: One can calculate the number of graphics scan lines
per pass from the formula g_slice/div_fac and the number of
scan lines per alpha text line from a_slice/div_fac.
This call has been previously mis-documented. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all printer drivers. |
Group: |
Special graphic functions |
See also: |
Binding
|
7.8.1.10 Bindings for vq_scan
C: |
void vq_scan ( int16_t handle, int16_t *g_slice, int16_t
*g_page, int16_t *a_slice, int16_t *a_page, int16_t *div_fac ); |
Binding: |
void vq_scan (int16_t handle, int16_t *g_slice,
int16_t *g_page, int16_t *a_slice,
int16_t *a_page, int16_t *div_fac)
{
contrl[0] = 5;
contrl[1] = 0;
contrl[3] = 0;
contrl[5] = 24;
contrl[6] = handle;
vdi ();
*g_slice = intout[0];
*g_page = intout[1];
*a_slice = intout[2];
*a_page = intout[3];
*div_fac = intout[4];
}
|
GEM-Arrays: |
|
7.8.1.11 vq_tabstatus
Name: |
»Inquire tablet status« - Obtain availability of a specialized
input device. |
Opcode: |
5 (Escape 16) |
Syntax: |
int16_t vq_tabstatus ( int16_t handle ); |
Description: |
The call vq_tabstatus checks on the workstation with the ID
handle for the availability of a graphics tablet, of a mouse,
a joystick or a similar device. |
Return value: |
The function returns the value 1 if a corresponding device is
available, else the value 0 if this is not the case. |
Availability: |
Supported by all screen drivers. |
Group: |
Special graphic functions |
See also: |
Binding
|
7.8.1.12 Bindings for vq_tabstatus
7.8.1.13 vq_tray_names
Name: |
»Inquire tray names« - Obtain name of the paper feed-in or
feed-out tray. |
Opcode: |
5 (Escape 36) |
Syntax: |
void vq_tray_names ( int16_t handle, int8_t *input_name, int8_t
*output_name, int16_t *input, int16_t *output ); |
Description: |
The call vq_tray_names obtains the name of the current feed-in
or feed-out tray.
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
input_name |
Pointer to the name of the input tray |
output_name |
Pointer to the name of the output tray |
input |
Number of the input tray |
output |
Number of the output tray
|
Note: If the parameters input_name or
output_name are NULL-pointers, they will not be returned. |
Return value: |
The function returns no direct result. |
Availability: |
The function is only present if contrl[4] is non-zero. |
Group: |
Special graphic functions |
See also: |
Binding v_tray v_copies v_orient
|
7.8.1.14 Bindings for vq_tray_names
C: |
void vq_tray_names ( int16_t handle, int8_t *input_name, int8_t
*output_name, int16_t *input, int16_t *output ); |
Binding: |
void vq_tray_names ( int16_t handle, int8_t *input_name,
int8_t *output_name, int16_t *input,
int16_t *output )
{
intin[0..1] = input_name;
intin[2..3] = output_name;
contrl[0] = 5;
contrl[1] = 0;
contrl[3] = 4;
contrl[5] = 36;
contrl[6] = handle;
vdi ();
*input = intout[0];
*output = intout[1];
}
|
GEM-Arrays: |
Note: If contrl[4] contains the value 0, the function is
not available.
|
7.8.1.15 vs_calibrate
Name: |
»Set calibration« - Set colour calibration. |
Opcode: |
5 (Escape 76) |
Syntax: |
int16_t vs_calibrate ( int16_t handle, int16_t flag, int16_t
*rgb ); |
Description: |
The call vs_calibrate switches colour calibration on or off and
can be used to set a calibration table.
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
flag |
Calibration:
|
rgb |
Pointer to calibration table, or NULL
|
Note: A calibration table consists of 1001 RGB entries,
that allocate for the value range 0- to 1000- thousandths of each
input value a corrected thousandth value. Before calling this
function, one should use vq_calibrate to check whether it is even
present.
The colour calibration is valid for the whole system for the
driver identified by handle. Hence it should not be set by
individual applications, but only with a CPX module or a desk
accessory. |
Return value: |
The function returns the value 0 if the calibration is
switched off, or the value 1 if this is switched on. |
Availability: |
No information to hand. |
Group: |
Special graphic functions |
See also: |
Binding vq_calibrate
|
7.8.1.16 Bindings for vs_calibrate
7.8.1.17 vs_document_info
Name: |
»Set document info« - Set document specifications for print
monitor. |
Opcode: |
5 (Escape 2103) |
Syntax: |
int16_t vs_document_info( int16_t handle, int16_t type, void
*s, int16_t wchar ); |
Description: |
The call vs_document_info passes to a program various
specifications about a document that the print monitor displays during
printout.
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
type |
0 = |
Name of the application |
1 = |
Name of the document |
2 = |
Name of the originator/editor |
3 = |
Comment |
4 = |
Filename of the document
|
|
s |
Pointer to the string |
wchar |
0: 8 bits per character
1: 16 bits per character
|
|
Return value: |
0: Function not present
1: All OK |
Availability: |
As of NVDI 5.00. |
Group: |
Special graphic functions |
See also: |
Binding
|
7.8.1.18 Bindings for vs_document_info
7.8.1.19 vs_palette
Name: |
»Select palette« - Select a colour palette. |
Opcode: |
5 (Escape 60) |
Syntax: |
int16_t vs_palette ( int16_t handle, int16_t palette ); |
Description: |
The call vs_palette permits the selection of the colour palette
on an IBM CGA graphics card in medium resolution. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
palette |
Colour palette
0 = |
Red, Green, Blue |
1 = |
Cyan, Magenta, White
|
|
|
Return value: |
The function returns the selected palette. |
Availability: |
This call was originally designed for use on IBM CGA-based
computers. Its usefulness and availability are not guaranteed under
any driver, so it should be avoided. |
Group: |
Special graphic functions |
See also: |
Binding
|
7.8.1.20 Bindings for vs_palette
7.8.1.21 v_bit_image
Name: |
»Output bit image file« - Output a bit image file on the
printer. |
Opcode: |
5 (Escape 23) |
Syntax: |
void v_bit_image ( int16_t handle, CONST int8_t *filename,
int16_t aspect, int16_t x_scale, int16_t y_scale, int16_t h_align,
int16_t v_align, int16_t *xyarray ); |
Description: |
The call v_bit_image permits print output of the image data
stored in a bit-Image (IMG) file. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
filename |
Pointer to filename |
aspect |
Aspect ratio:
0 = |
Ignore aspect ratio |
1 = |
Respect pixel aspect ratio
|
|
x_scale |
Scaling of the X-axis, and |
y_scale |
Scaling of the Y-axis, for both of which the following apply:
0 = |
Rational (exact) |
1 = |
Integer
|
|
h_align |
Horizontal alignment:
0 = |
Left |
1 = |
Center |
2 = |
Right
|
|
v_align |
Vertical alignment:
0 = |
Top |
1 = |
Middle |
2 = |
Bottom
|
|
xyarray[0] |
X-coordinate, and |
xyarray[1] |
Y-coordinate of top left corner of the output rectangle |
xyarray[2] |
X-coordinate, and |
xyarray[3] |
Y-coordinate of the bottom right corner of the output recangle
|
Notes: If the aspect ratio in aspect is honoured,
then circles will appear as circles, squares as squares etc. The image
will then be stretched correspondingly on the output device. In some
circumstances this can look bad when, say, fine dot rasters are
stretched or compressed. If the ratio is ignored, it is possible that
circles will become ellipses etc.
If rational scaling is used, the image will appear at the
coordinates given by the VDI format rectangle pointed to by
xyarray; if integer scaling is used, the image will be
displayed as large as possible within the given coordinates, using
h_align and v_align for justifying the image. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all printer, metafile, and memory drivers. |
Group: |
Special graphic functions |
See also: |
Binding v_xbit_image GDOS XIMG format
|
7.8.1.22 Bindings for v_bit_image
C: |
void v_bit_image ( int16_t handle, CONST int8_t *filename,
int16_t aspect, int16_t x_scale, int16_t y_scale, int16_t h_align,
int16_t v_align, int16_t *xyarray ); |
Binding: |
void v_bit_image (int16_t handle, CONST int8_t *filename,
int16_t aspect, int16_t x_scale,
int16_t y_scale, int16_t h_align,
int16_t v_align, int16_t *xyarray)
{
int16_t tmp;
ptsin[0..3] = xyarray[0..3];
intin[0] = aspect;
intin[1] = x_scale;
intin[2] = y_scale;
intin[3] = h_align;
intin[4] = v_align;
tmp = 5;
while (intin[tmp++] = *filename++)
;
contrl[0] = 5;
contrl[1] = 2;
contrl[3] = --tmp;
contrl[5] = 23;
contrl[6] = handle;
vdi ();
}
|
GEM-Arrays: |
|
7.8.1.23 v_clear_disp_list
Name: |
»Clear display list« - Clear the printer buffer list. |
Opcode: |
5 (Escape 22) |
Syntax: |
void v_clear_disp_list ( int16_t handle ); |
Description: |
The call v_clear_disp_list clears the printer buffer on the
workstation with the ID handle.
Note: A form-feed will not be performed by the
call. The function should be called, say, if the user wants to cancel
graphic output before the printout starts. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all printer, plotter, camera, metafile and memory
drivers. |
Group: |
Special graphic functions |
See also: |
Binding GDOS v_clrwk
|
7.8.1.24 Bindings for v_clear_disp_list
7.8.1.25 v_copies
Name: |
»Set number of copies« - Set number of copies of page to be
printed. |
Opcode: |
5 (Escape 28) |
Syntax: |
int16_t v_copies ( int16_t handle, int16_t count ); |
Description: |
The call v_copies determines the number of copies of the page
to be printed. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
count |
Number of copies (1 = normal), or -1 to obtain the number of
copies set
|
Note: All pages up to the closing or the output device
will be printed in the specified quantity. |
Return value: |
The function returns the number of copies set. |
Availability: |
GEM/3 Release 3.1, and otherwise only if contrl[4]
contains a non-zero value. |
Group: |
Special graphic functions |
See also: |
Binding v_orient v_tray
|
7.8.1.26 Bindings for v_copies
7.8.1.27 v_dspcur
Name: |
»Place graphic cursor at location« - Position the graphic
cursor at the specified position. |
Opcode: |
5 (Escape 18) |
Syntax: |
void v_dspcur ( int16_t handle, int16_t x, int16_t y ); |
Description: |
The call v_dspcur sets the graphic cursor (mouse pointer) at a
specified position. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
x |
New X-coordinate for mouse pointer |
y |
New Y-coordinate for mouse pointer
|
Note: The function is only available on devices that
permit position input, such as mouse, joystick or trackball, for
instance. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Special graphic functions |
See also: |
Binding
|
7.8.1.28 Bindings for v_dspcur
7.8.1.29 v_form_adv
Name: |
»Form advance« - Create a form-feed. |
Opcode: |
5 (Escape 20) |
Syntax: |
void v_form_adv ( int16_t handle ); |
Description: |
The call v_form_adv creates a form-feed on the workstation with
the ID handle.
Note: The data buffer and display list are not
cleared by this; with a metafile a corresponding entry will be made in
the file. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all drivers. |
Group: |
Special graphic functions |
See also: |
Binding v_clrwk
|
7.8.1.30 Bindings for v_form_adv
7.8.1.31 v_hardcopy
Name: |
»Hardcopy« - Create a hardcopy of the screen. |
Opcode: |
5 (Escape 17) |
Syntax: |
void v_hardcopy ( int16_t handle ); |
Description: |
The call v_hardcopy invokes the ALT-HELP screen dump to create
a hardcopy on the workstation with the ID handle (a printer or
a similar device).
Note: This is a function of the screen driver, which
accesses the XBIOS for this. |
Return value: |
The function does not return a result. |
Availability: |
Supported by screen drivers running under ST compatible
resolutions. |
Group: |
Special graphic functions |
See also: |
Binding
|
7.8.1.32 Bindings for v_hardcopy
7.8.1.33 v_orient
Name: |
»Set orientation for output« |
Opcode: |
5 (Escape 27) |
Syntax: |
int16_t v_orient ( int16_t handle, int16_t orientation ); |
Description: |
The call v_orient sets the output orientation for a device. The
following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
orientation |
Format:
-1 = |
Just return orientation |
0 = |
Set to portrait |
1 = |
Set to landscape
|
|
Note: The desired setting must be performed before
any output is actioned.
If there is insufficient memory free to alter the orientation, the
function returns the value -1; in that case the printer workstation
must be closed with v_clswk. |
Return value: |
The function returns the set output orientation, or -1 in case
of error. |
Availability: |
GEM/3 Release 3.1 and otherwise only if contrl[4] has a
non-zero value. |
Group: |
Special graphic functions |
See also: |
Binding v_copies v_tray
|
7.8.1.34 Bindings for v_orient
C: |
int16_t v_orient ( int16_t handle, int16_t orientation ); |
Binding: |
int16_t v_orient ( int16_t handle, int16_t orientation )
{
intin[0] = orientation;
contrl[0] = 5;
contrl[1] = 0;
contrl[3] = 1;
contrl[5] = 27;
contrl[6] = handle;
vdi ();
return ( intout[0] );
}
|
GEM-Arrays: |
Note: If contrl[4] contains the value 0, the function is
not available.
|
7.8.1.35 v_output_window
Name: |
»Output window« - Output window contents on the printer. |
Opcode: |
5 (Escape 21) |
Syntax: |
void v_output_window ( int16_t handle, int16_t *xyarray ); |
Description: |
The call v_output_window outputs a specified portion of the
current page, and permits a picture to be printed split up between
various sheets. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
xyarray[0] |
X-coordinate, and |
xyarray[1] |
Y-coordinate of a corner of the output rectangle |
xyarray[2] |
X-coordinate, and |
xyarray[3] |
Y-coordinate of the diagonally opposite corner point
|
Notes: The difference to v_updwk consists of the fact that
a section can be selected using the coordinate system of the printer.
Some printer drivers ignore the sides of the bounding box and
print the entire width of the page. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all printer and metafile drivers under any type of
GDOS. |
Group: |
Special graphic functions |
See also: |
Binding v_updwk
|
7.8.1.36 Bindings for v_output_window
7.8.1.37 v_page_size
Name: |
»Set page size« |
Opcode: |
5 (Escape 37) |
Syntax: |
int16_t v_page_size ( int16_t handle, int16_t page_id ); |
Description: |
The call v_page_size enables one to set the page format for an
output device. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
page_id |
Desired paper format:
0 = |
Default setting |
1 = |
DIN A3 |
2 = |
DIN A4 |
3 = |
DIN A5 |
4 = |
DIN B5 |
16 = |
Letter size |
17 = |
Half size |
18 = |
Legal size |
19 = |
Double size |
20 = |
Broadsheet size
|
|
Note: If the requested size does not exist, the default
setting will be used. |
Return value: |
The function returns the set paper format. For a return value
of -1 the workstation has to be closed, as insufficient free memory is
available. |
Availability: |
The function is only present of contrl[4] contains a non-zero
value. |
Group: |
Special graphic functions |
See also: |
Binding v_opnwk vq_extnd
|
7.8.1.38 Bindings for v_page_size
7.8.1.39 v_rmcur
Name: |
»Remove last graphic cursor« |
Opcode: |
5 (Escape 19) |
Syntax: |
void v_rmcur ( int16_t handle ); |
Description: |
The call v_rmcur removes the last mouse cursor displayed on the
workstation with the ID handle.
Note: This function should only be used in conjunction
with v_dspcur when the mouse is moved manually. graf_mouse or v_hide_c
should be used unless this is your intention. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Special graphic functions |
See also: |
Binding
|
7.8.1.40 Bindings for v_rmcur
7.8.1.41 v_tray
Name: |
»Set input and output tray« - Set input and output tray of the
printer. |
Opcode: |
5 (Escape 29) |
Syntax: |
void v_tray ( int16_t handle, int16_t input, int16_t output,
int16_t *set_input, int16_t *set_output ); |
Description: |
The call v_tray determines the printer slot or tray for the
paper feed-in and feed-out. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
input |
Paper feed:
-1 = |
Manual input |
0 = |
Default input (tray 1) |
1 = |
Tray 2 |
n = |
n-th optional tray or slot
|
|
output |
Paper output:
0 = |
Standard output (usually front) |
1 = |
Output 2 |
n = |
n-th optional slot or tray
|
|
set_input |
Actually selected feed-in |
set_output |
Actually set feed-out slot or tray
|
Note: If the requested tray does not exist, the standard
tray will be selected (input 0 and output 0). The names of the input
and output trays/slots can be determined with vq_tray_names. |
Return value: |
The function does not return a result. |
Availability: |
GEM/3 Release 3.1 and otherwise only if contrl[4] has a
non-zero value. In NVDI this function is called v_trays. |
Group: |
Special graphic functions |
See also: |
Binding vq_tray_names v_copies v_orient
|
7.8.1.42 Bindings for v_tray
C: |
void v_tray ( int16_t handle, int16_t input, int16_t output,
int16_t *set_input, int16_t *set_output ); |
Binding: |
void v_tray ( int16_t handle, int16_t input, int16_t output,
int16_t *set_input, int16_t *set_output )
{
intin[0] = input;
intin[1] = output;
contrl[0] = 5;
contrl[1] = 0;
contrl[3] = 2;
contrl[5] = 29;
contrl[6] = handle;
vdi ();
*set_input = intout[0];
*set_output = intout[1];
}
|
GEM-Arrays: |
|
7.8.1.43 v_xbit_image
Opcode: |
5 (Escape 101) |
Syntax: |
void v_xbit_image(int16_t handle, BYTE *filename, int16_t
aspect, int16_t x_scale, int16_t y_scale, int16_t h_align, int16_t
v_align, int16_t rotation, int16_t foreground, int16_t background,
int16_t xy[]) |
Description: |
The call v_xbit_image draws an image from a disk file onto the
current device - with rotation and colouring.
Passed #ptsin=2, #intin=8 + length of filename.
INTIN holds:
- 0 to ignore aspect ratio, 1 to preserve it
- X axis scaling: 0 = fractional, 1 = integer
- Y axis scaling: 0 = fractional, 1 = integer
- Horizontal alignment: 0=left 1=centre 2=right
- Vertical alignment: 0=top 1=centre 2=bottom
- Rotation angle, 0 - 3600 in 1/10th degrees
- Foreground colour if drawing a monochrome image on a colour
device
- Background colour
- Filename, one character per word
|
Availability: |
GEM/3 and later |
Group: |
Special graphic functions
|
7.8.2 Graphics tablet functions
This library contains functions to access a graphics tablet in an
optimum manner. The following routines are available for this purpose:
• vq_tdimensions |
Gets dimensions of the graphics tablet in 1/10 inch |
• vt_alignment |
Sets offsets to graphics tablet coordinate system |
• vt_axis |
Sets resolution of the graphics tablet |
• vt_origin |
Sets coordinate origin for graphics tablet |
• vt_resolution |
Sets resolution of the graphics tablet
|
See also: VDI workstations Style guidelines
7.8.2.1 vq_tdimensions
Name: |
»Return tablet x and y dimensions« - Dimensions of the graphics
tablets in 1/10-inch. |
Opcode: |
5 (Escape 84) |
Syntax: |
void vq_tdimensions ( int16_t handle, int16_t *xdimension,
int16_t *ydimension ); |
Description: |
The call vq_tdimensions returns the scanning dimensions of an
attached graphics tablet in 1/10 inch. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
xdimension |
Width in 1/10 inch on exit |
ydimension |
Height in 1/10 inch on exit
|
|
Return value: |
The function does not return a result. |
Availability: |
Supported by all tablet drivers. |
Group: |
Graphics tablet functions |
See also: |
Binding GDOS vq_tabstatus vt_alignment vt_resolution
vt_axis vt_origin
|
7.8.2.2 Bindings for vq_tdimensions
7.8.2.3 vt_alignment
Name: |
»Set tablet alignment« - Align coordinate system of the
graphics tablet. |
Opcode: |
5 (Escape 85) |
Syntax: |
void vt_alignment ( int16_t handle, int16_t dx, int16_t dy ); |
Description: |
The call vt_alignment allows the specification of an offset to
be applied to all coordinates output from a connected graphics tablet.
The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
dx |
X-offset from origin |
dy |
Y-offset from origin
|
|
Return value: |
The function does not return a result. |
Availability: |
Supported by all tablet drivers. |
Group: |
Graphics tablet functions |
See also: |
Binding GDOS vq_tabstatus vq_tdimensions
vt_resolution vt_axis vt_origin
|
7.8.2.4 Bindings for vt_alignment
7.8.2.5 vt_axis
Name: |
»Set tablet axis resolution in lines« - Set the resolution of
the graphics tablet in lines. |
Opcode: |
5 (Escape 82) |
Syntax: |
void vt_axis ( int16_t handle, int16_t xres, int16_t yres,
int16_t *xset, int16_t *yset ); |
Description: |
The call vt_axis sets the horizontal and vertical resolution
for an attached graphics tablet in lines. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
xres |
Desired resolution in lines in X-direction, |
yres |
and in Y-direction |
xset |
Actual resolution in lines in X-direction, |
yset |
and in Y-direction
|
|
Return value: |
The function does not return a result. |
Availability: |
Supported by all tablet drivers. |
Group: |
Graphics tablet functions |
See also: |
Binding GDOS vq_tabstatus vt_alignment vt_resolution
vt_origin vq_tdimensions
|
7.8.2.6 Bindings for vt_axis
C: |
void vt_axis ( int16_t handle, int16_t xres, int16_t yres,
int16_t *xset, int16_t *yset ); |
Binding: |
void vt_axis (int16_t handle, int16_t xres, int16_t yres,
int16_t *xset, int16_t *yset)
{
intin[0] = xres;
intin[1] = yres;
contrl[0] = 5;
contrl[1] = 0;
contrl[3] = 2;
contrl[5] = 82;
contrl[6] = handle;
vdi ();
*xset = intout[0];
*yset = intout[1];
}
|
GEM-Arrays: |
|
7.8.2.7 vt_origin
Name: |
»Set tablet X and Y origin« - Set coordinate origin for
graphics tablet. |
Opcode: |
5 (Escape 83) |
Syntax: |
void vt_origin ( int16_t handle, int16_t xorigin, int16_t
yorigin ); |
Description: |
The call vt_origin sets the point of origin for the coordinate
system (top left corner) of an attached graphics tablet. The following
apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
xorigin |
X-coordinate, and |
yorigin |
Y-coordinate of the top left corner
|
|
Return value: |
The function does not return a result. |
Availability: |
Supported by all tablet drivers. |
Group: |
Graphics tablet functions |
See also: |
Binding GDOS vq_tabstatus vt_alignment vt_resolution
vt_axis vq_tdimensions
|
7.8.2.8 Bindings for vt_origin
7.8.2.9 vt_resolution
Name: |
»Set tablet axis resolution in lines/inch« - Set the resolution
of the graphics tablet in lines per inch. |
Opcode: |
5 (Escape 81) |
Syntax: |
void vt_resolution ( int16_t handle, int16_t xres, int16_t
yres, int16_t *xset, int16_t *yset ); |
Description: |
The call vt_resolution sets the horizontal and vertical
resolution on an attached graphics tablet in lines per inch. The
following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
xres |
Resolution in lines per inch (lpi) in X-direction, and
in |
yres |
Y-direction |
xset |
Actually set resolution in X-direction, and |
yset |
Y-direction
|
|
Return value: |
The function does not return a result. |
Availability: |
Supported by all tablet drivers. |
Group: |
Graphics tablet functions |
See also: |
Binding GDOS vq_tabstatus vt_alignment vt_axis
vt_origin vq_tdimensions
|
7.8.2.10 Bindings for vt_resolution
7.8.3 Metafile functions
This library contains functions that are indispensable for
creating metafiles. In all, the following routines are available:
Note: The main purpose of a metafile lies in standardized
data exchange between various GEM systems.
See also:
Metafile format VDI workstations Style guidelines VDI
fundamentals
7.8.3.1 vm_coords
Name: |
»VDI metafile coordinates« - Custom coordinate system for
metafiles. |
Opcode: |
5 (Escape 99, Opcode 1) |
Syntax: |
void vm_coords ( int16_t handle, int16_t llx, int16_t lly,
int16_t urx, int16_t ury ); |
Description: |
The call vm_coords sets the coordinate system used for the page
of a metafile. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
llx |
X-coordinate, and |
lly |
Y-coordinate (lower left) |
urx |
X-coordinate, and |
ury |
Y-coordinate (upper right)
|
Notes: With this function one must note in which
coordinate type (NDC or RC) the metafile was opened, and if necessary
the Y-values have to be adapted.
This function permits use of almost any coordinate system with
limit of (-32768, -32768), (32767, 32767). |
Return value: |
The function does not return a result. |
Availability: |
Supported by all metafile drivers. |
Group: |
Metafile functions |
See also: |
Binding v_write_meta Metafile format sub-opcodes
|
7.8.3.2 Bindings for vm_coords
7.8.3.3 vm_filename
Name: |
»Change GEM VDI file name« - Change the name of a
metafile. |
Opcode: |
5 (Escape 100) |
Syntax: |
void vm_filename ( int16_t handle, CONST int8_t *filename ); |
Description: |
The call vm_filename renames a metafile from the default
GEMFILE.GEM to another name while retaining the extension GEM.
The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
filename |
New name of the metafile (NULL-terminated)
|
Note: The parameter filename can also contain a
path name with drive identifier. If the function is not called
immediately after an v_opnwk call, then it will have no effect. A
possibly opened metafile will be closed.
As older metafile drivers (in contrast to NVDI drivers) may not
delete the source file "GEMFILE.GEM" which is created in the
current directory, the application should take over this task itself. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all metafile drivers. |
Group: |
Metafile functions |
See also: |
Binding GDOS v_opnwk Metafile format sub-opcodes
|
7.8.3.4 Bindings for vm_filename
7.8.3.5 vm_pagesize
Name: |
»VDI page size« - Set the physical page size for metafiles. |
Opcode: |
5 (Escape 99, Opcode 0) |
Syntax: |
void vm_pagesize ( int16_t handle, int16_t pgwidth, int16_t
pgheight ); |
Description: |
The call vm_pagesize sets the metafile's source page size in
1/10 mm. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
pgwidth |
Page width in 1/10 mm |
pgheight |
Page height in 1/10 mm
|
Note: As the width and height of a page may be set
separately, it is also possible to create graphics in landscape format
(width greater than the height). |
Return value: |
The function does not return a result. |
Availability: |
Supported by all metafile drivers. |
Group: |
Metafile functions |
See also: |
Binding v_write_meta Metafile format sub-opcodes
|
7.8.3.6 Bindings for vm_pagesize
7.8.3.7 v_meta_extents
Name: |
»Update metafile extents« - Update the size information for a
metafile. |
Opcode: |
5 (Escape 98) |
Syntax: |
void v_meta_extents ( int16_t handle, int16_t min_x, int16_t
min_y, int16_t max_x, int16_t max_y ); |
Description: |
The call v_meta_extents updates the size information in the
header of a metafile. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
min_x |
Minimum X-value, and |
min_y |
Minimum Y-value of the smallest bounding box (the top left
corner) |
max_x |
Maximum X-value, and |
max_y |
Maximum Y-value of the smallest bounding box (the bottom left
corner)
|
Notes: The size information can be used to obtain quickly
the minimum or maximum dimensions of all the primitives stored in the
metafile.
The parameters sent to this call should be specified in whatever
coordinate system the metafile is using at the time. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all metafile drivers. |
Group: |
Metafile functions |
See also: |
Binding GDOS vm_filename v_write_meta Metafile
format
|
7.8.3.8 Bindings for v_meta_extents
7.8.3.9 v_write_meta
Name: |
»Write metafile item« - Write an object to a metafile. |
Opcode: |
5 (Escape 99) |
Syntax: |
void v_write_meta ( int16_t handle, int16_t num_intin, int16_t
*a_intin, int16_t num_ptsin, int16_t *a_ptsin ); |
Description: |
The call v_write_meta permits the marking of a parameter
written to a metafile with an opcode as a user-defined graphic object.
The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
num_intin |
Number of values in intin array (0 - 127) |
num_ptsin |
Number of values in ptsin array(0 - 127) |
a_intin[0] |
Sub-opcode (user-defined) |
a_intin[1] |
|
: |
|
: |
|
a_intin[num_intin-1] |
User-defined information |
a_ptsin[0] |
|
: |
|
: |
|
a_ptsin[num_ptsin-1] |
User-defined information
|
Note: Sub-opcodes 0 to 100 are reserved; some have been
pre-defined:
a_intin |
Meaning |
10 |
Start group |
11 |
End group |
49 |
Set no line style |
50 |
Set attribute shadow on |
51 |
Set attribute shadow off |
80 |
Start draw area type primitive |
81 |
End draw area type primitive |
|
Return value: |
The function does not return a result. |
Availability: |
Supported by all metafile drivers. |
Group: |
Metafile functions |
See also: |
Binding GDOS v_meta_extents Metafile format sub-opcodes
|
7.8.3.10 Bindings for v_write_meta
7.8.4 Polaroid functions
This library contains functions to access a Polaroid image
recorder. The following routines are available for this purpose:
• vqp_error |
Gets error codes of the Polaroid driver |
• vqp_filmname |
Gets name from a film number |
• vqp_films |
Gets available film types |
• vqp_state |
Gets status of the Polaroid driver |
• vsc_expose |
Switches on/off preview option for camera |
• vsp_film |
Sets film type and exposure time |
• vsp_message |
Suppresses or permits error-messages of the Polaroid driver |
• vsp_save |
Saves settings of the Polaroid driver |
• vsp_state |
Resets Polaroid driver
|
Note: Drivers for the Polaroid palette are non-existent at
the time of writing. The functions vsp_film, vqp_filmname and
vsc_expose were introduced with PC-GEM Version 2.0, and replace
the other six routines from GEM 1.x.
See also: VDI workstations Style guidelines
7.8.4.1 vqp_error
Name: |
»Palette error inquire« - Return the number of an error that
has occurred. |
Opcode: |
5 (Escape 96) |
Syntax: |
int16_t vqp_error ( int16_t handle ); |
Description: |
The call vqp_error obtains the last error occurring in
connection with the Polaroid image recorder with the ID
handle. |
Return value: |
The function returns:
Value |
Meaning |
|
|
0 |
No error |
1 |
Shutter open |
2 |
No port selected |
3 |
Palette not available at chosen port |
4 |
Connection broken off |
5 |
Operating system does not allow memory allocation |
6 |
Insuficient buffer memory |
7 |
No free memory |
8 |
Workstation driver file missing |
9 |
Workstation driver file has an invalid format |
10 |
Film at end
|
|
Availability: |
This function is no longer available from PC-GEM Version
2.0 onwards. |
Group: |
Polaroid functions |
See also: |
Binding GDOS
|
7.8.4.2 Bindings for vqp_error
7.8.4.3 vqp_filmname
Name: |
»Inquire camera film name« - Obtain the name of a given film
number. |
Opcode: |
5 (Escape 92) |
Syntax: |
int16_t vqp_filmname ( int16_t handle, int16_t index, int8_t
*name ); |
Description: |
The call vqp_filmname returns the corresponding name belonging
to a film number. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
index |
Number of the film type |
name |
Name of the film (NULL-terminated)
|
Note: With an invalid film number the return will be a
NULL-string. |
Return value: |
The function returns the value 0 if an invalid film number was
passed. |
Availability: |
The function is available only from PC-GEM Version 2.0
onwards. |
Group: |
Polaroid functions |
See also: |
Binding GDOS
|
7.8.4.4 Bindings for vqp_filmname
7.8.4.5 vqp_films
Name: |
»Inquire palette film types« - Obtain information about a film. |
Opcode: |
5 (Escape 91) |
Syntax: |
void vqp_films ( int16_t handle, int8_t *film_names ); |
Description: |
The call vqp_films obtains information about a film. The
following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
film_names |
Name, manufacturer and sensitivity of the film
|
Note: The parameter film_names should point to a
126 byte sized buffer in which 5 entries of 25 characters each are
stored. |
Return value: |
The function does not return a result. |
Availability: |
This function is no longer available from PC-GEM Version
2.0 onwards. |
Group: |
Polaroid functions |
See also: |
GDOS
|
7.8.4.6 vqp_state
Name: |
»Inquire palette driver state« - Obtain the device state of the
Polaroid image recorder. |
Syntax: |
void vqp_state ( int16_t handle, int16_t *port, int8_t
*film_name, int16_t *lightness, int16_t *interlace, int16_t *planes,
int16_t *indexes ); |
Description: |
The call vqp_state obtains the status of a Polaroid image
recorder. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
port |
Number of the port (0 = first port) |
film_name |
Number of the film name (0 to 4) |
lightness |
Brightness (-3 to 3, where each step corresponds to a third of
a stop) |
interlace |
Image is scanned with (1) or without (0) interlace |
planes |
Number of colours = 2^planes, where planes lies
between 1 and 4 |
indexes |
Specifies the colours of the colour palette. 16 bytes of memory
space is required. Each colour is identified by a number (for the rows
of the colour matrix) and a letter between A and H (for the column of
the colour matrix).
|
|
Return value: |
The function does not return a result. |
Availability: |
This function is no longer available from PC-GEM Version
2.0 onwards. |
Group: |
Polaroid functions |
See also: |
GDOS vsp_state vsp_save vsp_message vqp_films
|
7.8.4.7 vsc_expose
Name: |
»Disable or enable film exposure for frame preview« - Switch
on/off exposure for previews with an image recorder camera. |
Opcode: |
5 (Escape 93) |
Syntax: |
void vsc_expose ( int16_t handle, int16_t state ); |
Description: |
The call vsc_expose permits switching on/off the exposure for
image recorders with a preview option. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
state |
Exposure:
0 = |
Switch off |
<> 0 = |
Switch on |
|
|
Return value: |
The function does not return a result. |
Availability: |
This function is only available from PC-GEM Version 2.0
onwards. |
Group: |
Polaroid functions |
See also: |
Binding GDOS vsp_save vqp_state vsp_state
vqp_films vsp_message
|
7.8.4.8 Bindings for vsc_expose
7.8.4.9 vsp_film
Name: |
»Set camera film type and exposure time« |
Opcode: |
5 (Escape 91) |
Syntax: |
void vsp_film ( int16_t handle, int16_t index, int16_t
lightness ); |
Description: |
The call vsp_film specifies the film type and the exposure time
for the image recorder. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
index |
Number of the film type |
lightness |
Exposure time:
-3 = |
Half |
0 = |
Normal |
3 = |
Double
|
|
Note: With increasing value of the parameter
lightness the exposure is increased by one third of a stop.
The valid indices for index can be obtained with vqp_filmname. |
Return value: |
The function does not return a result. |
Availability: |
The function is only available from PC-GEM Version 2.0
onwards. |
Group: |
Polaroid functions |
See also: |
Binding GDOS
|
7.8.4.10 Bindings for vsp_film
7.8.4.11 vsp_message
Name: |
»Suppress palette message« - Suppress error-messages of the
Polaroid image recorder. |
Syntax: |
void vsp_message ( int16_t handle ); |
Description: |
The call vsp_message suppresses error-messages of the Polaroid
image recorder with the ID handle. |
Return value: |
The function does not return a result. |
Availability: |
The function is available only from PC-GEM Version 2.0
onwards. |
Group: |
Polaroid functions |
See also: |
GDOS vqp_error
|
7.8.4.12 vsp_save
Name: |
»Save palette driver state« - Save the device state of the
Polaroid image recorder. |
Syntax: |
void vsp_save ( int16_t handle ); |
Description: |
The call vsp_save saves the status of a Polaroid image recorder
with the ID handle. |
Return value: |
The function does not return a result. |
Availability: |
This function is no longer available from PC-GEM Version
2.0 onwards. |
Group: |
Polaroid functions |
See also: |
GDOS vqp_state vsp_state vsp_message vqp_films
vsc_expose
|
7.8.4.13 vsp_state
Name: |
»Set palette driver state« - Set the state of the Polaroid
recorder. |
Syntax: |
void vsp_state ( int16_t handle, int16_t port, int16_t
film_num, int16_t lightness, int16_t interlace, int16_t planes,
int16_t *indexes ); |
Description: |
The call vsp_state sets the output status of a Polaroid image
recorder. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
port |
Number of the port (0 = first port) |
film_num |
Number of the film name (0 to 4) |
lightness |
Brightness (-3 to 3, where each step corresponds to a third of
a stop) |
interlace |
Image is scanned with (1) or without (0) interlace |
planes |
Number of colours = 2^planes, where planes lies
between 1 and 4 |
indexes |
Specifies the colours of the colour palette. 16 bytes of memory
space is required. Each colour is identified by a number (for the rows
of the colour matrix) and a letter between A and H (for the column of
the colour matrix).
|
|
Return value: |
The function does not return a result. |
Availability: |
This function is no longer available from PC-GEM Version
2.0 onwards. |
Group: |
Polaroid functions |
See also: |
GDOS vsc_expose vqp_state vsp_save vsp_message
vqp_films
|
7.8.5 Special functions
This library contains functions for some special purposes that
cannot be assigned to any of the other groups of Escape functions. The
following routines are available:
See also: VDI workstations Style guidelines
7.8.5.1 v_escape2000
Name: |
»Escape 2000« - Special function for ATARI page-printer. |
Opcode: |
5 (Escape 2000) |
Syntax: |
void v_escape2000 ( int16_t handle, int16_t times ); |
Description: |
The call v_escape2000 prints any number of extra copies of the
current page. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
times |
Number of additional copies
|
Note: The function works only in connection with the Atari
SLM laser printers; therefore it is better to fall back to the
function v_copies. |
Return value: |
The function does not return a result. |
Availability: |
Supported only with some laser printer drivers (for instance
the Atari SLM laser printer driver) under some forms of GDOS. |
Group: |
Special functions |
See also: |
Binding GDOS
|
7.8.5.2 Bindings for v_escape2000
7.8.5.3 v_fontinit
Name: |
»Init system font« - Initializes a system font. |
Opcode: |
5 (Escape 102) |
Syntax: |
void v_fontinit ( int16_t handle, int16_t fh_high, int16_t
fh_low ); |
Description: |
The call v_fontinit installs a specified font as the system
font. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
fh_high |
Address of the font header (high) |
fh_low |
Address of the font header (low)
|
Note: The function is described in no official
documentation - use it at your own risk! Some attempts have shown that
the character width has to be a constant eight pixels and the font
must be in the Motorola (big-endian) format. |
Return value: |
The function does not return a result. |
Availability: |
All TOS versions; ROM screen driver. |
Group: |
Special functions |
See also: |
Binding Header for bitmap GDOS fonts
|
7.8.5.4 Bindings for v_fontinit
C: |
void v_fontinit ( int16_t handle, int16_t fh_high, int16_t
fh_low ); |
Binding: |
void v_fontinit (int16_t handle, int16_t fh_high,
int16_t fh_low)
{
intin[0] = fh_high;
intin[1] = fh_low;
contrl[0] = 5;
contrl[1] = 0;
contrl[3] = 2;
contrl[5] = 102;
contrl[6] = handle;
vdi ();
}
|
GEM-Arrays: |
Note: The pointer to the font header will be stored in the
fields intin[0..1] here.
|
7.8.5.5 v_offset
Name: |
»Set screen offset« - Set the top screen margin. |
Opcode: |
5 (Escape 101) |
Syntax: |
void v_offset ( int16_t handle, int16_t offset ); |
Description: |
The call v_offset sets the offset in raster lines to the start
of the logical screen. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
offset |
Number of raster lines below the top screen edge up to the
start of the logical screen
|
Note: The function is described in no official
documentation - use it at your own risk! |
Return value: |
The function does not return a result. |
Availability: |
ROM screen driver. |
Group: |
Special functions |
See also: |
Binding
|
7.8.5.6 Bindings for v_offset
7.8.5.7 v_sound
Name: |
»Generate specified tone« |
Opcode: |
5 (Escape 61) |
Syntax: |
void v_sound ( int16_t handle, int16_t frequency, int16_t
duration ); |
Description: |
The call v_sound generates a tone of a specified length and
frequency. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
frequency |
Tone frequency in Hertz |
duration |
Tone length in timer ticks
|
|
Return value: |
The function does not return a result. |
Availability: |
The function is only available under PC-GEM as of Version
2.0. |
Group: |
Special functions |
See also: |
Binding GDOS vs_mute
|
7.8.5.8 Bindings for v_sound
7.8.5.9 vs_mute
Name: |
»Set/clear tone muting flag« |
Opcode: |
5 (Escape 62) |
Syntax: |
int16_t vs_mute ( int16_t handle, int16_t action ); |
Description: |
The call vs_mute sets or clears the tone flag, or returns it
status. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
action |
Desired action:
-1 = |
Inquire status |
0 = |
Tone generation on |
1 = |
Tone generation off
|
|
|
Return value: |
The function returns the status of the tone generation. |
Availability: |
The function is available only under PC-GEM as of Version
2.0. |
Group: |
Special functions |
See also: |
Binding GDOS v_sound
|
7.8.5.10 Bindings for vs_mute
7.8.6 Text functions
This library contains functions for control of the alphanumeric
screen; the following routines are available for this purpose:
• v_alpha_text |
Outputs text in text mode to printer or metafile |
• v_curdown |
Moves text cursor one row down |
• v_curhome |
Moves text cursor to top left corner |
• v_curleft |
Moves text cursor one column left |
• v_curright |
Moves text cursor one column right |
• v_curtext |
Outputs text to screen from text cursor position on |
• v_curup |
Moves text cursor one row up |
• v_eeol |
Clears screen from text cursor to end of line |
• v_eeos |
Clears screen from text cursor to end of screen |
• v_enter_cur |
Switches on text mode |
• v_exit_cur |
Exits text mode |
• v_rvoff |
Switches off inverse video |
• v_rvon |
Switches on inverse video |
• vq_chcells |
Gets number of rows and columns of the text screen |
• vq_curaddress |
Gets row and column of current text cursor |
• vs_curaddress |
Positions text cursor at given row and column
|
See also: VDI workstations Style guidelines
7.8.6.1 vq_chcells
Name: |
»Inquire addressable alpha character cells« - Obtain the number
of rows and columns of a workstation. |
Opcode: |
5 (Escape 1) |
Syntax: |
void vq_chcells ( int16_t handle, int16_t *rows, int16_t
*columns ); |
Description: |
The call vq_chcells obtains the number of rows and columns that
can be accessed with the alpha cursor. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
rows |
Number of rows |
columns |
Number of columns
|
Note: A value of 0 in the parameters rows or
columns means that addressing is not possible. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen and printer drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur
|
7.8.6.2 Bindings for vq_chcells
7.8.6.3 vq_curaddress
Name: |
»Inquire current alpha cursor address« |
Opcode: |
5 (Escape 15) |
Syntax: |
void vq_curaddress ( int16_t handle, int16_t *row, int16_t
*column ); |
Description: |
The call vq_curaddress obtains the current alpha text cursor
position.
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
row |
Row number (1 to the maximum number of rows) |
column |
Column number (1 to the maximum number of columns)
|
|
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur
|
7.8.6.4 Bindings for vq_curaddress
7.8.6.5 v_alpha_text
Name: |
»Output alpha text« - Output a line of alpha text in text mode
to a printer or metafile. |
Opcode: |
5 (Escape 25) |
Syntax: |
void v_alpha_text ( int16_t handle, int8_t *string ); |
Description: |
The call v_alpha_text outputs a line of alpha text in text mode
to a printer (or metafile) at the current position of the printhead.
The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
string |
Address of text string (NULL-termminated)
|
Note: The output is not made in graphic mode. Two
special BYTE codes may be embedded in the text for control functions
that are standardized for all printers ('DC2' corresponds to ASCII
18):
Code |
Meaning |
|
|
DC2 0 |
Enable bold print |
DC2 1 |
Disable bold print |
DC2 2 |
Enable italic print |
DC2 3 |
Disable italic print |
DC2 4 |
Enable underlining |
DC2 5 |
Disable underlining |
DC2 6 |
Enable superscript |
DC2 7 |
Disable superscript |
DC2 8 |
Enable subscript |
DC2 9 |
Disable subscript |
DC2 A |
Enable NLQ mode |
DC2 B |
Disable NLQ mode |
DC2 C |
Enable wide printing |
DC2 D |
Disable wide printing |
DC2 E |
Enable light printing |
DC2 F |
Disable light printing |
DC2 G |
|
: |
|
: |
|
DC2 V |
Reserved, will be ignored |
DC2 W |
Switch to pica printing (10 cpi) |
DC2 X |
Switch to elite printing (12 cpi) |
DC2 Y |
Toggle compressed printing |
DC2 Z |
Toggle proportional printing
|
In addition, form-feed with the ASCII value 12 is supported. Under
PC-GEM, graphics can be taken into account as well; the syntax in
this case is:
(ESC)(ESC)GEM,x,y,w,h,C:\pathname\filename.img
The parameters x, y, w and h for this are to be
given in character units relative to the current cursor position. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all printer and metafile drivers. |
Group: |
Text functions |
See also: |
Binding OUT file format
|
7.8.6.6 Bindings for v_alpha_text
7.8.6.7 v_curaddress
Name: |
»Direct alpha cursor address« - Set the alpha cursor to the
specified position. |
Opcode: |
5 (Escape 11) |
Syntax: |
void v_curaddress ( int16_t handle, int16_t row, int16_t column
); |
Description: |
The call v_curaddress moves the alpha cursor to a given column
and row.
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
row |
Row number (1 to maximum number of rows) |
column |
Column number (1 to maximum number of columns)
|
Note: If addresses above the maximum limit are specified,
the function will assume the nearest valid value. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur
|
7.8.6.8 Bindings for v_curaddress
7.8.6.9 v_curdown
Name: |
»Alpha cursor down« - Move the alpha cursor down by one row. |
Opcode: |
5 (Escape 5) |
Syntax: |
void v_curdown ( int16_t handle ); |
Description: |
The call v_curdown moves the alpha cursor on the workstation
with the ID handle one row or line down.
Note: If the cursor is already in the last row, nothing
happens. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur
|
7.8.6.10 Bindings for v_curdown
7.8.6.11 v_curhome
Name: |
»Home alpha cursor« - Move the alpha cursor to the |
Opcode: |
5 (Escape 8) |
Syntax: |
void v_curhome ( int16_t handle ); |
Description: |
The call v_curhome moves the alpha cursor on the workstation
with the ID handle to the 'home' position.
Note: The 'home' position normally means the position at
the top left corner of the screen. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur
|
7.8.6.12 Bindings for v_curhome
7.8.6.13 v_curleft
Name: |
»Alpha cursor left« - Move the alpha cursor left by one
character. |
Opcode: |
5 (Escape 7) |
Syntax: |
void v_curleft ( int16_t handle ); |
Description: |
The call v_curleft moves the alpha cursor on the workstation
with the ID handle one column to the left.
Note: If it is already in the first column, nothing
happens. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur
|
7.8.6.14 Bindings for v_curleft
7.8.6.15 v_curright
Name: |
»Alpha cursor right« - Move the alpha cursor right by one
character. |
Opcode: |
5 (Escape 6) |
Syntax: |
void v_curright ( int16_t handle ); |
Description: |
The call moves v_curright the alpha cursor on the workstation
with the ID handle one column to the right.
Note: If the cursor is already in the last column, nothing
happens. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur
|
7.8.6.16 Bindings for v_curright
7.8.6.17 v_curtext
Name: |
»Output cursor addressable alpha text« - Output a line of text
to the screen from the alpha cursor onwards. |
Opcode: |
5 (Escape 12) |
Syntax: |
void v_curtext ( int16_t handle, int8_t *string ); |
Description: |
The call v_curtext outputs a line of text to the screen in text
mode from the current cursor position onwards. The following apply:
Parameter |
Meaning |
|
|
handle |
Workstation identifier |
string |
Pointer to text string (max. 127 chars.)
|
The cursor is advanced by one position for each character output
(alpha mode).
Note: Text output with this function can be faster
than via GEMDOS. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur v_curup v_curdown v_curright
v_curleft v_curhome vs_curaddress
|
7.8.6.18 Bindings for v_curtext
7.8.6.19 v_curup
Name: |
»Alpha cursor up« - Move the alpha cursor up by one row. |
Opcode: |
5 (Escape 4) |
Syntax: |
void v_curup ( int16_t handle ); |
Description: |
The call v_curup moves the alpha cursor on the workstation with
the ID handle one row or line upwards.
Note: If the cursor is already in the first row, nothing
happens. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur
|
7.8.6.20 Bindings for v_curup
7.8.6.21 v_eeol
Name: |
»Erase to end of alpha text line« - Clear the text line from
the alpha cursor onwards. |
Opcode: |
5 (Escape 10) |
Syntax: |
void v_eeol ( int16_t handle ); |
Description: |
The call v_eeol clears the current text line from the current
text cursor position rightwards on the workstation with the ID
handle.
Note: The position of the cursor will not be altered by
this. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur
|
7.8.6.22 Bindings for v_eeol
7.8.6.23 v_eeos
Name: |
»Erase to end of alpha screen« - Clear the screen of text from
the alpha cursor onwards. |
Opcode: |
5 (Escape 9) |
Syntax: |
void v_eeos ( int16_t handle ); |
Description: |
The call v_eeos clears the alphanumeric screen of text from the
current cursor position onwards on the workstation with the ID
handle.
Note: The position of the cursor will not be altered by
this. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur
|
7.8.6.24 Bindings for v_eeos
7.8.6.25 v_enter_cur
Name: |
»Enter alpha mode« - Switch text mode on for screen or
metafile. |
Opcode: |
5 (Escape 3) |
Syntax: |
void v_enter_cur ( int16_t handle ); |
Description: |
The call v_enter_cur exits the graphic mode on the workstation
with the ID handle (screen or metafile) if this is not
identical to the alpha mode.
In addition the mouse pointer will be removed, the alpha cursor
set to the top left character cell, and the alpha screen will be
cleared (by setting it to the colour 0); with a metafile a
corresponding entry will be made in the file. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_exit_cur
|
7.8.6.26 Bindings for v_enter_cur
7.8.6.27 v_exit_cur
Name: |
»Exit alpha mode« - Switch text mode off for screen or
metafile. |
Opcode: |
5 (Escape 2) |
Syntax: |
void v_exit_cur ( int16_t handle ); |
Description: |
The call v_exit_cur switches off the alpha mode on the
workstation with the ID handle (screen or metafile) if the
alpha and graphic modes are different.
The alpha mode is the normal text mode without any graphics, such
as used by the desktop for depicting files and folders in windows set
to 'Display > As Text' for instance.
Note: The function also clears the graphics screen and
restores the mouse pointer (to completely restore the screen, you
should call form_dial( FMD_FINISH sx, sy, sw, sh ) where
sx, sy, sw, sh are the coordinates of the screen); with a
metafile a corresponding entry is made in the file. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur
|
7.8.6.28 Bindings for v_exit_cur
7.8.6.29 v_rvoff
Name: |
»Reverse video off« - Switch off inverse video mode. |
Opcode: |
5 (Escape 14) |
Syntax: |
void v_rvoff ( int16_t handle ); |
Description: |
The call v_rvoff switches off the inverse alpha text display
(causing it to appear as normal video) on the workstation with the ID
handle. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur v_rvon
|
7.8.6.30 Bindings for v_rvoff
7.8.6.31 v_rvon
Name: |
»Reverse video on« - Switch on inverse video mode. |
Opcode: |
5 (Escape 13) |
Syntax: |
void v_rvon ( int16_t handle ); |
Description: |
The call v_rvon activates the inverse alpha text display on the
workstation with the ID handle. |
Return value: |
The function does not return a result. |
Availability: |
Supported by all screen drivers. |
Group: |
Text functions |
See also: |
Binding v_enter_cur v_rvoff
|
7.8.6.32 Bindings for v_rvon