Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-File
                              VDI  Workstations


Every system call made to the VDI must include a workstation handle. This
handle is a unique integer which identifies the device and current
attribute array. Workstation handles are returned by the VDI calls
v_opnwk() or v_opnvwk().

Workstations provide a lookup array of attributes such as line width,
text color, clipping state, etc. that are unique to it.

Physical Workstations

Each device must be initialized by opening its physical workstation.
Opening a physical workstation causes all drawing and clipping attributes
to be reset and the current page (display) to be reset to the default
background color. Only one physical workstation may be opened to a single
device at any given time.
The screen device's physical workstation is automatically initialized by
the AES upon bootup. Its physical workstation handle may be obtained from
the AES call graf_handle().
Devices such as printers and plotters must have their physical
workstation opened by the application wishing to utilize them. When
opening a physical workstation the application must specify a device ID
which identifies the device to open. Device identification codes are
assigned as follows:

             VDI Device Identification Numbers

                    Screen      1-10

                    Plotters   11-20

                    Printers   21-30

                    Metafiles  31-40

                    Cameras    41-50

                    Tablets    51-60

                    Memory     61-70

                    Other      71-

The "MEMORY.SYS" driver should always be assigned to device #61.

These values correspond to the value listed in the leftmost column of the
user's 'ASSIGN.SYS' file. The following code segment demonstrates opening
a physical workstation to the printer device with ID #21. It is important
to note that the function assumes that the presence of GDOS has been
tested for and was verified.

work_in[0] is set to the desired device ID and work_in[1-9] are filled in
with common defaults for workstation attributes. work_in[10] is set to 2
to indicate raster coordinates as explained later in this chapter. The
function returns a non-zero value if an error occurred.

        WORD work_in[11],work_out[57];
        WORD handle;

        WORD
        printer_open( VOID )
        {
                WORD i;

                work_in[0] = 21;
                for(i = 1;i < 10; work_in[i++] = 1);
                work_in[10] = 2;

                v_opnwk(work_in,&handle,work_out);

                return (handle == 0);
        }

Virtual Workstations

Each physical workstation may have multiple virtual workstations opened
which allow individual applications to maintain separate workstation
attributes. In fact, a single application may open multiple virtual
workstations to the same device to manage workstation attributes more
efficiently. Opening a virtual workstation does not affect the current
contents of the display.

Most GEM applications will open a virtual workstation to the current
screen device upon initialization. The following code segment illustrates
opening a virtual workstation to the display device.

The device identification code for the display device must be specified
as Getrez() + 2 for all VDI features to work correctly. All other
parameters are passed the same as the example for opening a physical
workstation except that handle must contain the physical workstation
handle of the device for which you wish to obtain a virtual workstation
handle.

A more programmer-friendly method of opening workstations involves the
use of the VDI_Workstation structure which is discussed in the reference
entry for V_Opnvwk()

        WORD work_in[11],work_out[57];
        WORD handle;
        WORD wcell, hcell, wbox, hbox;

        WORD
        screen_open( VOID )
        {
                WORD i;

                handle = graf_handle( &wcell, &hcell, &wbox, &hbox);

                work_in[0] = Getrez() + 2;
                for(i = 1;i < 10;work_in[i++] = 1);
                work_in[10] = 2;

                v_opnvwk(work_in, &handle, work_out);

                return (handle == 0);
        }