plotutils-graph-patches-lloda/libplot/README

This directory holds the source files for a C/C++ 2-D vector graphics
library: GNU libplot/libplotter.  It is distributed under the GNU GPL
(see the file ../COPYING).

The library provides a uniform interface to numerous display devices and
output formats.  The interface presents each output device as a opaque
`Plotter' object: a virtual pen plotter.  Each of libplot's output drivers
is accessed at run time through an Plotter object of the appropriate type.
Many types of Plotter are supported: Metafile, Tektronix, ReGIS, HP-GL/2,
PCL 5, xfig, CGM (by default, WebCGM), idraw-editable Postscript, Adobe
Illustrator, SVG, GIF, PNM (i.e. PBM/PGM/PPM), PNG, X Drawable, and X.  All
but the final two write graphic output to an output stream.  The final two
draw graphics by calling X routines.  The X Drawable driver draws graphics
in one or two `drawables' (windows or pixmaps), which must be passed to it
via pointers, as Plotter parameters.  The X driver pops up a window
(actually, a Label widget) on an X display, and draws graphics in it.

The names of the source files include as prefix a letter indicating which
driver they include code for.  For example, the file h_openpl.c is part of
the HP-GL/2 driver, and contains low-level code which is called when the
API function pl_openpl_r() is invoked on an HP-GL/2 or PCL 5 Plotter.
Namely, it contains the _pl_h_begin_page() function.  As prefixes,
m=Metafile, t=Tektronix, r=ReGIS, h=HP-GL[/2] and PCL 5, f=Fig, c=CGM,
p=Postscript, a=Adobe Illustrator, s=SVG, i=GIF, n=PNM, z=PNG, x=XDrawable,
and y=X.  (Actually, XPlotters use mostly XDrawablePlotter methods.)  The
many files whose names begin with `g' (e.g., g_relative.c) contain generic
code, i.e. code used by the base Plotter class from which all other classes
are derived.  Similarly, `b' files contain code for a generic bitmap
Plotter class, from which the PNM and PNG Plotter classes are derived.

The library comes in two versions: libplot, which provides two C APIs (an
old non-thread-safe API, and a new thread-safe API), and libplotter, which
is a full-fledged C++ class library.  They are compiled in separate
directories (respectively, in this directory and in ../libplotter).
However, the same source files are used in both libraries.  That is a bit
remarkable.  It is arranged in the the two key header files
../include/plotter.h and ./extern.h.  If LIBPLOTTER is defined and a C++
compiler is used, a C++ class library results.  Otherwise, a conventional C
function library results.  There are a lot of conditionalizations in those
two header files.

In libplot, a Plotter is implemented as a C-style struct.  Each such struct
includes approximately 20 function pointers: one function pointer for each
of the low-level functions that define the semantics of the Plotter.  It is
by dereferencing these function pointers that polymorphism is implemented
in libplot.  The initialization of the `function pointer part' of each
Plotter is contained in the corresponding ?_defplot.c file.  At present,
the low-level functions include

   initialize
   terminate
   begin_page
   erase_page
   end_page
   push_state
   pop_state
   paint_path
   paint_paths
   path_is_flushable
   maybe_prepaint_segments
   paint_marker
   paint_point
   paint_text_string_with_escapes
   paint_text_string
   get_text_width
   retrieve_font
   flush_output
   warning
   error

For an explanation of the functionality of each of the above, see the
comments in ../include/plotter.h.

Here are some more details on how polymorphism is implemented.  In libplot,
each API function or internal Plotter method takes a pointer to a Plotter
struct as its first argument.  In the code, this pointer argument is always
written as `_plotter'.  It's the function pointers in `_plotter' that are
dereferenced, when performing any low-level operation.  For example, in the
libplot code you may see a function invocation like
`_plotter->begin_page(...)'.  This will (1) dereference the `_plotter'
pointer to get a Plotter, and (2) dereference the function pointer in the
Plotter to find the Plotter-specific implementation of the low-level
operation `begin_page()'.  This would be _pl_h_begin_page() if `_plotter'
points to an HP-GL/2 or PCL Plotter, for example.

