Line fill C reference
These static helpers belong to rbcGrLine.c. They are not cross-module APIs. See Area fills and error bands for geometry,
ownership and renderer fallback rules.
- group Line fill internals
Private area and uncertainty-band geometry and screen drawing services.
Source data is borrowed; mapped polygons belong to the line element.
Functions
-
static void MapFillArea(Graph *graphPtr, Line *linePtr, MapInfo *mapPtr)
Build one clipped polygon from the mapped center line.
Discontinuous input is not filled. Baseline closure adds two screen vertices, origin closure adds mapped (0,0), and chord closure adds none. On success transfers the clipped array to fillPts/nFillPts. Insufficient points, invalid origin, size overflow, allocation failure or an empty clip leave those fields unchanged. Temporary unclipped storage is always freed. This routine does not free a previous fill: ResetLine must run first.
- Parameters:
graphPtr – Borrowed graph in the element’s mapping viewport.
linePtr – Borrowed line with old fill storage already cleared.
mapPtr – Borrowed smoothed/reduced screen points, never modified here.
-
static void AppendErrorBandPolygon(Graph *graphPtr, Point2D *upper, Point2D *lower, Tcl_Size count, LineBandPolygon ***tailPtr)
Append a clipped uncertainty polygon to an owned list.
Copies upper forward and lower backward, clips the resulting polygon, and appends an owned node and point array. Updates the insertion link only on success. Fewer than two samples, size overflow, allocation failure or fewer than three clipped vertices leave the list unchanged. Neither input array is retained or modified.
- Parameters:
graphPtr – Borrowed graph providing current plot extents.
upper – Borrowed upper boundary in source traversal order.
lower – Borrowed lower boundary in source traversal order.
count – Number of samples present in both arrays.
tailPtr – In/out pointer to the list’s next insertion link.
-
static void MapErrorBand(Graph *graphPtr, Line *linePtr)
Map source error bounds into independently clipped run polygons.
Uses original paired samples and the selected X or Y error inputs, not reduced center-line points. Symmetric errors take precedence over paired low/high bounds. Invalid values, log-domain violations and trace-direction breaks terminate runs. Step mode inserts X-first boundary corners. Renderer point limits split long runs at shared samples. Temporary boundary arrays are freed; successful polygons remain owned by errorBand.polygons. Disabled/unpainted bands, short input and workspace failure produce no list. Individual polygon failures omit that piece rather than rolling back earlier pieces. Configuration must already have restricted bands to Cartesian axes and linear or step smoothing. No Tcl callbacks are invoked.
- Parameters:
graphPtr – Borrowed graph in the element’s mapping viewport.
linePtr – Borrowed line whose old band list has been cleared.
-
static void DrawLineFill(Graph *graphPtr, Drawable drawable, const Point2D *points, Tcl_Size count, XColor *foreground, XColor *background, GC gc, Rbc_Tile tile, Pixmap stipple, double opacity)
Draw borrowed fill geometry with Cairo-first/native fallback policy.
A tile without a pixmap suppresses drawing rather than exposing the pattern beneath it. A successful Cairo fill ends dispatch; otherwise a native fill context is begun and ended here. Input geometry and resources remain owned by the element. Tile drawing uses the tile’s own image transparency.
- Parameters:
graphPtr – Borrowed graph with the desired renderer and active clip.
drawable – Target window or pixmap.
points – Borrowed clipped polygon, or NULL to skip drawing.
count – Number of polygon vertices.
foreground – Borrowed foreground color; Cairo can recover it from gc.
background – Borrowed optional stipple background color.
gc – Borrowed native fill GC.
tile – Borrowed optional tile, which takes precedence over stipple.
stipple – Bitmap, PATTERN_SOLID sentinel, or None.
opacity – Validated pattern opacity; native fallback does not blend it.
-
static void MapFillArea(Graph *graphPtr, Line *linePtr, MapInfo *mapPtr)
Configuration and resource transactions
These helpers cover fill resources and the adjacent scalar/symbol parsers used by line configuration. The scope is documentation-only and avoids collisions with file-local names in other modules.
- group Line scalar and fill option transactions
Parsing, temporary ownership, resource transfer and tile invalidation.
Functions
-
static LineScalarOption GetLineScalarOption(Element *elemPtr, Tcl_Obj *objPtr)
Identify a manually parsed scalar option by its canonical Tk name.
Recognizes maxsymbols, smooth and trace; returns NONE for other options or unresolved names. The enclosing Tk option pass has already validated names and abbreviations. Does not parse the option value or change live fields.
- Parameters:
elemPtr – [in] Borrowed element supplying the option table for canonical-name resolution.
objPtr – [in] Borrowed option-name object, already validated by the enclosing Tk option pass.
-
static LineAreaOption GetLineAreaOption(Element *elemPtr, Tcl_Obj *objPtr, int band)
Identify pattern or tile options for an area or error-band transaction.
band selects errorbandpattern/errorbandtile instead of areapattern/areatile. Resolves canonical names through the element option table; returns NONE for other options. Tk has already checked ambiguous or unknown option names.
- Parameters:
elemPtr – [in] Borrowed element supplying the option table for canonical-name resolution.
objPtr – [in] Borrowed option-name object, already validated by the enclosing Tk option pass.
band – [in] Nonzero selects error-band resources; zero selects ordinary area-fill resources.
-
static int GetPatternFromString(Tcl_Interp *interp, Tk_Window tkwin, const char *string, Pixmap *stipplePtr)
Acquire a fill pattern without modifying live element resources.
NULL or empty text yields None; exact solid yields PATTERN_SOLID. Other text is a Tk bitmap name and acquires a bitmap reference. Assigns stipplePtr only on success. Returns TCL_ERROR with the bitmap diagnostic on lookup failure. Only a real bitmap result requires Tk_FreeBitmap; sentinels do not.
- Parameters:
interp – [inout] Borrowed interpreter for lookup and diagnostics; see Interpreter arguments.
tkwin – [in] Borrowed live Tk window supplying the display and resource lookup context.
string – [in] Borrowed NUL-terminated bitmap name or exact solid; NULL or empty selects None.
stipplePtr – [out] Required pattern output, assigned only on TCL_OK; real bitmap ownership transfers to the caller.
-
static int GetPatternFromObj(Tcl_Interp *interp, Tk_Window tkwin, Tcl_Obj *objPtr, Pixmap *stipplePtr)
Parse a borrowed Tcl pattern object through GetPatternFromString.
NULL is treated as empty. Does not retain the object; successful bitmap ownership belongs to the caller and must be released or transferred.
- Parameters:
interp – [inout] Borrowed interpreter for lookup and diagnostics; see Interpreter arguments.
tkwin – [in] Borrowed live Tk window supplying the display and resource lookup context.
objPtr – [in] Borrowed pattern specification, or NULL for None; no object reference is acquired.
stipplePtr – [out] Required pattern output, assigned only on TCL_OK; real bitmap ownership transfers to the caller.
-
static void FreeLinePattern(Display *display, Pixmap stipple)
Release an owned bitmap pattern, excluding None and PATTERN_SOLID.
Does not modify the caller’s field. Requires the bitmap’s display context; callers must clear or replace ownership to avoid a second release.
- Parameters:
display – [in] Borrowed display on which the bitmap references were acquired; must remain live through release.
stipple – [in] Owned bitmap reference to release, or None/PATTERN_SOLID for no action.
-
static int StageLineAreaPattern(Graph *graphPtr, Tcl_Obj *objPtr, LineAreaTransaction *transactionPtr)
Acquire a replacement stipple before releasing an earlier candidate.
Failure retains prior staged state. Success stores the pattern or sentinel and marks the pattern bit. The transaction owns real bitmap references until commit or FreeLineAreaTransaction; live line resources are unchanged.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the live window, display and interpreter for resource operations.
objPtr – [in] Borrowed pattern specification; NULL or empty stages a cleared resource.
transactionPtr – [inout] Initialized transaction owning any earlier candidates; successful staging replaces only the selected candidate, preserving live line state.
-
static int StageLineAreaTile(Graph *graphPtr, Tcl_Obj *objPtr, LineAreaTransaction *transactionPtr)
Acquire a replacement tile client in temporary transaction storage.
NULL or empty input stages a cleared tile. Nonempty input resolves an RBC tile before releasing any previous staged client. Failure leaves that earlier candidate intact. Does not install the line notification callback yet.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the live window, display and interpreter for resource operations.
objPtr – [in] Borrowed tile image specification; NULL or empty stages a cleared resource.
transactionPtr – [inout] Initialized transaction owning any earlier candidates; successful staging replaces only the selected candidate, preserving live line state.
-
static GC CreateLineFillGC(Graph *graphPtr, XColor *foreground, XColor *background, Pixmap stipple)
Acquire a Tk GC for effective fill colors and a pattern.
Colors and stipple are borrowed. Non-NULL colors supply foreground/background pixels; a real bitmap selects FillStippled without a background and FillOpaqueStippled with one. None and PATTERN_SOLID do not install stippling. Returns a Tk-managed GC reference for later Tk_FreeGC; this helper does not decide whether geometry should be filled or implement opacity or tile drawing.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the live window, display and interpreter for resource operations.
foreground – [in] Borrowed resolved Tk foreground color, or NULL to omit the GC foreground field; not COLOR_DEFAULT.
background – [in] Borrowed resolved Tk background color, or NULL for transparent stippling; not COLOR_DEFAULT.
stipple – [in] Borrowed bitmap on the graph display, or None/PATTERN_SOLID for an unstippled GC.
-
static void FreeLineAreaTransaction(Graph *graphPtr, LineAreaTransaction *transactionPtr)
Release all remaining owned area candidates and zero the transaction.
Releases a staged real pattern, any tile client and any candidate GC. Does not free the live line resources or Tk-managed color options. Safe after commit because moved ownership is cleared. Requires the owning display.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the live display for candidate bitmap and GC release.
transactionPtr – [inout] Initialized, possibly empty or committed transaction; remaining owned candidates are released and the record is zeroed.
-
static int PrepareLineAreaTransaction(Graph *graphPtr, Element *elemPtr, Line *linePtr, LineAreaTransaction *transactionPtr, int band)
Prepare pattern, tile and replacement GC for area or band configuration.
Initializes fresh transaction storage. Initial defaults are parsed only for options not explicitly supplied. Every explicit occurrence is processed in caller order; an invalid earlier value cannot be hidden by a later one. Builds a GC using the staged or retained stipple and colors already installed by Tk_SetOptions. Failure frees staged resources and leaves live derived resources unchanged; the caller remains responsible for Tk option rollback.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the live window, display and interpreter for resource operations.
elemPtr – [in] Borrowed core of linePtr supplying validated ordered option/value pairs and initial-configuration state.
linePtr – [in] Borrowed line corresponding to elemPtr, with candidate Tk option values installed and current derived resources still retained.
transactionPtr – [out] Fresh transaction storage with no owned candidates; initialized here. Commit only after TCL_OK; failure state is described above.
band – [in] Nonzero selects error-band resources; zero selects ordinary area-fill resources.
-
static void CommitLineAreaTransaction(Graph *graphPtr, Line *linePtr, LineAreaTransaction *transactionPtr, int band)
Transfer prepared area or band resources to their live line fields.
Replaces only staged pattern/tile fields and transfers the candidate GC when present, releasing displaced resources. Installs TileChangedProc on a new tile or ensures it is installed on the retained tile. Clears moved candidates and stagedMask for cleanup. No parsing, geometry mapping or redraw is performed.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the live display for displaced bitmap and GC release.
linePtr – [inout] Live destination line; prepared candidate fields replace the corresponding committed fields, releasing displaced resources.
transactionPtr – [inout] Successfully prepared transaction; moved ownership or staged bits are cleared for subsequent cleanup.
band – [in] Nonzero selects error-band resources; zero selects ordinary area-fill resources.
-
static void FreeParsedSymbol(Display *display, ParsedSymbol *symbolPtr)
Release bitmap and mask references owned by a parsed symbol.
Clears each released handle to None; repeated cleanup is safe. Leaves the symbol type untouched. The caller supplies the bitmap display context.
- Parameters:
display – [in] Borrowed display on which the bitmap references were acquired; must remain live through release.
symbolPtr – [inout] Initialized symbol holding owned bitmap/mask references or None; handles are cleared but type is retained.
-
static int GetSymbolFromObj(Tcl_Interp *interp, Tk_Window tkwin, Tcl_Obj *objPtr, ParsedSymbol *symbolPtr)
Parse a geometric symbol name or acquire a bitmap and optional mask.
Initializes fresh output storage to SYMBOL_NONE with empty handles; do not pass an already owning result. Empty input disables symbols. Built-in names use legacy prefix rules, with two-character minima for c/s names. Otherwise accepts a one- or two-item bitmap list. A missing mask releases the already acquired bitmap before returning TCL_ERROR. Success transfers owned bitmap/mask references to the caller; mask dimensions are not validated here.
- Parameters:
interp – [inout] Borrowed interpreter for lookup and diagnostics; see Interpreter arguments.
tkwin – [in] Borrowed live Tk window supplying the display and resource lookup context.
objPtr – [in] Required borrowed symbol specification; empty disables symbols, otherwise a built-in name or bitmap/mask list.
symbolPtr – [out] Fresh nonowning output record, initialized here; successful bitmap references must be transferred or freed.
-
static int GetSmoothFromString(Tcl_Interp *interp, const char *string, Smoothing *valuePtr)
Parse an exact entry in the smoothing table without modifying the line.
Accepts linear, step, natural, cubic, quadratic and catrom; cubic aliases natural. No prefix matching is performed. Writes valuePtr only on success. Failure returns TCL_ERROR with a diagnostic listing all accepted names.
- Parameters:
interp – [inout] Borrowed interpreter for lookup and diagnostics; see Interpreter arguments.
string – [in] Required borrowed NUL-terminated exact smoothing name.
valuePtr – [out] Required smoothing output, assigned only on TCL_OK.
-
static int GetSmoothFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, Smoothing *valuePtr)
Parse the string of a borrowed Tcl object as a smoothing value.
Delegates to GetSmoothFromString without retaining or evaluating the object. Leaves the output unchanged on parse failure.
- Parameters:
interp – [inout] Borrowed interpreter for lookup and diagnostics; see Interpreter arguments.
objPtr – [in] Required borrowed Tcl object whose string is parsed; NULL is not accepted.
valuePtr – [out] Required smoothing output, assigned only on TCL_OK.
-
static int GetPenDirFromString(Tcl_Interp *interp, const char *string, int *penDirPtr)
Parse a nonempty prefix of increasing, decreasing or both.
The leading i/d/b selects the candidate; longer-than-name strings are rejected. Writes penDirPtr only on success, otherwise returns TCL_ERROR with a diagnostic. Does not alter traces or mapped geometry.
- Parameters:
interp – [inout] Borrowed interpreter for lookup and diagnostics; see Interpreter arguments.
string – [in] Required borrowed NUL-terminated trace-direction prefix; empty is invalid.
penDirPtr – [out] Required trace-direction output, assigned only on TCL_OK.
-
static int GetPenDirFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, int *penDirPtr)
Parse a borrowed Tcl object’s string as a trace-direction prefix.
Delegates to GetPenDirFromString without retaining the object or evaluating an expression. Returns the delegated Tcl status.
- Parameters:
interp – [inout] Borrowed interpreter for lookup and diagnostics; see Interpreter arguments.
objPtr – [in] Required borrowed Tcl object whose string is parsed; NULL is not accepted.
penDirPtr – [out] Required trace-direction output, assigned only on TCL_OK.
-
static int StageLineScalarOption(Graph *graphPtr, Tcl_Obj *objPtr, LineScalarOption option, LineScalarTransaction *transactionPtr)
Convert one recognized scalar into candidate storage and mark its bit.
maxsymbols uses the existing nonnegative pixel parser; smooth and trace use their dedicated name parsers. Conversion failure leaves that candidate field and mask unchanged. An invalid option enum is an internal programming error and calls Tcl_Panic. Does not modify the live line or schedule redraw.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the live window, display and interpreter for resource operations.
objPtr – [in] Required borrowed value for the selected scalar; conversion does not retain it.
option – [in] Recognized MAX_SYMBOLS, SMOOTH or TRACE discriminator; NONE is a programming error.
transactionPtr – [inout] Initialized transaction owning any earlier candidates; successful staging replaces only the selected candidate, preserving live line state.
-
static int PrepareLineScalarTransaction(Graph *graphPtr, Element *elemPtr, Line *linePtr, LineScalarTransaction *transactionPtr)
Parse ordered scalar defaults and explicit values into a fresh transaction.
Processes initial defaults only when not explicitly overridden, then each explicit occurrence in caller order. Strip elements have no trace option and their traceObjPtr remains NULL. Failure may leave earlier staged scalar values in the transaction, but owns no resources to release and changes no live field. The caller must not commit a failed transaction.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the live window, display and interpreter for resource operations.
elemPtr – [in] Borrowed core of linePtr supplying validated ordered option/value pairs and initial-configuration state.
linePtr – [in] Borrowed line corresponding to elemPtr, with candidate Tk option values installed and current derived resources still retained.
transactionPtr – [out] Fresh transaction storage with no owned candidates; initialized here. Commit only after TCL_OK; failure state is described above.
-
static void CommitLineScalarTransaction(Line *linePtr, LineScalarTransaction *transactionPtr)
Copy successfully staged scalar values into live line configuration.
Copies maxsymbols to reqMaxSymbols, smoothing to reqSmooth, and trace direction to penDir only when their bits are present. Clears stagedMask afterward. Values are already validated; mapping, redraw and effective smoothing selection belong to later stages, not this commit helper.
- Parameters:
linePtr – [inout] Live destination line; prepared candidate fields replace the corresponding committed fields, releasing displaced resources.
transactionPtr – [inout] Successfully prepared transaction; moved ownership or staged bits are cleared for subsequent cleanup.
-
static void TileChangedProc(ClientData clientData, Rbc_Tile tile)
Schedule line redisplay when a retained area or band tile changes.
clientData is the stable owning Line; tile is unused. If the graph window exists, sets REDRAW_WORLD and REDRAW_BACKING_STORE and queues redraw. Does not filter hidden elements, remap source data or synchronously draw. Resource teardown must detach tile clients before their owner storage is released.
- Parameters:
clientData – [inout] Stable owning Line pointer whose graph remains live; tile-client teardown precedes owner disposal.
tile – [in] Unused notifying tile handle; callback registration already identifies the owner.
-
static LineScalarOption GetLineScalarOption(Element *elemPtr, Tcl_Obj *objPtr)