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
                            Workstation Specifics


Coordinate Systems

The VDI defaults to the usage of Raster Coordinates (RC) which places the
origin at the upper-left of the page or display. As an example, the
coordinate range for the 1040ST's monochrome graphics mode is shown here:

                     (0,0)





                                   (639,399)

RC coordinate ranges vary with the device. It is up to the application to
interpret and scale the size and position of its output appropriately.

With the addition of GDOS, the VDI gains the ability to utilize
Normalized Device Coordinates (NDC). When using NDC, GDOS translates and
scales all coordinates to the device as appropriate. All devices using NDC
will have their origin at the lower-left hand corner of the display or
page as follows:

                                 (32767,32767)





                     (0,0)

Using NDC provides an excellent manner of reducing the overhead of having
to internally scale every coordinate, however, applications which depend
on the proper aspect ratio for their output should consider managing
coordinates internally.

Rendering Graphics

Each VDI output function uses attributes set by other related VDI
functions to determine characteristics such as line width, text face, and
color. The following table lists VDI attribute calls and the functions
they affect.

To output a VDI object, set each attribute as desired and then make the
appropriate call. For example, to output a line of text in the System font
at 9 point colored red, make the following sequence of calls.

vst_font( handle, 1 );        /* Select the System Font */
vst_point( handle, 9 );
vst_color( handle, 2 );
v_ftext( handle, 10, 10, "The Atari Compendium" );

Generalized Device Primitives

GDP's (Generalized Device Primitives) are basic drawing components
available through the VDI. All current device drivers support all GDP's
though specialized drivers may not be able to. intout[14-24] may be used
to determine the presence of GDP's. Currently there are 10 supported GDP's
as follows:

                    #   GDP

                    1   Bar (Rectangle)

                    2   Arc

                    3   Pie Slice

                    4   Circle

                    5   Ellipse

                    6   Elliptical Arc

                    7   Elliptical Pie

                    8   Rounded Rectangle

                    9   Filled Rounded Rectangle

                   10   Justified Graphics Text

VDI Rectangles

Several VDI functions require that a rectangle in VDI format be passed to
them. VDI rectangles are different from AES rectangles in the manner in
which they are specified.

To correctly define a VDI rectangle you must specify two coordinate pairs
one representing the upper-left point of the rectangle and the other
specifying the lower-right as follows:

                    (x1,y1)





                                    (x2,y2)

The following two functions provide simple conversion between AES GRECTs
and VDI rectangles in an array.

        VOID
        Grect2xy( GRECT *g, short *pxy)
        {
                pxy[0] = g.g_x;
                pxy[1] = g.g_y;
                pxy[2] = g.g_x + g.g_w - 1;
                pxy[3] = g.g_y + g.g_h - 1;
        }

        VOID
        Xy2Grect( short *pxy, GRECT *g )
        {
                g.g_x = pxy[0];
                g.g_y = pxy[1];
                g.g_w = pxy[2] - pxy[0] + 1;
                g.g_h = pxy[3] - pxy[1] + 1;
        }

Device Types vs. Required Functions

Not all VDI functions are supported by all drivers. The presence of GDP
functions may be checked using the information returned in the intout
array after a v_opnwk() call. Other calls may be checked for by entering
a test call and comparing returned information with what would be
expected.

In addition, each type of driver has a certain number of required
functions which must be supported by the device. Each entry in the VDI
Function Reference specifies the support required for a function.

Write Modes

All VDI graphics primitives are subject to one of four writing modes set
by vswr_mode(), with the exception of vro_cpyfm() which is passed one of
sixteen writing modes.
The following logic tables illustrate the effects of each of the four
primary modes. Graphic examples can be found under the reference entry for
vswr_mode().

     Mode                 Logic

     Replace              Destination = Source

     Transparent          Destination = Source OR Destination

     XOR                  Destination = Source XOR Destination

     Reverse Transparent  Destination = (NOT Source) AND Destination