home *** CD-ROM | disk | FTP | other *** search
- Distribution:
- ~~~~~~~~~~~~
-
- ./bin contains external executables which may be called by gnpltdrw.drv
- (one for a PM window output, another for X11 output);
-
- ./dll contains the required DLLs (EMX -Zcrtdll -Zmt);
-
- ./include ./lib and ./examples are useful for developers who want to
- build applications around this API;
-
- ./examples/gnuplot.inf contains a lot of developers and users info
-
- ./build is for people who want to rebuild this distribution;
-
- What it is:
- ~~~~~~~~~~
-
- This is an extraction of gnuplot's low-level drawing routines. Gnuplot
- allows drawing on an enormous number of output devices, from dumb terminals
- to VT100 graphic screens to PM windows to PostScript, GIF, PNG etc.
- All these devices are supported using basically the same calls.
-
- I made an API (in Gnuplot.h) so that one does not need to know anything about
- gnuplot's internals to use these drawing API. The API is documented in the
- file examples/Gnuplot.pm (it is a part of the Perl module Term::Gnuplot,
- which is build around this API). The C part of this module is contained in
- examples/Gnuplot.xs (which is not exactly C, but is close to C).
-
- Another example of how this API is used in real applications is
- examples/plot_gnuplot.c (which is a part of GP/PARI system).
-
- There are 4 ways to build an application using Gnuplot.h,
- e.g. examples/plot_gnuplot.c:
-
- a) Do not provide any -Ddefines. Then you need to link statically
- with a static library having the same .obj files as Gnupldrw.dll
- [not included in this distribution].
- (But you do not need to have "native" gnuplot headers around.)
-
- This is how the "gnuplot-enabled" compile of GP/PARI is done;
-
- b) Provide -DDYNAMIC_PLOTTING. In this case the application is
- "standalone"; it does not need to be linked with any external
- library. At runtime it needs to make the following call:
-
- v_set_term_ftable(ftable);
-
- after this the run-time connection with a drawing DLL is done,
- the application may start using the API calls. Here ftable is
- the function dispatch table of gnpltdrw.dll; one can obtain it
- by calling the function
-
- ftable = get_term_ftable()
-
- exported from this DLL. It is the application's responsibility
- to load the DLL and get the address of the function 'get_term_ftable',
- or to obtain ftable some other way.
-
- This is how the Math::Pari Perl module is implemented. Quite often this
- module is used so that PARI's graphing subsystem is not touched.
- It makes little sense to carry the overhead of the plotting
- subsystem all the time. So the plotting subsystem is made
- dynamically attachable from another Perl module, Term::Gnuplot.
-
- When plotting is needed, one can ask Term::Gnuplot, and it returns the
- 'ftable' address as a Perl integer. This integer is given to an
- a Math::Pari's function, which calls v_set_term_ftable(ftable).
- (Of course, in reality this interaction is hidden behind a
- convenience function.)
-
- c) With flags -DDYNAMIC_PLOTTING -DDYNAMIC_PLOTTING_STATIC_LINK. you can
- link your application with the supplied DLL (use the supplied import
- library). Since the link is established at compile time, your
- application will not run without gnpltdrw.dll around.
-
- This is the simplest possible way to use this distribution;
-
- d) With flags -DDYNAMIC_PLOTTING_RUNTIME_LINK=\"gnpltdrw\"
- -DDYNAMIC_PLOTTING you get a combination of the transparency of (c),
- and of the freedom of (b). You do not need to have the DLL around
- until you actually start the plotting. You do not need to perform
- any initialization call before the plotting may be performed; instead.
- the API calls you back when such an initialization is required.
- At this moment a function
-
- get_term_ftable_t *get_term_ftable_get()
-
- is called. This function should be supplied by your application,
- and must return the address of the function 'get_term_ftable'
- explained in (b). For an example of such a function (which would look
- for a DLL named as in the -Ddefine above, or from an environment
- variable GNUPLOT_DRAW_DLL) is in examples/plot_gnuplot.c.
-
- This is how my OS/2 distribution of GP/PARI is imlemented.
-
- Keep in mind that Gnuplot.h is a very dirty hack; it should not be included
- in more than one C file.
-
- Ilya Zakharevich ilya@math.ohio-state.edu
-