1SFSGFA(3NCARG)                   NCAR GRAPHICS                  SFSGFA(3NCARG)
2
3
4

NAME

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

SYNOPSIS

16       CALL SFSGFA (XRA, YRA, NRA, DST, NST, IND, NND, ICI)
17

C-BINDING SYNOPSIS

19       #include <ncarg/ncargC.h>
20
21       void c_sfsgfa (float *xra, float *yra, int nra,
22       float *dst, int nst, int *ind, int nnd, int ici)
23

DESCRIPTION

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
31       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
37       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
41       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
45       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
53       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
57       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
61       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

C-BINDING DESCRIPTION

67       The C-binding argument descriptions are the same as the Fortran
68       argument descriptions.
69

USAGE

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
76       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
82       '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
90                   A value of ICI greater than or equal to zero specifies the
91                   color index of the fill area.
92
93                   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
98       'TY' = 1    SFSGFA fills the area with parallel lines by calling
99                   SFWRLD.
100
101                   A value of ICI greater than or equal to zero specifies the
102                   polyline color index.
103
104                   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
109                   Parameters 'AN', 'CH', 'DO', and 'SP' further affect the
110                   nature of the fill.
111
112                   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
120       '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
124                   ICI, if zero or greater, specifies the polyline color
125                   index.
126
127                   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
132                   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
136       '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
141                   ICI determines the density of the lines drawn at each
142                   angle.
143
144                   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
149                   'TY'  Angles Used (in Degrees)
150
151                    -1   'AN'
152                    -2   'AN', 'AN'+90
153                    -3   'AN', 'AN'+60, 'AN'+120
154                    -4   'AN', 'AN'+45, 'AN'+90, 'AN'+135
155
156                   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
166                   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
183       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
188       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
194       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
200       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

EXAMPLES

211       Use the ncargex command to see the following relevant examples: cpex04,
212       cpex05, sfex02, tsoftf fsfsgfa.
213

ACCESS

215       To use SFSGFA or c_sfsgfa, load the NCAR Graphics libraries ncarg,
216       ncarg_gks, and ncarg_c, preferably in that order.
217

MESSAGES

219       See the softfill man page for a description of all Softfill error
220       messages and/or informational messages.
221

SEE ALSO

223       Online: softfill, softfill_params, sfgetc, sfgeti, sfgetp, sfgetr,
224       sfsetc, sfseti, sfsetp, sfsetr, sfwrld, ncarg_cbind
225
226       Hardcopy: NCAR Graphics Fundamentals, UNIX Version
227
229       Copyright (C) 1987-2009
230       University Corporation for Atmospheric Research
231
232       The use of this Software is governed by a License Agreement.
233
234
235
236UNIX                              March 1993                    SFSGFA(3NCARG)
Impressum