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

HomeVDIColour table functionsRaster functions

7.10 Control functions

This library contains functions to open and close working devices and to load fonts. Furthermore, these functions allow manipulation for Bezier spline creation and the management of vector font caches.

In total the following routines are available:

v_bez_on Switches on Bezier spline creation
v_bez_off Switches off Bezier spline creation
• v_clr_cachedir No information available at present
v_clrwk Reinitializes workstation
v_clsbm Closes an off-screen bitmap
v_clsvwk Closes a virtual screen workstation
v_clswk Closes a physical workstation
• v_def_cachedir No information available at present
• v_delete_cache No information available at present
• v_fgetoutline No information available at present
v_flushcache Clears vector font cachen.
• v_get_cachedir No information available at present
v_get_outline Calculates outline of a character (improved version for NVDI)
v_getoutline Calculates outline of a character
v_killoutline Releases memory for outline generation
v_loadcache Loads vector font cache
v_open_bm Opens an off-screen bitmap (modernized version)
v_opnbm Opens an off-screen bitmap
v_opnprn Opens a printer driver
v_opnvwk Opens a virtual screen workstation
v_opnwk Opens a physical workstation.
v_pat_rotate Rotates a pattern
v_resize_bm Alters the size of an off-screen bitmap
v_savecache Saves outline font cache to disk.
v_set_app_buff Designates memory workspace for Bezier spline creation
• v_set_cachedir No information available at present.
v_updwk Executes buffered workstation output commands
• vs_backmap No information available at present
vs_clip Sets or deletes a clipping rectangle
• vs_outmode No information available at present
• vs_use_fonts No information available at present
vst_ex_load_fonts Loads additional fonts (extended version)
vst_load_fonts Loads fonts
vst_unload_fonts nloads fonts

See also: VDI workstations   Style guidelines

7.10.1 v_bez_off

Name: »Disable Bezier capabilities« - Switch off Bezier spline creation.
Opcode: 11 (Sub-Opcode 13)
Syntax: void v_bez_off ( int16_t handle );
Description: The call v_bez_off deactivates the Bezier spline creation of GDOS on the workstation with the ID handle and frees the associated memory.

Note: Although handle specifies a given workstation, the deactivation applies to all workstations.
Return value: The function does not return a result.
Availability: As of GEM/3 Release 3.1, FONTGDOS, FSMGDOS, from SpeedoGDOS 4.00 onwards, and as of NVDI 2.10.
Group: Control functions
See also: Binding   v_bez_on   v_bez   v_bez_fill   v_bez_qual   v_set_app_buff

7.10.2 Bindings for v_bez_off

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

   vdi ();
}
GEM-Arrays:

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

7.10.3 v_bez_on

Name: »Enable Bezier capabilities« - Switch on Bezier spline creation.
Opcode: 11 (Sub-Opcode 13)
Syntax: int16_t v_bez_on ( int16_t handle );
Description: The call v_bez_on activates the Bezier spline creation of GDOS on the workstation with the ID handle.

Notes: Although handle specifies a given workstation, the activation applies to all workstations.

This function is present for reasons of compatibility. It serves to make calls of v_pline without the sub-function number 13 to act as calls of v_bez, and calls of v_fillarea without the subfunction number to act as calls of v_bez_fill. The function is normally used only to check whether Beziers are present.
Return value: This function returns a value between 0 (no Beziers) and 7 (maximum quality) and represents the Bezier depth. You should only use this value to determine if the driver is able to draw Bezier curves.
Availability: As of GEM/3 Release 3.1, FONTGDOS, FSMGDOS, from SpeedoGDOS 4.00 onwards, and as of NVDI 2.10.
Group: Control functions
See also: Binding   v_bez_off   v_bez   v_bez_fill   v_bez_qual   v_set_app_buff

7.10.4 Bindings for v_bez_on

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

   vdi ();

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

Address Element Contents
contrl contrl[0] 11 # 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] 13 # Sub-opcode
contrl+12 contrl[6] handle
intout intout[0] Return Value

7.10.5 v_clrwk

Name: »Clear workstation« - Reinitialize working device.
Opcode: 3
Syntax: void v_clrwk ( int16_t handle );
Description: The call v_clrwk sets the physical workstation with the ID handle to an exactly defined initial state. The following apply:
Workstation Effect of the call
   
Screen The screen will be cleared, and set to the selected background colour
Plotter Clears the plotter's buffer
Printer Clears the printer's buffer, and also performs a form-feed
Metafile Saves the opcode
Camera Deletes the output, and sets the background colour


Notes: With a v_opnwk call the relevant device (e.g. the screen) will be cleared automatically.

Applying this function to a virtual workstation will clear the underlying physical workstation; generally this is not recommended as it will affect all virtual workstations, not just your own.
Return value: The function does not return a result.
Availability: Supported by all drivers.
Group: Control functions
See also: Binding   v_form_adv

7.10.6 Bindings for v_clrwk

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

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 3 # 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+12 contrl[6] handle

7.10.7 v_clsbm

Name: »Close bitmap« - Close an off-screen bitmap.
Opcode: 101 (Sub-Opcode 1)
Syntax: void v_clsbm ( int16_t handle );
Description: The call v_clsbm closes the bitmap specified with handle. The memory of the bitmap will be freed if the VDI has allocated it.
Return value: The function does not return a direct result.
Availability: As of EdDI Version 1.00.
Group: Control functions
See also: Binding   NVDI   Off-screen bitmaps   v_opnbm

7.10.8 Bindings for v_clsbm

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

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 101 # 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] 1 # Sub-opcode
contrl+12 contrl[6] handle

7.10.9 v_clsvwk

Name: »Close virtual screen workstation« - Close a virtual screen workstation.
Opcode: 101
Syntax: void v_clsvwk ( int16_t handle );
Description: The call v_clsvwk closes the workstation with the ID handle that was previously opened with v_opnvwk.

Note: This function must not be used if an error occurred while opening the workstation.
Return value: The function does not return a result.
Availability: Supported by all drivers.
Group: Control functions
See also: Binding   v_opnvwk   v_clswk

7.10.10 Bindings for v_clsvwk

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

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 101 # 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+12 contrl[6] handle

7.10.11 v_clswk

Name: »Close workstation« - Close a physical workstation.
Opcode: 2
Syntax: void v_clswk ( int16_t handle );
Description: The call v_clswk closes the device with the ID handle that was opened previously with a v_opnwk call.

The function call has the following effects on the various device types:
Device Effect of the call
   
Screen Switch over to the alpha mode
Plotter Update
Drucker Update, if not happened already
Metafile File will be closed
Camera Update


Note: Before calling this function one should ensure that all virtual workstations on the corresponding device are closed.
Return value: The function does not return a result.
Availability: Available only with some form of GDOS.
Group: Control functions
See also: Binding   GDOS   v_opnwk   v_opnvwk   v_clsvwk

