1SFSGFA(3NCARG) NCAR GRAPHICS SFSGFA(3NCARG)
2
6 SFSGFA - (which stands for "SOFTFILL - Simulate GFA") fills, in one of
7 various ways, an area of the plotter frame defined by a given set of
8 points; it is intended to provide a way to use the GKS fill-area
9 routine, if it works (as is the case in the version of GKS distributed
10 with NCAR Graphics), or a suitable pattern-fill substitute, otherwise.
11 Doing all area fills with SFSGFA has the advantage that the way in
12 which they are done can then be changed by modifying the value of a
13 single internal parameter of Softfill, named 'TY'.
14
16 CALL SFSGFA (XRA, YRA, NRA, DST, NST, IND, NND, ICI)
17
19 #include <ncarg/ncargC.h>
20 void c_sfsgfa (float *xra, float *yra, int nra,
22 float *dst, int nst, int *ind, int nnd, int ici)
23
25 XRA (an input/output array of type REAL, dimensioned NRA or
26 greater) contains the X coordinates of the points defining
27 the area to be filled, in the user coordinate system. Upon
28 return, the contents of XRA will have been converted to the
29 fractional coordinate system.
30 YRA (an input/output array of type REAL, dimensioned NRA or
32 greater) contains the Y coordinates of the points defining
33 the area to be filled, in the user coordinate system. Upon
34 return, the contents of YRA will have been converted to the
35 fractional coordinate system.
36 NRA (an input expression of type INTEGER) is the number of
38 points defining the area to be filled. NRA must be greater
39 than two.
40 DST (a scratch array of type REAL, dimensioned NST) is for use
42 when fill lines are generated by means of calls to SFWRLD
43 and/or SFNORM.
44 NST (an input expression of type INTEGER) is the length of the
46 array DST. NST must be greater than or equal to NRA + NIM,
47 where NIM is the largest number of intersection points of
48 any fill line with the boundary lines. To be sure DST is
49 large enough, use NIM = NRA; in practice, NIM rarely needs
50 to be that large. For a convex polygon, for example, NIM =
51 2.
52 IND (a scratch array of type INTEGER, dimensioned NND) is for
54 use when fill lines are generated by means of calls to
55 SFWRLD and/or SFNORM.
56 NND (an input expression of type INTEGER) is the length of the
58 array IND. It must be greater than or equal to NRA + 2 *
59 NIM, where NIM is as defined above.
60 ICI (an input expression of type INTEGER) is, nominally, the
62 fill-area color index to be used. When the internal
63 parameter 'TY' has a value other than zero, ICI may be used
64 in some other manner.
65
67 The C-binding argument descriptions are the same as the Fortran
68 argument descriptions.
69
71 SFSGFA fills the area defined by the points (XRA(I),YRA(I)), for I from
72 1 to NRA. The lines connecting point 1 to point 2, point 2 to point 3,
73 . . ., point NRA-1 to point NRA, and point NRA to point 1 bound the
74 area to be filled.
75 The values of the internal parameter 'TY' (for 'TYPE OF FILL') and the
77 argument ICI determine how the fill is done. The function of ICI
78 changes depending on the value of 'TY'. ICI can determine the fill
79 area color index, the polyline color index, or the density of the fill
80 pattern.
81 'TY' = 0 This is the default. SFSGFA does color fill by calling GFA.
83 GFA does either hollow, solid, or pattern fill. Hollow fill
84 (only boundaries are drawn) is GFA's default, but you can
85 change the type of fill by calling the GKS subroutine
86 GSFAIS. Notice that one of the first steps in the code for
87 the example "sfex02" is to force solid fill by calling
88 GSFAIS with the argument "1".
89 A value of ICI greater than or equal to zero specifies the
91 color index of the fill area.
92 A value of ICI less than zero specifies that the fill area
94 color index is not to be set before calling GFA; the last
95 call to the GKS subroutine GSFACI then determines the fill
96 area color index.
97 'TY' = 1 SFSGFA fills the area with parallel lines by calling
99 SFWRLD.
100 A value of ICI greater than or equal to zero specifies the
102 polyline color index.
103 A value of ICI less than zero specifies that the polyline
105 color index is not to be set before calling SFWRLD; the
106 last call to the GKS subroutine GSPLCI determines the
107 polyline color index.
108 Parameters 'AN', 'CH', 'DO', and 'SP' further affect the
110 nature of the fill.
111 Note: If 'CH' and 'DO' are set to select dot fill or
113 character fill, the values of ICI will not affect the color
114 of the dots or characters. The intended use of 'TY' > 0 is
115 to do color fill using colored lines; no provision is made
116 for the use of colored dots or colored characters. (The
117 current values of the polymarker and text color indices are
118 used to determine the color.)
119 'TY' = 2 SFSGFA calls SFWRLD to fill the area with parallel lines
121 and calls SFNORM to fill the area again with parallel lines
122 perpendicular to the first set.
123 ICI, if zero or greater, specifies the polyline color
125 index.
126 A negative value of ICI specifies that the polyline color
128 index is not to be set before calling SFWRLD; the last call
129 to the GKS subroutine GSPLCI determines the polyline color
130 index.
131 Parameters 'AN', 'CH', 'DO', and 'SP' further affect the
133 nature of the fill. See the note above about ICI's function
134 with 'CH' and 'DO'.
135 'TY' = -4, -3, -2, -1
137 SFSGFA fills the area with line patterns by calling SFWRLD
138 and/or SFNORM. The absolute value of 'TY' determines the
139 maximum number of fill-line angles used in a pattern.
140 ICI determines the density of the lines drawn at each
142 angle.
143 Angles Used: When 'TY' has one of the following values,
145 fill is done by using lines drawn at the angles shown ('AN'
146 is an internal parameter that specifies an angle in
147 degrees):
148 'TY' Angles Used (in Degrees)
150 -1 'AN'
152 -2 'AN', 'AN'+90
153 -3 'AN', 'AN'+60, 'AN'+120
154 -4 'AN', 'AN'+45, 'AN'+90, 'AN'+135
155 Line Density: ICI is used to select the density of the
157 lines in each direction. A zero or negative value of ICI
158 selects a blank pattern. Positive values of ICI select
159 patterns that increase in density as the value of ICI
160 increases. The largest usable value of ICI is
161 approximately 5*ABS('TY'); beyond that, the pattern becomes
162 essentially solid. For example, if 'TY' is -4, 20 is about
163 the largest value of ICI that you can use and still see a
164 pattern.
165 For each increase in ICI, fill lines are added at one of
167 the usable angles. The first time lines are added at a
168 given angle, they are spaced 32*'SP' units apart. (The
169 default value of the internal parameter 'SP' is .00125.)
170 After the first time, each time lines are added at a given
171 angle, they are added between the existing lines so that
172 the distance between lines at that angle is halved. An ICI
173 value that is evenly divisible by the absolute value of
174 'TY' yields a pattern that is evenly dense at all angles.
175 For example, if 'TY' has the value -2, the patterns
176 associated with the first three values of ICI are formed as
177 follows: ICI=1 uses lines at the angle 'AN', spaced 32*'SP'
178 units apart; ICI=2 uses lines at the angles 'AN' and
179 'AN'+90, both spaced 32*'SP' units apart; ICI=3 uses lines
180 at the angle 'AN', spaced 32*'SP' units apart, and lines at
181 the angle 'AN'+90, spaced 16*'SP' units apart.
182 For SFSGFA to fill an uncomplicated polygon (one without holes), XRA
184 and YRA should contain the world coordinates of the polygon's vertices
185 in the order in which they are encountered as the boundary of the
186 polygon is traced.
187 To leave an unfilled hole in a polygon, do the following: (1) add the
189 vertices of the hole, in the proper order, to XRA and YRA; (2) repeat
190 the first vertex of the hole to close it; (3) repeat the last vertex of
191 the outer polygon boundary to tie the first point of the hole to the
192 last point of the polygon's outer boundary.
193 To fill what was unfilled and vice versa, do the following: (1) add the
195 four coordinates of the frame corners; (2) repeat the coordinates of
196 the first corner of the frame; (3) repeat the final point of the
197 original polygon. In effect, this makes what was previously inside,
198 outside, and what was previously outside, inside.
199 When a polygon contains holes, there are connecting lines between the
201 outer boundary of the polygon and the boundaries of the holes. When
202 doing software fill (internal parameter 'TY' not equal to 0), these
203 connecting lines cause no trouble; however, when doing solid fill
204 (internal parameter 'TY'= 0), the hardware fill algorithms will
205 frequently display unfortunate edge effects along such lines. You can
206 minimize these effects by using only horizontal or vertical connecting
207 lines and by ensuring they do not cross any of the original boundary
208 lines.
209
211 Use the ncargex command to see the following relevant examples: cpex04,
212 cpex05, sfex02, tsoftf fsfsgfa.
213
215 To use SFSGFA or c_sfsgfa, load the NCAR Graphics libraries ncarg,
216 ncarg_gks, and ncarg_c, preferably in that order.
217
219 See the softfill man page for a description of all Softfill error
220 messages and/or informational messages.
221
223 Online: softfill, softfill_params, sfgetc, sfgeti, sfgetp, sfgetr,
224 sfsetc, sfseti, sfsetp, sfsetr, sfwrld, ncarg_cbind
225 Hardcopy: NCAR Graphics Fundamentals, UNIX Version
227
229 Copyright (C) 1987-2007
230 University Corporation for Atmospheric Research
231 This documentation is free software; you can redistribute it and/or
233 modify it under the terms of the GNU General Public License as
234 published by the Free Software Foundation; either version 2 of the
235 License, or (at your option) any later version.
236 This software is distributed in the hope that it will be useful, but
238 WITHOUT ANY WARRANTY; without even the implied warranty of
239 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
240 General Public License for more details.
241 You should have received a copy of the GNU General Public License along
243 with this software; if not, write to the Free Software Foundation,
244 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
245UNIX March 1993 SFSGFA(3NCARG)