SFSGFA(3NCARG)

📦 version 6.6.2, in epel 9, fedora 43, fedora 44

✨ NAME ✨

SFSGFA — bestie, this one stands for "SOFTFILL - Simulate GFA" 💖 and what it does is fill an area of the plotter frame (defined by a given set of points) in one of various ways. It's literally here to give you a way to use the GKS fill-area routine, if that routine actually works (which it does in the version of GKS that ships with NCAR Graphics 🫶), or to hand you a suitable pattern-fill substitute if it doesn't.

And the flex? Doing all your area fills with SFSGFA means the way they're done can be changed later by modifying the value of a single internal parameter of Softfill, named 'TY'. One knob. That's the whole vibe. 👑

🌸 SYNOPSIS 🌸

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

🦋 C-BINDING SYNOPSIS 🦋

#include <ncarg/ncargC.h>

void c_sfsgfa (float *xra, float *yra, int nra,
float *dst, int nst, int *ind, int nnd, int ici)

💜 DESCRIPTION 💜

okay so here's every single argument, no skips, no skimming, we are thorough in this house 💅

  • XRA — an input/output array of type REAL, dimensioned NRA or greater. It holds the X coordinates of the points that define the area you're filling, in the user coordinate system. Upon return, the contents of XRA will have been converted to the fractional coordinate system. So it goes in as one thing and comes back as another — glow-up behavior fr fr ✨
  • YRA — an input/output array of type REAL, dimensioned NRA or greater. The Y coordinates of those same area-defining points, also in the user coordinate system. Upon return, the contents of YRA will have been converted to the fractional coordinate system. Same deal as XRA. They're a matching set, your honor 🎀
  • NRA — an input expression of type INTEGER, and it's the number of points defining the area to be filled. NRA must be greater than two. Three or more, periodt. Two points is not a polygon, it's a line, and we don't do that here 😭
  • DST — a scratch array of type REAL, dimensioned NST. It's for use when fill lines are generated by means of calls to SFWRLD and/or SFNORM. It's just here to hold stuff, don't overthink it 🫶
  • NST — an input expression of type INTEGER, the length of the array DST. NST must be greater than or equal to NRA + NIM, where NIM is the largest number of intersection points of any fill line with the boundary lines. To be sure DST is large enough, use NIM = NRA; in practice, NIM rarely needs to be that large. For a convex polygon, for example, NIM = 2. So like, yes you can go big to be safe, but you probably don't have to, iykyk 💀
  • IND — a scratch array of type INTEGER, dimensioned NND. It's for use when fill lines are generated by means of calls to SFWRLD and/or SFNORM. Another little helper just doing its job 🧚
  • NND — an input expression of type INTEGER, the length of the array IND. It must be greater than or equal to NRA + 2 * NIM, where NIM is as defined above. Notice that it's got a 2 * in there, don't forget it, bestie ⭐
  • ICI — an input expression of type INTEGER and, nominally, the fill-area color index to be used. But here's the twist 🌀: when the internal parameter 'TY' has a value other than zero, ICI may be used in some other manner. It's giving "main character with a secret identity" energy, and we'll get into all of that below 👇

🌈 C-BINDING DESCRIPTION 🌈

The C-binding argument descriptions are the same as the Fortran argument descriptions. That's it. Same tea, different mug ☕💖

👑 USAGE 👑

SFSGFA fills the area defined by the points (XRA(I),YRA(I)), for I from 1 to NRA. The lines connecting point 1 to point 2, point 2 to point 3, . . ., point NRA-1 to point NRA, and point NRA to point 1 bound the area to be filled. Yes, it wraps all the way around and closes itself. Self-sufficient. Iconic. 💅

The values of the internal parameter 'TY' (for 'TYPE OF FILL') and the argument ICI determine how the fill is done. The function of ICI changes depending on the value of 'TY'. ICI can determine the fill area color index, the polyline color index, or the density of the fill pattern. Three jobs, one argument, she's versatile 😌

  • 'TY' = 0 — This is the default. SFSGFA does color fill by calling GFA. GFA does either hollow, solid, or pattern fill. Hollow fill (only boundaries are drawn) is GFA's default, but you can change the type of fill by calling the GKS subroutine GSFAIS. Notice that one of the first steps in the code for the example "sfex02" is to force solid fill by calling GSFAIS with the argument "1". 👀

A value of ICI greater than or equal to zero specifies the color index of the fill area.

A value of ICI less than zero specifies that the fill area color index is not to be set before calling GFA; the last call to the GKS subroutine GSFACI then determines the fill area color index. So negative ICI = "you handle it, I'm not touching that setting" 🙈

  • 'TY' = 1 — SFSGFA fills the area with parallel lines by calling SFWRLD. 📏

A value of ICI greater than or equal to zero specifies the polyline color index.

A value of ICI less than zero specifies that the polyline color index is not to be set before calling SFWRLD; the last call to the GKS subroutine GSPLCI determines the polyline color index.

Parameters 'AN', 'CH', 'DO', and 'SP' further affect the nature of the fill.

