1Dashpack(3NCARG) NCAR GRAPHICS Dashpack(3NCARG)
2
6 Dashpack - a set of routines allowing you to draw curves using dashed-
7 line patterns that may include gap-portion specifiers, solid-portion
8 specifiers, and label-string specifiers. DASHPACK is intended to
9 replace and unify the old family of NCAR Graphics routines (DASHLINE,
10 DASHCHAR, DASHSMTH, and DASHSUPR), all of which date from the early
11 1970s or before. At the time of its introduction, DASHPACK will do
12 anything that DASHLINE, DASHCHAR, and DASHSMTH will (and a number of
13 things that they won't); it does not yet functionally replace all of
14 DASHSUPR, but it is intended that this will eventually happen. For the
15 moment, the older routines will stay in NCAR Graphics.
16 Structurally, DASHPACK is rather different from the routines that it
18 replaces: Its behavior is controlled by "internal parameters" that are
19 accessed by calling parameter-access routines, rather than by
20 manipulating the contents of labelled common blocks. There is only one
21 version of DASHPACK; rather than load a different version of it in
22 order to, say, turn smoothing on, one just changes the value of the
23 internal parameter that controls whether or not smoothing is done.
24 There is no analog of the old routines DASHDB and DASHDC in DASHPACK;
25 to use a different dash pattern, one just changes the values of the
26 internal parameters that specify what dash pattern to use.
27 As in other NCAR Graphics packages, each of the internal parameters of
29 DASHPACK has a three-character mnemonic name. The internal parameters
30 are described in detail in the man page "dashpack_params".
31 Dashed-Line Patterns
33 A dashed-line pattern (or just "dash pattern") may be specified using
35 either an integer or a character string (see the parameters 'DPL',
36 'DPS', and 'DPT'). However the pattern is specified, it is applied in
37 a repetitive fashion as a curve is drawn. For example, if the dash
38 pattern specifies a solid, a gap, and the label "A", a curve drawn
39 using it will include a solid, a gap, the label "A", a solid, a gap,
40 the label "A", and so on, until the end of the curve is reached. When a
41 new curve is begun, use of the dash pattern starts over: the new curve
42 starts with a solid, a gap, and the label "A".
43 If an integer dash pattern is used, the low-order "n" bits of the
45 integer (where "n" is the absolute value of the user-specified
46 parameter, 'DPS', and is between 1 and 32, inclusive) are interpreted;
47 0's represent gaps and 1's represent solids.
48 In a character-string dash pattern, the character used to represent a
50 gap (by default, an underscore) and the character used to represent a
51 solid (by default, a dollar sign) are determined by the values of other
52 internal parameters ('CRG' and 'CRS'); such characters may be mixed
53 with other strings of characters that are to be used as label strings.
54 There are parameters allowing one to specify how much distance along
55 the curve should be devoted to each gap ('WOG') and solid ('WOS'), what
56 size characters should be used for writing label strings ('WOC'),
57 whether label strings should be written at a fixed angle relative to
58 the plotter frame or in the direction of the curve ('SAF'), and, if
59 they are written in the direction of the curve, whether or not they
60 should be made to "bend" with the curve ('CRB' and 'SCF') and whether
61 or not it is allowed to rotate them by 180 degrees to make them more
62 nearly upright on the plotter frame ('SAF').
63 A label string written along a curve may either be placed in a gap left
65 in the curve or just written on top of it ('LS1', 'LS2', and 'LTL');
66 the latter is most effective when the characters are written in a color
67 different from that of the curve itself.
68 Output of label strings is buffered so that, if the end of the curve
70 occurs prior to the occurrence of the next solid or gap in the dash
71 pattern, the curve itself may be drawn in lieu of an incomplete label,
72 and so that, when labels are being made to "bend" with the curve, the
73 entire label can be inverted, if necessary, so as to have the majority
74 of it right-side up. This buffering is done by default, but may be
75 turned off, if desired ('SBF').
76 All character strings are written using calls to PLOTCHAR routines.
78 There is an internal parameter ('PCF') that says whether to call
79 PLCHHQ, PLCHMQ, or PLCHLQ. By default, PLCHHQ is used.
80 Curve Smoothing
82 Curve smoothing is turned on and off by setting a single internal
84 parameter ('TCS') that also specifies the tension on the cubic splines
85 used to do the smoothing. Another parameter ('SSL') specifies the
86 distance between points used to plot the smoothed curve and another
87 ('EPS') specifies the minimum distance between input points required
88 for them to be considered separate points.
89
91 DPCURV - draws a complete curve with a single call.
92 DPDRAW - called to just draw the curve by connecting a given sequence
94 of points.
95 DPFRST - does a "pen-up" move to the first in a sequence of points
97 defining a curve.
98 DPGETC - called with the name of an internal parameter of type
100 CHARACTER and a character variable in which the value of that parameter
101 is to be returned.
102 DPGETI - called with the name of an internal parameter of type INTEGER
104 or REAL and an integer variable in which the integer equivalent of the
105 value of that parameter is to be returned.
106 DPGETR - called with the name of an internal parameter of type INTEGER
108 or REAL and a real variable in which the real equivalent of the value
109 of that parameter is to be returned.
110 DPLAST - called to say that the latest call to DPVECT was the last one
112 in the sequence, that drawing of the curve should be completed, and
113 that buffers should be flushed.
114 DPLINE - draws the straight line joining two points. (No smoothing
116 takes place, even if smoothing is turned on.)
117 DPSETC - called with the name of an internal parameter of type
119 CHARACTER and a character variable or constant that is to supply the
120 new value of that parameter.
121 DPSETI - called with the name of an internal parameter of type INTEGER
123 or REAL and an integer expression that is to become the new value of
124 that parameter.
125 DPSETR - called with the name of an internal parameter of type INTEGER
127 or REAL and a real expression that is to become the new value of that
128 parameter.
129 DPSMTH - called to create a smooth curve passing through a sequence of
131 points and then to interpolate points along that smoothed curve and
132 pass them on to DPDRAW.
133 DPVECT - does a "pen-down" move to the next in a sequence of points
135 defining a curve.
136
138 #include <ncarg/ncargC.h>
139 c_dpcurv
141 c_dpdraw
142 c_dpfrst
143 c_dpgetc
144 c_dpgeti
145 c_dpgetr
146 c_dplast
147 c_dpline
148 c_dpsetc
149 c_dpseti
150 c_dpsetr
151 c_dpsmth
152 c_dpvect
153
155 To use the Dashpack C or Fortran routines, load the NCAR Graphics
156 libraries ncarg, ncarg_gks, and ncarg_c, preferably in that order.
157
159 When error conditions are detected, the support routine SETER is
160 called. By default, SETER writes a message to the standard error file
161 (as defined by I1MACH(4)) and then terminates execution. It is
162 possible to put SETER into recovery mode and regain control after a
163 recoverable error (which includes all of the possible errors).
164 The possible error messages are listed below. All errors are
166 recoverable in the sense that a user program which has called ENTSR to
167 set recovery mode will get control back after one of these errors
168 occurs.
169 DPCURV - UNCLEARED PRIOR ERROR
171 This error message indicates that, at the time DPCURV was called,
173 there was an unrecovered outstanding error. In this case, DPCURV
174 cannot continue; it forces the error message for the outstanding
175 error to be printed and then substitutes this one for it.
176 DPDRAW - IMPLEMENTATION ERROR - SEE SPECIALIST
178 An internal error has occurred which indicates that DASHPACK has
180 not been correctly installed. See a specialist.
181 DPDRAW - UNCLEARED PRIOR ERROR
183 This error message indicates that, at the time DPDRAW was called,
185 there was an unrecovered outstanding error. In this case, DPDRAW
186 cannot continue; it forces the error message for the outstanding
187 error to be printed and then substitutes this one for it.
188 DPFRST - UNCLEARED PRIOR ERROR
190 This error message indicates that, at the time DPFRST was called,
192 there was an unrecovered outstanding error. In this case, DPFRST
193 cannot continue; it forces the error message for the outstanding
194 error to be printed and then substitutes this one for it.
195 DPGETC - PARAMETER NAME NOT KNOWN - X
197 The first argument in a call to DPGETC is not one of the legal
199 internal parameter names of DASHPACK. "X" is the value of the
200 offending first argument.
201 DPGETC - PARAMETER NAME TOO SHORT - X
203 The given parameter name is only one or two characters long. All
205 DASHPACK parameter names are at least three characters long, so
206 there is something wrong. "X" is the value of the offending first
207 argument.
208 DPGETC - UNCLEARED PRIOR ERROR
210 This error message indicates that, at the time DPGETC was called,
212 there was an unrecovered outstanding error. In this case, DPGETC
213 cannot continue; it forces the error message for the outstanding
214 error to be printed and then substitutes this one for it.
215 DPGETI - UNCLEARED PRIOR ERROR
217 This error message indicates that, at the time DPGETI was called,
219 there was an unrecovered outstanding error. In this case, DPGETI
220 cannot continue; it forces the error message for the outstanding
221 error to be printed and then substitutes this one for it.
222 DPGETR - PARAMETER NAME NOT KNOWN - X
224 The first argument in a call to DPGETR is not one of the legal
226 internal parameter names of DASHPACK. "X" is the value of the
227 offending first argument.
228 DPGETR - PARAMETER NAME TOO SHORT - X
230 The given parameter name is only one or two characters long. All
232 DASHPACK parameter names are at least three characters long, so
233 there is something wrong. "X" is the value of the offending first
234 argument.
235 DPGETR - UNCLEARED PRIOR ERROR
237 This error message indicates that, at the time DPGETR was called,
239 there was an unrecovered outstanding error. In this case, DPGETR
240 cannot continue; it forces the error message for the outstanding
241 error to be printed and then substitutes this one for it.
242 DPLAST - UNCLEARED PRIOR ERROR
244 This error message indicates that, at the time DPLAST was called,
246 there was an unrecovered outstanding error. In this case, DPLAST
247 cannot continue; it forces the error message for the outstanding
248 error to be printed and then substitutes this one for it.
249 DPLINE - UNCLEARED PRIOR ERROR
251 This error message indicates that, at the time DPLINE was called,
253 there was an unrecovered outstanding error. In this case, DPLINE
254 cannot continue; it forces the error message for the outstanding
255 error to be printed and then substitutes this one for it.
256 DPSETC - PARAMETER NAME NOT KNOWN - X
258 The first argument in a call to DPSETC is not one of the legal
260 internal parameter names of DASHPACK. "X" is the value of the
261 offending first argument.
262 DPSETC - PARAMETER NAME TOO SHORT - X
264 The given parameter name is only one or two characters long. All
266 DASHPACK parameter names are at least three characters long, so
267 there is something wrong. "X" is the value of the offending first
268 argument.
269 DPSETC - UNCLEARED PRIOR ERROR
271 This error message indicates that, at the time DPSETC was called,
273 there was an unrecovered outstanding error. In this case, DPSETC
274 cannot continue; it forces the error message for the outstanding
275 error to be printed and then substitutes this one for it.
276 DPSETI - UNCLEARED PRIOR ERROR
278 This error message indicates that, at the time DPSETI was called,
280 there was an unrecovered outstanding error. In this case, DPSETI
281 cannot continue; it forces the error message for the outstanding
282 error to be printed and then substitutes this one for it.
283 DPSETR - PARAMETER NAME NOT KNOWN - X
285 The first argument in a call to DPSETR is not one of the legal
287 internal parameter names of DASHPACK. "X" is the value of the
288 offending first argument.
289 DPSETR - PARAMETER NAME TOO SHORT - X
291 The given parameter name is only one or two characters long. All
293 DASHPACK parameter names are at least three characters long, so
294 there is something wrong. "X" is the value of the offending first
295 argument.
296 DPSETR - UNCLEARED PRIOR ERROR
298 This error message indicates that, at the time DPSETR was called,
300 there was an unrecovered outstanding error. In this case, DPSETR
301 cannot continue; it forces the error message for the outstanding
302 error to be printed and then substitutes this one for it.
303 DPSMTH - UNCLEARED PRIOR ERROR
305 This error message indicates that, at the time DPSMTH was called,
307 there was an unrecovered outstanding error. In this case, DPSMTH
308 cannot continue; it forces the error message for the outstanding
309 error to be printed and then substitutes this one for it.
310 DPVECT - UNCLEARED PRIOR ERROR
312 This error message indicates that, at the time DPVECT was called,
314 there was an unrecovered outstanding error. In this case, DPVECT
315 cannot continue; it forces the error message for the outstanding
316 error to be printed and then substitutes this one for it.
317
320 Online: dashpack_params, dpcurv, dpdraw, dpfrst, dpgetc, dpgeti,
321 dpgetr, dplast, dpline, dpsetc, dpseti, dpsetr, dpsmth, dpvect,
322 ncarg_cbind.
323 Hardcopy: None.
325
327 Copyright (C) 1987-2007
328 University Corporation for Atmospheric Research
329 This documentation is free software; you can redistribute it and/or
331 modify it under the terms of the GNU General Public License as
332 published by the Free Software Foundation; either version 2 of the
333 License, or (at your option) any later version.
334 This software is distributed in the hope that it will be useful, but
336 WITHOUT ANY WARRANTY; without even the implied warranty of
337 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
338 General Public License for more details.
339 You should have received a copy of the GNU General Public License along
341 with this software; if not, write to the Free Software Foundation,
342 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
343UNIX March 1995 Dashpack(3NCARG)