Annotation of OpenXM_contrib/gnuplot/term/README, Revision 1.1.1.1
1.1 maekawa 1: DOCUMENTATION FOR GNUPLOT TERMINAL DRIVER WRITERS
2: By Russell Lang 1/90
3:
4: Updated for new file layout by drd 4/95
5:
6: Paragraphs about inclusion of TERM_HELP added by rcc 1/96
7:
8: No change to the interface between gnuplot and the terminal drivers,
9: but we would like to make the terminal drivers standalone
10:
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
13: contributed drivers
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.
18:
19: CORRECTION - scale() interface is no longer supported, since it
20: is incompatible with multiplot.
21:
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.
26:
27: term.h, and therefore each file.trm file, may be loaded more than once,
28: with different sections selected by macros.
29:
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 plot.h:
33:
34: struct TERMENTRY {
35:
36: /* required entries */
37:
38: char *name;
39: char *description;
40: unsigned int xmax,ymax,v_char,h_char,v_tic,h_tic;
41:
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,char*));
52:
53: /* optional entries */
54:
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, int));
60: int (*set_font) __PROTO((char *font)); /* "font,size" */
61: void (*set_pointsize) __PROTO((double size)); /* notification of set 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 (*boxfill) __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));
67: void (*pointsize) __PROTO((double pointsize));
68: };
69:
70: One consequence of (1) is that we would like drivers to be backwards
71: compatible - drivers in the correct form below should work in future
72: versions of gnuplot without change. C compilers guarantee to fill
73: unitialised members of a structure to zero, so gnuplot can detect old
74: drivers, in which fields have not been initalised, and can point
75: new interface entry pointers to dummy functions.
76:
77: We can add fields to the terminal structure, but only at the end of the list.
78: If you design a terminal that cant work without a new interface being defined,
79: and consequent changes to the main gnuplot source, please contact
80: bug-gnuplot@dartmouth.edu simply to ensure that you have the most
81: up to date defn of the terminal structure. Also, please ensure that
82: the 'set term' command checks for 0 values in added fields when an
83: old driver is selected, and a pointer to a suitable 'cant do' function
84: is provided. It is therefore not required (and in fact not possible)
85: to add padding fields to the end of all drivers.
86:
87: Similarly, if you add an optional field to an old driver, take care
88: to ensure that all intervening fields are padded with zeros.
89:
90: Some of the above fields are required - this should not be a problem,
91: since they were all required in earlier releases of gnuplot.
92: The later fields are interfaces to capabilities that not all devices
93: can do, or for which the generic routines provided should be adequate.
94: There are several null ('cant do') functions provided by term.c which
95: a driver can reference in the table. Similarly, for bitmap devices, there
96: are generic routines for lines and text provided by bitmap.c
97:
98:
99:
100: Here's a brief description of each variable:
101:
102: The char *name is a pointer to a string containing the name
103: of the terminal. This name is used by the 'set terminal' and
104: 'show terminal' commands.
105: The name must be unique and must not be confused with an abbreviation
106: of another name. For example if the name "postscript" exists, it is not
107: possible to have another name "postscript2".
108: Keep the name under 15 characters.
109:
110: The char *description is a pointer to a string containing a
111: description of the terminal, which is displayed in response
112: to the 'set terminal' command.
113: Keep the description under 60 characters.
114:
115: xmax is the maximum number of points in the x direction.
116: The range of points used by gnuplot is 0 to xmax-1.
117:
118: ymax is the maximum number of points in the y direction.
119: The range of points used by gnuplot is 0 to ymax-1.
120:
121: v_char is the height of characters, in the same units as xmax and ymax.
122: The border for labelling at the top and bottom of the plot is
123: calculated using v_char.
124: v_char is used as the vertical line spacing for characters.
125:
126: h_char is the width of characters, in the same units as xmax and ymax.
127: The border for labelling at the left and right of the plot is
128: calculated using h_char, for example.
129: If the _justify_text function returns FALSE, h_char is used to justify
130: text right or centre. If characters are not fixed width, then the
131: _justify_text function must correctly justify the text.
132:
133: v_tic is the vertical size of tics along the x axis,
134: in the same units as ymax.
135:
136: h_tic is the horizontal size of tics along the y axis,
137: in the same units as xmax.
138:
139: v_tic and h_tic should give tics of the same physical size on the
140: output. The ratio of these two quantities is used by gnuplot to set the
141: aspect ratio to 1 so that circles appear circular when 'set size square'
142: is active.
143:
144: All the above values need not be static - values can be substituted
145: into the table during terminal initialisation, based on options for
146: example.
147:
148:
149:
150: Here's a brief description of what each term.c function does:
151:
152: _options() Called when terminal type is selected.
153: This procedure should parse options on the command line. A list of the
154: currently selected options should be stored in term_options[] in a form
155: suitable for use with the set term command. term_options[] is used by
156: the save command. Use options_null() if no options are available.
157:
158: _init() Called once, when the device is first selected. This procedure
159: should set up things that only need to be set once, like handshaking and
160: character sets etc...
161: There is a global variable 'pointsize' which you might want to use here.
162: If set pointsize is issued after init has been called, the set_pointsize()
163: function is called.
164:
165: _reset() Called when gnuplot is exited, the output device changed or
166: the terminal type changed. This procedure should reset the device,
167: possibly flushing a buffer somewhere or generating a form feed.
168:
169: _scale(xs,ys) Called just before _graphics(). This takes the x and y
170: scaling factors as information. If the terminal would like to do its
171: own scaling, it returns TRUE. Otherwise, it can ignore the information
172: and return FALSE: do_plot will do the scaling for you. null_scale is
173: provided to do just this, so most drivers can ignore this function
174: entirely. The Latex driver is currently the only one providing its own
175: scaling. PLEASE DO NOT USE THIS INTERFACE - IT IS NOT COMPATIBLE WITH
176: MULTIPLOT.
177:
178: _graphics() Called just before a plot is going to be displayed. This
179: procedure should set the device into graphics mode. Devices which can't
180: be used as terminals (like plotters) will probably be in graphics mode
181: always and therefore won't need this.
182:
183: _text() Called immediately after a plot is displayed. This procedure
184: should set the device back into text mode if it is also a terminal, so
185: that commands can be seen as they're typed. Again, this will probably
186: do nothing if the device can't be used as a terminal. This call can
187: be used to trigger conversion and output for bitmap devices.
188:
189: _move(x,y) Called at the start of a line. The cursor should move to the
190: (x,y) position without drawing.
191:
192: _vector(x,y) Called when a line is to be drawn. This should display a line
193: from the last (x,y) position given by _move() or _vector() to this new (x,y)
194: position.
195:
196: _linetype(lt) Called to set the line type before text is displayed or
197: line(s) plotted. This procedure should select a pen color or line
198: style if the device has these capabilities.
199: lt is an integer from -2 to 0 or greater.
200: An lt of -2 is used for the border of the plot.
201: An lt of -1 is used for the X and Y axes.
202: lt 0 and upwards are used for plots 0 and upwards.
203: If _linetype() is called with lt greater than the available line types,
204: it should map it to one of the available line types.
205: Most drivers provide 9 different linetypes (lt is 0 to 8).
206:
207: _put_text(x,y,str) Called to display text at the (x,y) position,
208: while in graphics mode. The text should be vertically (with respect
209: to the text) justified about (x,y). The text is rotated according
210: to _text_angle and then horizontally (with respect to the text)
211: justified according to _justify_text.
212:
213:
214: The following are optional
215:
216:
217: _text_angle(ang) Called to rotate the text angle when placing the y label.
218: If ang = 0 then text is horizontal. If ang = 1 then text is vertically
219: upwards. Returns TRUE if text can be rotated, FALSE otherwise.
220: [But you must return TRUE if called with ang=0]
221:
222: _justify_text(mode) Called to justify text left, right or centre.
223: If mode = LEFT then text placed by _put_text is flushed left against (x,y).
224: If mode = CENTRE then centre of text is at (x,y).
225: If mode = RIGHT then text is placed flushed right against (x,y).
226: Returns TRUE if text can be justified
227: Returns FALSE otherwise and then _put_text assumes text is flushed left;
228: justification of text is then performed by calculating the text width
229: using strlen(text) * h_char.
230:
231: _point(x,y,point) Called to place a point at position (x,y).
232: point is -1 or an integer from 0 upwards.
233: At least 6 point types (numbered 0 to 5) are normally provided.
234: Point type -1 is a dot.
235: If point is more than the available point types then it should
236: be mapped back to one of the available points.
237: Two _point() functions called do_point() and line_and_point() are
238: provided in term.c and should be suitable for most drivers.
239: do_point() draws the points in the current line type.
240: If your driver uses dotted line types (generally because it is
241: monochrome), you should use line_and_point() which changes to
242: line type 0 before drawing the point. line type 0 should be solid.
243:
244: There is a global variable 'pointsize' which is controlled by the
245: set pointsize command. If possible, use that. pointsize should be
246: examined at terminal init. If it is subsequently changed, the
247: set_pointsize() fn will be called.
248:
249:
250: _arrow(sx,sy,ex,ey,head) Called to draw an arrrow from (sx,sy) to (ex,ey).
251: A head is drawn on the arrow if head = TRUE.
252: An _arrow() function called do_arrow() is provided in term.c which will
253: draw arrows using the _move() and _vector() functions.
254: Drivers should use do_arrow unless it causes problems.
255:
256: _set_font() is called to set the font of labels, etc [new 3.7 feature]
257: fonts are selected as strings "name,size"
258:
259: _pointsize() is used to set the pointsize for subsequent points
260:
261: _flags stores various flags describing driver capabilities. Currently
262: three bits are allocated
263: - TERM_CAN_MULTIPLOT - driver can do multiplot
264: fully-interactively when output is not redirected. ie text and graphics
265: go to different places, or driver can flip using suspend.
266: - TERM_CANT_MULTIPLOT - driver cannot multiplot, even if output
267: is redirected.
268: - TERM_BINARY - output file must be opened in binary mode
269: Another bit is earmarked for VMS_PASTHRU, but not yet implemented.
270:
271: _suspend() - called before gnuplot issues a prompt in multiplot mode
272: linux vga driver uses this entry point to flip from graphics to
273: text mode. X11 driver will take this opportunity to paint the window
274: on the display.
275:
276: _resume() - called after suspend(), before subsequent plots of a multiplot.
277:
278: _boxfill() - fills a box in given style (currently unimplemented - always
279: background colour at present). used by 'clear' in multiplot for
280: support of inset graphs
281:
282: _linewidth() - sets the linewidth
283:
284: The following should illustrate the order in which calls to these
285: routines are made:
286:
287: _options()
288: _init()
289: _scale(xs,ys)
290: _graphics()
291: _linewidth(lw)
292: _linetype(lt)
293: _move(x,y)
294: _vector(x,y)
295: _pointsize(size)
296: _point(x,y,point)
297: _text_angle(angle)
298: _justify(mode)
299: _set_font(font)
300: _put_text(x,y,text)
301: _arrow(sx,sy,ex,ey)
302: _text()
303: _graphics()
304: .
305: _suspend()
306: _set_pointsize()
307: _resume()
308: .
309: _text()
310: _reset()
311:
312:
313: ------------------------------------
314:
315: BITMAP DEVICES
316:
317: A file bitmap.c is provided, implementing a generic set of bitmap
318: routines. It provides all the routines required to generate a
319: bitmap in memory, drawing lines and writing text. A simple driver
320: need provide only a text() entry point, which converts and outputs
321: the stored bitmap in the format required by the device.
322:
323: Internally, the bitmap is built of one or more planes of 1
324: bit per pixel. In fact, I think the library would be easier to
325: use if it offered one or more planes of pixels with 1,2,4 or 8
326: bits per pixel, since not all bitmap devices are based on planes,
327: and the planes have to be recombined at the end at present.
328: In general, a device would use either planes or bits-per-pixel,
329: though I guess a 24-bit bitmap could use 3 planes of 8 bits
330: per pixel..?
331:
332:
333: The pixels are currently organised horizontally packed into bytes.
334:
335: ie
336:
337: ********%%%%%%%%$$$$$$$$!!!!!!!! etc
338: ^^^^^^^^@@@@@@@@########++++++++ etc
339:
340: where like symbols are stored in one byte. Vertical packing can be
341: arranged by reversing x and y dimensions and setting the global
342: b_rastermode to TRUE. (eg epson 8-pin dot-matrix printer)
343:
344:
345: Functions provided are
346:
347: (internal fns ? - should probably be static, not external ?)
348: b_setpixel(x,y,value)
349: b_setmaskpixel(x,y,value)
350: b_putc(x,y,char,angle)
351: b_setvalue(size)
352:
353: setting up stuff
354:
355: b_makebitmap(x,y,planes) - make a bitmap of size x * y
356: b_freebitmap() - free bitmap
357: b_charsize(size)
358:
359:
360: gnuplot driver interface functions (can go straight into gnuplot structure)
361:
362: b_setlinetype(linetype)
363: b_move(x,y)
364: b_vector(x,y)
365: b_put_text(x,y,*str)
366: b_text_angle(ang)
367:
368:
369:
370: I think that the library could be made easier to use if we defined
371: a structure which described the bitmap (raster mode, planes, bits-per-pixel,
372: colours, etc) and then added to the gnuplot term struct a pointer to
373: this structure. Then we could have b_graphics() routine which did all
374: the initialisation that presently has to be done by the driver graphics()
375: entry point. Also, one day I would like to have parsing, including
376: terminal driver options, table-driven, but I'm getting ahead of myself
377: here.
378:
379:
380: At present, bitmap.c is linked into gnuplot unconditionally. Perhaps
381: it should be put into a library, so that it is linked in only if
382: any of the user-selected drivers require bitmap support.
383:
384: There may be scope to do similar things with some of the other
385: stuff that is shared by several drivers. Rather than requiring,
386: for example, that LATEX driver is required if EMTEX is to be used,
387: the shared routines could be extracted to a library and linked
388: if any of the drivers which use them are used. Just a thought...
389:
390: ------------------------------------
391:
392: FILE LAYOUT
393: -----------
394:
395: I think a file layout like the following will leave most flexibility
396: to the gnuplot maintainers. I use REGIS for example.
397:
398:
399: #include "driver.h"
400:
401:
402: #ifdef TERM_REGISTER
403: register_term(regis) /* no ; */
404: #endif
405:
406:
407: #ifdef TERM_PROTO
408: TERM_PUBLIC void REGISinit __PROTO((void));
409: TERM_PUBLIC void REGISgraphics __PROTO((void));
410: /* etc */
411: #define GOT_REGIS_PROTO
412: #endif
413:
414:
415: #ifndef TERM_PROTO_ONLY
416: #ifdef TERM_BODY
417:
418: TERM_PUBLIC void REGISinit()
419: {
420: /* etc */
421: }
422:
423: /* etc */
424:
425: #endif
426:
427:
428: #ifdef TERM_TABLE
429:
430: TERM_TABLE_START(regis_driver)
431: /* no { */
432: "regis", "REGIS graphics language",
433: REGISXMAX, /* etc */
434: /* no } */
435: TERM_TABLE_END(regis_driver)
436:
437: #undef LAST_TERM
438: #define LAST_TERM regis_driver
439:
440: #endif /* TERM_TABLE */
441: #endif /* TERM_PROTO_ONLY */
442:
443:
444:
445:
446: #ifdef TERM_HELP
447: START_HELP(regis)
448: "1 regis",
449: "?set terminal regis",
450: "?regis",
451: " The `regis` terminal device generates output in the REGIS graphics language.",
452: " It has the option of using 4 (the default) or 16 colors.",
453: "",
454: " Syntax:",
455: " set term regis {4 | 16}"
456: END_HELP(regis)
457: #endif
458:
459:
460: --------------
461:
462: The first three lines in the TERM_HELP section must contain the same
463: name as that specified by register_term, since this is the name that
464: will be entered into the list of available terminals. If more than
465: one name is registered, the additional names should have their own
466: two "?" lines, but not the "1" line.
467:
468: Each record is enclosed in double-quotes and (except for the last
469: record) followed by a comma. The text is copied as a single string
470: into gnuplot.doc, so the syntax must obey the rules of that entity.
471: If the text includes double-quotes or backslashes, these must be
472: escaped by preceding each occurence with a backslash.
473:
474: --------------
475:
476: Rationale:
477:
478: We may want to compile all drivers into term.c or one driver at a time
479: this layout should support both
480: TERM_PUBLIC will be static if all modules are in term.c, or blank
481: otherwise.
482: Please make private support functions static if possible.
483:
484:
485: We may include term.h, and therefore all these files, one or more times.
486: If just once (all modules compiled into term.c) putting the four
487: parts in this order should make it work.
488:
489: we may compile the table entries into either an array or a linked list
490: This organisation should support both
491:
492: For separate compilation, we may write a program which
493: defines TERM_REGISTER and #include term.h to find out which drivers are
494: selected in term.h and thereby generate a makefile.
495:
496:
497:
498: For a driver which depends on another (eg enhpost and pslatex on post)
499: the driver can do something like
500:
501: #ifndef GOT_POST_PROTO
502: #define TERM_PROTO_ONLY
503: #include "post.trm"
504: #undef TERM_PROTO_ONLY
505: #endif
506:
507: this is probably needed only in the TERM_TABLE section only, but may
508: also be used in the body. The TERM_PROTO_ONLY means that we pick up
509: only the protos from post.trm, even if current driver is being compiled
510: with TERM_BODY or TERM_TABLE
511:
512: If we do it the linked-list way, the arg to TERM_TABLE_START will be
513: the name of the variable, so any valid, unique name is fine.
514: The TERM_TABLE_START macro will do all the work of linking the entries
515: together, probably using LAST_TERM
516:
517: The inclusion of the TERM_HELP section (and removal of terminal documentation
518: from the master gnuplot.doc file) means that the online help will include
519: discussions of only those terminals available to the user. For generation
520: of the printed manual, all can be included.
521:
522:
523: Please make as many things as possible static, but do still try to use unique
524: names since all drivers may all be compiled into term.o
525:
526: The bit in the PROTO section is basically what you would put into a .h
527: file if we had them - everything that is needed by the TABLE_ENTRY
528: should be defined in this part. In particular, dont forget all the maxes
529: and character sizes and things for the table entry.
530:
531: Dont forget to put TERM_PUBLIC in the defns of the fns as well as the
532: prototypes. It will probably always expand to 'static' except for pcs.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gnuplot / term