Note: If 'CH' and 'DO' are set to select dot fill or character fill, the values of ICI will not affect the color of the dots or characters. The intended use of 'TY' > 0 is to do color fill using colored lines; no provision is made for the use of colored dots or colored characters. (The current values of the polymarker and text color indices are used to determine the color.) 😭 so real, so unfair, but that's the deal.
  • 'TY' = 2 — SFSGFA calls SFWRLD to fill the area with parallel lines and calls SFNORM to fill the area again with parallel lines perpendicular to the first set. A whole crosshatch moment 🔥

ICI, if zero or greater, specifies the polyline color index.

A negative value of ICI specifies that the polyline color index is not to be set before calling SFWRLD; the last call to the GKS subroutine GSPLCI determines the polyline color index.

Parameters 'AN', 'CH', 'DO', and 'SP' further affect the nature of the fill. See the note above about ICI's function with 'CH' and 'DO'. ⬆️

  • 'TY' = -4, -3, -2, -1 — SFSGFA fills the area with line patterns by calling SFWRLD and/or SFNORM. The absolute value of 'TY' determines the maximum number of fill-line angles used in a pattern. 🌀

ICI determines the density of the lines drawn at each angle.

Angles Used: When 'TY' has one of the following values, fill is done by using lines drawn at the angles shown ('AN' is an internal parameter that specifies an angle in degrees):

  • 'TY' = -1 → 'AN'
  • 'TY' = -2 → 'AN', 'AN'+90
  • 'TY' = -3 → 'AN', 'AN'+60, 'AN'+120
  • 'TY' = -4 → 'AN', 'AN'+45, 'AN'+90, 'AN'+135

Line Density: ICI is used to select the density of the lines in each direction. A zero or negative value of ICI selects a blank pattern. Positive values of ICI select patterns that increase in density as the value of ICI increases. The largest usable value of ICI is approximately 5*ABS('TY'); beyond that, the pattern becomes essentially solid. For example, if 'TY' is -4, 20 is about the largest value of ICI that you can use and still see a pattern. So like, past that it's just a solid slab of ink, no pattern left 💀

For each increase in ICI, fill lines are added at one of the usable angles. The first time lines are added at a given angle, they are spaced 32*'SP' units apart. (The default value of the internal parameter 'SP' is .00125.) After the first time, each time lines are added at a given angle, they are added between the existing lines so that the distance between lines at that angle is halved. An ICI value that is evenly divisible by the absolute value of 'TY' yields a pattern that is evenly dense at all angles. For example, if 'TY' has the value -2, the patterns associated with the first three values of ICI are formed as follows: ICI=1 uses lines at the angle 'AN', spaced 32*'SP' units apart; ICI=2 uses lines at the angles 'AN' and 'AN'+90, both spaced 32*'SP' units apart; ICI=3 uses lines at the angle 'AN', spaced 32*'SP' units apart, and lines at the angle 'AN'+90, spaced 16*'SP' units apart. The math is mathing, bestie, trust 🧮✨

For SFSGFA to fill an uncomplicated polygon (one without holes), XRA and YRA should contain the world coordinates of the polygon's vertices in the order in which they are encountered as the boundary of the polygon is traced. Just go around the outside, in order. Like a little walk 🚶♀️

To leave an unfilled hole in a polygon, do the following:

  1. add the vertices of the hole, in the proper order, to XRA and YRA;
  2. repeat the first vertex of the hole to close it;
  3. repeat the last vertex of the outer polygon boundary to tie the first point of the hole to the last point of the polygon's outer boundary.

To fill what was unfilled and vice versa, do the following:

  1. add the four coordinates of the frame corners;
  2. repeat the coordinates of the first corner of the frame;
  3. repeat the final point of the original polygon.

In effect, this makes what was previously inside, outside, and what was previously outside, inside. INSIDE-OUT, OUTSIDE-IN, a total reversal moment 🔄😌

When a polygon contains holes, there are connecting lines between the outer boundary of the polygon and the boundaries of the holes. When doing software fill (internal parameter 'TY' not equal to 0), these connecting lines cause no trouble; however, when doing solid fill (internal parameter 'TY' = 0), the hardware fill algorithms will frequently display unfortunate edge effects along such lines. Unfortunate. You can minimize these effects by using only horizontal or vertical connecting lines and by ensuring they do not cross any of the original boundary lines. Do that and you'll be fine, do otherwise and... 😬💀

🎀 EXAMPLES 🎀

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

Go look at them, fr fr, they're right there and they're helpful 🫶

⭐ ACCESS ⭐

To use SFSGFA or c_sfsgfa, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c, preferably in that order. In that order! Please and thank you, the linker is sensitive 🙏

💌 MESSAGES 💌

See the softfill man page for a description of all Softfill error messages and/or informational messages. Everything she has to say lives over there 📬

🌸 SEE ALSO 🌸

Online: softfill, softfill_params, sfgetc, sfgeti, sfgetp, sfgetr, sfsetc, sfseti, sfsetp, sfsetr, sfwrld, ncarg_cbind

Hardcopy: NCAR Graphics Fundamentals, UNIX Version

Copyright (C) 1987-2009 University Corporation for Atmospheric Research

The use of this Software is governed by a License Agreement.

and that's the whole page, bestie — every flag, every array, every internal parameter, all of it, no notes left behind 💅 this was the SFSGFA(3NCARG) page from the UNIX manual, dated March 1993, and honestly? she ate. 🎀 mwah 💋

📦 where this page comes from