Programming with the VDI
Graphics is a major part of many modern programs, and as all Falcon users
will be aware, compatibility with the multitude of resolutions is a must
for the modern application. This compatibility is provided by the Virtual
Device Interface ( or VDI).
This documents some of the functions that the VDI offers, and enables the
programmer to use graphics without loosing compatibility. I am by no
means an expert at GEM/VDI programming, so don't take this document as
gospel - its only what I have been able to find out from various tutorials
etc. If something is wrong - email me.
I have used the syntax from C to give examples of code, but it is equally
applicable to any language that supports GEM...
Getting Started...
The first thing that you must do is register with both the AES and the
VDI, so that they can allocate you handles etc. To do this, use:
appl_init();
handle=graf_handle(&dummy,&dummy,&dummy,&dummy);
for (i = 0; i < 10; i++) work_in[i] = 1;
work_in[7] = 0;
work_in[10] = 2;
v_opnvwk(work_in, &handle, work_out);
This will initialise GEM, ready for use, and then get the VDI handle.
A virtual workstation is then opened, so that you can use VDI functions
on the screen. handle is the handle of your virtual workstation,
which will be needed in all other functions.
Graphics functions...
There are numerous functions which draw various graphical primatives. These
are :
v_pline(WORD handle, WORD count, WORD xyarray[]);
This function draws a series of collected lines. COUNT specifies the
number of lines which are to be drawn. XYARRAY[] is an array of 16-bit
integers which stores the co-ordinates. They are pairs of co-ordinates,
with the X co-ordinate stored first. The lines are drawn from the first
point to the next. From this point, a line is drawn to the next one, and
so on...
v_pmarker(WORD handle, WORD count, WORD xyarray[]);
This function allows you to plot COUNT markers at the points specified in
XYARRAY[]. The type of marker can be changed as detailed below, and may
be used to plot single pixels.
v_fillarea(WORD handle, WORD count, WORD xyarray[]);
v_fillarea can be used to fill parts of the screen. It uses a seed-fill
algorithm. The starting point of the fill is given in XYARRAY[]. COUNT
number of fills will be performed, starting from successive points as
defined in XYARRAY[]. NOTE: I'm a bit dubious about this one...
v_recfl(WORD handle, WORD xyarray[]);
This function draws a filled rectangle. XYARRAY[] is
a pointer to an array of 16-bit integers. These integers give the
co-ordinates of the top left, and the bottom right corners of the
area to be covered by the rectangle.
v_bar(WORD handle, WORD xyarray[]);
Again, this function draws a filled rectangle at the co-ordinates
stored in XYARRAY[]. I cannot see a difference between
this and the above function...
v_rbox(WORD handle, WORD xyarray[]);
This function draws a rounded rectangle. Again, XYARRAY[]
contains the co-ordinates of the top left, and the bottom right
corners of the rectangle.
v_rfbox(WORD handle, WORD xyarray[]);
v_rfbox draws a filled rounded rectangle. Again XYARRAY[]
contains the co-ordinates of the top-left/bottom-right corners of the
rectangle.
v_arc(WORD handle, WORD x, WORD y, WORD radius, WORD begang, WORD endang);
This function draws an (unfilled) arc, which is centred at the point X,Y
and has a radius of RADIUS pixels. BEGANG and ENDANG are the angles at
which the arc should begin and end. The angles are messured in tenths of
degrees, and 0 degrees is vertically upwards.
v_pieslice(WORD handle, WORD x, WORD y, WORD radius, WORD begang, WORD endang);
This function draws a filled arc, centered at X,Y with a radius of RADIUS.
Again, BEGANG and ENDANG give the beginning and ending angles, messured
in tenths of degrees.
v_circle(WORD handle, WORD x, WORD y, WORD radius);
v_circle draws a circle on the virtual workstation HANDLE, centred
at the point X,Y and has a radius of RADIUS.
v_ellarc(WORD handle, WORD x, WORD y, WORD xradius, WORD yradius, WORD begang, WORD endang);
v_ellpie(WORD handle, WORD x, WORD y, WORD xradius, WORD yradius, WORD begang, WORD endang);
v_ellipse(WORD handle, WORD x, WORD y, WORD xradius, WORD yradius);
Text functions...
As well as the graphical functions, there are also many text functions. These
include the ability to draw text, and allow the use of (Speedo) GDOS.
void v_gtext(WORD handle, WORD x, WORD y, unsigned const char * astring);
Attributes...
The effects of many of the functions detailed above can be changed. This is
done by changing various attributes, as detailed below:
WORD vswr_mode(WORD handle, WORD mode);
Finishing off...
Thats almost it... just before you exit the program, however, you must call:
v_clsvwk();
appl_exit();
Back to the programmers page
Back to the Atari Pages...
Anthony Jacques : jacquesa@zetnet.co.uk