1 DOCUMENTATION FOR GNUPLOT TERMINAL DRIVER WRITERS
4 Updated for new file layout by drd 4/95
6 Paragraphs about inclusion of TERM_HELP added by rcc 1/96
8 No change to the interface between gnuplot and the terminal drivers,
9 but we would like to make the terminal drivers standalone
11 1) in order move the support for the terminal drivers outside of the
12 support for the main program, thereby encouraging a library of
14 2) To make it easy for users to add contributed drivers, by adding
15 a single #include line to term.h
16 3) To allow individual compilation on DOS, to save the overlay
17 manager from having to load _all_ drivers together.
19 CORRECTION - scale() interface is no longer supported, since it
20 is incompatible with multiplot.
22 Whole of terminal driver should be contained in one <driver>.trm file,
23 with a fairly strict layout as detailed below - this allows the
24 gnuplot maintainers to change the way the terminal drivers are
25 compiled without having to change the drivers themselves.
27 term.h, and therefore each file.trm file, may be loaded more than once,
28 with different sections selected by macros.
30 Each driver provides all the functions it needs, and a table of
31 function pointers and other data to interface to gnuplot.
32 The table entry is currently defined as follows in term_api.h:
36 /* required entries */
39 const char *description;
40 unsigned int xmax,ymax,v_char,h_char,v_tic,h_tic;
42 void (*options) __PROTO((void));
43 void (*init) __PROTO((void));
44 void (*reset) __PROTO((void));
45 void (*text) __PROTO((void));
46 int (*scale) __PROTO((double, double));
47 void (*graphics) __PROTO((void));
48 void (*move) __PROTO((unsigned int, unsigned int));
49 void (*vector) __PROTO((unsigned int, unsigned int));
50 void (*linetype) __PROTO((int));
51 void (*put_text) __PROTO((unsigned int, unsigned int, const char*));
53 /* optional entries */
55 int (*text_angle) __PROTO((int));
56 int (*justify_text) __PROTO((enum JUSTIFY));
57 void (*point) __PROTO((unsigned int, unsigned int,int));
58 void (*arrow) __PROTO((unsigned int, unsigned int, unsigned int,
59 unsigned int, TBOOLEAN));
60 int (*set_font) __PROTO((const char *font)); /* "font,size" */
61 void (*pointsize) __PROTO((double pointsize));
62 int flags; /* various flags */
63 void (*suspend) __PROTO((void)); /* after one plot of multiplot */
64 void (*resume) __PROTO((void)); /* before subsequent plot of multiplot */
65 void (*fillbox) __PROTO((int style, unsigned int x1, unsigned int y1, unsigned int width, unsigned int height)); /* clear part of multiplot */
66 void (*linewidth) __PROTO((double linewidth));
68 int (*waitforinput) __PROTO((void));
69 void (*put_tmptext) __PROTO((int i, const char str[]));
70 void (*set_ruler) __PROTO((int x, int y));
71 void (*set_cursor) __PROTO((int c, int x, int y));
72 void (*set_clipboard) __PROTO((const char s[]));
74 int (*make_palette)__PROTO((t_sm_palette *palette));
75 void (*previous_palette) __PROTO(());
76 void (*set_color) __PROTO((t_colorspec *colorspec));
77 void (*filled_polygon) __PROTO((int points, gpiPoint *corners));
79 void (*image) __PROTO((unsigned, unsigned, coordval *, gpiPoint *, t_imagecolor));
81 /* Enhanced text mode driver call-backs */
82 void (*enhanced_open) __PROTO((char * fontname, double fontsize,
83 double base, TBOOLEAN widthflag, TBOOLEAN showflag,
85 void (*enhanced_flush) __PROTO((void));
86 void (*enhanced_writec) __PROTO((int c));
87 /* Driver-specific synchronization or other layering commands */
88 void (*layer) __PROTO((t_termlayer syncpoint));
89 /* Path control for end-joins of closed polygons on PostScript-like devices */
90 void (*path) __PROTO((int p));
93 One consequence of (1) is that we would like drivers to be backwards
94 compatible - drivers in the correct form below should work in future
95 versions of gnuplot without change. C compilers guarantee to fill
96 uninitialised members of a structure to zero, so gnuplot can detect old
97 drivers, in which fields have not been initialised, and can point
98 new interface entry pointers to dummy functions.
100 We can add fields to the terminal structure, but only at the end of the list.
101 If you design a terminal that can't work without a new interface being defined,
102 and consequent changes to the main gnuplot source, please contact
103 gnuplot-beta@lists.sourceforge.net simply to ensure that you have the most
104 up to date definition of the terminal structure. Also, please ensure that
105 the 'set term' command checks for 0 values in added fields when an
106 old driver is selected, and a pointer to a suitable 'can't do' function
107 is provided. It is therefore not required (and in fact not possible)
108 to add padding fields to the end of all drivers.
110 Similarly, if you add an optional field to an old driver, take care
111 to ensure that all intervening fields are padded with zeros.
113 Some of the above fields are required - this should not be a problem,
114 since they were all required in earlier releases of gnuplot.
115 The later fields are interfaces to capabilities that not all devices
116 can do, or for which the generic routines provided should be adequate.
117 There are several null ('can't do') functions provided by term.c which
118 a driver can reference in the table. Similarly, for bitmap devices, there
119 are generic routines for lines and text provided by bitmap.c
123 Here's a brief description of each variable:
125 The char *name is a pointer to a string containing the name
126 of the terminal. This name is used by the 'set terminal' and
127 'show terminal' commands.
128 The name must be unique and must not be confused with an abbreviation
129 of another name. For example if the name "postscript" exists, it is not
130 possible to have another name "postscript2".
131 Keep the name under 15 characters.
133 The char *description is a pointer to a string containing a
134 description of the terminal, which is displayed in response
135 to the 'set terminal' command.
136 Keep the description under 60 characters.
138 xmax is the maximum number of points in the x direction.
139 The range of points used by gnuplot is 0 to xmax-1.
141 ymax is the maximum number of points in the y direction.
142 The range of points used by gnuplot is 0 to ymax-1.
144 v_char is the height of characters, in the same units as xmax and ymax.
145 The border for labelling at the top and bottom of the plot is
146 calculated using v_char.
147 v_char is used as the vertical line spacing for characters.
149 h_char is the width of characters, in the same units as xmax and ymax.
150 The border for labelling at the left and right of the plot is
151 calculated using h_char, for example.
152 If the _justify_text function returns FALSE, h_char is used to justify
153 text right or centre. If characters are not fixed width, then the
154 _justify_text function must correctly justify the text.
156 v_tic is the vertical size of tics along the x axis,
157 in the same units as ymax.
159 h_tic is the horizontal size of tics along the y axis,
160 in the same units as xmax.
162 v_tic and h_tic should give tics of the same physical size on the
163 output. The ratio of these two quantities is used by gnuplot to set the
164 aspect ratio to 1 so that circles appear circular when 'set size square'
167 All the above values need not be static - values can be substituted
168 into the table during terminal initialisation, based on options for
173 Here's a brief description of what each term.c function does:
175 _options() Called when terminal type is selected. Also called by
176 'set termoption'. The two cases can be distinguished because on entry
177 the value of c_token is either 3 or 2, respectively.
178 This procedure should parse options on the command line. A list of the
179 currently selected options should be stored in term_options[] in a form
180 suitable for use with the set term command. term_options[] is used by
181 the save command. Use options_null() if no options are available.
183 _init() Called once, when the device is first selected. This procedure
184 should set up things that only need to be set once, like handshaking and
185 character sets etc...
186 There is a global variable 'pointsize' which you might want to use here.
187 If set pointsize is issued after init has been called, the pointsize()
190 _reset() Called when gnuplot is exited, the output device changed or
191 the terminal type changed. This procedure should reset the device,
192 possibly flushing a buffer somewhere or generating a form feed.
194 _scale(xs,ys) Called just before _graphics(). This takes the x and y
195 scaling factors as information. If the terminal would like to do its
196 own scaling, it returns TRUE. Otherwise, it can ignore the information
197 and return FALSE: do_plot will do the scaling for you. null_scale is
198 provided to do just this, so most drivers can ignore this function
199 entirely. The Latex driver is currently the only one providing its own
200 scaling. PLEASE DO NOT USE THIS INTERFACE - IT IS NOT COMPATIBLE WITH
203 _graphics() Called just before a plot is going to be displayed. This
204 procedure should set the device into graphics mode. Devices which can't
205 be used as terminals (like plotters) will probably be in graphics mode
206 always and therefore won't need this.
208 _text() Called immediately after a plot is displayed. This procedure
209 should set the device back into text mode if it is also a terminal, so
210 that commands can be seen as they're typed. Again, this will probably
211 do nothing if the device can't be used as a terminal. This call can
212 be used to trigger conversion and output for bitmap devices.
214 _move(x,y) Called at the start of a line. The cursor should move to the
215 (x,y) position without drawing.
217 _vector(x,y) Called when a line is to be drawn. This should display a line
218 from the last (x,y) position given by _move() or _vector() to this new (x,y)
221 _linetype(lt) Called to set the line type before text is displayed or
222 line(s) plotted. This procedure should select a pen color or line
223 style if the device has these capabilities.
224 lt is an integer from -3 to 0 or greater.
225 An lt of -3 is solid and drawn with xor (for temporary interactive annotations).
226 An lt of -2 is used for the border of the plot.
227 An lt of -1 is used for the X and Y axes.
228 lt 0 and upwards are used for plots 0 and upwards.
229 If _linetype() is called with lt greater than the available line types,
230 it should map it to one of the available line types.
231 Most drivers provide 9 different linetypes (lt is 0 to 8).
233 _put_text(x,y,str) Called to display text at the (x,y) position,
234 while in graphics mode. The text should be vertically (with respect
235 to the text) justified about (x,y). The text is rotated according
236 to _text_angle and then horizontally (with respect to the text)
237 justified according to _justify_text.
240 The following are optional
243 _text_angle(ang) Called to rotate the text angle when placing the y label.
244 Ang is the rotation angle in degrees. If ang = 0 then text is horizontal.
245 Returns TRUE if text can be rotated, FALSE otherwise.
246 [But you must return TRUE if called with ang=0]
248 _justify_text(mode) Called to justify text left, right or centre.
249 If mode = LEFT then text placed by _put_text is flushed left against (x,y).
250 If mode = CENTRE then centre of text is at (x,y).
251 If mode = RIGHT then text is placed flushed right against (x,y).
252 Returns TRUE if text can be justified
253 Returns FALSE otherwise and then _put_text assumes text is flushed left;
254 justification of text is then performed by calculating the text width
255 using strlen(text) * h_char.
257 _point(x,y,point) Called to place a point at position (x,y).
258 point is -1 or an integer from 0 upwards.
259 At least 6 point types (numbered 0 to 5) are normally provided.
260 Point type -1 is a dot. 'point' corresponds to (pointtype - 1),
261 e.g. 'plot x with points pointtype 2' will call _point(x, y, 1).
262 If possible, the driver should support the following 13 point types
272 6 7 circle (disk) filled
275 9 10 upside down triangle
276 10 11 upside down triangle filled
280 If point is more than the available point types then it should
281 be mapped back to one of the available points.
282 Two _point() functions called do_point() and line_and_point() are
283 provided in term.c and should be suitable for most drivers.
284 do_point() draws the points in the current line type.
285 If your driver uses dotted line types (generally because it is
286 monochrome), you should use line_and_point() which changes to
287 line type 0 before drawing the point. line type 0 should be solid.
289 There is a global variable 'pointsize' which is controlled by the
290 set pointsize command. If possible, use that. pointsize should be
291 examined at terminal init. If it is subsequently changed, the
292 pointsize() function will be called.
295 _arrow(sx,sy,ex,ey,head) Called to draw an arrow from (sx,sy) to (ex,ey).
296 A head is drawn on the arrow if head = TRUE.
297 An _arrow() function called do_arrow() is provided in term.c which will
298 draw arrows using the _move() and _vector() functions.
299 Drivers should use do_arrow unless it causes problems.
301 _set_font() is called to set the font of labels, etc. [new 3.7 feature]
302 - fonts are selected as strings "name,size".
303 - _set_font("") restores the terminal's default font.
305 _pointsize() is used to set the pointsize for subsequent points
307 _flags stores various flags describing driver capabilities.
308 - TERM_CAN_MULTIPLOT - driver can do multiplot in interactive mode,
309 - TERM_CANNOT_MULTIPLOT - driver cannot multiplot, even if output
310 is redirected. (not used by any current driver)
311 - TERM_BINARY - output file must be opened in binary mode
312 - TERM_ENHANCED_TEXT - terminal is currently in enhanced text mode
313 - TERM_NO_OUTPUTFILE - terminal does not use gpoutfile
315 _suspend() - Called before gnuplot issues a prompt in multiplot mode.
316 Called only in interactive mode, and only for drivers that have set the
317 flag TERM_CAN_MULTIPLOT. Some of these must flip between text/graphics
318 mode (e.g. linuxvga). X11 driver will take this opportunity to paint
319 the window on the display.
321 _resume() - called after suspend(), before subsequent plots of a multiplot.
322 Called only in interactive mode, and only for drivers that have set the
323 flag TERM_CAN_MULTIPLOT.
325 _fillbox() - draws a filled axis-aligned rectangular box. The first
326 argument controls the type of fill-in: either a solid color at some
327 percentage of full intensity, or a hatch pattern. Used by plot style
328 "with filledboxes" and by the "clear" command (with background as
329 fill colour) to do inset plots via multiplot.
331 _linewidth() - sets the linewidth
333 The next five functions are used for mouse support, and should be
334 conditioned on USE_MOUSE:
336 _waitforinput() - used for mouse input. Return the next character
337 that can be read from stdin. In the mean time, process any mouse
340 _put_tmptext(int i, const char str[]) - Display temporary text, after
341 erasing any temporary text displayed previously at this location.
342 The int determines where: 0=statusline, 1,2: at corners of zoom
343 box, with \r separating text above and below the point.
345 _set_ruler(int x, int y) - Draw a ruler (crosshairs) centered at the
346 indicated screen coordinates. If x<0, switch ruler off.
348 _set_cursor(int c, int x, int y) - Set cursor style and corner of
349 rubber band rectangle. c selects the action: -2=warp the cursor to
350 the given point, -1=start zooming, 0=standard cross-hair cursor,
351 1=cursor during rotation, 2=cursor during scaling, 3=cursor during
352 zooming, -3=draw line between ruler and current mouse position,
353 -4=don't draw (erase) line between ruler and current mouse position.
355 _set_clipboard(const char s[]) - Write a string to the clipboard.
358 The following four functions were conditioned on #ifdef PM3D; this necessity
359 was removed in August 2005. For further documentation about pm3d routines,
360 see also pm3d/old-docs/README-pm3d.
362 _make_palette(t_sm_palette *palette) - If argument is NULL, return
363 number of colors available. If the number of colors is not limited
364 (continuously shaded colors can be generated), return 0.
365 Otherwise, allocate the palette. (t_sm_palette is defined in
368 _set_color(t_colorspec *colorspec) - EAM November 2004 ***CHANGED***
369 This routine used to accept a single double value, which was
370 interpreted as a fractional index into the current color palette.
371 Changing the parameter to a colorspec allows terminals to support
372 other methods of specifying a color. If a given driver can not
373 support a particular color request mechanism, it ignores it.
374 If (colorspec->type == TC_FRAC) (this was the old behavior):
375 Set current color according to colorspec->value, where 0 <= value <= 1.
376 If using a palette, first map value to an integer i in the interval
377 [0...num_colors-1], then set to the ith color in the palette.
378 If (colorspec->type == TC_RGB):
379 Set current color to the rgb triple given in colorspec->lt.
381 _filled_polygon(int points, gpiPoint *corners) - Draw a polygon with
382 the fill color set by set_color, and no border. (gpiPoint is
383 defined in src/color.h.)
385 _previous_palette() - Release the palette that the above routine
386 allocated and get back the palette that was active before. Some
387 terminals, like displays, may draw parts of the figure using their
388 own palette. Terminals that use only one palette for the whole plot
389 don't need this routine.
391 The following 3 functions are required for drivers that support enhanced
392 text mode. They are called only by the term.c routine enhanced_recursion().
394 _enhanced_open() - initialize state variables to process an enhanced text
396 _enhanced_writec() - write (or buffer) a single character of the text fragment
398 _enhanced_flush() - finish processing of previous fragment and write it to
401 The following function should be conditioned on WITH_IMAGE. See also:
402 src/README for notes about image support.
404 _image(unsigned M, unsigned N, coordval *image, gpiPoint *corner, t_imagecolor color_mode)
405 This routine is to plot a pixel-based image on the display device.
406 'M' is the number of pixels along the y-dimension of the image and
407 'N' is the number of pixels along the x-dimension of the image. The
408 coordval pointer 'image' is the pixel values normalized to the range
409 [0:1]. These values should be scaled accordingly for the output
410 device. They 'image' data starts in the upper left corner and scans
411 along rows finishing in the lower right corner. If 'color_mode' is
412 IC_PALETTE, the terminal is to use palette lookup to generate color
413 information. In this scenario the size of 'image' is M*N. If
414 'color_mode' is IC_RGB, the terminal is to use RGB components. In
415 this scenario the size of 'image' is 3*M*N. The data appears in RGB
416 tripples, i.e., image[0] = R(1,1), image[1] = G(1,1), image[2] =
417 B(1,1), image[3] = R(1,2), image[4] = G(1,2), ..., image[3*M*N-1] =
418 B(M,N). The 'image' is actually an "input" image in the sense that
419 it must also be properly resampled for the output device. Many output
420 mediums, e.g., PostScript, do this work via various driver functions.
421 To determine the appropriate rescaling, the 'corner' information
422 should be used. There are four entries in the gpiPoint data array.
423 'corner[0]' is the upper left corner (in terms of plot location) of
424 the outer edge of the image. Similarly, 'corner[1]' is the lower
425 right corner of the outer edge of the image. (Outer edge means the
426 outer extent of the corner pixels, not the middle of the corner
427 pixels.) 'corner[2]' is the upper left corner of the visible part
428 of the image, and 'corner[3]' is the lower right corner of the visible
429 part of the image. The information is provided in this way because
430 often it is necessary to clip a portion of the outer pixels of the
434 _layer(t_termlayer syncpoint)
435 Driver-specific synchronization or other layering commands.
436 As of this point (July 2005) used only by pslatex.trm
439 PostScript-like devices make a distinction between the end of a
440 line segment that is internal to a polyline and one that has no
441 line-join to another segment. In order to treat the endpoints of
442 a closed polygon as "internal" line-joins, one must bracket the
443 polygon segments with "newpath ... closepath".
444 term->path(0) triggers a "newpath"
445 term->path(1) triggers a "closepath"
446 These calls are optional, and only required by a few drivers.
449 The following should illustrate the order in which calls to these
468 _enhanced_open(fontname,fontsize,base,width,show,overprint)
469 _enhanced_writec(char)
472 _image(M,N,image,corner,color_mode)
484 ------------------------------------
488 A file bitmap.c is provided, implementing a generic set of bitmap
489 routines. It provides all the routines required to generate a
490 bitmap in memory, drawing lines and writing text. A simple driver
491 need provide only a text() entry point, which converts and outputs
492 the stored bitmap in the format required by the device.
494 Internally, the bitmap is built of one or more planes of 1
495 bit per pixel. In fact, I think the library would be easier to
496 use if it offered one or more planes of pixels with 1,2,4 or 8
497 bits per pixel, since not all bitmap devices are based on planes,
498 and the planes have to be recombined at the end at present.
499 In general, a device would use either planes or bits-per-pixel,
500 though I guess a 24-bit bitmap could use 3 planes of 8 bits
504 The pixels are currently organised horizontally packed into bytes.
508 ********%%%%%%%%$$$$$$$$!!!!!!!! etc
509 ^^^^^^^^@@@@@@@@########++++++++ etc
511 where like symbols are stored in one byte. Vertical packing can be
512 arranged by reversing x and y dimensions and setting the global
513 b_rastermode to TRUE. (e.g. Epson 8-pin dot-matrix printer)
516 Functions provided are
518 (internal functions ? - should probably be static, not external ?)
519 b_setpixel(x,y,value)
520 b_setmaskpixel(x,y,value)
521 b_putc(x,y,char,angle)
526 b_makebitmap(x,y,planes) - make a bitmap of size x * y
527 b_freebitmap() - free bitmap
531 gnuplot driver interface functions (can go straight into gnuplot structure)
533 b_setlinetype(linetype)
541 I think that the library could be made easier to use if we defined
542 a structure which described the bitmap (raster mode, planes, bits-per-pixel,
543 colours, etc) and then added to the gnuplot term struct a pointer to
544 this structure. Then we could have b_graphics() routine which did all
545 the initialisation that presently has to be done by the driver graphics()
546 entry point. Also, one day I would like to have parsing, including
547 terminal driver options, table-driven, but I'm getting ahead of myself
551 At present, bitmap.c is linked into gnuplot unconditionally. Perhaps
552 it should be put into a library, so that it is linked in only if
553 any of the user-selected drivers require bitmap support.
555 There may be scope to do similar things with some of the other
556 stuff that is shared by several drivers. Rather than requiring,
557 for example, that LATEX driver is required if EMTEX is to be used,
558 the shared routines could be extracted to a library and linked
559 if any of the drivers which use them are used. Just a thought...
561 ------------------------------------
566 I think a file layout like the following will leave most flexibility
567 to the gnuplot maintainers. I use REGIS for example.
574 register_term(regis) /* no ; */
579 TERM_PUBLIC void REGISinit __PROTO((void));
580 TERM_PUBLIC void REGISgraphics __PROTO((void));
582 #define GOT_REGIS_PROTO
586 #ifndef TERM_PROTO_ONLY
589 TERM_PUBLIC void REGISinit()
601 TERM_TABLE_START(regis_driver)
603 "regis", "REGIS graphics language",
606 TERM_TABLE_END(regis_driver)
609 #define LAST_TERM regis_driver
611 #endif /* TERM_TABLE */
612 #endif /* TERM_PROTO_ONLY */
620 "?set terminal regis",
622 " The `regis` terminal device generates output in the REGIS graphics language.",
623 " It has the option of using 4 (the default) or 16 colors.",
626 " set term regis {4 | 16}"
633 The first three lines in the TERM_HELP section must contain the same
634 name as that specified by register_term, since this is the name that
635 will be entered into the list of available terminals. If more than
636 one name is registered, the additional names should have their own
637 two "?" lines, but not the "1" line.
639 Each record is enclosed in double-quotes and (except for the last
640 record) followed by a comma. The text is copied as a single string
641 into gnuplot.doc, so the syntax must obey the rules of that entity.
642 If the text includes double-quotes or backslashes, these must be
643 escaped by preceding each occurrence with a backslash.
649 We may want to compile all drivers into term.c or one driver at a time
650 this layout should support both
651 TERM_PUBLIC will be static if all modules are in term.c, or blank
653 Please make private support functions static if possible.
656 We may include term.h, and therefore all these files, one or more times.
657 If just once (all modules compiled into term.c) putting the four
658 parts in this order should make it work.
660 We may compile the table entries into either an array or a linked list.
661 This organisation should support both.
663 For separate compilation, we may write a program which
664 defines TERM_REGISTER and #include term.h to find out which drivers are
665 selected in term.h and thereby generate a makefile.
669 For a driver which depends on another (e.g. enhpost and pslatex on post)
670 the driver can do something like
672 #ifndef GOT_POST_PROTO
673 #define TERM_PROTO_ONLY
675 #undef TERM_PROTO_ONLY
678 this is probably needed only in the TERM_TABLE section, but may
679 also be used in the body. The TERM_PROTO_ONLY means that we pick up
680 only the prototypes from post.trm, even if current driver is being compiled
681 with TERM_BODY or TERM_TABLE
683 If we do it the linked-list way, the argument to TERM_TABLE_START will be
684 the name of the variable, so any valid, unique name is fine.
685 The TERM_TABLE_START macro will do all the work of linking the entries
686 together, probably using LAST_TERM
688 The inclusion of the TERM_HELP section (and removal of terminal documentation
689 from the master gnuplot.doc file) means that the online help will include
690 discussions of only those terminals available to the user. For generation
691 of the printed manual, all can be included.
694 Please make as many things as possible static, but do still try to use unique
695 names since all drivers may be compiled into term.o
697 The bit in the PROTO section is basically what you would put into a .h
698 file if we had them - everything that is needed by the TABLE_ENTRY
699 should be defined in this part. In particular, don't forget all the maxes
700 and character sizes and things for the table entry.
702 Don't forget to put TERM_PUBLIC in the definitions of the functions as
703 well as the prototypes. It will probably always expand to 'static'