view release on metacpan or  search on metacpan

gnuterm/term/README  view on Meta::CPAN

   support for the main program, thereby encouraging a library of
   contributed drivers
2) To make it easy for users to add contributed drivers, by adding
   a single #include line to term.h
3) To allow individual compilation on DOS, to save the overlay
   manager from having to load _all_ drivers together.

CORRECTION - scale() interface is no longer supported, since it
is incompatible with multiplot.

Whole of terminal driver should be contained in one <driver>.trm file,
with a fairly strict layout as detailed below - this allows the
gnuplot maintainers to change the way the terminal drivers are
compiled without having to change the drivers themselves.

term.h, and therefore each file.trm file, may be loaded more than once,
with different sections selected by macros.

Each driver provides all the functions it needs, and a table of
function pointers and other data to interface to gnuplot.
The table entry is currently defined as follows in plot.h:

struct TERMENTRY {

/* required entries */

    const char *name;
    const char *description;
    unsigned int xmax,ymax,v_char,h_char,v_tic,h_tic;

    void (*options) __PROTO((void));
    void (*init) __PROTO((void));
    void (*reset) __PROTO((void));
    void (*text) __PROTO((void));
    int (*scale) __PROTO((double, double));
    void (*graphics) __PROTO((void));
    void (*move) __PROTO((unsigned int, unsigned int));
    void (*vector) __PROTO((unsigned int, unsigned int));
    void (*linetype) __PROTO((int));
    void (*put_text) __PROTO((unsigned int, unsigned int, const char*));

/* optional entries */

    int (*text_angle) __PROTO((int));
    int (*justify_text) __PROTO((enum JUSTIFY));
    void (*point) __PROTO((unsigned int, unsigned int,int));
    void (*arrow) __PROTO((unsigned int, unsigned int, unsigned int,
                           unsigned int, TBOOLEAN));
   int (*set_font) __PROTO((const char *font));  /* "font,size" */
   void (*pointsize) __PROTO((double pointsize));
                              int flags; /* various flags */
   void (*suspend) __PROTO((void)); /* after one plot of multiplot */
   void (*resume) __PROTO((void));  /* before subsequent plot of multiplot */
   void (*fillbox) __PROTO((int style, unsigned int x1, unsigned int y1, unsigned int width, unsigned int height)); /* clear part of multiplot */
   void (*linewidth) __PROTO((double linewidth));
#ifdef USE_MOUSE
   int (*waitforinput) __PROTO((void));
   void (*put_tmptext) __PROTO((int i, const char str[]));
   void (*set_ruler) __PROTO((int x, int y));
   void (*set_cursor) __PROTO((int c, int x, int y));
   void (*set_clipboard) __PROTO((const char s[]));
#endif
#ifdef PM3D
   int (*make_palette)__PROTO((t_sm_palette *palette));
   void (*previous_palette) __PROTO(());
   void (*set_color) __PROTO((double gray));
   void (*filled_polygon) __PROTO((int points, gpiPoint *corners));
#endif
};

One consequence of (1) is that we would like drivers to be backwards
compatible - drivers in the correct form below should work in future
versions of gnuplot without change. C compilers guarantee to fill
unitialised members of a structure to zero, so gnuplot can detect old
drivers, in which fields have not been initalised, and can point
new interface entry pointers to dummy functions.

We can add fields to the terminal structure, but only at the end of the list.
If you design a terminal that cant work without a new interface being defined,
and consequent changes to the main gnuplot source, please contact
bug-gnuplot@dartmouth.edu simply to ensure that you have the most
up to date defn of the terminal structure. Also, please ensure that
the 'set term' command checks for 0 values in added fields when an
old driver is selected, and a pointer to a suitable 'cant do' function
is provided. It is therefore not required (and in fact not possible)
to add padding fields to the end of all drivers.

Similarly, if you add an optional field to an old driver, take care
to ensure that all intervening fields are padded with zeros.

Some of the above fields are required - this should not be a problem,
since they were all required in earlier releases of gnuplot.
The later fields are interfaces to capabilities that not all devices
can do, or for which the generic routines provided should be adequate.
There are several null ('cant do') functions provided by term.c which
a driver can reference in the table. Similarly, for bitmap devices, there
are generic routines for lines and text provided by bitmap.c



Here's a brief description of each variable:

The char *name is a pointer to a string containing the name
of the terminal.  This name is used by the 'set terminal' and 
'show terminal' commands.  
The name must be unique and must not be confused with an abbreviation 
of another name.  For example if the name "postscript" exists, it is not
possible to have another name "postscript2".
Keep the name under 15 characters.

