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

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:

Here is a sample implementation of these functions: <font face="verdana,courier> extern "C" WINAPI int Names(int i, char **s, void **p) { if (i == 0) { *s = "piechart"; *p = (void*)piechart; } else { *s = NULL; *p = NULL; } return ((*s) != NULL); }; extern "C" WINAPI int Count() { return 1; } extern "C" WINAPI int Version() { return 630; }

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

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

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.