Adding device drivers



next up previous
Next: Adding polygon types Up: A reference Guide Previous: The Unifpack libraries

Adding device drivers

The following section must be revised and completed, use it only as a guideline, but the best information in (as usual) on the code, in other words UTSL

Unifpack can generate drawings on several devices, current devices include SRGP , and Fig . When porting Unifpack to a new architecture it may be necessary to write a new device driver, we describe here tha main steps to do so.

A device driver is implemented as an structure call (yes, you guessed it) DeviceDriver, most of the fields in this structure are pointer to functions, you must provide this functions since they do the real work such as drawing lines or arcs. Since Unifpack uses always the same coordinates ( in both axes) you must scale and translate as needed for your device, also remember to keep the coordinate growing upwards.

Usually one uses the script pltempla found on ./Unifpack/utils to create two files, this files are templates where you add the real driver code, the script takes two parameters, the device name and the file names (or part of the file names); for instance the command

    drtempla Stub stub

would create the files drstub.h and drstub.c, this files would contain all the code of the driver Stub; below we use this name (Stub) to fix ideas.

First of all edit your configuration file (the file that sets the parameters for your architecture) and add drstub.c to the DRIVERS variable.

Usually there is no need to edit the file drstub.h, it just contains the driver declaration and some macro definitions, the file you must edit is drstub.c, the file itself contains some directions on what to write on it, but we describe here the main guidelines.

You must decide wether your driver will need to keep some private data, if it is so then you must add the necessary fields into the _AuxDriverData structure, next you must some data into the _DeviceDriver structure (such as the number of line and fill styles supported). You must now write the real code, writing or completing the following methods

Create
Should initialize and open the device, if any parameters are needed they must be read from the va_list.
Destroy
Closes the device, if any memory is allocated in the data field you must free it here.
Clear
Deletes any drawing on the device.
Refresh
Redraws and/or flushes the device.
Line
Draws a line, using the current line style.
Arc
Draws an arc, the center, radius, initial and final angle (in radians) are the parameters.
FillPoly
Fill a polygon using current fill style, not used really can be noop.
WriteText
Writes a string at the prescribed coordinates.
SetLineStyle
Changes the line style, no standard names or definitions are yet provided for the line styles, this should be corrected on future versions.
SetFillStyle
As above but for the fill style.

To gain access to your driver in uniflang and uni2dev you must change some code, the file defines a preprocessor variable called UP_USE_Stub, you can use this variable to detect whether your driver is installed or not, there is no need to #include the file drstub.h, the drivers makefile creates driver.h pasting all the dr*.h drivers that are needed.

I think that uni2dev code is self explanatory, just follow the directions contained therein.

To use Stub in uniflang you have to add a builtin function into the calculator, edit files symbol.h, builtin.h and builtin.c on directory ./Unifpack/src/lang, to add a builtin function Stub you must declare and define a function called UlStub on builtin.h and builtin.c, of course you can use another name, we will use this name to fix ideas. Since uniflang is implemented as a stack machine you must pop the parameters (if any) from the stack, see the other builtin functions as examples, notice that parameters are popped from last to first, and the stack contains just UlValue's this is a tagged union containning the data, some macros are provided to get the right parameter; your function should Destroy the current driver (if it is different from DeviceInvalid) and store the new driver in the global variable ulDevice.

The file symbol.c contains the ``prototype'' for your new builtin functions you have to add an entry to the static array called proto, this entry contains the name of the function, the number of parameters it take, the type of the return value (UL_VAL_NONE for device creation functions, a pointer to NULL and a pointer to the function we added in the last paragraph, the pointer to NULL is used as a place holder, the initialization procedure puts a pointer to an array that defines the parameters types, this array is obtained from the static array types; so you have to add the types of your parameters in this array (if any).



next up previous
Next: Adding polygon types Up: A reference Guide Previous: The Unifpack libraries



coryan@mat.puc.cl