The char *description is a pointer to a string containing a
description of the terminal, which is displayed in response
to the 'set terminal' command.  
Keep the description under 60 characters.

xmax is the maximum number of points in the x direction.  
The range of points used by gnuplot is 0 to xmax-1.

ymax is the maximum number of points in the y direction.  
The range of points used by gnuplot is 0 to ymax-1.

gnuterm/term/README  view on Meta::CPAN

pointsize() fn will be called.


_arrow(sx,sy,ex,ey,head)  Called to draw an arrrow from (sx,sy) to (ex,ey).
A head is drawn on the arrow if head = TRUE.
An _arrow() function called do_arrow() is provided in term.c which will
draw arrows using the _move() and _vector() functions.  
Drivers should use do_arrow unless it causes problems.

_set_font() is called to set the font of labels, etc [new 3.7 feature]
fonts are selected as strings "name,size"

_pointsize() is used to set the pointsize for subsequent points

_flags stores various flags describing driver capabilities. Currently
 three bits are allocated
  - TERM_CAN_MULTIPLOT - driver can do multiplot
  fully-interactively when output is not redirected. ie text and graphics
  go to different places, or driver can flip using suspend.
  - TERM_CANT_MULTIPLOT - driver cannot multiplot, even if output
  is redirected.
  - TERM_BINARY - output file must be opened in binary mode
  Another bit is earmarked for VMS_PASTHRU, but not yet implemented.

_suspend() - called before gnuplot issues a prompt in multiplot mode
   linux vga driver uses this entry point to flip from graphics to
   text mode. X11 driver will take this opportunity to paint the window
   on the display.

_resume() - called after suspend(), before subsequent plots of a multiplot.

_fillbox() - draws a filled axis-aligned rectangular box. The first
   argument controls the type of fill-in: either a solid color at some
   percentage of full intensity, or a hatch pattern.  Used by plot style
   "with filledboxes" and by the "clear" command (with background as
   fill colour) to do inset plots via multiplot.

_linewidth() - sets the linewidth

The next five functions are used for mouse support, and should be
conditioned on USE_MOUSE:

_waitforinput() - used for mouse input.  Return the next character
   that can be read from stdin.  In the mean time, process any mouse
   events.

_put_tmptext(int i, const char str[]) - Display temporary text, after
   erasing any temporary text displayed previously at this location.
   The int determines where: 0=statusline, 1,2: at corners of zoom
   box, with \r separating text above and below the point.

_set_ruler(int x, int y) - Draw a ruler (crosshairs) centered at the
   indicated screen coordinates.  If x<0, switch ruler off.

_set_cursor(int c, int x, int y) - Set cursor style and corner of
   rubber band rectangle.  c selects the action: -2=warp the cursor to
   the given point, -1=start zooming, 0=standard cross-hair cursor,
   1=cursor during rotation, 2=cursor during scaling, 3=cursor during
   zooming.

_set_clipboard(const char s[]) - Write a string to the clipboard.


The following four functions should be conditioned on PM3D.  See also:
pm3d/old-docs/README-pm3d.

_make_palette(t_sm_palette *palette) - If argument is NULL, return
   number of colors available.  If the number of colors is not limited
   (continuously shaded colors can be generated), return 0.
   Otherwise, allocate the palette.  (t_sm_palette is defined in
   src/color.h.)

_set_color(double value) - Set polygon fill color according to value,
   where 0 <= value <= 1.  If using a palette, first map value to an
   integer i in the interval [0...num_colors-1], then set to the ith
   color in the palette.

_filled_polygon(int points, gpiPoint *corners) - Draw a polygon with
   the fill color set by set_color, and no border.  (gpiPoint is
   defined in src/color.h.)

_previous_palette() - Release the palette that the above routine
   allocated and get back the palette that was active before.  Some
   terminals, like displays, may draw parts of the figure using their
   own palette. Terminals that use only one palette for the whole plot
   don't need this routine.


The following should illustrate the order in which calls to these
routines are made:

 _options()
  _init()
    _scale(xs,ys)
    _graphics()
      _linewidth(lw)
      _linetype(lt)
      _move(x,y)
      _vector(x,y)
      _pointsize(size)
      _point(x,y,point)
      _text_angle(angle)
      _justify(mode)
      _set_font(font)
      _put_text(x,y,text)
      _arrow(sx,sy,ex,ey)
    _text()
    _graphics()
      .
    _suspend()
    _set_pointsize()
    _resume()
      .
    _text()
  _reset()


------------------------------------

BITMAP DEVICES