home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 22 gnu / 22-gnu.zip / gnuplapi.zip / gnuplot-api-os2 / README
Text File  |  2001-03-07  |  4KB  |  101 lines
  1. Distribution:
  2. ~~~~~~~~~~~~
  3.  
  4.  ./bin contains external executables which may be called by gnpltdrw.drv
  5.     (one for a PM window output, another for X11 output);
  6.  
  7.  ./dll contains the required DLLs (EMX -Zcrtdll -Zmt);
  8.  
  9.  ./include ./lib and ./examples are useful for developers who want to
  10.     build applications around this API;
  11.  
  12.  ./examples/gnuplot.inf contains a lot of developers and users info
  13.  
  14.  ./build is for people who want to rebuild this distribution;
  15.  
  16. What it is:
  17. ~~~~~~~~~~
  18.  
  19. This is an extraction of gnuplot's low-level drawing routines.  Gnuplot
  20. allows drawing on an enormous number of output devices, from dumb terminals
  21. to VT100 graphic screens to PM windows to PostScript, GIF, PNG etc.
  22. All these devices are supported using basically the same calls.
  23.  
  24. I made an API (in Gnuplot.h) so that one does not need to know anything about
  25. gnuplot's internals to use these drawing API.  The API is documented in the
  26. file examples/Gnuplot.pm (it is a part of the Perl module Term::Gnuplot,
  27. which is build around this API).  The C part of this module is contained in
  28. examples/Gnuplot.xs (which is not exactly C, but is close to C).
  29.  
  30. Another example of how this API is used in real applications is 
  31. examples/plot_gnuplot.c (which is a part of GP/PARI system).
  32.  
  33. There are 4 ways to build an application using Gnuplot.h,
  34. e.g. examples/plot_gnuplot.c:
  35.  
  36.   a) Do not provide any -Ddefines.  Then you need to link statically
  37.     with a static library having the same .obj files as Gnupldrw.dll
  38.     [not included in this distribution].
  39.     (But you do not need to have "native" gnuplot headers around.)
  40.  
  41.      This is how the "gnuplot-enabled" compile of GP/PARI is done;
  42.  
  43.   b) Provide -DDYNAMIC_PLOTTING.  In this case the application is
  44.     "standalone"; it does not need to be linked with any external
  45.     library.  At runtime it needs to make the following call:
  46.  
  47.       v_set_term_ftable(ftable);
  48.  
  49.     after this the run-time connection with a drawing DLL is done,
  50.     the application may start using the API calls.  Here ftable is
  51.     the function dispatch table of gnpltdrw.dll; one can obtain it
  52.     by calling the function
  53.  
  54.       ftable = get_term_ftable() 
  55.  
  56.     exported from this DLL.  It is the application's responsibility
  57.     to load the DLL and get the address of the function 'get_term_ftable',
  58.     or to obtain ftable some other way.
  59.  
  60.       This is how the Math::Pari Perl module is implemented.  Quite often this
  61.     module is used so that PARI's graphing subsystem is not touched.
  62.     It makes little sense to carry the overhead of the plotting
  63.     subsystem all the time.  So the plotting subsystem is made
  64.     dynamically attachable from another Perl module, Term::Gnuplot.
  65.  
  66.       When plotting is needed, one can ask Term::Gnuplot, and it returns the
  67.     'ftable' address as a Perl integer.  This integer is given to an
  68.     a Math::Pari's function, which calls v_set_term_ftable(ftable).
  69.     (Of course, in reality this interaction is hidden behind a
  70.     convenience function.)
  71.  
  72.    c) With flags -DDYNAMIC_PLOTTING -DDYNAMIC_PLOTTING_STATIC_LINK. you can
  73.     link your application with the supplied DLL (use the supplied import
  74.     library).  Since the link is established at compile time, your
  75.     application will not run without gnpltdrw.dll around.
  76.  
  77.       This is the simplest possible way to use this distribution;
  78.  
  79.    d) With flags -DDYNAMIC_PLOTTING_RUNTIME_LINK=\"gnpltdrw\"
  80.     -DDYNAMIC_PLOTTING you get a combination of the transparency of (c),
  81.     and of the freedom of (b).  You do not need to have the DLL around
  82.     until you actually start the plotting.  You do not need to perform
  83.     any initialization call before the plotting may be performed; instead.
  84.     the API calls you back when such an initialization is required.
  85.     At this moment a function
  86.  
  87.       get_term_ftable_t *get_term_ftable_get()
  88.  
  89.     is called.  This function should be supplied by your application,
  90.     and must return the address of the function 'get_term_ftable'
  91.     explained in (b).  For an example of such a function (which would look
  92.     for a DLL named as in the -Ddefine above, or from an environment
  93.     variable GNUPLOT_DRAW_DLL) is in examples/plot_gnuplot.c.
  94.  
  95.       This is how my OS/2 distribution of GP/PARI is imlemented.
  96.  
  97. Keep in mind that Gnuplot.h is a very dirty hack; it should not be included
  98. in more than one C file.
  99.  
  100. Ilya Zakharevich ilya@math.ohio-state.edu
  101.