Extending GeXX

The major new feature added in VTeX 6.3 is GeXX. The second "X" stands for eXtensible. With GeXX you can supplement the existing set of the PostScript operators with new constructs, implemented in C or C++.

This feature is applicable to both VTeX/Windows and VTeX/Linux implementations. The terminology in this document is tailored to Windows users; Linux users should have no problem with it as long as they translate a few platform-dependant terms; for example, Dynamic Libraries (DLL)'s under Linux are just Shared Objects (.SO's).}

To enrich VTeX with new GeX operators, you should

Implement them within a C-language DLL, see Writing an implementation DLL.
Call the .extend operator to load the new language extensions, see Loading an extension DLL
Provide additional \TeX\ and/or PostScript code for easy access to the new operators.

VTeX 6.3+ distributions includes an example of such an extension for drawing the PieCharts.

Note: To be visible to the VTeX compiler, the extension DLL's should be placed into the VTEX\BIN\GEX subdirectory.

Writing an implementation DLL

An extention DLL must export the following three functions:

int Version()
This function must return the version of the interface as defined in \verb+gexi.h+. If the version returned by the extention DLL does not match the version needed for the V\TeX\ compiler, the DLL is not loaded.
int Count()
which returns the number of extensions implemented ($\geq1$).
int Names(int i, char **s, void **p)
which returns the PostScript names and memory addresses of the new extensions. This function will be called with the index argument i and should fill up the parameter s with the name of the i's operator implemented and the parameter p with the address of the operator implementation. Notice that i is counted from 0 through Count-1.

Here is a sample implementation of these functions:

The code above adds new PostScript operator piechart. Notice that .extend will define it in the current top PostScript dictionary.

Writing an extention operator

An extension operator should be declared as an int function; its solo argument is the GeX interface structure, gexi. The function should return 0 in case of success, and a non-zero value otherwise (triggering a PostScript internal error).

The gexi structure provides the plugin author with full access to the GeX imaging machinery, and, via the .tkread/.tkwrite extentions, to the TeX tokens.

The detailed description of the interface is provided in the Pdf version of the documentation; here we only show the flavor of the code one can write. Here is (a very crude) example of sine curve drawing plugin.

int SineCurve(GEXI g) { double x1,x2; g->getOstackNumeric(&x1); // get low bound g->getOstackNumeric(&x2); // get upper bound .............. g->moveto(x1,sin(x2)); for (int i=1; i<=100; i++) g->lineto(x1+(x2-x1)*i/100,sin(x1+(x2-x1)*i/100)) g->stroke(); .............. return 0; }

Even if writing GeX plugin's requires some programming work, it is much simpler than doing graphics programming in PSTricks, MetaPost, or GnuPlot.

Loading an extension DLL

To load an extension .DLL, execute the .extend operator:

string .extend ==> integer

where the string argument contains the name of the .DLL file with the language extentions, the returned integer is the number of extention operators loaded. Upon successful execution of .extend the newly defined operators become available in the current PostScript environment.

The .extend operator will fail with an error if

the specified DLL cannot be found
the specified DLL does not export all three required functions
the version returned by the DLL does not match the version of the VTeX compiler.

In all three cases, .extend will cause a PostScript fileerror.

PieChart

PieChart is a short but useful example of using GeXX.

PieChart implements MS Word-like PieChart in VTeX. The implementation consists of

PieChart.DLL, the extension library.
PieChart.Sty, a LaTeX 2E style for using PieChart.

Here is a sample code for using PieChart:

\usepackage{piechart} ....... %% Define some colors \definecolor{lightyell}{rgb}{1,1,0.75} \definecolor{peach}{cmyk}{0,0.50,0.70,0} \definecolor{orange}{cmyk}{0,0.61,0.87,0} \definecolor{navyblue}{cmyk}{0.94,0.54,0,0} \begin{center} Shares of \TeX\ dialects:\par \fbox{\begin{PieChart}[rt]{2in} \PieSlice{lightyell}{65}{\LaTeXe} \PieSlice{green}{20}{Plain \TeX} \PieSlice{navyblue}{10}{AmS\TeX} \PieSlice{yellow}{4}{\LaTeX\ 2.09} \PieSlice{orange}{1}{Other} \end{PieChart}} \end{center} %%

and a sample PieChart produced by this extension:

VTeX distribution contains the full source of this plugin.