7.10.12 Bindings for v_clswk

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

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 2 # 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+12 contrl[6] handle

7.10.13 v_flushcache

Name: »Flush outline cache« - Clear vector font cache.
Opcode: 251
Syntax: int16_t v_flushcache ( int16_t handle );
Description: The call v_flushcache clears the contents the outline (= vector) character cache that holds the bitmaps of the vector characters.

The parameter handle specifies the ID of the relevant workstation.
Return value: The function returns the value -1 in case of error, else the value 0.
Availability: FSMGDOS, as of SpeedoGDOS 4.00 and from NVDI 3.00 on; however, no binding is shown for NVDI.
Group: Control functions
See also: Binding   v_loadcache   v_savecache   vqt_cachesize

7.10.14 Bindings for v_flushcache

C: int16_t v_flushcache ( int16_t handle );
Binding:
int16_t v_flushcache ( int16_t handle );
{
   contrl[0] = 251;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[6] = handle;

   vdi ();

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

Address Element Contents
contrl contrl[0] 251 # 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+12 contrl[6] handle
intout intout[0] Return value

7.10.15 v_getoutline

Name: »Get character outline« - Calculate outline of a vector character.
Opcode: 243
Syntax: void v_getoutline ( int16_t handle, int16_t ch, int16_t *xyarray, int8_t *bezarray, int16_t maxpts, int16_t *count );
Description: The call v_getoutline uses Bezier curves to create the outline that belongs to a given vector character. The following apply:
Parameter Meaning
   
handle Workstation identifier
ch Character whose outline is to be calculated
xyarray Coordinate buffer
bezarray Vertice-type buffer (jump, bez)
maxpts Maximum number of vertices
count Number of vertices


Note: The returned values can be passed directly to the output function for Bezier splines (v_bez, v_bez_fill).

If one wants to use the information from this function as a vector graphic, say as a part of a metafile, then it is recommended that a large text height is set before the call; otherwise the quality of the returned Bezier may be quite poor, as the internal presentation in 1/65536 pixels is rounded off to integer fixed point pixels, i.e. 16 bits will be lost. The text height should be oriented to the raster resolution of the font outline, as returned by the function vqt_fontheader.
Return value: The function does not return a result.
Availability: As of SpeedoGDOS 4.00 and from NVDI 3.00 on.
Group: Control functions
See also: Binding   v_get_outline   v_killoutline   SpeedoGDOS   NVDI   fix31

7.10.16 Bindings for v_getoutline

C: void v_getoutline ( int16_t handle, int16_t ch, int16_t *xyarray, int8_t *bezarray, int16_t maxpts, int16_t *count );
Binding:
void v_getoutline (int16_t handle, int16_t ch, int16_t *xyarray,
                   int8_t *bezarray, int16_t maxpts,
                   int16_t *count)
{
   intin[0] = ch;
   intin[1] = maxpts;
   intin[2..3] = xyarray;
   intin[4..5] = bezarray;

   contrl[0] = 243;
   contrl[1] = 0;
   contrl[3] = 6;
   contrl[6] = handle;

   vdi ();

   *count = intout[0];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 243 # 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] 0 # Entry in intout
contrl+12 contrl[6] handle
intin intin[0] ch
intin+2 intin[1] maxpts
intin+4 intin[2..3] xyarray
intin+8 intin[4..5] bezarray
intout intout[0] count

7.10.17 v_get_outline

Name: »Get character outline« - Calculate outline of a character (improved version).
Opcode: 243 (Sub-Opcode 1)
Syntax: int16_t v_get_outline ( int16_t handle, uint16_t index, uint16_t x_offset, uint16_t y_offset, int16_t *xyarray, uint8_t *bezarray, int16_t max_pts );
Description: The call v_get_outline creates the outline that belongs to a given character. This improved version of v_getoutline:
  • Works the same way for any font format
  • Accepts offsets for X- and Y-coordinates
  • Also works with rotation
  • Respects vertical alignment
  • Respects horizontal alignment
Parameter Meaning
   
handle Workstation identifier
index Character index
x_offset Is added to all X-coordinates in xyarray
y_offset Is added to all Y-coordinates in xyarray
xyarray Buffer for the coordinates
bezarray Buffer for vertice information
max_pts Maximum number of vertices to be output


Note 1: The returned values can be passed directly to the output function for Bezier splines (v_bez, v_bez_fill).

Note 2: With the previous v_getoutline (old Speedo function), rotation did not work at all, and alignment was ignored as well. Furthermore, with Speedo fonts the Y-coordinate 0 corresponded to the top coordinate used in the character (so, depending on the character, was positioned somewhere within the character cell), while with Postscript and TrueType fonts the Y-coordinate 0 always corresponded to the top edge of the character cell.
Return value: The function returns the number of vertices output.
Availability: As of NVDI 5.00.
Group: Control functions
See also: Binding   v_getoutline   v_killoutline   SpeedoGDOS   NVDI   fix31

7.10.18 Bindings for v_get_outline

C: int16_t v_get_outline ( int16_t handle, uint16_t index, uint16_t x_offset, uint16_t y_offset, int16_t *xyarray, uint8_t *bezarray, int16_t max_pts );
Binding:
int16_t v_get_outline ( int16_t handle, uint16_t index,
                        uint16_t x_offset, uint16_t y_offset,
                        int16_t *xyarray, uint8_t *bezarayr,
                        int16_t max_pts )
{
   intin[0] = index;
   intin[1] = max_pts;
   intin[2..3] = xyarray;
   intin[4..5] = bezarray;
   intin[6] = x_offset;
   intin[7] = y_offset;

   contrl[0] = 243;
   contrl[1] = 0;
   contrl[3] = 8;
   contrl[5] = 1;
   contrl[6] = handle;

   vdi ();

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

Address Element Contents
contrl contrl[0] 243 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 8 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+10 contrl[5] 1 # Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] ch
intin+2 intin[1] maxpts
intin+4 intin[2..3] xyarray
intin+8 intin[4..5] bezarray
intin+12 intin[6] x_offset
intin+14 intin[7] y_offset
intout intout[0] Return value

7.10.19 v_killoutline

Name: »Kill FSM outline« - Release memory for outline generation
Opcode: 242
Syntax: void v_killoutline ( int16_t handle, fsm_component_t *component );
Description: The call v_killoutline releases the memory allocated for the creation of font outlines. The following apply:
Parameter Meaning
   
handle Workstation identifier
component Address of an outline generated with v_getoutline


Note: The function should always be called as soon as an outline is no longer needed. Otherwise there is a risk of running out of memory.
Return value: The function does not return a result.
Availability: In FSMGDOS; no longer needed from SpeedoGDOS 4.00 on, so is not documented further.
Group: Control functions
See also: GDOS   SpeedoGDOS   v_getoutline

7.10.20 v_loadcache

Name: »Load outline cache« - Load vector font cache.
Opcode: 250
Syntax: int16_t v_loadcache ( int16_t handle, int8_t *filename, int16_t mode );
Description: The call v_loadcache fills the vector character cache with the contents of a previously saved file. The following apply:
Parameter Meaning
   
handle Workstation identifier
filename Name of the file
mode Fill mode:
0 = Append file to current cache
1 = Flush current cache, and load file completely into the cache
Return value: The function returns the value -1 in case of error, else the value 0.
Availability: FSMGDOS, as of SpeedoGDOS 4.00.
Group: Control functions
See also: Binding   v_flushcache   v_savecache   vqt_cachesize

7.10.21 Bindings for v_loadcache

C: int16_t v_loadcache ( int16_t handle, int8_t *filename, int16_t mode );
Binding:
int16_t v_loadcache ( int16_t handle, int8_t *filename,
                      int16_t mode )
{
   intin[0] = mode;
   intin[1..n] = filename;

   contrl[0] = 250;
   contrl[1] = 0;
   contrl[3] = 1+n;
   contrl[6] = handle;

   vdi ();

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

Address Element Contents
contrl contrl[0] 250 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1+n # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+12 contrl[6] handle
intin intin[0] mode
intin+2 intin[1..n] filename
intout intout[0] Return value

7.10.22 v_open_bm

Name: »Open bitmap« - Open an off-screen bitmap (modernized version)
Opcode: 100 (Sub-Opcode 3)
Syntax: int16_t v_open_bm ( int16_t base_handle, GCBITMAP *bitmap, int16_t color_flags, int16_t unit_flags, int16_t pixel_width, int16_t pixel_height );
Description: The call v_open_bm serves for the creation of off-screen bitmaps. One can either specify the size of a bitmap that it should allocate, or pass a bitmap to it. The bitmap is managed in the same format as that of the screen, which makes fast copying between the two possible.

v_open_bm is the modern variant of v_opnbm and works with the same bitmap and pixel format description as vr_transfer_bits. The following apply:
Parameter Meaning
   
base_handle graf_handle
bitmap Pointer to GCBITMAP, or 0.
If GCBITMAP is 0, then the GCBITMAP of the handle base_handle will be used. Entries in the bitmap are evaluated as follows:
Entry Function
addr Address of the bitmap, or 0 (VDI reserves the memory and later enters the address here)
width Width of a line in bytes, if addr is valid
bits Bit-depth, corresponds to px_format
px_format Pixel format, or 0 (pixel format will be taken on by base_handle) if all following coordinates are set to 0 and the VDI reserves the memory; if addr is 0, the dimensions will be taken from base_handle
xmin Minimum discrete X-coordinate of the bitmap (0 as a rule)
ymin Minimum discrete Y-coordinate of the bitmap (0 as a rule)
xmax Maximum discrete X-coordinate of the bitmap + 1 (the width as a rule)
ymax Maximum discrete Y-coordinate of the bitmap + 1 (the height as a rule)
ctab Is ignored
itab Is ignored
reserved0 Must be 0!
reserved1 Must be 0!
color_flags Treatment of the colour tables:
If the lowest bit of color_flags is set then the bitmap uses the same colour table as base_handle. If the bit is cleared, the bitmap will have its own colour table and own inverse colour table created for it (which should make the handling of screen caches or background buffers appreciably easier for some programs); colour changes on the screen will then not alter entries in the bitmap. Of color_flags only the lowest bit is used at present; all other bits have to be 0. Note: If the bitmap and screen use the same colour table, the colours may be altered only via the handle of the screen (i.e. base_handle), as otherwise the colours will not be entered in the hardware (CLUT).
unit_flags Measurement unit of the pixel size
pixel_width Pixel width, or 0
pixel_height Pixel height, or 0


Additionally, the pixel size is passed in pixel_width and pixel_height, so that the fonts may be scaled correctly. If one of these two entries is 0, the task will be taken on by base_handle. The size specifications will be interpreted dependent on unit_flags:

-1: Specification in dpi
 0: Specification in microns (1/1000 mm)
 1: Specification in 1/10 microns (1/10000 mm)
 2: Specification in 1/100 microns (1/100000 mm)
 3: Specification in 1/1000 microns (1/1000000 mm)

As ctab is ignored, a system colour table corresponding to the colour depth will be created for the bitmap in CSPACE_RGB (RGB) colour space. The variable is present for possible later extensions in this area, which therefore has to be set to 0 at present.
Return value: If the function is successful, a non-zero handle will be returned. If the VDI has reserved memory for the bitmap and only an empty (or only partially filled) GCBITMAP structure has been passed in the call, the structure is initialized completely after the call. Programs may not alter either the colour table nor the inverse colour table of the structure with a direct access. All changes must be made with the colour functions under the returned handle.
Availability: As of EdDI Version 1.20.
Group: Control functions
See also: Binding   NVDI   Off-screen bitmaps   v_clsbm

7.10.23 Bindings for v_open_bm

C: int16_t v_open_bm ( int16_t base_handle, GCBITMAP *bitmap, int16_t color_flags, int16_t unit_flags, int16_t pixel_width, int16_t pixel_height );
Binding:
int16_t v_open_bm ( int16_t base_handle, GCBITMAP *bitmap,
                    int16_t color_flags, int16_t unit_flags,
                    int16_t pixel_width, int16_t pixel_height )
{
   intin[0] = color_flags;
   intin[1] = unit_flags;
   intin[2] = pixel_width;
   intin[3] = pixel_height;

   contrl[0] = 100;
   contrl[1] = 0;
   contrl[3] = 4;
   contrl[5] = 3;
   contrl[6] = base_handle;
   contrl[7..8] = bitmap;

   vdi ();

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

Address Element Contents
contrl contrl[0] 100 # 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] 1 # Entry in intout
contrl+10 contrl[5] 3 # Sub-opcode
contrl+12 contrl[6] base_handle
contrl+14 contrl[7..8] bitmap
intin intin[0] color_flags
intin+2 intin[1] unit_flags
intin+4 intin[2] pixel_width
intin+6 intin[3] pixel_height
intout intout[0] 1

7.10.24 v_opnbm

Name: »Open bitmap« - Open an off-screen bitmap.
Opcode: 100 (Sub-Opcode 1)
Syntax: void v_opnbm ( int16_t *work_in, MFDB *bitmap, int16_t *handle, int16_t *work_out );
Description: The call v_opnbm serves for the creation of off-screen bitmaps. One can either specify the size of a bitmap that it should allocate, or pass a bitmap to it. The bitmap is managed in the same format as that of the screen, which makes fast copying between the two possible.The following apply:
Parameter Meaning
   
handle graf_handle
work_in[0..10] See v_opnwk/v_opnvwk
work_in[11] Width -1 (e.g. 1279)
work_in[12] Height -1 (e.g. 959)
work_in[13] Width of a pixel in 1/1000 mm
work_in[14] Height of a pixel in 1/1000 mm
work_in[15..19] Reserved, should contain 0


If the EdDI cookie has version number 1.1 or newer, v_opnbm takes additional arguments in work_in[15..19] into account: An attempt is made then to open a bitmap in the format described by these parameters. If there is no driver for the specified format, then the bitmap cannot be created. The following apply:
work_in[15..16] Number of simultaneously displayable colours
work_in[17] Number of planes
work_in[18] Pixel format
work_in[19] Bit order


Pixel format and bit order are described in greater detail in vq_scrninfo. With the following parameters, for instance, one can create an off-screen bitmap with 256 colours and interleaved planes:
work_in[15..16] = 256;  /* 256 colours           */
work_in[17] = 8;        /* 8 Planes              */
work_in[18] = 0;        /* Interleaved planes    */
work_in[19] = 1;        /* Normal bit order      */


Attention: work_in[11] + 1 should be divisible by 16 without remainder. Otherwise the VDI driver will round up (work_in[11] + 1) to the next number which can be divided by 16 without remainder.

If pixel width and height are 0 the pixel size of the screen workstation is used.

Note: The use of off-screen bitmaps can be useful if one wants to avoid effects such as heavy flicker on the screen. In that case one builds up the parts of the graphic in the bitmap and transfers the bitmap with vrt_cpyfm or vro_cpyfm to the screen.
Return value: Information is passed to the outside via the work_out array or the Memory Form Definiton Block (MFDB):
Parameter Meaning
   
work_out[0..1] See v_opnwk/v_opnvwk
work_out[2] 0
work_out[3..38] See v_opnwk/v_opnvwk
work_out[39] 0 (no hardware CLUT)
work_out[39..56] See v_opnwk/v_opnvwk
bitmap Pointer to MFDB


If bitmap->fd_addr is zero, the VDI will allocate memory for the bitmap and will clear it (in contrast to v_opnvwk).

To open a bitmap in device-specific format, bitmap->fd_nplanes should be zero, or the number of planes of the screen (work_out[4] from vq_extnd). If bitmap->fd_nplanes is 1, a monochrome bitmap will be created.

The elements of the MFDB (fd_addr, fd_w, fd_h, fd_wdwidth, fd_stand, fd_nplanes) are set by the VDI before returning from v_opnbm. If there is not enough memory to create a bitmap the handle will be zero and the MFDB will not be changed.

If bitmap->fd_addr is not zero, it will be used as pointer to a bitmap. If the bitmap is in standard format, it will be transformed into device-specific format. If the number of planes of the bitmap is not supported by the VDI, a zero handle will be returned.
Availability: The function is available as of EdDI Version 1.00. From EdDI 1.1 onwards, v_opnbm can be called with additional parameters.
Group: Control functions
See also: Binding   NVDI   Off-screen bitmaps   v_clsbm

7.10.25 Bindings for v_opnbm

C: void v_opnbm ( int16_t *work_in, MFDB *bitmap, int16_t *handle, int16_t *work_out );
Binding:
void v_opnbm (int16_t *work_in, MFDB *bitmap, int16_t *handle,
              int16_t *work_out)
{
   intin[0..19] = work_in[0..19];

   contrl[0] = 100;
   contrl[1] = 0;
   contrl[3] = 20;
   contrl[5] = 1;
   contrl[6] = handle;
   contrl[7..8] = bitmap;

   vdi ();

   *handle = contrl[6];
   work_out[0..44]  = intout[0..44];
   work_out[45..56] = ptsout[0..11];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 100 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 6 # Entry in ptsout
contrl+6 contrl[3] 20 # Entry in intin
contrl+8 contrl[4] 45 # Entry in intout
contrl+10 contrl[5] 1 # Sub-opcode
contrl+12 contrl[6] handle
contrl+14 contrl[7..8] bitmap
intin intin[0..19] work_in[0..19]
intout intout[0..44] work_out[0..44]
ptsout ptsout[0..11] work_out[45..56]

7.10.26 v_opnprn

Name: »Open printer driver«
Opcode: 1
Syntax: int16_t v_opnprn( int16_t base_handle, PRN_SETTINGS *settings, int16_t *work_out );
Description: The call v_opnprn opens a printer driver. The following apply:
Parameter Meaning
   
base_handle graf_handle
settings Pointer to a structure of the type PRN_SETTINGS
work_out Pointer to an int16_t work_out[57]
Return value: VDI handle, or 0 (error)
Availability: The passing of PRN_SETTINGS is possible as of NVDI 4.1x (27.11.96). The binding appears for the first time in NVDI 5.00.
Group: Control functions
See also: Binding

7.10.27 Bindings for v_opnprn

C: int16_t v_opnprn( int16_t base_handle, PRN_SETTINGS *settings, int16_t *work_out );
Binding:
int16_t v_opnprn( int16_t base_handle, PRN_SETTINGS *settings,
                  int16_t *work_out )
{
  int16   work_in[16];
  int16   i;

  vdi_pb.intin = (int *) work_in;
  vdi_pb.intout = (int *) work_out;
  vdi_pb.ptsout = (int *) work_out + 45;

  work_in[0] = settings->driver_id;            /* Driver number             */
  for ( i = 1; i < 10; i++ )
    work_in[i] = 1;
  work_in[10] = 2;                             /* Use raster coordinates    */
  work_in[11] = (int16) settings->size_id;     /* Use page format from settings */
  *(int8 **) &work_in[12] = settings->device;  /* Use output channel from settings */
  *(PRN_SETTINGS **) &work_in[14] = settings;  /* Printer settings          */

  contrl[0] = 1;                               /* Function number           */
  contrl[1] = 0;
  contrl[3] = 16;                              /* Extended parameter number */
  contrl[6] = base_handle;

  vdi( &vdi_pb );                              /* Open driver               */

  vdi_pb.intin = (int *) intin;                /* Reset pointer             */
  vdi_pb.intout = (int *) intout;
  vdi_pb.ptsout = (int *) ptsout;

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

Address Element Contents
contrl contrl[0] 1 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 6 # Entry in ptsout
contrl+6 contrl[3] 16 # Entry in intin
contrl+8 contrl[4] 45 # Entry in intout
contrl+10 contrl[5] 1 # Sub-opcode
contrl+12 contrl[6] base_handle
intin intin[0..19] work_in[0..15]
intout intout[0..44] work_out[0..44]
ptsout ptsout[0..11] work_out[45..56]

7.10.28 v_opnvwk

Name: »Open virtual screen workstation« - Open a screen workstation.
Opcode: 100
Syntax: void v_opnvwk ( int16_t *work_in, int16_t *handle, int16_t *work_out );
Description: The call v_opnvwk opens a virtual VDI workstation on an already opened physical device. After the call the parameter handle receives the ID of the virtual device, or the value 0 in case of error. The following aply:
Parameter Meaning
   
work_in Pointer to an integer field with more exact specifications of the device driver to be loaded:
work_in[0] Number of the device driver as entered in the ASSIGN.SYS file; the following apply for the screen:
x = 2 + Getrez()  
work_in[1] Default line type
work_in[2] Defaut line colour index
work_in[3] Default marker type
work_in[4] Default marker colour index
work_in[5] Default font ID
work_in[6] Default text colour index
work_in[7] Default fill interior style
work_in[8] Default fill style index
work_in[9] Default fill colour inde
work_in[10] Coordinate type flag:
0 = NDC (Normalized Device Coordinates, only for external drivers with GDOS)
2 = RC (Raster Coordinates)
work_in[11] Page format:
0 = Use 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
work_in[12]  
+  
work_in[13] Pointer to a GEMDOS file name (C string) or 0L
work_in[14] Reserved, should be 0
work_in[15] Reserved, should be 0
work_out Pointer to an integer field containing more exact specifications of the loaded device driver:
work_out[0] Maximum addressable width (0 - Xmax)
work_out[1] Maximum addressable height (0 - Ymax)
work_out[2] Scalability flag:
0 = Device capable of producing a precisely scaled image (e.g. the screen, printer)
1 = Device not capable of producing a precisely scaled image (e.g. a film recorder)
work_out[3] Pixel width in microns
work_out[4] Pixel height in microns
work_out[5] Number of character heights (0: continous scaling)
work_out[6] Number of line types
work_out[7] Number of line widths (0: continous scaling)
work_out[8] Number of marker types
work_out[9] Number of marker heights (0: continous scaling)
work_out[10] Number of accessible fonts
work_out[11] Number of patterns
work_out[12] Number of hatch styles
work_out[13] Number of simultaneously depicted colours (e.g. 256 on an 8 bit screen)
work_out[14] Number of GDPs (General Drawing Primitives) supported
work_out[15] List of the GDPs available on the device; -1 indicates the end of the list
1 = v_bar
2 = v_arc
3 = v_pieslice
4 = v_circle
5 = v_ellipse
6 = v_ellarc
7 = v_ellpie
8 = v_rbox
9 = v_rfbox
10 = v_justified
:  
work_out[24]  
work_out[25] List of attributes associated with each GDP:
0 = Polyline
1 = Marker
2 = Text
3 = Fill area
4 = No attributes
:  
work_out[34]  
work_out[35] Colour capability flag
work_out[36] Text rotation capability flag
work_out[37] Fill area capability flag
work_out[38] CELLARRAY capability flag
work_out[39] Number of colour levels available, or:
0 = More than 32767
2 = Monochrome
work_out[40] Number of locator devices available for graphic cursor control:
0 = None
1 = Keyboard only
2 = Keyboard and mouse (or other device)
work_out[41] Number of valuator devices available for various inputs:
0 = None
1 = Keyboard only
2 = Another device
work_out[42] Number of choice devices available:
0 = None
1 = Function keys on keyboard
2 = Function keys + extra keypad
work_out[43] Number of string devices available for alphanumeric input:
0 = None
1 = Keyboard
work_out[44] Device type:
0 = Output only
1 = Input only
2 = Input and output
3 = Reserved
4 = Metafile output
work_out[45] Minimum character width (pixels)
work_out[46] Minimum character height (pixels)
work_out[47] Maximum character width (pixels)
work_out[48] Maximum character height (pixels)
work_out[49] Minimum representable line width (pixels)
work_out[50] 0
work_out[51] Maximum line width
work_out[52] 0
work_out[53] Minimum marker width
work_out[54] Minimum marker heigh
work_out[55] Maximum marker width
work_out[56] Maximum marker height


Note: Unfortunately the VDI has no mechanism to manage the input devices for multiple workstations. Therefore this has to be taken on by the application that has opened the physical workstation of the screen.

Important: The ID of the current physical screen workstation must be established from the AES with graf_handle.

Warning: In the TOS versions 1.00, 1.04, 1.06, 1.62 and 2.05 there is an error in the management of the virtual workstations. This can show itseslf in the multiple assignation of IDs, and hence the workstation attributes may be misplaced in some circumstances. This error appears if there are gaps in the internal workstation list of the screen driver. Remedy: Place the patch-program VDIFIX in the AUTO folder.
Return value: The function returns no direct result.
Availability: Supported by all drivers.
Group: Control functions
See also: Binding   v_opnwk   v_clsvwk   graf_handle

7.10.29 Bindings for v_opnvwk

C: void v_opnvwk ( int16_t *work_in, int16_t *handle, int16_t *work_out );
Binding:
void v_opnvwk (int16_t *work_in, int16_t *handle,
               int16_t *work_out)
{
   intin[0..10] = work_in[0..10]

   contrl[0] = 100;
   contrl[1] = 0;
   contrl[3] = 11;
   contrl[6] = *handle;

   vdi ();

   *handle = contrl[6];
   work_out[0..44]  = intout[0..44];
   work_out[45..56] = ptsout[0..11];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 100 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 6 # Entry in ptsout
contrl+6 contrl[3] 11 # Entry in intin
contrl+8 contrl[4] 45 # Entry in intout
contrl+12 contrl[6] handle
intin intin[0..10] work_in[0..10]
intout intout[0..44] work_out[0..44]
ptsout ptsout[0..11] work_out[45..56]

7.10.30 v_opnwk

Name: »Open workstation« - Initialize a device driver for a specified input/output device.
Opcode: 1
Syntax: void v_opnwk ( int16_t *work_in, int16_t *handle, int16_t *work_out );
Description: The call v_opnwk opens a physical workstation to load a device driver. However, for this to work, a GDOS (or its equivalent) must be present in memory and the device driver must be listed in the ASSIGN.SYS file. If all went well handle will contain a positive device ID, or 0 in case of error.
Parameter Meaning
   
work_in Pointer to an integer field with more exact specifications of the device driver to be loaded:
work_in[0] Number of the device driver as entered in the ASSIGN.SYS file; the following apply for the screen:
x = 2 + Getrez()  
work_in[1] Default line type
work_in[2] Defaut line colour index
work_in[3] Default marker type
work_in[4] Default marker colour index
work_in[5] Default font ID
work_in[6] Default text colour index
work_in[7] Default fill interior style
work_in[8] Default fill style index
work_in[9] Default fill colour inde
work_in[10] Coordinate type flag:
0 = NDC (Normalized Device Coordinates, only for external drivers with GDOS)
2 = RC (Raster Coordinates)
work_in[11] Page format:
0 = Use 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
work_in[12]  
+  
work_in[13] Pointer to a GEMDOS file name (C string) or 0L
work_in[14] Reserved, should be 0
work_in[15] Reserved, should be 0
work_out Pointer to an integer field containing more exact specifications of the loaded device driver:
work_out[0] Maximum addressable width (0 - Xmax)
work_out[1] Maximum addressable height (0 - Ymax)
work_out[2] Scalability flag:
0 = Device capable of producing a precisely scaled image (e.g. the screen, printer)
1 = Device not capable of producing a precisely scaled image (e.g. a film recorder)
work_out[3] Pixel width in microns
work_out[4] Pixel height in microns
work_out[5] Number of character heights (0: continous scaling)
work_out[6] Number of line types
work_out[7] Number of line widths (0: continous scaling)
work_out[8] Number of marker types
work_out[9] Number of marker heights (0: continous scaling)
work_out[10] Number of accessible fonts
work_out[11] Number of patterns
work_out[12] Number of hatch styles
work_out[13] Number of simultaneously depicted colours (e.g. 256 on an 8 bit screen)
work_out[14] Number of GDPs (General Drawing Primitives) supported
work_out[15] List of the GDPs available on the device; -1 indicates the end of the list
1 = v_bar
2 = v_arc
3 = v_pieslice
4 = v_circle
5 = v_ellipse
6 = v_ellarc
7 = v_ellpie
8 = v_rbox
9 = v_rfbox
10 = v_justified
:  
work_out[24]  
work_out[25] List of attributes associated with each GDP:
0 = Polyline
1 = Marker
2 = Text
3 = Fill area
4 = No attributes
:  
work_out[34]  
work_out[35] Colour capability flag
work_out[36] Text rotation capability flag
work_out[37] Fill area capability flag
work_out[38] CELLARRAY capability flag
work_out[39] Number of colour levels available, or:
0 = More than 32767
2 = Monochrome
work_out[40] Number of locator devices available for graphic cursor control:
0 = None
1 = Keyboard only
2 = Keyboard and mouse (or other device)
work_out[41] Number of valuator devices available for various inputs:
0 = None
1 = Keyboard only
2 = Another device
work_out[42] Number of choice devices available:
0 = None
1 = Function keys on keyboard
2 = Function keys + extra keypad
work_out[43] Number of string devices available for alphanumeric input:
0 = None
1 = Keyboard
work_out[44] Device type:
-1 = Device can output in landscape format (as of PC-GEM/3)
0 = Output only
1 = Input only
2 = Input and output
3 = Reserved
4 = Metafile output
work_out[45] Minimum character width (pixels)
work_out[46] Minimum character height (pixels)
work_out[47] Maximum character width (pixels)
work_out[48] Maximum character height (pixels)
work_out[49] Minimum representable line width (pixels)
work_out[50] 0
work_out[51] Maximum line width
work_out[52] 0
work_out[53] Minimum marker width
work_out[54] Minimum marker heigh
work_out[55] Maximum marker width
work_out[56] Maximum marker height


Notes: The components work_in[11] to work_in[15] are only useful under NVDI and allow setting the page format for printers and bit-image drivers, as well as the output channel. For a metafile driver the setting of the page format will not take effect; only the filename will be adopted here. To check whether the page or paper format was set successfully one should fall back on the function vq_extnd.

The values returned in the elements work_out[0,1] show the actual printable area; the non-printable areas can be obtained with vq_extnd.

The allocation of the work_in and work_out arrays given here is no longer fully compatible to PC-GEM, as from GEM/3 onwards a number of considerable changes or extensions were made that were either not adopted on the Atari or were made in a different manner.

Physical workstations should be opened only when they are needed, and closed immediately afterwards; so, for instance, a word processor should not open the printer driver when the application launches and close it when it ends, as otherwise the user will not be able to change printers with a printer setup CPX.

Warning: With printer drivers, and specially with the Atari SLM laser page-printers, some special features have to be heeded.
Return value: The function returns no direct result.
Availability: Available only with some forms of GDOS.
Group: Control functions
See also: Binding   GDOS   v_clswk   v_opnvwk

7.10.31 Bindings for v_opnwk

C: void v_opnwk ( int16_t *work_in, int16_t *handle, int16_t *work_out );
Binding:
void v_opnwk (int16_t *work_in, int16_t *handle,
              int16_t *work_out)
{
   intin[0..15] = work_in[0..15];

   contrl[0] = 1;
   contrl[1] = 0;
   contrl[3] = 16;
   contrl[6] = 0;

   vdi ();

   *handle = contrl[6];
   work_out[0..44]  = intout[0..44];
   work_out[45..56] = ptsout[0..11];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 1 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 6 # Entry in ptsout
contrl+6 contrl[3] 16 # Entry in intin
contrl+8 contrl[4] 45 # Entry in intout
contrl+12 contrl[6] handle
intin intin[0..15] work_in[0..15]
intout intout[0..44] work_out[0..44]
ptsout ptsout[0..11] work_out[45..56]


Note: The specified binding is valid for use under NVDI. With printer drivers some special features have to be taken into account: First of all, with matrix printers the maximum resolution can be specified, as follows:
ptsin[0] = Maximum resolution in X-direction
ptsin[1] = Maximum resolution in Y-direction
contrl[1] = 1


In addition, the address of the internal buffer for the Atari SLM laser page-printers can be obtained:
contrl[0] = High word, and
contrl[1] = Low word of the buffer address
See also: v_opnwk   GDOS   GDOS drivers

7.10.32 Changes in PC-GEM

From PC-GEM/3 onwards the work_in field of v_opnwk was extended, so that one could still undertake some driver settings at runtime. The following information however is not compatible to Atari GEM or to NVDI. The following apply:

Element Meaning
   
work_in[11] In the lower value byte the output is specified more exactly. Output is to:
0 = File
1 = Serial port
2 = Parallel port
3 = Device-specific (direct)
255 = Default port

In the higher value byte the page size is specified:
0 = Letter size ( 8.50 * 11.00 inch)
5 = Half size ( 8.50 * 5.50 inch)
10 = B5 size (18.20 * 25.00 cm)
20 = Letter size ( 8.50 * 11.00 inch)
30 = A4 size (21.00 * 29.70 cm)
40 = Legal size ( 8.50 * 14.00 inch)
50 = Double size (11.00 * 17.00 inch)
55 = Broadsheet (14.00 * 11.00 inch)
255 = Benutzerspezifiziert (work_in[101,102])
work_in[12] Output port or filename
...  
...  
work_in[100]  
work_in[101] Page width in 1/100 inch
work_in[102] Page height in 1/100 inch
work_out[14] Has the value 11 if escapement text is available
work_out[24] Has the value 1 if escapement text is the only available text on the output device, or otherwise the value 10
work_out[44] A value of -1 means that the output device can output in landscape format without the application having to rotate the graphic itself. The OUTPUT program of PC-GEM however takes on the rotation itself, as this option was not yet available in older GEM versions.

Note: If work_in[11] has the value 1 or 2, then work_in[12] must be set to the port number (LPT1 = 0, LPT2 = 1, COM1 = 0, etc.). On the other hand if work_in[11] has the value 0, then the name of the file which is to be written must be contained in work_in[12] onwards; this will be written character by character (16-bit WORDS) and must be NULL-terminated.

See also: Control functions   v_opnwk

7.10.33 v_pat_rotate

Name: »Pattern rotation«
Opcode: 134
Syntax: void v_pat_rotate( int16_t handle, int16_t angle)
Description: The call v_pat_rotate specifies a pattern rotation angle. It is implemented only in printer drivers and is restricted to multiples of 90 degrees.
Parameter Meaning
   
handle Workstation identifier
angle Angle in tenths of a degree
Return value: The function does not return a result.
Availability: GEM/3 Release 3.1
Group: Control functions
See also: Binding

7.10.34 Bindings for v_pat_rotate

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

   contrl[0] = 134;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 134 # 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+12 contrl[6] handle
intin intin[0] angle

7.10.35 v_resize_bm

Name: »Resize bitmap« - Alter the size of an off-screen bitmap.
Opcode: 100 (Sub-Opcode 2)
Syntax: int16_t v_resize_bm( int16_t handle, int16_t width, int16_t height, int32_t byte_width, uint16_t *addr );
Description: With the function v_resize_bm the size of an off-screen bitmap may be changed. The function can also be passed its own block of memory, for which then the following points must be abided by:
  • The memory block must start on a 16-byte boundary.

  • At least 16 bytes that belong to the caller must be free before and after the memory block, as, depending on the output scope, some graphics functions read and possibly even write a few bytes before or after the bitmap (actually, the contents of these memory blocks is not altered; just some masked data will be written back unchanged).



If you do not take heed of this, you may be blessed with some nasty memory collisions! Hence we recommend leaving memory allocation to the NVDI!
Parameter Meaning
   
handle Handle from v_opnbm or v_open_bm.
width New width in pixels
height New height in pixels
byte_width Width of a line in bytes (only if addr is valid)
addr Pointer to own memory block, or 0L
Return value: If the function result is 0 then the new bitmap could not be built up. As the old bitmap has been released already in this case, one can attempt to create a smaller bitmap, or the bitmap must be closed with v_clsbm.
Availability: As of EdDI Version 1.20
Group: Control functions
See also: Binding   NVDI   Off-screen bitmaps

7.10.36 Bindings for v_resize_bm

C: int16_t v_resize_bm( int16_t handle, int16_t width, int16_t height, int32_t byte_width, uint16_t *addr );
Binding:
int16_t v_resize_bm( int16_t handle, int16_t width,
                     int16_t height, int32_t byte_width,
                     uint16_t *addr )
{
   intin[0] = width;
   intin[1] = height;
   intin[2..3] = byte_width;
   intin[4..5] = addr;

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

   vdi ();

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

Address Element Contents
contrl contrl[0] 100 # 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] 2 # Sub-opcode
contrl+12 contrl[6] handle
intin intin[0] width
intin+2 intin[1] height
intin+4 intin[2..3] byte_width
intin+8 intin[4..5] addr
intout intout[0] Return value

7.10.37 v_savecache

Name: »Save outline cache to disk« - Save the contents of the vector (outline) font cache.
Opcode: 249
Syntax: int16_t v_savecache ( int16_t handle, int8_t *filename );
Description: The call v_savecache saves the contents of the vector font cache to a file. The following apply:
Parameter Meaning
   
handle Workstation identifier
filename Name of the file


Note: The file will be stored in the current directory.
Return value: The function returns the value -1 in case of error, else the value 0.
Availability: FSMGDOS, from SpeedoGDOS 4.00 onwards.
Group: Control functions
See also: Binding   v_flushcache   v_loadcache   vqt_cachesize

7.10.38 Bindings for v_savecache

C: int16_t v_savecache ( int16_t handle, int8_t *filename );
Binding:
int16_t v_savecache ( int16_t handle, int8_t *filename )
{
   intin[0..n] = filename;      /* In 16-bit words */

   contrl[0] = 249;
   contrl[1] = 0;
   contrl[3] = n;
   contrl[6] = handle;

   vdi ();

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

Address Element Contents
contrl contrl[0] 249 # 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+12 contrl[6] handle
intin intin[0..n] filename
intout intout[0] Return value

7.10.39 v_set_app_buff

Name: »Reserve Bezier workspace« - Designate memory for generating Bezier splines.
Opcode: -1
Syntax: void v_set_app_buff ( int16_t handle, int16_t **address, int16_t nparagraphs );
Description: The call v_set_app_buff designates buffer memory for use by the Bezier spline generation routines. The following apply:
Parameter Meaning
   
handle Workstation identifier
address Address of the buffer
nparagraphs Buffer size in 16-byte blocks


Note: If Bezier functions are called then the spline data will be stored in this buffer. Before program termination one should use this function to set a NULL pointer as a buffer of size 0. The application is then responsible for deallocating the reserved memory.

If this function is not called by the application then GDOS will create its own buffer of around 8 kbyte.
Return value: The function does not return a result.
Availability: FONTGDOS, FSMGDOS, as of GEM/3 Release 3.1, from SpeedoGDOS 4.00 and from NVDI 2.10 on. The function surfaces in the (paper) documentation for NVDI 2.10, but no longer in all remaining descriptions.
Group: Control functions
See also: Binding   v_bez_on   v_bez_off   v_bez   v_bez_fill   v_bez_qual   GDOS   SpeedoGDOS

7.10.40 Bindings for v_set_app_buff

C: void v_set_app_buff ( int16_t handle, int16_t **address, int16_t nparagraphs );
Binding:
void v_set_app_buff ( int16_t handle, int16_t **address,
                      int16_t nparagraphs )
{
   intin[0..1] = address;
   intin[2] = nparagraphs;

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

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] -1 # 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] 6 # Sub-opcode
contrl+12 contrl[6] handle
intin intin[0..1] address
intin+4 intin[2] nparagraphs

7.10.41 v_updwk

Name: »Update workstation« - Execute buffered output commands.
Opcode: 4
Syntax: void v_updwk ( int16_t handle );
Description: The call v_updwk induces the output device with the ID handle to execute all buffered output commands.

Note: On the screen or with off-screen bitmaps this function is not required, as here all graphics commands are carried out immediately. With a printer no form-feed will be performed, while with a metafile only the opcode is written to the buffer.

Incidentally, before print output the function should be called once to initialize the printer. There are some special features that have to be heeded with printer drivers, and specially with the Atari SLM laser page-printers.
Return value: The function does not return a result.
Availability: Supported by all printer, metafile, plotter, and camera devices when using any form of GDOS.
Group: Control functions
See also: Binding   v_opnwk   v_output_window

7.10.42 Bindings for v_updwk

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

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 4 # 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+12 contrl[6] handle


Note: With printer drivers, one can output also a custom buffer instead of the current page. This is done as follows:
intin[0]  = High word, (!U)and(!u)
intin[1]  = Low word of the buffer address
contrl[0] = 4;
contrl[1] = 1; /* Do not clear buffer */
contrl[3] = 2;
contrl[6] = handle;
vdi ();


For laser printers of the Atari SLM series one can also obtain the status of the output device. The following apply:
intout[0] Meaning
   
0 No error
2 Printer not ready
3 Out of toner
5 Out of paper
See also: v_updwk   Control functions   GDOS   GDOS drivers

7.10.43 vs_clip

Name: »Set clipping rectangle«
Opcode: 129
Syntax: void vs_clip ( int16_t handle, int16_t clip_flag, int16_t *pxyarray );
Description: The call vs_clip limits all graphical output to a given region. The following apply:
Parameter Meaning
   
handle Workstation identifier
clip_flag
0 = Clipping off
1 = Clipping on
pxyarray[0] X-coordinate, and
pxyarray[1] Y-coordinate of a rectangle corner point
pxyarray[2] X-coordinate, and
pxyarray[3] Y-coordinate of the diagonally opposite corner point


Note: Do not switch off clipping, because a graphic object which is drawn outside of the visible screen area will overwrite memory or cause a bus error.

If the working area is to include the complete screen, it is advisable to set the screen dimensions for vs_clip obtained from v_opnvwk.
Return value: The function does not return a result.
Availability: Supported by all drivers.
Group: Control functions
See also: Binding   Clipping

7.10.44 Bindings for vs_clip

C: void vs_clip ( int16_t handle, int16_t clip_flag, int16_t *pxyarray );
Binding:
void vs_clip (int16_t handle, int16_t clip_flag,
              int16_t *pxyarray)
{
   intin[0] = clip_flag;
   ptsin[0..3] = pxyarray[0..3];

   contrl[0] = 129;
   contrl[1] = 2;
   contrl[3] = 1;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 129 # Function opcode
contrl+2 contrl[1] 2 # 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+12 contrl[6] handle
intin intin[0] clip_flag
ptsin ptsin[0..3] pxyarray[0..3]

7.10.45 vst_ex_load_fonts

Name: »Load fonts« - Extended version of additional font loading routine.
Opcode: 119
Syntax: int16_t vst_ex_load_fonts ( int16_t handle, int16_t select, int16_t font_max, int16_t font_free );
Description: The call vst_ex_load_fonts is an extension of the existing vst_load_fonts call, with two additional input arguments to provide control over font paging memory. The current defaults in units of paragraphs are:
                  font_max     font_free
For screens:     5120 (80K)         0
For printers:      32767       640 (10K)


The GDOS attempts to allocate font_max paragraphs or all of available menory (whichever is smaller) less font_free paragraphs, and use this amount for font paging.

Depending on your needs, you can use either version of this call. Note that both version use the same opcode.
Parameter Meaning
   
handle Workstation identifier
select Reserved, should be 0
font_max Maximum number of paragraphs to allocate
font_free Minimum number of paragraphs to leave free
Return value: The number of loaded fonts.
Availability: GEM/3 Release 3.1
Group: Control functions
See also: Binding   vst_unload_fonts   vst_font   vqt_name   ASSIGN.SYS file   GDOS

7.10.46 Bindings for vst_ex_load_fonts

C: int16_t vst_ex_load_fonts ( int16_t handle, int16_t select, int16_t font_max, int16_t font_free );
Binding:
int16_t vst_ex_load_fonts ( int16_t handle, int16_t select,
                            int16_t font_max, int16_t font_free )
{
   intin[0] = select;
   intin[1] = font_max;
   intin[2] = font_free;

   contrl[0] = 119;
   contrl[1] = 0;
   contrl[3] = 3;
   contrl[6] = handle;

   vdi ();

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

Address Element Contents
contrl contrl[0] 119 # 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+12 contrl[6] handle
intin intin[0] select
intin+2 intin[1] font_max
intin+4 intin[2] font_free
intout intout[0] Return value

7.10.47 vst_load_fonts

Name: »Load fonts«
Opcode: 119
Syntax: int16_t vst_load_fonts ( int16_t handle, int16_t select );
Description: The call vst_load_fonts loads further font information from disk into memory for the workstation with the ID handle; the fonts have to be listed in the ASSIGN.SYS file.
Parameter Meaning
   
handle Workstation identifier
select Reserved for future use = 0


Note: Before you call vst_load_fonts, call vq_gdos and make sure that the VDI can load additional fonts.
Return value: This will be the number of additional fonts loaded. If the function is called more than once before using vst_unload_fonts, the return will be 0.
Availability: Available with any form of GDOS.
Group: Control functions
See also: Binding   vst_unload_fonts   vst_font   vqt_name   ASSIGN.SYS file   GDOS

7.10.48 Bindings for vst_load_fonts

C: int16_t vst_load_fonts ( int16_t handle, int16_t select );
Binding:
int16_t vst_load_fonts (int16_t handle, int16_t select)
{
   intin[0] = select;

   contrl[0] = 119;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[6] = handle;

   vdi ();

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

Address Element Contents
contrl contrl[0] 119 # 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+12 contrl[6] handle
intin intin[0] select
intout intout[0] Return value

7.10.49 vst_unload_fonts

Name: »Unload fonts« - Remove loaded fonts.
Opcode: 120
Syntax: void vst_unload_fonts ( int16_t handle, int16_t select );
Description: The call vst_unload_fonts removes all fonts that were loaded previously by a vst_load_fonts call, and frees the associated memory. The following apply:
Parameter Meaning
   
handle Workstation identifier
select Reserved, should be 0


Note: System and vector fonts are not affected by this function.
Return value: The function does not return a result.
Availability: Available with any form of GDOS.
Group: Control functions
See also: Binding   GDOS   vst_load_fonts

7.10.50 Bindings for vst_unload_fonts

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

   contrl[0] = 120;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 120 # 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+12 contrl[6] handle
intin intin[0] select

HomeVDIColour table functionsRaster functions