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 (or ps_plotinit_hires),
26 which defines macros, sets up the plot-coordinate system, scales, and
27 [optionally] opens a file where all the PostScript code will be writ‐
28 ten. Normally, the plot code is written to stdout. The measure unit
29 for sizes and positions can be set to be centimeter (c), inch (i), or
30 meter (m). When all plotting is done, you must terminate the plotting
31 system by calling 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_bitimage (xpos, ypos, xlength, ylength, buffer, nx, ny,
92 invert, f_rgb, b_rgb)
93 double xpos, ypos, xlength, ylength;
94 unsigned char buffer[];
95 int nx, ny, invert, f_rgb[3], b_rgb[3];
96 Plots a 1-bit image using the given foreground color f_rgb
97 and background color b_rgb. Specify position of lower left
98 corner and size (in inches) of image. buffer is an unsigned
99 character array with 8 pixels per byte. nx,ny refers to the
100 number of pixels in image. The rowlength of buffer must be
101 an integral number of 8. buffer[0] is upper left corner.
102 buffer values are stored as columns, starting at the lower
103 left corner and ending at the upper right corner. If invert
104 is 0 then the bits that are 1 are painted with the foreground
105 color, while bits that are 0 are painted with the backgound
106 color. If invert is 1, foreground and background are
107 switched. To get a partly transparent image, set the first
108 index of the foreground or background color to -1, i.e.
109 f_rgb[0]=-1 or b_rgb[0]=1. See the Adobe Systems PostScript
110 Reference Manual for more details.
111 void ps_circle (xcenter, ycenter, diameter, rgb, outline)
113 double xcenter, ycenter, diameter;
114 int rgb[3], outline;
115 Plots a circle and fills it with the specified color. If
116 outline == 1, the outline will be drawn using current pen-
117 width and -pattern.
118 void ps_clipoff ()
120 Resets the clip path to what it was before the last call to
121 ps_clipon.
122 void ps_clipon (xarray, yarray, npoints, rgb, flag)
124 double xarray[], yarray[];
125 long npoints;
126 int rgb[3], flag;
127 Sets up a user-definable clip path. Plotting outside this
128 polygon will be clipped until ps_clipoff is called. If red
129 >= 0 the inside of the path is filled with the specified
130 color. flag is used to create complex clip paths consisting
131 of several disconnected regions, and takes on values 0-3.
132 flag = 1 means this is the first path in a multi-segment clip
133 path. flag = 2 means this is the last segment. Thus, for a
134 single path, flag = 3.
135 void ps_colorimage (xpos, ypos, xlength, ylength, buffer, nx,
137 ny, depth)
138 double xpos, ypos, xlength, ylength;
139 unsigned char buffer[];
140 int nx, ny, depth;
141 Plots a 1-, 2-, 4-, 8-, or 24-bit deep image. This functions
142 sets up a call to the PostScript colorimage or image opera‐
143 tors. xpos, ypos, xlength, ylength specify the position of
144 lower left corner and size (in inches) of image. The pixel
145 values are stored in buffer, an unsigned character array in
146 scanline orientation with gray shade or r/g/b values (0 -
147 255) where 0 is black, 255 is white. buffer[0] is upper left
148 corner. depth is number of bits per pixel (24, 8, 4, 2, or
149 1). nx,ny refers to the number of pixels in image. The
150 rowlength of buffer must be an integral number of 8/depth.
151 E.g. if depth = 4, then buffer[j]/16 gives shade for
152 pixel[2j-1] and buffer[j]%16 (mod 16) gives shade for
153 pixel[2j]. When -depth is passed instead then "hardware"
154 interpolation of the image is requested. If -nx is passed
155 with 8- or 24-bit images then the first one or three bytes of
156 buffer holds the gray or r/g/b color for pixels that are to
157 be masked out using the PostScript Level 3 Color Mask method.
158 See the Adobe Systems PostScript Reference Manual for more
159 details.
160 void ps_colortiles (x0, y0, xlength, ylength, buffer, nx, ny)
162 double x0, y0, xlength, ylength;
163 int nx, ny;
164 unsigned char buffer[];
165 Plots a true color image based on individual color tiles. x0,
166 y0 is the location of the lower left corner of the image in
167 inches. xlength, ylength is the image size in inches. buf‐
168 fer contains rgb triplets stored as rgbrgbrgb... nx, ny is
169 the image size in pixels.
170 void ps_command (text)
172 char *text;
173 Writes a raw PostScript command to the PostScript output
174 file, e.g. "1 setlinejoin".
175 void ps_comment (text)
177 char *text;
178 Writes a comment (text) to the PostScript output file, e.g.
179 "Start of graph 2".
180 void ps_cross (xcenter, ycenter, diameter)
182 double xcenter, ycenter, diameter;
183 Plots a cross (x) at the specified point using current pen-
184 width and -pattern that fits inside a circle of given diame‐
185 ter. No fill possible.
186 void ps_diamond (xcenter, ycenter, diameter, rgb, outline)
188 double xcenter, ycenter, diameter;
189 int rgb[3], outline;
190 Plots a diamond and fills it with the specified color. If
191 outline == 1, the outline will be drawn using current pen-
192 width and -pattern. The symbol will fit inside a circle of
193 given diameter.
194 void ps_ellipse (xcenter, ycenter, angle, major, minor, rgb,
196 outline)
197 double xcenter, ycenter, angle, major, minor;
198 int rgb[3], outline;
199 Plots a ellipse with its major axis rotated by angle degrees
200 and fills it with the specified color. If outline == 1, the
201 outline will be drawn using current pen-width and -pattern.
202 void ps_encode_font (font_no)
204 int font_no;
205 Will reencode this font using the current encoding vector if
206 it is not StandardEncoding.
207 void ps_epsimage (xpos, ypos, xlength, ylength, buffer, size,
209 nx, ny, ox, oy)
210 double xpos, ypos, xlength, ylength;
211 unsigned char buffer[];
212 int size, nx, ny, ox, oy;
213 Plots an Encapsulated PostScript (EPS) image. The EPS file is
214 stored in buffer and has size bytes. This functions simply
215 includes the image in the PostScript output stream within an
216 appropriate wrapper. Specify position of lower left corner
217 and size (in inches) of image. nx,ny,ox,oy refers to the
218 width, height and origin (lower left corner) of the Bounding‐
219 Box.
220 void ps_flush ()
222 Flushes the output buffer.
223 void ps_hexagon (xcenter, ycenter, diameter, rgb, outline)
225 double xcenter, ycenter, diameter;
226 int rgb[3], outline;
227 Plots a hexagon and fills it with the specified color. If
228 outline == 1, the outline will be drawn using current pen-
229 width and -pattern. The symbol will fit inside a circle of
230 given diameter.
231 void ps_image (xpos, ypos, xlength, ylength, buffer, nx, ny,
233 bits)
234 double xpos, ypos, xlength, ylength;
235 unsigned char buffer[];
236 int nx, ny, bits;
237 Obsolete, simply passes arguments to ps_colorimage.
238 void ps_imagefill (x, y, n, image, imagefile, invert, dpi, out‐
240 line, f_rgb, b_rgb)
241 double x[], y[], x0, y0;
242 int n, image, invert, dpi, outline, f_rgb[3], b_rgb[3];
243 char imagefile;
244 Similar to ps_polygon, but fills the area with an image pat‐
245 tern rather than a color or grayshade. x and y hold the
246 arrays of n points. 90 predefined patterns are available
247 (See GMT Appendix E). image gives the image number (1-90).
248 If set to 0, imagefile must be the name to the user's image,
249 which must be stored as a Sun 1-, 8-, or 24-bit rasterfile.
250 1-bit images only: (i) The set pixels (1) are colored using
251 the RGB combination in f_rgb, while the unset pixels (0) are
252 painted with b_rgb. Set the f_rgb[0] to -1 to make set pix‐
253 els transparent. Set b_rgb[0] to -1 to make the unset pixels
254 transparent. (ii) If invert is TRUE (1), the set and unset
255 pixels are interchanged before plotting.
256 The unit size of the image is controlled by dpi (in dots-per-
257 inch). If set to zero, the image is plotted at the device
258 resolution. If outline is TRUE, the current penwidth is used
259 to draw the polygon outline.
260 void ps_itriangle (xcenter, ycenter, diameter, rgb, outline)
262 double xcenter, ycenter, diameter;
263 int rgb[3], outline;
264 Plots an inverted and fills it with the specified color. If
265 outline == 1, the outline will be drawn using current pen-
266 width and -pattern. The symbol will fit inside a circle of
267 given diameter.
268 long ps_line (xarray, yarray, npoints, type, close, dummy)
270 double xarray[], yarray[];
271 long npoints;
272 int type, close, dummy;
273 Draw a continuous line from the positions in the x-y arrays.
274 If close == 1, the first and last point will automatically be
275 closed by the PostScript driver. If this is the first seg‐
276 ment in a multi-segment path, set type == 1. To end the seg‐
277 ments and have the line(s) drawn, set type == 2. Thus, for
278 a single segment, type must be 3. The line is drawn using
279 the current penwidth. The dummy is an obsolete parameter no
280 longer used internally.
281 unsigned char *ps_load_image (fp, header)
283 FILE *fp;
284 struct imageinfo *header;
285 Reads the image contents of the EPS file or Sun rasterfile
286 pointed to by the open filepointer fp. The routine can han‐
287 dle Encapsulated PostScript files or 1-, 8-, 24-, or 32-bit
288 rasterfiles in old, standard, run-length encoded, or RGB-
289 style Sun format.
290 void ps_octagon (xcenter, ycenter, diameter, rgb, outline)
292 double xcenter, ycenter, diameter;
293 int rgb[3], outline;
294 Plots a octagon and fills it with the specified color. If
295 outline == 1, the outline will be drawn using current pen-
296 width and -pattern. The symbol will fit inside a circle of
297 given diameter.
298 void ps_patch (xarray, yarray, npoints, rgb, outline)
300 double xarray[], yarray[];
301 long npoints;
302 int rgb[3], outline;
303 Identical to ps_polygon except polygon must be < 20 points
304 long and there will be no attempt to shorten the path by dis‐
305 carding unnecessary intermediate points along straight seg‐
306 ments. Primarily used when painting large number of small
307 polygons and not waste output space. If more than 20 points
308 are given we pass the buck to ps_polygon.
309 void ps_pentagon (xcenter, ycenter, diameter, rgb, outline)
311 double xcenter, ycenter, diameter;
312 int rgb[3], outline;
313 Plots a pentagon and fills it with the specified color. If
314 outline == 1, the outline will be drawn using current pen-
315 width and -pattern. The symbol will fit inside a circle of
316 given diameter.
317 void ps_pie (xcenter, ycenter, radius, azimuth1, azimuth2, rgb,
319 outline)
320 double xcenter, ycenter, radius, azimuth1, azimuth2;
321 int rgb[3], outline;
322 Plots a sector of a circle and paints it with the specified
323 RGB combination. If outline == 1, the outline will be drawn
324 using current pen-width and -pattern.
325 void ps_plot (xabs, yabs, kpen)
327 double xabs, yabs;
328 int kpen;
329 Absolute move (kpen=3) or draw (kpen=2), using current
330 linewidth. Use (kpen=-2) to make sure the line is stroked.
331 void ps_plotend (last_page)
333 int last_page;
334 Terminates the plotting sequence and closes plot file (if
335 other than stdout). If last_page == 1, then a PostScript
336 showpage command is issued, which initiates the printing
337 process on hardcopy devices.
338 void ps_plotinit (plotfile, overlay, mode, xoff, yoff, xscl,
340 yscl, ncopies, dpi, unit, pagesize, rgb, encoding, eps)
341 char *plotfile, *encoding;
342 int overlay, mode, ncopies, dpi, unit;
343 double xoff, yoff, xscl, yscl;
344 int pagesize[2], rgb[3]; struct EPS * eps;
345 Initializes the plotting. If plotfile == NULL (or ""), then
346 output is sent to stdout, else output is sent to plotfile.
347 overlay should be 1 only if you plan to append it to some
348 existing PostScript file. mode contains three flags in the
349 three lowest bits. The lowest bit controls the plot orienta‐
350 tion and can be 0 (Landscape) or 1 (Portrait). The next bit,
351 if set to 1, will re-encode the fonts to include European
352 accented characters using the now-obsolete GMT 3.4 encoding.
353 To use the ISOLatin1 encoding set the 5th bit to 1. The
354 third bit controls the format used to write PostScript
355 images: 0 means binary, 1 means hexadecimal. Most printers
356 needs the latter while some can handle binary which are 50%
357 smaller and therefore execute faster. xoff,yoff are used to
358 move the origin from the default position in the lower left
359 corner. xscl,yscl are used to scale the entire plot (Usually
360 set to 1.0, 1.0). Set ncopies to get more than 1 copy. dpi
361 sets the hardcopy resolution in dots pr units. For optimum
362 plot quality and processing speed, choose dpi to match the
363 intended plotter resolution. Examples are 300 for most
364 laserwriters, 2540 for Linotype-300, and ~85 for Sun screens.
365 When in doubt, use 300. unit can be any of 0 (cm), 1 (inch),
366 or 2 (m), telling the plot system what units are used for
367 distance and sizes. Note that, regardless of choice of unit,
368 dpi is still in dots-pr-inch. pagesize means the physical
369 width and height of the plotting media in points, (typically
370 612 by 792 for Letter or 595 by 842 for A4 laserwriter plot‐
371 ters. The rgb array holds the color of the page (usually
372 white = 255,255,255). The encoding is the name of a charac‐
373 ter encoding scheme to be used, e.g., Standard, ISOLatin1,
374 ISO-8859-2, etc. The EPS structure is defined in the pslib.h
375 include file and contains information that will make up the
376 comments header of a EPS file. Programmers who plan to call
377 pslib routines should read the comments in pslib.h first.
378 Note that the FORTRAN binding does not expect this last argu‐
379 ment.
380 void ps_plotinit_hires (plotfile, overlay, mode, xoff, yoff,
382 xscl, yscl, ncopies, dpi, unit, pagesize, rgb, encoding, eps)
383 char *plotfile, *encoding;
384 int overlay, mode, ncopies, dpi, unit, rgb[3];
385 double xoff, yoff, xscl, yscl;
386 double pagesize[2]; struct EPS * eps;
387 Same as ps_plotinit but expects the page size to be given in
388 double precision points.
389 void ps_plotr (xrel, yrel, kpen)
391 double xrel, yrel;
392 int kpen;
393 Move (kpen = 3) or draw (kpen = 2) relative to current point
394 (see ps_plot). Use (kpen=-2) to make sure the line is
395 stroked.
396 void ps_plus (xcenter, ycenter, diameter)
398 double xcenter, ycenter, diameter;
399 Plots a plus (+) at the specified point using current pen-
400 width and -pattern that fits inside a circle of given diame‐
401 ter. No fill possible.
402 void ps_point (xcenter, ycenter, diameter)
404 double xcenter, ycenter, diameter;
405 Plots a point (dot) using current pen with given diameter.
406 Note the linecap setting must first be set to 1 for this
407 function to work.
408 void ps_polygon (xarray, yarray, npoints, rgb, outline)
410 double xarray[], yarray[];
411 long npoints;
412 int rgb[3], outline;
413 Creates a colored polygon from the positions in the x-y
414 arrays. Polygon will automatically be closed by the Post‐
415 Script driver. If outline == 0, no outline is drawn. If
416 outline == 1, the outline is drawn using current penwidth.
417 void ps_rect (x1, y1, x2, y2, rgb, outline)
419 double x1, y1, x2, y2;
420 int rgb[3], outline;
421 Plots a colored rectangle. (x1,y1) and (x2,y2) are any two
422 corners on a diagonal. If outline == 1, the outline will be
423 drawn using current pen-width and -pattern.
424 void ps_rotaterect (x, y, angle, xsize, ysize, rgb, outline)
426 double x, y, angle, xsize, ysize;
427 int rgb[3], outline;
428 Plots a colored rectangle rotated angle degrees from base‐
429 line. (x,y) is the center and (xsize,ysize) are the dimen‐
430 sions. If outline == 1, the outline will be drawn using cur‐
431 rent pen-width and -pattern.
432 void ps_rotatetrans (x, y, angle)
434 double x, y, angle;
435 Rotates the coordinate system by angle degrees, then trans‐
436 lates origin to (x,y).
437 void ps_segment (x0, y0, x1, y1)
439 double x0, y0, x1, y1;
440 Draws a line segment between the two points using current pen
441 attributes.
442 void ps_setdash (pattern, offset)
444 char *pattern;
445 int offset;
446 Changes the current dashpattern. The character string pat‐
447 tern is set to the desired pattern. E.g., "4 2" and offset =
448 1 will plot like:
449 x ---- ---- ----
450 etc, where x is starting point (The x is not plotted). That
451 is, the line is made up of a repeating pattern of a 4 units
452 long line and a 2 unit long gap, starting 1 unit after the x.
453 To reset to solid line, specify pattern = NULL ("") and off‐
454 set = 0. Units are in dpi units.
455 void ps_setfill (rgb, outline)
457 int rgb[3], outline;
458 Sets the current fill color and whether or not outline is
459 needed for symbols.
460 void ps_setfont (fontnr)
462 int fontnr;
463 Changes the current font number to fontnr. The fonts avail‐
464 able are: 0 = Helvetica, 1 = H. Bold, 2 = H. Oblique, 3 = H.
465 Bold-Oblique, 4 = Times, 5 = T. Bold, 6 = T. Italic, 7 = T.
466 Bold Italic, 8 = Courier, 9 = C. Bold, 10 = C Oblique, 11 = C
467 Bold Oblique, 12 = Symbol, 13 = AvantGarde-Book, 14 =
468 A.-BookOblique, 15 = A.-Demi, 16 = A.-DemiOblique, 17 = Book‐
469 man-Demi, 18 = B.-DemiItalic, 19 = B.-Light, 20 = B.-LightI‐
470 talic, 21 = Helvetica-Narrow, 22 = H-N-Bold, 23 = H-N-
471 Oblique, 24 = H-N-BoldOblique, 25 = NewCenturySchlbk-Roman,
472 26 = N.-Italic, 27 = N.-Bold, 28 = N.-BoldItalic, 29 = Pala‐
473 tino-Roman, 30 = P.-Italic, 31 = P.-Bold, 32 = P.-BoldItalic,
474 33 = ZapfChancery-MediumItalic, 34 = ZapfDingbats, 35 = Ryu‐
475 min-Light-EUC-H, 36 = Ryumin-Light-EUC-V, 37 = GothicBBB-
476 Medium-EUC-H, and 38 = GothicBBB-Medium-EUC-V. If fontnr is
477 outside this range, it is set to 0.
478 void ps_setformat (n_decimals)
480 int n_decimals;
481 Sets number of decimals to be used when writing color or gray
482 values. The default setting of 3 gives 1000 choices per red,
483 green, and blue value, which is more than the 255 choices
484 offered by most 24-bit platforms. Choosing a lower value
485 will make the output file smaller at the expense of less
486 color resolution. Still, a value of 2 gives 100 x 100 x 100
487 = 1 million colors, more than most eyes can distinguish. For
488 a setting of 1, you will have 10 nuances per primary color
489 and a total of 1000 unique combinations.
490 void ps_setline (linewidth)
492 int linewidth;
493 Changes the current linewidth in DPI units. 0 gives thinnest
494 line, but the use of 0 is implementation-dependent (Works
495 fine on most laserwriters).
496 void ps_setlinecap (cap)
498 int cap;
499 Changes the current linecap. 0 gives butt cap [Default], 1
500 gives round, and 2 gives square.
501 void ps_setlinejoin (join)
503 int join;
504 Changes the current linejoin. 0 gives mitered [Default], 1
505 gives round, and 2 gives bevel joins.
506 void ps_setmiterlimit (limit)
508 int limit;
509 Changes the current miter limit. 0 gives default miter,
510 other values are the cutoff-, acute- angle when mitering
511 takes place.
512 void ps_setpaint (rgb)
514 int rgb[3];
515 Changes the current RGB setting for pens and text.
516 void ps_square (xcenter, ycenter, diameter, rgb, outline)
518 double xcenter, ycenter, diameter;
519 int rgb[3], outline;
520 Plots a square and fills it with the specified color. If
521 outline == 1, the outline will be drawn using current pen-
522 width and -pattern. The symbol will fit inside a circle of
523 given diameter.
524 void ps_star (xcenter, ycenter, diameter, rgb, outline)
526 double xcenter, ycenter, diameter;
527 int rgb[3], outline;
528 Plots a star and fills it with the specified color. If out‐
529 line == 1, the outline will be drawn using current pen-width
530 and -pattern. The symbol will fit inside a circle of given
531 diameter.
532 void ps_text (x, y, pointsize, text, angle, justify, form)
534 double x, y, pointsize, angle;
535 char *text;
536 int justify, form;
537 The text is plotted starting at (x,y), and will make an angle
538 with the horizontal. The point (x,y) maps onto different
539 points of the textstring by giving various values for jus‐
540 tify. It is used as follows:
541 9------------10----------- 11
543 | |
544 5 6 7
545 | |
546 1------------ 2------------ 3
547 The box represents the textstring. E.g., to plot a
548 textstring with its center of gravity at (x,y), you must use
549 justify == 6. If justify is negative, then all leading and
550 trailing blanks are stripped before plotting. Certain char‐
551 acter sequences (flags) have special meaning to ps_text. @~
552 toggles between current font and the Mathematical Symbols
553 font. @%no% sets font to no; @%% resets to starting font.
554 @- turns subscript on/off, @+ turns superscript on/off, @#
555 turns small caps on/off, and @\ will make a composite charac‐
556 ter of the following two character. @;r/g/b; changes the
557 font color (@;; resets it), @:size: changes the font size
558 (@:: resets it), and @_ toggles underline on/off. Give font‐
559 size in points (72 points = 1 inch). Normally, the text is
560 typed using solid characters. To draw outline characters,
561 set form == 1. If pointsize is negative it means that the
562 current point has already been set before ps_text was called
563 and that (x,y) should be ignored.
564 void ps_textbox (x, y, pointsize, text, angle, justify, outline,
566 dx, dy, rgb)
567 double x, y, angle, pointsize, dx, dy;
568 char *text;
569 int justify, outline, rgb[3];
570 This function is used in conjugation with ps_text when a box
571 surrounding the text string is desired. Taking most of the
572 arguments of ps_text, the user must also specify the color of
573 the resulting rectangle, and whether its outline should be
574 drawn. More room between text and rectangle can be obtained
575 by setting dx and dy accordingly.
576 void ps_transrotate (x, y, angle)
578 double x, y, angle;
579 Translates the origin to (x,y), then rotates the coordinate
580 system by angle degrees.
581 void ps_triangle (xcenter, ycenter, diameter, rgb, outline)
583 double xcenter, ycenter, diameter;
584 int rgb[3], outline;
585 Plots a triangle and paints it with the specified RGB combi‐
586 nation. If outline == 1, the outline will be drawn using
587 current pen-width and -pattern. The symbol will fit inside a
588 circle of given diameter.
589 void ps_vector (xtail, ytail, xtip, ytip, tailwidth, headlength,
591 headwidth, headshape, rgb, outline)
592 double xtail, ytail, xtip, ytip, tailwidth, headlength, head‐
593 width, headshape;
594 int rgb[3], outline;
595 Draws a vector of size and appearance as specified by the
596 various parameters. headshape can take on values from 0-1
597 and specifies how far the intersection point between the base
598 of a straight vector head and the vector line is moved toward
599 the tip. 0 gives a triangular head, 1.0 gives an arrow
600 shaped head. If outline == 1, the outline will be drawn using
601 current penwidth. Add 8 to outline for a double-headed vec‐
602 tor.
603 void ps_words (x, y, text, n_words, line_space, par_width,
605 par_just, font, font_size, angle, rgb, justify, draw_box, x_off,
606 y_off, x_gap, y_gap, boxpen_width, boxpen_texture, boxpen_off‐
607 set, boxpen_rgb, vecpen_width, vecpen_texture, vecpen_offset,
608 vecpen_rgb, boxfill_rgb)
609 double x, y, line_space, par_width, angle, x_off, y_off, x_gap,
610 y_gap;
611 long n_words;
612 int font, font_size, justify, draw_box, boxpen_width, box‐
613 pen_offset;
614 int boxpen_rgb[3], vecpen_width, vecpen_offset, vecpen_rgb[3],
615 boxfill_rgb[3];
616 char **text, *boxpen_texture, *vecpen_texture;
617 Typesets paragraphs of text. text is an array of the words
618 to typeset, using the given line-spacing and paragraph width.
619 The whole text block is positioned at x, y which is the
620 anchor point on the box as indicated by justify (see
621 ps_text). The whole block is then shifted by x_off, y_off.
622 Inside the box, text is justified left, centered, right, or
623 justified as governed by par_just (lcrj). draw_box contains
624 4 bit flags pertaining to the surrounding outline box. If
625 on, the first (lowest) bit draws the box outline. The second
626 bit fills the box interior. The third bit makes the outline
627 box have rounded corners (unless x_gap, y_gap, which speci‐
628 fies the padding between the text and the box, are zero),
629 while the forth bit draws a line from the original x, y point
630 to the shifted position. The escape sequences described for
631 ps_text applies as well.
632
634 Paul Wessel, School of Ocean and Earth Science and Technology, 1680
635 East-West Road, Honolulu, Hawaii 96822, (808) 956-4778, Internet
636 address: pwessel@hawaii.edu.
637
639 Caveat Emptor: The author is not responsible for any disasters, sui‐
640 cide attempts, or ulcers caused by correct or incorrect use of pslib.
641 If you find bugs, please report them to the author by electronic mail.
642 Be sure to provide enough detail so that I can recreate the problem.
643
645 Adobe Systems Inc., 1990, PostScript language reference manual, 2nd
646 edition, Addison-Wesley, (ISBN 0-201-18127-4).
647GMT 4.5.6 10 Mar 2011 PSLIB(3)