The two special files apinewc.c and apioldc.c, which alone among the source
files are included in libplot but not libplotter, define the libplot API.
Each function in the new (thread-safe) API takes as first argument a
pointer to a Plotter struct to which the Plotter operations should be
applied.  It is this pointer which is passed down to the low-level code as
`_plotter'.  Each function in the old (non-thread-safe) API acts on a
Plotter which is globally selected by calling the function pl_selectpl().
Both old and new C APIs include functions like pl_newpl[_r]() and
pl_deletepl[_r](), which create and destroy Plotters.

The C++ binding, i.e. the libplotter C++ class library, is easier to
understand.  There is a generic Plotter class and derived classes that are
declared in ../include/plotter.h.  These classes include as public members
the API functions, such as openpl(), and low-level device-specific
functions, such as begin_page(), which are protected and virtual.  All this
is arranged by a *lot* of conditional #defines in ../include/extern.h.  For
example, if LIBPLOTTER is defined then the internal function _h_begin_page
is redefined to be HPGLPlotter::begin_page, which overrides the generic
begin_page method, which is a no-op.

Also, if LIBPLOTTER is defined then the Plotter methods don't all have a
special first argument called `_plotter'.  By the magic of the C/C++
preprocessor, the first argument disappears.  And in the code for each
method, `_plotter' is redefined to be `this', i.e. a pointer to the Plotter
whose operation is being invoked.  Believe it or not, it works: the same
source files can be used in the compilation of both libplot and libplotter.

A further implementation note: in libplot, any Plotter contains a `tag
field', identifying its type (X11, PS, PCL5, etc.).  This tag field is used
only in libplot, and only by a very few forwarding functions, so if
-DLIBPLOTTER is used, it's #ifdef'd out.  (See ../include/plotter.h.)
Other than that, the data members are essentially the same in the libplot
Plotter struct as they are in the libplotter Plotter class.

Actually, it's a bit more complicated.  In libplot, each Plotter struct, no
matter what its type, contains essentially the same data members.  But
there are a lot of data members, some of them which are relevant to all
Plotters (e.g., `line_type') and some of which are specific to individual
types of Plotter (e.g., `hpgl_line_type', which keeps track of an HP-GL
display device's internal state).  That means there's a lot of redundancy
(an XPlotter struct, for example, contains all the private data members
that an HPGLPlotter uses, but never uses them).  In libplotter, the design
is cleaner: each of the many data members which in libplot are contained in
every Plotter struct is moved to the appropriate derived class.  So
`hpgl_line_type' is a data member of the HPGLPlotter class, but not of the
base (generic) Plotter class, or any of its other subclasses.  That's
arranged by extensive #ifdef's in ../include/plotter.h.  It's a bit awkward
though: each data member needs to be declared twice in that file.

Adding support for a new type of display device or output file format,
given the object-oriented way that libplot/libplotter is structured, is
easy.  A new type of Plotter, derived from the base Plotter class, would be
declared in ../include/plotter.h.  If it needs any private data members,
which it probably will, they would be declared in two places in that file,
as just mentioned.  Also, conditional #defines for the methods used by the
new Plotter (to distinguish libplot from libplotter) would be added at the
end of ./extern.h.

A `defplot' file for the new Plotter type would need to be written too.
Besides low-level initialize() and terminate() routines for the new Plotter
type, it would include, for the benefit of libplot, an initialization
routine for the part of the Plotter struct that contains low-level
device-specific functions.  (See, for example, the initializing structure
_pl_h_default_plotter in the file h_defplot.c, as well as the routines
_pl_h_initialize and _pl_h_terminate.)  The new Plotter initialization
would need to be added to the _plotter_data[] table in apinewc.c, which is
specific to libplot.  No such initialization is required for libplotter,
since the C++ compiler itself initializes any instance of a derived Plotter
class.

To see how easy it is to add or remove support for a Plotter type, search
for the symbol X_DISPLAY_MISSING.  If this is defined, support for X
Drawable Plotters and X Plotters will be dropped at compile time.  The only
occurrences in the code of tests like `#ifdef X_DISPLAY_MISSING' are in the
header files ../include/plotter.h and ./extern.h, in apinewc.c, and in
g_defstate.c.  And the only reason for the appearance of X_DISPLAY_MISSING
in g_defstate.c is that the drawing state structure initialization located
in that file contains some X-specific fields, which need to be omitted if X
support is dropped.  That's because they rely on symbols defined in X11
header files.

Up to now we haven't mentioned drawing states, but every Plotter includes a
pointer to a stack of them.  Drawing states, which are structs in both
libplot and libplotter, contain numerous fields that are specific to
individual types of Plotter.  The reason device-specific information is
kept in the drawing state struct is that it's convenient.  For example,
when the user-frame line width is changed, the device-frame line width
changes too.  Rather than compute the device-frame line width each time a
graphical object is drawn, it's easier to store it in the drawing state.
There are many other such examples (see the declaration of the drawing
state structure as the `plDrawstate' typedef in ../include/plotter.h).