1PSLIB(3) Generic Mapping Tools PSLIB(3)
2
6 pslib 4.3 - A PostScript based plotting library
7
9 pslib was created to make the generation of PostScript page description
10 code easier. It is a library that contains a series of tools that can
11 be used to create plots. The resulting PostScript code is ASCII text
12 and can be edited using any text editor. Thus, it is fairly easy to
13 modify a plot file even after it has been created, e.g., to change text
14 strings, set new gray shades or colors, experiment with various pen
15 widths, etc. pslib is written in C but now includes FORTRAN bindings
16 (thanks to John Goff, WHOI) and can therefore be called from both C and
17 FORTRAN programs. To use this library, you must link your plotting
18 program with pslib.a. pslib is the core of the GMT graphics programs.
19 pslib output conforms to the Adobe Encapsulated PostScript File Speci‐
20 fication Version 3.0 (EPSL), and may be used as EPS files and inserted
21 into, say, a Word document on a Mac. See Appendix F in the Technical
22 Reference for detailed instructions.
23 Before any pslib calls can be issued, the plotting system must be ini‐
25 tialized. This is done by calling ps_plotinit, which defines macros,
26 sets up the plot-coordinate system, scales, and [optionally] opens a
27 file where all the PostScript code will be written. Normally, the plot
28 code is written to stdout. The measure unit for sizes and positions
29 can be set to be centimeter (c), inch (i), or meter (m). When all
30 plotting is done, you must terminate the plotting system by calling
31 ps_plotend.
32 pslib uses the direct color model where red, green, and blue are given
34 separately, each must be in the range from 0-255. If red < 0 then no
35 fill operation takes place. Most plot-items can be plotted with or
36 without outlines. If outline is desired (i.e., set to 1), it will be
37 drawn using the current linewidth and pattern. pslib uses highly opti‐
38 mized macro substitutions and scales the coordinates depending on the
39 resolution of the hardcopy device so that the output file is kept as
40 compact as possible.
41 A wide variety of output devices that support PostScript exist, includ‐
43 ing laserwriters (color or monochrome) and workstations running Post‐
44 Script based window systems like Sun's OpenWindows. xnews (part of
45 OpenWindows) or ghostscript (public domain) can be used to create
46 rasterfiles at a user-defined resolution (DPI), making it possible to
47 render PostScript on a Versatec and other non-PostScript raster
48 devices. Regular Sun rasterfiles created under NeWS from PostScript
49 files can be sent to a variety of color hardcopy units. Check the
50 devices available on your network.
51 The pslib is now fully 64-bit compliant. However, only a few function
53 parameters are affected by this (such as the number of point in an
54 array which can now be a 64-bit integer). These few parameters are
55 here given the type long to distinguish them from int. Note that under
56 standard 32-bit compilation they are equivalent. Users of this library
57 under 64-bit mode must make sure they pass proper long variables (under
58 Unix flavors) or __int64 under Windows 64.
59
61 The following is a list of available functions and a short description
62 of what they do and what parameters they expect. All floating point
63 variables are expected to be double (i.e., 8 bytes), whereas all inte‐
64 gers are assumed to be 4 bytes long. All plotting functions are
65 declared as functions returning an int. Currently, the return value is
66 undefined.
67 void ps_arc (x, y, radius, angle1, angle2, status)
69 double x, y, radius, angle1, angle2;
70 int status;
71 Draws a circular arc centered on (x,y) from angle angle1 to
72 angle2. Angles must be given in decimal degrees. If angle1
73 > angle2, a negative arc is drawn. status is a value from 0
74 through 3. 1 means set new anchor point, 2 means stroke the
75 circle, 3 means both, 0 means none of the above.
76 void ps_axis (xpos, ypos, length, startval, stopval, tickval,
78 label, annotpointsize, side)
79 double xpos, ypos, length, startval, stopval, tickval;
80 double annotpointsize, side;
81 char *label;
82 Plots an axis with tickmarks, annotation, and label. xpos,
83 ypos, and length are in inches (or cm or meters), annotpoint‐
84 size in points (72 points = 1 inch), else data units are
85 used. side can be 0, 1, 2, or 3, which selects lower x-axis,
86 right y-axis, upper x-axis, or left y-axis, respectively.
87 labelpointsize = 1.5 * annotpointsize. A negative tickval
88 will reverse the sense of positive direction, e.g., to have
89 the y-axis be positive down.
90 void ps_circle (xcenter, ycenter, diameter, rgb, outline)
92 double xcenter, ycenter, diameter;
93 int rgb[3], outline;
94 Plots a circle and fills it with the specified color. If
95 outline == 1, the outline will be drawn using current pen-
96 width and -pattern.
97 void ps_clipoff ()
99 Resets the clip path to what it was before the last call to
100 ps_clipon.
101 void ps_clipon (xarray, yarray, npoints, rgb, flag)
103 double xarray[], yarray[];
104 long npoints;
105 int rgb[3], flag;
106 Sets up a user-definable clip path. Plotting outside this
107 polygon will be clipped until ps_clipoff is called. If red
108 >= 0 the inside of the path is filled with the specified
109 color. flag is used to create complex clip paths consisting
110 of several disconnected regions, and takes on values 0-3.
111 flag = 1 means this is the first path in a multi-segment clip
112 path. flag = 2 means this is the last segment. Thus, for a
113 single path, flag = 3.
114 void ps_colorimage (xpos, ypos, xlength, ylength, buffer, nx,
116 ny, depth)
117 double xpos, ypos, xlength, ylength;
118 unsigned char buffer[];
119 int nx, ny, depth;
120 Plots a 1-, 2-, 4-, 8-, or 24-bit deep image. This functions
121 sets up a call to the PostScript colorimage or image opera‐
122 tors. xpos, ypos, xlength, ylength specify the position of
123 lower left corner and size (in inches) of image. The pixel
124 values are stored in buffer, an unsigned character array in
125 scanline orientation with gray shade or r/g/b values (0 -
126 255) where 0 is black, 255 is white. buffer[0] is upper left
127 corner. depth is number of bits per pixel (24, 8, 4, 2, or
128 1). nx,ny refers to the number of pixels in image. The
129 rowlength of buffer must be an integral number of 8/depth.
130 E.g. if depth = 4, then buffer[j]/16 gives shade for
131 pixel[2j-1] and buffer[j]%16 (mod 16) gives shade for
132 pixel[2j]. When -depth is passed instead then "hardware"
133 interpolation of the image is requested. If -nx is passed
134 then the first three bytes of buffer holds the r/g/b color
135 for pixels that are to be masked out using the PostScript
136 Level 3 Color Mask method. See the Adobe Systems PostScript
137 Reference Manual for more details.
138 void ps_colortiles (x0, y0, xlength, ylength, buffer, nx, ny)
140 double x0, y0, xlength, ylength;
141 int nx, ny;
142 unsigned char buffer[];
143 Plots a true color image based on individual color tiles. x0,
144 y0 is the location of the lower left corner of the image in
145 inches. xlength, ylength is the image size in inches. buf‐
146 fer contains rgb triplets stored as rgbrgbrgb... nx, ny is
147 the image size in pixels.
148 void ps_command (text)
150 char *text;
151 Writes a raw PostScript command to the PostScript output
152 file, e.g. "1 setlinejoin".
153 void ps_comment (text)
155 char *text;
156 Writes a comment (text) to the PostScript output file, e.g.
157 "Start of graph 2".
158 void ps_cross (xcenter, ycenter, diameter)
160 double xcenter, ycenter, diameter;
161 Plots a cross at the specified point using current pen-width
162 and -pattern that fits inside a circle of given diameter.
163 void ps_diamond (xcenter, ycenter, diameter, rgb, outline)
165 double xcenter, ycenter, diameter;
166 int rgb[3], outline;
167 Plots a diamond and fills it with the specified color. If
168 outline == 1, the outline will be drawn using current pen-
169 width and -pattern. The symbol will fit inside a circle of
170 given diameter.
171 void ps_ellipse (xcenter, ycenter, angle, major, minor, rgb,
173 outline)
174 double xcenter, ycenter, angle, major, minor;
175 int rgb[3], outline;
176 Plots a ellipse with its major semiaxis rotated by angle
177 degrees and fills it with the specified color. If outline ==
178 1, the outline will be drawn using current pen-width and
179 -pattern.
180 void ps_encode_font (font_no)
182 int font_no;
183 Will reencode this font using the current encoding vector if
184 it is not StandardEncoding.
185 void ps_epsimage (xpos, ypos, xlength, ylength, buffer, size,
187 nx, ny, ox, oy)
188 double xpos, ypos, xlength, ylength;
189 unsigned char buffer[];
190 int size, nx, ny, ox, oy;
191 Plots an Encapsulated PostScript (EPS) image. The EPS file is
192 stored in buffer and has size bytes. This functions simply
193 includes the image in the PostScript output stream within an
194 appropriate wrapper. Specify position of lower left corner
195 and size (in inches) of image. nx,ny,ox,oy refers to the
196 width, height and origin (lower left corner) of the Bounding‐
197 Box.
198 void ps_flush ()
200 Flushes the output buffer.
201 void ps_hexagon (xcenter, ycenter, diameter, rgb, outline)
203 double xcenter, ycenter, diameter;
204 int rgb[3], outline;
205 Plots a hexagon and fills it with the specified color. If
206 outline == 1, the outline will be drawn using current pen-
207 width and -pattern. The symbol will fit inside a circle of
208 given diameter.
209 void ps_image (xpos, ypos, xlength, ylength, buffer, nx, ny,
211 bits)
212 double xpos, ypos, xlength, ylength;
213 unsigned char buffer[];
214 int nx, ny, bits;
215 Obsolete, simply passes arguments to ps_colorimage.
216 void ps_imagefill (x, y, n, image, imagefile, invert, dpi, out‐
218 line, f_rgb, b_rgb)
219 double x[], y[], x0, y0;
220 int n, image, invert, dpi, outline, f_rgb[3], b_rgb[3];
221 char imagefile;
222 Similar to ps_polygon, but fills the area with an image pat‐
223 tern rather than a color or grayshade. x and y hold the
224 arrays of n points. 90 predefined patterns are available
225 (See GMT Appendix E). image gives the image number (1-90).
226 If set to 0, imagefile must be the name to the user's image,
227 which must be stored as a Sun 1-, 8-, or 24-bit rasterfile.
228 1-bit images only: (i) The set pixels (1) are colored using
229 the RGB combination in f_rgb, while the unset pixels (0) are
230 painted with b_rgb. Set the f_rgb[0] to -1 to make set pix‐
231 els transparent. Set b_rgb[0] to -1 to make the unset pixels
232 transparent. (ii) If invert is TRUE (1), the set and unset
233 pixels are interchanged before plotting.
234 The unit size of the image is controlled by dpi (in dots-per-
235 inch). If set to zero, the image is plotted at the device
236 resolution. If outline is TRUE, the current penwidth is used
237 to draw the polygon outline.
238 void ps_bitimage (xpos, ypos, xlength, ylength, buffer, nx, ny,
240 invert, f_rgb, b_rgb)
241 double xpos, ypos, xlength, ylength;
242 unsigned char buffer[];
243 int nx, ny, invert, f_rgb[3], b_rgb[3];
244 Plots a 1-bit image using the given foreground color f_rgb
245 and background color b_rgb. Specify position of lower left
246 corner and size (in inches) of image. buffer is an unsigned
247 character array with 8 pixels per byte. nx,ny refers to the
248 number of pixels in image. The rowlength of buffer must be
249 an integral number of 8. buffer[0] is upper left corner.
250 buffer values are stored as columns, starting at the lower
251 left corner and ending at the upper right corner. If invert
252 is 0 then the bits that are 1 are painted with the foreground
253 color, while bits that are 0 are painted with the backgound
254 color. If invert is 1, foreground and background are
255 switched. To get a partly transparent image, set the first
256 index of the foreground or background color to -1, i.e.
257 f_rgb[0]=-1 or b_rgb[0]=1. See the Adobe Systems PostScript
258 Reference Manual for more details.
259 void ps_itriangle (xcenter, ycenter, diameter, rgb, outline)
261 double xcenter, ycenter, diameter;
262 int rgb[3], outline;
263 Plots an inverted and fills it with the specified color. If
264 outline == 1, the outline will be drawn using current pen-
265 width and -pattern. The symbol will fit inside a circle of
266 given diameter.
267 long ps_line (xarray, yarray, npoints, type, close, split)
269 double xarray[], yarray[];
270 long npoints;
271 int type, close, split;
272 Draw a continuous line from the positions in the x-y arrays.
273 If close == 1, the first and last point will automatically be
274 closed by the PostScript driver. If this is the first seg‐
275 ment in a multi-segment path, set type == 1. To end the seg‐
276 ments and have the line(s) drawn, set type == 2. Thus, for
277 a single segment, type must be 3. The line is drawn using
278 the current penwidth. Only if split is TRUE may ps_line use
279 multiple strokes to draw lines longer that MAX_PATH.
280 ps_polygon will call ps_line with split = FALSE since the
281 path must be continuous. If split is FALSE and the path‐
282 length exceeds MAX_PATH a warning will be issued.
283 unsigned char *ps_load_image (fp, header)
285 FILE *fp;
286 struct imageinfo *header;
287 Reads the image contents of the EPS file or Sun rasterfile
288 pointed to by the open filepointer fp. The routine can han‐
289 dle Encapsulated PostScript files or 1-, 8-, 24-, or 32-bit
290 rasterfiles in old, standard, run-length encoded, or RGB-
291 style Sun format.
292 void ps_octagon (xcenter, ycenter, diameter, rgb, outline)
294 double xcenter, ycenter, diameter;
295 int rgb[3], outline;
296 Plots a octagon and fills it with the specified color. If
297 outline == 1, the outline will be drawn using current pen-
298 width and -pattern. The symbol will fit inside a circle of
299 given diameter.
300 void ps_patch (xarray, yarray, npoints, rgb, outline)
302 double xarray[], yarray[];
303 long npoints;
304 int rgb[3], outline;
305 Identical to ps_polygon except polygon must be < 20 points
306 long and there will be no attempt to shorten the path by dis‐
307 carding unnecessary intermediate points along straight seg‐
308 ments. Primarily used when painting large number of small
309 polygons and not waste output space. If more than 20 points
310 are given we pass the buck to ps_polygon.
311 void ps_pentagon (xcenter, ycenter, diameter, rgb, outline)
313 double xcenter, ycenter, diameter;
314 int rgb[3], outline;
315 Plots a pentagon and fills it with the specified color. If
316 outline == 1, the outline will be drawn using current pen-
317 width and -pattern. The symbol will fit inside a circle of
318 given diameter.
319 void ps_pie (xcenter, ycenter, radius, azimuth1, azimuth2, rgb,
321 outline)
322 double xcenter, ycenter, radius, azimuth1, azimuth2;
323 int rgb[3], outline;
324 Plots a sector of a circle and paints it with the specified
325 RGB combination. If outline == 1, the outline will be drawn
326 using current pen-width and -pattern.
327 void ps_plot (xabs, yabs, kpen)
329 double xabs, yabs;
330 int kpen;
331 Absolute move (kpen=3) or draw (kpen=2), using current
332 linewidth. Use (kpen=-2) to make sure the line is stroked.
333 void ps_plotend (last_page)
335 int last_page;
336 Terminates the plotting sequence and closes plot file (if
337 other than stdout). If last_page == 1, then a PostScript
338 showpage command is issued, which initiates the printing
339 process on hardcopy devices.
340 void ps_plotinit (plotfile, overlay, mode, xoff, yoff, xscl,
342 yscl, ncopies, dpi, unit, pagesize, rgb, encoding, eps)
343 char *plotfile, *encoding;
344 int overlay, mode, ncopies, dpi, unit;
345 double xoff, yoff, xscl, yscl;
346 int pagesize[2], rgb[3]; struct EPS * eps;
347 Initializes the plotting. If plotfile == NULL (or ""), then
348 output is sent to stdout, else output is sent to plotfile.
349 overlay should be 1 only if you plan to append it to some
350 existing PostScript file. mode contains three flags in the
351 three lowest bits. The lowest bit controls the plot orienta‐
352 tion and can be 0 (Landscape) or 1 (Portrait). The next bit,
353 if set to 1, will re-encode the fonts to include European
354 accented characters using the now-obsolete GMT 3.4 encoding.
355 To use the ISOLatin1 encoding set the 5th bit to 1. The
356 third bit controls the format used to write PostScript
357 images: 0 means binary, 1 means hexadecimal. Most printers
358 needs the latter while some can handle binary which are 50%
359 smaller and therefore execute faster. xoff,yoff are used to
360 move the origin from the default position in the lower left
361 corner. xscl,yscl are used to scale the entire plot (Usually
362 set to 1.0, 1.0). Set ncopies to get more than 1 copy. dpi
363 sets the hardcopy resolution in dots pr units. For optimum
364 plot quality and processing speed, choose dpi to match the
365 intended plotter resolution. Examples are 300 for most
366 laserwriters, 2540 for Linotype-300, and ~85 for Sun screens.
367 When in doubt, use 300. unit can be any of 0 (cm), 1 (inch),
368 or 2 (m), telling the plot system what units are used for
369 distance and sizes. Note that, regardless of choice of unit,
370 dpi is still in dots-pr-inch. pagesize means the physical
371 width and height of the plotting media in points, (typically
372 612 by 792 for Letter or 595 by 842 for A4 laserwriter plot‐
373 ters. The rgb array holds the color of the page (usually
374 white = 255,255,255). The encoding is the name of a charac‐
375 ter encoding scheme to be used, e.g., Standard, ISOLatin1,
376 ISO-8859-2, etc. The EPS structure is defined in the pslib.h
377 include file and contains information that will make up the
378 comments header of a EPS file. Programmers who plan to call
379 pslib routines should read the comments in pslib.h first.
380 Note that the FORTRAN binding does not expect this last argu‐
381 ment.
382 void ps_plotr (xrel, yrel, kpen)
384 double xrel, yrel;
385 int kpen;
386 Move (kpen = 3) or draw (kpen = 2) relative to current point
387 (see ps_plot). Use (kpen=-2) to make sure the line is
388 stroked.
389 void ps_point (xcenter, ycenter, diameter)
391 double xcenter, ycenter, diameter;
392 Plots a point using current pen with given diameter. Note
393 the linecap setting must first be set to 1 for this function
394 to work.
395 void ps_polygon (xarray, yarray, npoints, rgb, outline)
397 double xarray[], yarray[];
398 long npoints;
399 int rgb[3], outline;
400 Creates a colored polygon from the positions in the x-y
401 arrays. Polygon will automatically be closed by the Post‐
402 Script driver. If outline == 0, no outline is drawn. If
403 outline == 1, the outline is drawn using current penwidth.
404 void ps_rect (x1, y1, x2, y2, rgb, outline)
406 double x1, y1, x2, y2;
407 int rgb[3], outline;
408 Plots a colored rectangle. (x1,y1) and (x2,y2) are any two
409 corners on a diagonal. If outline == 1, the outline will be
410 drawn using current pen-width and -pattern.
411 void ps_rotaterect (x, y, angle, xsize, ysize, rgb, outline)
413 double x, y, angle, xsize, ysize;
414 int rgb[3], outline;
415 Plots a colored rectangle rotated angle degrees from base‐
416 line. (x,y) is the center and (xsize,ysize) are the dimen‐
417 sions. If outline == 1, the outline will be drawn using cur‐
418 rent pen-width and -pattern.
419 void ps_rotatetrans (x, y, angle)
421 double x, y, angle;
422 Rotates the coordinate system by angle degrees, then trans‐
423 lates origin to (x,y).
424 void ps_segment (x0, y0, x1, y1)
426 double x0, y0, x1, y1;
427 Draws a line segment between the two points using current pen
428 attributes.
429 void ps_setdash (pattern, offset)
431 char *pattern;
432 int offset;
433 Changes the current dashpattern. The character string pat‐
434 tern is set to the desired pattern. E.g., "4 2" and offset =
435 1 will plot like:
436 x ---- ---- ----
437 etc, where x is starting point (The x is not plotted). That
438 is, the line is made up of a repeating pattern of a 4 units
439 long line and a 2 unit long gap, starting 1 unit after the x.
440 To reset to solid line, specify pattern = NULL ("") and off‐
441 set = 0. Units are in dpi units.
442 void ps_setfont (fontnr)
444 int fontnr;
445 Changes the current font number to fontnr. The fonts avail‐
446 able are: 0 = Helvetica, 1 = H. Bold, 2 = H. Oblique, 3 = H.
447 Bold-Oblique, 4 = Times, 5 = T. Bold, 6 = T. Italic, 7 = T.
448 Bold Italic, 8 = Courier, 9 = C. Bold, 10 = C Oblique, 11 = C
449 Bold Oblique, 12 = Symbol, 13 = AvantGarde-Book, 14 =
450 A.-BookOblique, 15 = A.-Demi, 16 = A.-DemiOblique, 17 = Book‐
451 man-Demi, 18 = B.-DemiItalic, 19 = B.-Light, 20 = B.-LightI‐
452 talic, 21 = Helvetica-Narrow, 22 = H-N-Bold, 23 = H-N-
453 Oblique, 24 = H-N-BoldOblique, 25 = NewCenturySchlbk-Roman,
454 26 = N.-Italic, 27 = N.-Bold, 28 = N.-BoldItalic, 29 = Pala‐
455 tino-Roman, 30 = P.-Italic, 31 = P.-Bold, 32 = P.-BoldItalic,
456 33 = ZapfChancery-MediumItalic, 34 = ZapfDingbats, 35 = Ryu‐
457 min-Light-EUC-H, 36 = Ryumin-Light-EUC-V, 37 = GothicBBB-
458 Medium-EUC-H, and 38 = GothicBBB-Medium-EUC-V. If fontnr is
459 outside this range, it is set to 0.
460 void ps_setformat (n_decimals)
462 int n_decimals;
463 Sets number of decimals to be used when writing color or gray
464 values. The default setting of 3 gives 1000 choices per red,
465 green, and blue value, which is more than the 255 choices
466 offered by most 24-bit platforms. Choosing a lower value
467 will make the output file smaller at the expense of less
468 color resolution. Still, a value of 2 gives 100 x 100 x 100
469 = 1 million colors, more than most eyes can distinguish. For
470 a setting of 1, you will have 10 nuances per primary color
471 and a total of 1000 unique combinations.
472 void ps_setline (linewidth)
474 int linewidth;
475 Changes the current linewidth in DPI units. 0 gives thinnest
476 line, but the use of 0 is implementation-dependent (Works
477 fine on most laserwriters).
478 void ps_setlinecap (cap)
480 int cap;
481 Changes the current linecap. 0 gives butt cap [Default], 1
482 gives round, and 2 gives square.
483 void ps_setlinejoin (join)
485 int join;
486 Changes the current linejoin. 0 gives mitered [Default], 1
487 gives round, and 2 gives bevel joins.
488 void ps_setmiterlimit (limit)
490 int limit;
491 Changes the current miter limit. 0 gives default miter,
492 other values are the cutoff-, acute- angle when mitering
493 takes place.
494 void ps_setpaint (rgb)
496 int rgb[3];
497 Changes the current RGB setting for pens and text.
498 void ps_square (xcenter, ycenter, diameter, rgb, outline)
500 double xcenter, ycenter, diameter;
501 int rgb[3], outline;
502 Plots a square and fills it with the specified color. If
503 outline == 1, the outline will be drawn using current pen-
504 width and -pattern. The symbol will fit inside a circle of
505 given diameter.
506 void ps_star (xcenter, ycenter, diameter, rgb, outline)
508 double xcenter, ycenter, diameter;
509 int rgb[3], outline;
510 Plots a star and fills it with the specified color. If out‐
511 line == 1, the outline will be drawn using current pen-width
512 and -pattern. The symbol will fit inside a circle of given
513 diameter.
514 void ps_text (x, y, pointsize, text, angle, justify, form)
516 double x, y, pointsize, angle;
517 char *text;
518 int justify, form;
519 The text is plotted starting at (x,y), and will make an angle
520 with the horizontal. The point (x,y) maps onto different
521 points of the textstring by giving various values for jus‐
522 tify. It is used as follows:
523 9------------10----------- 11
525 | |
526 5 6 7
527 | |
528 1------------ 2------------ 3
529 The box represents the textstring. E.g., to plot a
530 textstring with its center of gravity at (x,y), you must use
531 justify == 6. If justify is negative, then all leading and
532 trailing blanks are stripped before plotting. Certain char‐
533 acter sequences (flags) have special meaning to ps_text. @~
534 toggles between current font and the Mathematical Symbols
535 font. @%no% sets font to no; @%% resets to starting font.
536 @- turns subscript on/off, @+ turns superscript on/off, @#
537 turns small caps on/off, and @\ will make a composite charac‐
538 ter of the following two character. @;r/g/b; changes the
539 font color (@;; resets it), @:size: changes the font size
540 (@:: resets it), and @_ toggles underline on/off. Give font‐
541 size in points (72 points = 1 inch). Normally, the text is
542 typed using solid characters. To draw outline characters,
543 set form == 1. If pointsize is negative it means that the
544 current point has already been set before ps_text was called
545 and that (x,y) should be ignored.
546 void ps_textbox (x, y, pointsize, text, angle, justify, outline,
548 dx, dy, rgb)
549 double x, y, angle, pointsize, dx, dy;
550 char *text;
551 int justify, outline, rgb[3];
552 This function is used in conjugation with ps_text when a box
553 surrounding the text string is desired. Taking most of the
554 arguments of ps_text, the user must also specify the color of
555 the resulting rectangle, and whether its outline should be
556 drawn. More room between text and rectangle can be obtained
557 by setting dx and dy accordingly.
558 void ps_transrotate (x, y, angle)
560 double x, y, angle;
561 Translates the origin to (x,y), then rotates the coordinate
562 system by angle degrees.
563 void ps_triangle (xcenter, ycenter, diameter, rgb, outline)
565 double xcenter, ycenter, diameter;
566 int rgb[3], outline;
567 Plots a triangle and paints it with the specified RGB combi‐
568 nation. If outline == 1, the outline will be drawn using
569 current pen-width and -pattern. The symbol will fit inside a
570 circle of given diameter.
571 void ps_vector (xtail, ytail, xtip, ytip, tailwidth, headlength,
573 headwidth, headshape, rgb, outline)
574 double xtail, ytail, xtip, ytip, tailwidth, headlength, head‐
575 width, headshape;
576 int rgb[3], outline;
577 Draws a vector of size and appearance as specified by the
578 various parameters. headshape can take on values from 0-1
579 and specifies how far the intersection point between the base
580 of a straight vector head and the vector line is moved toward
581 the tip. 0 gives a triangular head, 1.0 gives an arrow
582 shaped head. If outline == 1, the outline will be drawn using
583 current penwidth. Add 8 to outline for a double-headed vec‐
584 tor.
585 void ps_words (x, y, text, n_words, line_space, par_width,
587 par_just, font, font_size, angle, rgb, justify, draw_box, x_off,
588 y_off, x_gap, y_gap, boxpen_width, boxpen_texture, boxpen_off‐
589 set, boxpen_rgb, vecpen_width, vecpen_texture, vecpen_offset,
590 vecpen_rgb, boxfill_rgb)
591 double x, y, line_space, par_width, angle, x_off, y_off, x_gap,
592 y_gap;
593 long n_words;
594 int font, font_size, justify, draw_box, boxpen_width, box‐
595 pen_offset;
596 int boxpen_rgb[3], vecpen_width, vecpen_offset, vecpen_rgb[3],
597 boxfill_rgb[3];
598 char **text, *boxpen_texture, *vecpen_texture;
599 Typesets paragraphs of text. text is an array of the words
600 to typeset, using the given line-spacing and paragraph width.
601 The whole text block is positioned at x, y which is the
602 anchor point on the box as indicated by justify (see
603 ps_text). The whole block is then shifted by x_off, y_off.
604 Inside the box, text is justified left, centered, right, or
605 justified as governed by par_just (lcrj). draw_box contains
606 4 bit flags pertaining to the surrounding outline box. If
607 on, the first (lowest) bit draws the box outline. The second
608 bit fills the box interior. The third bit makes the outline
609 box have rounded corners (unless x_gap, y_gap, which speci‐
610 fies the padding between the text and the box, are zero),
611 while the forth bit draws a line from the original x, y point
612 to the shifted position. The escape sequences described for
613 ps_text applies as well.
614
616 Paul Wessel, School of Ocean and Earth Science and Technology, 1680
617 East-West Road, Honolulu, Hawaii 96822, (808) 956-4778, Internet
618 address: pwessel@hawaii.edu.
619
621 Caveat Emptor: The author is not responsible for any disasters, sui‐
622 cide attempts, or ulcers caused by correct or incorrect use of pslib.
623 If you find bugs, please report them to the author by electronic mail.
624 Be sure to provide enough detail so that I can recreate the problem.
625
627 Adobe Systems Inc., 1990, PostScript language reference manual, 2nd
628 edition, Addison-Wesley, (ISBN 0-201-18127-4).
629GMT 4.3.1 15 May 2008 PSLIB(3)