Area fills and error bands
Line elements keep ordinary area fills and uncertainty bands as separate geometry. Both are implemented in
rbcGrLine.c and use renderer polygon services, but their input, closure and continuity rules differ. Selected
private contracts are in Line fill C reference.
Resources and configuration
An area and a band each have independent colors, pattern, tile, opacity and GC. A pattern is None for disabled, the
PATTERN_SOLID sentinel for solid, or a retained Tk bitmap. Only actual bitmaps are passed to Tk_FreeBitmap.
Tiles are retained RBC tile clients, not element-owned Tk image commands.
rbcGrLineOptions.PrepareLineAreaTransaction() stages pattern and tile acquisition and builds a candidate GC. It
handles initial defaults/option-database values and checks explicit occurrences in their original order. A failed later
option releases the staged resources without replacing the live ones. Commit transfers resource ownership, installs the
tile-change callback on the stable line record and releases replaced resources. This follows Component configuration and resources,
rather than relying on Tk option rollback to undo derived-resource changes.
Both opacity values must be finite and within zero to one. Enabled error bands require Cartesian axes and linear or step smoothing; configuration rejects other smoothing modes. Ordinary area fills also support polar elements and can follow their parametric smoothing. The shared implementation does not mean that every concrete element exposes every fill option.
rbcGrLineOptions.TileChangedProc() schedules graph/backing-store redisplay while the Tk window
exists. rbcGrLineGeometry.DestroyLine() releases tile clients, real pattern bitmaps and derived GCs. It does not
destroy the application’s source images. See Image storage and tile clients for tile notification and resource lifetime.
Ordinary area geometry
rbcGrLineMapping.MapLine() clears old geometry, maps the source points, applies smoothing and any explicit
geometric reduction, then calls MapFillArea(). Configured area fills exclude the pixel-density decimation path;
explicit -reduce remains separate. See Line decimation and source identity and Spline interpolation and graph smoothing.
The area stores one polygon in fillPts/nFillPts. If the mapped input has a breakBefore array, no area is
produced: joining separate runs into one polygon would bridge gaps. This is a deliberate limitation, not the multi-run
behavior used for bands.
Closure |
Construction |
Minimum mapped points |
|---|---|---|
Baseline |
Add vertical screen edges from the last and first points to a lower screen baseline. |
Two |
Origin |
Add the mapped data origin |
Two |
Chord |
Close directly from last point to first. |
Three |
Baseline closure retains the historical one-pixel positive screen-X offset. Its baseline is the greater of the current plot bottom and the largest mapped screen Y. It is not a data-Y zero baseline, and inversion does not turn it into a data-axis-relative closure. Origin closure has no such offset and is skipped when either axis is logarithmic or the mapped origin is nonfinite. Chord adds no auxiliary vertex.
The mapper allocates temporary unclipped points and a clipping destination, with overflow checks and capacity 3 *
inputCount + 1. Rbc_PolyRectClip() generates the closing edge and clips against the current graph/track
extents. The temporary input is freed; a successful destination transfers to the line. Too few clipped points or
allocation failure leaves no new area. Plot clipping and its allocation contract are described in Geometry, clipping and simplification.
Error-band geometry
MapErrorBand() runs before center-line mapping and reads original source arrays. Symbol thinning, center-line
decimation and geometric reduction cannot remove an independently varying uncertainty bound. A band needs an enabled X/Y
mode, a tile or pattern, and at least two usable samples.
For an X band, boundaries are (high,y) and (low,y); for a Y band they are (x,high) and (x,low). Nonempty
symmetric error input takes precedence over explicit low/high arrays. Processing stops at the shortest required input.
Reversed low/high bounds are swapped, including those produced by negative symmetric errors.
Nonfinite source/bound values, log-domain violations and nonfinite mapped coordinates end the current run. A trace-direction break also ends it, but the valid breaking sample starts the next run. The direction test uses original source X. Each run needs two boundary samples before it can form a polygon.
Linear boundaries connect adjacent samples directly. Step boundaries insert the same X-first, then Y corner convention as the trace; inversion changes which screen coordinate implements that step. Boundaries are not independently spline-smoothed.
AppendErrorBandPolygon() copies the upper boundary forward and the lower boundary backward, then clips the
polygon. Each successful node owns its point array; nodes are linked through errorBand.polygons in traversal order.
Temporary upper/lower workspaces are freed after mapping. Failure to construct one polygon omits that piece; already
appended pieces are retained.
The workspace also respects Rbc_RenderPolygonPointLimit(). A finite native limit reserves worst-case clipping
expansion and closure space. Long runs split at shared boundary samples so neighboring pieces meet. Cairo, export and
the current Windows native backend report no finite point-count bound; native X11 supplies a request-size limit. This
chunking applies to band construction and must not be assumed to describe the ordinary area mapper.
Drawing, export and cleanup
Normal drawing paints the area first, then band polygons, then traces and annotations. These fills are element-level resources, rather than per-point palette styles. Picking remains based on the element’s trace/symbol geometry; the fill polygon does not introduce a separate interior-hit operation.
DrawLineFill() borrows the polygons and resources. A tile takes precedence over a pattern; a tile without a
pixmap suppresses output. With Cairo selected, rbcGrLineOutput.DrawRenderedFill() first attempts a photo tile or
an opacity-aware pattern. The tile path uses image transparency and does not receive the area/band opacity
argument. Failed or unsupported Cairo rendering falls back to a native fill context. Native pattern filling retains its
non-blended behavior. Do not infer identical transparency support merely from the common polygon interface.
Export builds Rbc_RenderFillStyle and uses export fill contexts with the mapped geometry. It preserves
area-before-band ordering and supplies tiles through Rbc_RenderSetFillTile(). PostScript retains its
opaque/tile-background policy; format capabilities remain the renderer’s responsibility. See Rendering architecture and contracts and
Export orchestration and document ownership.
rbcGrLineGeometry.ResetLine() frees every band node and its points, then frees and zeros the ordinary fill. It
runs before mapping can return early, so shortened or empty data cannot leave a stale polygon on screen. Mapping helpers
assume this reset has happened; they are not replacement APIs for an already populated list.
Pattern and tile transaction details
rbcGrLineOptions.GetLineAreaOption() resolves canonical names using the concrete element option table. The same
transaction code handles ordinary area and error-band resources, selected by its band argument. This shares ownership
machinery, not option availability or geometry rules.
Pattern parsing has three results: empty/NULL means None, exact solid means PATTERN_SOLID, and other strings
acquire a Tk bitmap. rbcGrLineOptions.GetPatternFromString() writes its output only after successful lookup.
rbcGrLineOptions.FreeLinePattern() releases only actual bitmap references. Tile parsing similarly treats
empty/NULL as a staged clear; nonempty input acquires a client through Rbc_GetTile().
rbcGrLineOptions.StageLineAreaPattern() and rbcGrLineOptions.StageLineAreaTile() acquire the new
resource before releasing an earlier candidate, preserving that candidate if the replacement fails.
rbcGrLineOptions.PrepareLineAreaTransaction() initializes fresh candidate storage. Initial defaults are
considered only for fields not explicitly supplied; explicit repetitions are processed in caller order. A bad early
pattern or tile still fails even if a later occurrence would replace it. The fill colors are already managed by Tk’s
saved-option transaction and are borrowed by this preparation step.
rbcGrLineOptions.CreateLineFillGC() sets foreground/background pixels only for non-NULL colors. A real
bitmap selects transparent stippling without a background or opaque stippling with one. None and PATTERN_SOLID leave
stippling disabled. The GC’s existence does not itself mean an area will be drawn: geometry and draw dispatch still
determine that. Opacity and tile rendering are not implemented by this GC constructor.
rbcGrLineOptions.CommitLineAreaTransaction() transfers staged resources, installs tile notifications on the
stable line record, and releases the displaced resources. An unchanged retained tile also receives the callback if
needed. Moved candidate fields and the staged mask are cleared so subsequent
rbcGrLineOptions.FreeLineAreaTransaction() cleanup is safe. Cleanup frees only the resources it still owns; it
never destroys the application’s image command or frees the Tk-owned fill colors. A tile change requests redisplay while
the graph window exists, even if the element is hidden. It does not draw synchronously.
Adjacent scalar and symbol parsing
Line scalar configuration separately stages maxsymbols, smooth and trace values.
rbcGrLineOptions.GetLineScalarOption() recognizes canonical option identities after Tk has validated the names.
rbcGrLineOptions.PrepareLineScalarTransaction() follows the same default-versus-explicit ordering as resource
transactions. Failed preparation can retain earlier staged numbers, but owns no resources requiring cleanup; those
numbers must not be committed. rbcGrLineOptions.CommitLineScalarTransaction() copies only marked fields and
clears the mask, leaving mapping and redraw to the enclosing configuration operation.
The parsers deliberately preserve their existing differences:
Value |
Accepted form |
|---|---|
maxsymbols |
The existing nonnegative pixel conversion, rather than a separate count parser. |
smooth |
Exact linear, step, natural, cubic, quadratic or catrom; cubic aliases natural. |
trace |
Nonempty prefixes of increasing, decreasing or both. |
The string parsers rbcGrLineOptions.GetSmoothFromString() and rbcGrLineOptions.GetPenDirFromString()
leave their outputs unchanged on failure; their object adapters borrow required, non-NULL Tcl objects. The smoothing
failure diagnostic lists all accepted names, including the cubic alias and catrom. Matching remains exact; the
diagnostic does not change parsing.
rbcGrLineOptions.GetSymbolFromObj() initializes a fresh ParsedSymbol rather than releasing an old
one. Empty input disables symbols. Geometric names use legacy prefix rules: none, diamond, plus, triangle and arrow
accept one-character prefixes; circle, cross, square, splus and scross require at least two characters. Matching is
case-sensitive. Other input is parsed as a one- or two-item bitmap/mask list. The bitmap is released if mask lookup
fails, and success transfers both acquired references to the result. This parser does not validate bitmap/mask
dimensions. rbcGrLineOptions.FreeParsedSymbol() clears released handles but leaves the type field unchanged.