Element data C reference
These interfaces are private. See Element data and dispatch for ownership and ordering.
Element ownership, data and picking records
-
typedef struct ElementStruct Element
-
struct ElementStruct
Shared prefix of graph element implementations.
Element is the typedef for this record. The graph owns registered elements; concrete records extend this prefix. Data slots, named-pen references and mapped geometry have distinct cleanup paths.
Public Members
-
char *name
Element identifier used by the graph registry and widget subcommands.
-
Rbc_Uid classUid
Type of element.
-
unsigned int flags
Indicates if the entire element is active, or if coordinates need to be calculated.
-
char **tags
Owned configured binding-tag list; tag keys are resolved during dispatch.
If non-zero, don’t display the element.
-
int plotHidden
If non-zero, don’t plot the element, but keep it in the display list and legend.
-
Tcl_HashEntry *hashPtr
Registry entry referring to this record; NULL after detachment.
-
char *label
Tk option-managed legend label.
-
int labelRelief
Relief of label in legend.
-
Tcl_Obj *trackObjPtr
Tk option-managed Tcl representation for track; released with option state.
-
ElemVector x
X-coordinate data slot.
-
ElemVector y
Y-coordinate data slot.
-
ElemVector w
Palette weight data slot.
-
ElemVector xError
Symmetric X-error magnitude data slot.
-
ElemVector yError
Symmetric Y-error magnitude data slot.
-
ElemVector xHigh
Explicit high X-error endpoint data slot.
-
ElemVector xLow
Explicit low X-error endpoint data slot.
-
ElemVector yHigh
Explicit high Y-error endpoint data slot.
-
ElemVector yLow
Explicit low Y-error endpoint data slot.
-
Tcl_Size *activeIndices
Array of indices (malloc-ed) which indicate which data points are active (drawn with “active” colors).
-
Tcl_Size nActiveIndices
Number of active data points.
Special case: if nActiveIndices < 0 and the active bit is set in “flags”, then all data points are drawn active.
-
ElementProcs *procsPtr
Borrowed immutable concrete-element operation table.
-
const Tk_OptionSpec *optionSpecs
Borrowed immutable option specifications for the concrete component type.
-
Tk_OptionTable optionTable
Tk option table associated with this record; managed by its configuration lifecycle.
-
int optionMask
Change mask from the current option transaction.
-
Tcl_Size optionObjc
Number of objects in the current borrowed configure argument slice.
-
Tcl_Obj *const *optionObjv
Borrowed configure arguments, valid only during the synchronous configuration transaction.
-
int optionsConfigured
Nonzero after the first successful configuration.
-
Tcl_Obj *activePenObjPtr
Tk option-managed Tcl representation for active pen; released with option state.
-
Tcl_Obj *bindTagsObjPtr
Tk option-managed Tcl representation for bind tags; released with option state.
-
Tcl_Obj *dataObjPtr
Tk option-managed Tcl representation for data; released with option state.
-
Tcl_Obj *mapXObjPtr
Tk option-managed Tcl representation for map x; released with option state.
-
Tcl_Obj *mapYObjPtr
Tk option-managed Tcl representation for map y; released with option state.
-
Tcl_Obj *normalPenObjPtr
Tk option-managed Tcl representation for normal pen; released with option state.
-
Tcl_Obj *stateObjPtr
Tk option-managed Tcl representation for state; released with option state.
-
Tcl_Obj *stylesObjPtr
Tk option-managed Tcl representation for styles; released with option state.
-
Tcl_Obj *weightsObjPtr
Tk option-managed Tcl representation for weights; released with option state.
-
Tcl_Obj *xObjPtr
Tk option-managed Tcl representation for x; released with option state.
-
Tcl_Obj *yObjPtr
Tk option-managed Tcl representation for y; released with option state.
-
Tcl_Obj *xErrorObjPtr
Tk option-managed Tcl representation for x error; released with option state.
-
Tcl_Obj *xHighObjPtr
Tk option-managed Tcl representation for x high; released with option state.
-
Tcl_Obj *xLowObjPtr
Tk option-managed Tcl representation for x low; released with option state.
-
Tcl_Obj *yErrorObjPtr
Tk option-managed Tcl representation for y error; released with option state.
-
Tcl_Obj *yHighObjPtr
Tk option-managed Tcl representation for y high; released with option state.
-
Tcl_Obj *yLowObjPtr
Tk option-managed Tcl representation for y low; released with option state.
-
int optionsInitialized
Nonzero once Tk option initialization has completed.
-
int tkResourcesReleased
Nonzero after the guarded Tk-resource release pass.
-
Tcl_Size *xErrorToData
Owned mapping from each X-error segment to its original data-point index.
-
Tcl_Size *yErrorToData
Owned mapping from each Y-error segment to its original data-point index.
-
int errorBarCapWidth
Length of cap on error bars.
-
Pen *normalPenPtr
Selected normal pen; a named pen is retained, an embedded default pen is borrowed.
-
Rbc_Chain *palette
Owned chain of per-weight pen styles, with named-pen references and borrowed geometry slices.
-
int scaleSymbols
If non-zero, the symbols will scale in size as the graph is zoomed in/out.
-
double xRange
Initial X-axis range used for symbol scaling.
-
double yRange
Initial Y-axis range used for symbol scaling.
-
int state
Element display state selector, maintained with derived visibility flags.
-
char *name
-
struct ElemVector
Element data slot backed by a list copy or an observed RBC vector.
List-backed slots own value storage; vector-backed slots retain a client token and borrow current vector storage. Free through Rbc_FreeElemVector rather than freeing valueArr unconditionally.
Public Members
-
Rbc_Vector *vecPtr
Borrowed external RBC vector record when vector-backed, otherwise NULL.
-
double *valueArr
Owned list-value array or borrowed external vector values; ownership follows clientId.
-
Tcl_Size nValues
Number of available scalar values in this slot.
-
Tcl_Size arraySize
Allocated or external storage capacity associated with valueArr.
-
double min
Cached minimum value used for element limits.
-
double max
Cached maximum value used for element limits.
-
Rbc_VectorId clientId
Owned observation token for an external vector, or NULL for list-backed data.
-
int changePending
Nonzero after at least one notification since the last mapping.
-
int changeAll
Nonzero when notifications do not provide an exact source range.
-
Tcl_Size changedFirst
First source index covered by the accumulated change range.
-
Tcl_Size changedLast
Last source index covered by the accumulated change range.
-
Rbc_Vector *vecPtr
-
struct ClosestSearch
Input query and mutable closest-element result.
A search callback improves the current candidate in place. Result element pointers are borrowed and valid only while the graph/components remain live.
Public Members
-
int halo
Maximum accepted distance in display pixels.
-
int mode
Indicates whether to find the closest data point or the closest point on the trace by interpolating the line segments.
Can also be SEARCH_AUTO, indicating to choose how to search.
-
int x
Test-point X in display pixels.
-
int y
Test-point Y in display pixels.
-
int along
Indicates to let search run along a particular axis: x, y, or both.
-
Tcl_Size index
Original source-point index associated with the candidate.
-
double dist
Current candidate distance in display pixels.
-
int halo
-
struct ErrorBarAttributes
Resolved error-bar drawing policy.
The concrete pen owns configured resources; this record does not own element data or mapped segment arrays.
Data slots
-
int Rbc_ParseElemVectorObj(Tcl_Interp *interp, Element *elemPtr, Tcl_Obj *objPtr, ElemVector *candidatePtr)
Stage a real named vector or a list of numeric expressions.
Never pass a populated slot: initialization would discard its resources. Complex vectors are rejected here. Named data borrows storage and owns a client ID; literal data owns an allocated double array. No notification callback is installed and the live element is unchanged. Release an unused successful candidate with Rbc_FreeElemVector.
- Parameters:
interp – Interpreter used for lookup, conversion and errors.
elemPtr – Borrowed element that will own the staged data.
objPtr – Borrowed option value; vector-name lookup precedes list parsing.
candidatePtr – Empty caller-owned slot overwritten by initialization.
- Returns:
TCL_OK with owned candidate resources, or TCL_ERROR on failure.
-
void Rbc_FreeElemVector(ElemVector *vPtr)
Release an element data slot and zero its record.
Releases a named-vector client ID when present; otherwise frees the owned literal array. Does not destroy the source vector or free borrowed storage.
- Parameters:
vPtr – Initialized slot or zeroed candidate owned by the caller.
Common data transactions
-
int Rbc_PrepareElemDataTransaction(Graph *graphPtr, Element *elemPtr, ElemDataTransaction *transactionPtr)
Stage common element data options without replacing live data.
Processes defaults during initial configuration and explicit options in their original argument order. Repeated options are each validated. Commit only after all other fallible component validation succeeds; otherwise free the transaction. The borrowed option argument vector must remain valid.
- Parameters:
graphPtr – Borrowed owning graph and interpreter context.
elemPtr – Element with current configuration arguments and option state.
transactionPtr – Empty caller-owned transaction initialized by this call.
- Returns:
TCL_OK with staged resources, or TCL_ERROR after freeing candidates.
-
Tcl_Size Rbc_ElemDataTransactionPointCount(Element *elemPtr, const ElemDataTransaction *transactionPtr)
Count the ordinary X/Y pairs after a proposed data transaction.
Does not commit data or invoke a type-specific polar point-count callback. Named sources use current vector lengths, including pending resizes; literal slots use stored counts. Does not refresh arrays or deliver notifications.
- Parameters:
elemPtr – Borrowed element supplying unchanged live dimensions.
transactionPtr – Staged transaction, or NULL to use only live data.
- Returns:
Minimum of the effective X and Y lengths.
-
void Rbc_CommitElemDataTransaction(Element *elemPtr, ElemDataTransaction *transactionPtr)
Transfer staged common data into the element’s stable member slots.
Replaced slots are released. Candidate ownership moves to the destination, named-vector callbacks are installed there, and stagedMask is cleared. No fallible validation or redraw scheduling is performed here.
- Parameters:
elemPtr – Live destination element.
transactionPtr – Successfully prepared transaction to consume.
-
void Rbc_FreeElemDataTransaction(ElemDataTransaction *transactionPtr)
Release all remaining staged arrays and vector client IDs.
Zeros its slots and staged mask. Safe after commit, which has transferred ownership out of the candidates. Does not modify the live element.
- Parameters:
transactionPtr – Initialized or zeroed caller-owned transaction.
Type dispatch signatures
Callbacks borrow graph and element records; dispatch does not itself retain components or protect against arbitrary Tcl callback reentry. The concrete operation’s contract supplies any additional restrictions.
-
typedef void ElementDrawProc(Graph *graphPtr, Drawable drawable, Element *elemPtr)
Draw mapped normal or active element geometry to a screen drawable.
- Param graphPtr:
[inout] Borrowed live owning graph; the callback must respect its current lifecycle phase.
- Param drawable:
[in] Borrowed destination drawable in mapped pixel coordinates.
- Param elemPtr:
[inout] Borrowed concrete element; generic lifecycle code owns record reclamation.
-
typedef void ElementExportProc(Graph *graphPtr, Rbc_ExportContext *exportPtr, Element *elemPtr)
Append mapped normal or active element geometry to a document.
- Param graphPtr:
[inout] Borrowed live owning graph; the callback must respect its current lifecycle phase.
- Param exportPtr:
[inout] Borrowed initialized document context; output is appended without transferring ownership.
- Param elemPtr:
[inout] Borrowed concrete element; generic lifecycle code owns record reclamation.
-
typedef void ElementDestroyProc(Graph *graphPtr, Element *elemPtr)
Release concrete element resources before generic record reclamation.
- Param graphPtr:
[inout] Borrowed live owning graph; the callback must respect its current lifecycle phase.
- Param elemPtr:
[inout] Borrowed concrete element; generic lifecycle code owns record reclamation.
-
typedef int ElementConfigProc(Graph *graphPtr, Element *elemPtr)
Validate element option state and prepare concrete resources.
- Param graphPtr:
[inout] Borrowed live owning graph; the callback must respect its current lifecycle phase.
- Param elemPtr:
[inout] Borrowed concrete element; generic lifecycle code owns record reclamation.
- Return:
TCL_OK on success or TCL_ERROR with graph interpreter diagnostics.
-
typedef void ElementMapProc(Graph *graphPtr, Element *elemPtr)
Rebuild mapped element geometry after data or layout changes.
- Param graphPtr:
[inout] Borrowed live owning graph; the callback must respect its current lifecycle phase.
- Param elemPtr:
[inout] Borrowed concrete element; generic lifecycle code owns record reclamation.
-
typedef void ElementExtentsProc(Element *elemPtr, Extents2D *extsPtr)
Compute source-data extents for automatic axis limits.
- Param elemPtr:
[in] Borrowed concrete element; generic lifecycle code owns record reclamation.
- Param extsPtr:
[out] Required caller-owned source-data bounds.
-
typedef void ElementClosestProc(Graph *graphPtr, Element *elemPtr, ClosestSearch *searchPtr)
Improve the caller closest-point candidate using mapped geometry.
- Param graphPtr:
[inout] Borrowed live owning graph; the callback must respect its current lifecycle phase.
- Param elemPtr:
[inout] Borrowed concrete element; generic lifecycle code owns record reclamation.
- Param searchPtr:
[inout] Borrowed query and current candidate; update only according to the concrete closest-search rules.
-
typedef void ElementDrawSymbolProc(Graph *graphPtr, Drawable drawable, Element *elemPtr, int x, int y, int symbolSize, int width, int height)
Draw a concrete element legend sample on the screen.
- Param graphPtr:
[inout] Borrowed live owning graph; the callback must respect its current lifecycle phase.
- Param drawable:
[in] Borrowed destination drawable in mapped pixel coordinates.
- Param elemPtr:
[inout] Borrowed concrete element; generic lifecycle code owns record reclamation.
- Param x:
[in] Mapped sample X coordinate in display pixels.
- Param y:
[in] Mapped sample Y coordinate in display pixels.
- Param symbolSize:
[in] Requested legend symbol size in display pixels.
- Param width:
[in] Available screen target width in pixels.
- Param height:
[in] Available screen target height in pixels.
-
typedef void ElementSymbolExportProc(Graph *graphPtr, Rbc_ExportContext *exportPtr, Element *elemPtr, double x, double y, int symSize)
Append a concrete element legend sample to a document.
- Param graphPtr:
[inout] Borrowed live owning graph; the callback must respect its current lifecycle phase.
- Param exportPtr:
[inout] Borrowed initialized document context; output is appended without transferring ownership.
- Param elemPtr:
[inout] Borrowed concrete element; generic lifecycle code owns record reclamation.
- Param x:
[in] Mapped sample X coordinate in display pixels.
- Param y:
[in] Mapped sample Y coordinate in display pixels.
- Param symSize:
[in] Requested legend symbol size in display pixels.
-
typedef Tcl_Size ElementPointCountProc(Element *elemPtr)
Report the concrete element source-point count.
- Param elemPtr:
[in] Borrowed concrete element; generic lifecycle code owns record reclamation.
- Return:
Number of source points; does not transfer or allocate data storage.
-
typedef int ElementClosestInfoProc(Graph *graphPtr, Element *elemPtr, const ClosestSearch *searchPtr, Tcl_Obj *resultObjPtr)
Append concrete closest-point fields to a private result dictionary.
Do not run Tcl callbacks or publish Tcl variables while reading element state.
- Param graphPtr:
[inout] Borrowed live owning graph; the callback must respect its current lifecycle phase.
- Param elemPtr:
[inout] Borrowed concrete element; generic lifecycle code owns record reclamation.
- Param searchPtr:
[in] Borrowed completed closest-search result; not modified.
- Param resultObjPtr:
[inout] Caller-owned private result dictionary; append owned Tcl values without writing variables or running callbacks.
- Return:
Tcl status; the caller publishes the dictionary only after element reads finish.
-
struct ElementProcs
Immutable operation table for a concrete element type.
Callbacks borrow graph and element pointers; table dispatch does not itself protect against callback deletion. Optional entries must be checked by their caller before use.
Public Members
-
ElementClosestProc *closestProc
Improve a ClosestSearch candidate using this concrete element; the search and element are borrowed.
-
ElementConfigProc *configProc
Validate configured values and rebuild concrete resources; returns Tcl status.
-
ElementDestroyProc *destroyProc
Release concrete element resources; generic lifecycle code owns registry and record teardown.
-
ElementDrawProc *drawActiveProc
Draw active element geometry to the borrowed screen drawable.
-
ElementDrawProc *drawNormalProc
Draw normal element geometry to the borrowed screen drawable.
-
ElementDrawSymbolProc *drawSymbolProc
Draw a legend sample using borrowed element/style resources.
-
ElementExtentsProc *extentsProc
Write source-data limits to caller-owned Extents2D storage.
-
ElementExportProc *exportActiveProc
Append active geometry to the borrowed document context.
-
ElementExportProc *exportNormalProc
Append normal geometry to the borrowed document context.
-
ElementSymbolExportProc *exportSymbolProc
Append the element legend sample to the borrowed document context.
-
ElementMapProc *mapProc
Rebuild element-owned screen geometry from current data and axis mapping.
-
ElementPointCountProc *pointCountProc
Return the concrete element source-point count without transferring storage.
-
ElementClosestInfoProc *closestInfoProc
Append concrete closest-point fields to the caller result object; returns Tcl status.
-
ElementClosestProc *closestProc
Configuration transaction internals
These helpers separate candidate preparation from live-field commit and from retained Tcl option representations. See Element data and dispatch for their differing failure and cleanup rules.
- group Element transaction internals
Candidate ownership, option identity and retained representations.
Functions
-
static void CommitElemVector(Element *elemPtr, ElemVector *destPtr, ElemVector *candidatePtr)
Move a parsed data slot into its stable element destination.
- Parameters:
elemPtr – Live owner of the destination field.
destPtr – Initialized live slot to replace; distinct from candidatePtr.
candidatePtr – Successfully parsed slot whose ownership is transferred. Releases the old slot, copies the candidate and zeroes it. Installs the owning element and, for named-vector data, a change callback whose client data points to destPtr rather than temporary storage. Does not destroy the source vector, copy its numeric storage, or schedule redraw independently.
-
static ElemDataOption GetElemDataOption(Element *elemPtr, Tcl_Obj *objPtr)
Identify an element’s common data option after Tk validation.
- Parameters:
elemPtr – Element with concrete optionSpecs.
objPtr – Borrowed original option-name object.
- Returns:
The corresponding ElemDataOption, or NONE for unrelated/unresolved names. Uses Rbc_GetCanonicalOptionName so synonyms and accepted abbreviations resolve through the concrete table. Does not parse values, acquire resources or change state. Exact -x and -y names must retain precedence over longer data names.
-
static ElemAxisOption GetElemAxisOption(Element *elemPtr, Tcl_Obj *objPtr)
Identify an element’s axis mapping option after Tk validation.
- Parameters:
elemPtr – Element with concrete optionSpecs.
objPtr – Borrowed original option-name object.
- Returns:
X or Y axis identity, or NONE for unrelated/unresolved names. Uses Rbc_GetCanonicalOptionName so synonyms and accepted abbreviations resolve through the concrete table. Does not parse values, acquire resources or change state. Exact -x and -y names must retain precedence over longer data names.
-
static int IsElemStateOption(Element *elemPtr, Tcl_Obj *objPtr)
Identify an element’s state option after Tk validation.
- Parameters:
elemPtr – Element with concrete optionSpecs.
objPtr – Borrowed original option-name object.
- Returns:
Nonzero only for the canonical -state option. Uses Rbc_GetCanonicalOptionName so synonyms and accepted abbreviations resolve through the concrete table. Does not parse values, acquire resources or change state. Exact -x and -y names must retain precedence over longer data names.
-
static int IsElemBindTagsOption(Element *elemPtr, Tcl_Obj *objPtr)
Identify an element’s binding tags option after Tk validation.
- Parameters:
elemPtr – Element with concrete optionSpecs.
objPtr – Borrowed original option-name object.
- Returns:
Nonzero only for the canonical -bindtags option. Uses Rbc_GetCanonicalOptionName so synonyms and accepted abbreviations resolve through the concrete table. Does not parse values, acquire resources or change state. Exact -x and -y names must retain precedence over longer data names.
-
static int StageElemTags(Tcl_Interp *interp, Tcl_Obj *objPtr, ElemTagsTransaction *transactionPtr)
Replace a candidate tag list only after its successor parses.
- Parameters:
interp – Interpreter for list syntax diagnostics.
objPtr – Borrowed tag-list object; NULL represents an empty list.
transactionPtr – Initialized transaction owning any earlier candidate.
- Returns:
TCL_OK on staging; TCL_ERROR preserves the earlier candidate. Success frees the old candidate block, transfers the new single-block string list and sets staged even for an empty list. Does not modify live element tags or execute a binding script.
-
void Rbc_FreeElemTagsTransaction(ElemTagsTransaction *transactionPtr)
Release candidate binding tags and reset their transaction.
- Parameters:
transactionPtr – Initialized transaction, possibly empty or already committed. Frees the owned string-list block if present and zeroes the complete record. Does not alter the element or free tags already transferred to it.
-
int Rbc_PrepareElemTagsTransaction(Graph *graphPtr, Element *elemPtr, ElemTagsTransaction *transactionPtr)
Validate every relevant binding-tag occurrence before element commit.
- Parameters:
graphPtr – Live owning graph and interpreter.
elemPtr – Element with a validated, even optionObjv/optionObjc sequence.
transactionPtr – [out] Fresh transaction; any earlier owned candidate must already have been released before this function zeroes the record.
- Returns:
TCL_OK on preparation; TCL_ERROR after freeing all staged tag storage. On initial configuration, processes the retained default only if not explicitly overridden. Then parses explicit occurrences in caller order, so a later valid value cannot hide an earlier invalid list. Live tags remain unchanged.
-
void Rbc_CommitElemTagsTransaction(Element *elemPtr, ElemTagsTransaction *transactionPtr)
Transfer a prepared tag-list block into the live element.
- Parameters:
elemPtr – Live destination element owning its previous tags.
transactionPtr – Successfully prepared tags transaction. Does nothing unless staged. Otherwise moves tags (including NULL), clears the candidate and flag, then frees the old live block. No parsing or binding script execution occurs; subsequent transaction cleanup is safe.
-
int Rbc_PrepareElemStateTransaction(Graph *graphPtr, Element *elemPtr, ElemStateTransaction *transactionPtr)
Validate state values in their original configuration order.
- Parameters:
graphPtr – Live graph supplying the error interpreter.
elemPtr – Element with an even validated option sequence.
transactionPtr – [out] Transaction reset before preparation.
- Returns:
TCL_OK when all relevant values pass; TCL_ERROR on the first bad state. Uses the initial retained state only when not explicitly overridden, then checks every explicit occurrence. Does not change live state. Unlike owning resource transactions, failure may leave an earlier scalar candidate marked staged; there is nothing to free, but callers must not commit after TCL_ERROR.
-
void Rbc_CommitElemStateTransaction(Element *elemPtr, ElemStateTransaction *transactionPtr)
Install a successfully prepared scalar state.
- Parameters:
elemPtr – Live destination element.
transactionPtr – Transaction whose preparation returned TCL_OK. Copies state only when staged, then clears staged. Performs no resource cleanup, redraw scheduling or binding repick; the configuration caller handles those.
-
static int StageElemAxis(Graph *graphPtr, Tcl_Obj *objPtr, ElemAxisTransaction *transactionPtr, Axis **candidatePtrPtr, ElemAxisOption option)
Acquire a replacement axis before releasing the staged predecessor.
- Parameters:
graphPtr – Live graph containing the axis registry.
objPtr – Borrowed axis-name object; an empty name is not accepted.
transactionPtr – Initialized axis transaction.
candidatePtrPtr – Address of the candidate matching option.
option – X or Y; any other identity is an internal fatal error.
- Returns:
TCL_OK after staging; TCL_ERROR retains the previous candidate. Rbc_GetAxisFromObj checks in-use orientation (or assigns the class of an unused axis) and acquires a reference without creating an absent axis. Success releases the earlier staged reference, stores the new one and sets its mask bit. Live element axes are unchanged.
-
void Rbc_FreeElemAxisTransaction(Graph *graphPtr, ElemAxisTransaction *transactionPtr)
Release owned candidate axes and clear their transaction.
- Parameters:
graphPtr – Owning graph used for reference release.
transactionPtr – Initialized, partially prepared or committed transaction. Releases each non-NULL candidate independently, then zeroes the record. It does not release references transferred to live element fields by commit.
-
int Rbc_PrepareElemAxisTransaction(Graph *graphPtr, Element *elemPtr, ElemAxisTransaction *transactionPtr)
Resolve ordered element axis options into owned candidates.
- Parameters:
graphPtr – Live owning graph.
elemPtr – Element with even validated configuration arguments.
transactionPtr – [out] Fresh transaction, zeroed before use.
- Returns:
TCL_OK on preparation; TCL_ERROR after releasing all staged references. Initial mapx/mapy defaults are processed only when not explicitly overridden. Every explicit occurrence is then resolved in caller order. Failure does not change live mappings; successful output must be committed or freed.
-
void Rbc_CommitElemAxisTransaction(Graph *graphPtr, Element *elemPtr, ElemAxisTransaction *transactionPtr)
Move prepared axis references to the element and release old mappings.
- Parameters:
graphPtr – Owning graph for release of replaced references.
elemPtr – Live destination element.
transactionPtr – Successfully prepared axis transaction. Only staged X/Y slots are replaced. Clears transferred pointers and then the mask, allowing later transaction cleanup. No lookup or parsing occurs here; reference release may destroy a delete-pending axis whose count reaches zero.
-
void Rbc_FreeElemPenTransaction(Graph *graphPtr, ElemPenTransaction *transactionPtr)
Release uncommitted named pens and zero the transaction.
Safe after commit or a failed prepare. Does not free the transaction record.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live component resources on its Tk thread.
transactionPtr – [inout] Required initialized or already-cleared transaction; releases only candidates still owned by it.
-
int Rbc_PrepareElemPenTransaction(Graph *graphPtr, Element *elemPtr, Rbc_Uid penType, ElemPenTransaction *transactionPtr)
Stage named pens without replacing live element resources.
Processes repeated explicit options in caller order, including invalid earlier values. Returns TCL_OK with candidates, or TCL_ERROR after releasing candidates and zeroing the transaction. On success, commit or free the transaction.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live component resources on its Tk thread.
elemPtr – [in] Borrowed element with the pending even-length option/value array and effective option objects.
penType – [in] Required element pen-class UID used to validate named pens.
transactionPtr – [out] Required fresh transaction storage; initialized here. Do not pass a transaction still owning candidates.
-
void Rbc_CommitElemPenTransaction(Graph *graphPtr, Element *elemPtr, Pen *builtinPenPtr, ElemPenTransaction *transactionPtr)
Commit staged named pens and release replaced resources.
Unstaged options remain unchanged. Complete all other validation before committing; this operation does not provide rollback.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live component resources on its Tk thread.
elemPtr – [inout] Borrowed live element receiving successfully staged resources.
builtinPenPtr – [in] Borrowed embedded pen selected by an empty normal-pen value; never released as a named pen.
transactionPtr – [inout] Successfully prepared transaction; committed candidate ownership transfers to the element and candidate pointers are cleared.
-
static int StageElemDataVector(Tcl_Interp *interp, Element *elemPtr, Tcl_Obj *objPtr, ElemDataTransaction *transactionPtr, ElemVector *candidatePtr, ElemDataOption option)
Parse a data slot before discarding its previous candidate.
- Parameters:
interp – Interpreter used by the data parser.
elemPtr – Live owning element.
objPtr – Borrowed vector-name or expression-list object.
transactionPtr – Initialized common-data transaction.
candidatePtr – Candidate slot corresponding to option.
option – Data identity whose mask bit tracks this slot.
- Returns:
TCL_OK after transferring the parsed candidate, TCL_ERROR with the previous candidate intact. Frees a failed temporary candidate before returning. Named data owns a vector client ID; literal data owns an array. The parser can evaluate Tcl expressions, so caller-owned element and argument lifetimes must survive callbacks. This staging helper adds no preservation boundary.
-
static int StageElemDataPairs(Tcl_Interp *interp, Element *elemPtr, Tcl_Obj *objPtr, ElemDataTransaction *transactionPtr)
Stage a paired data value as an atomic X/Y candidate replacement.
- Parameters:
interp – Interpreter for pair parsing and expression errors.
elemPtr – Live owning element.
objPtr – Borrowed alternating coordinate-expression list.
transactionPtr – Initialized common-data transaction.
- Returns:
TCL_OK after replacing both staged slots; TCL_ERROR preserves both previous candidates. Failure frees both temporary slots. Success frees earlier staged X/Y records only after pair parsing succeeds, moves the new records and sets both mask bits. Live coordinates remain unchanged. Parsing can run Tcl.
-
static void ReplaceElemOptionObject(Tcl_Obj **objPtrPtr, Tcl_Obj *newObjPtr)
Replace one owned Tcl option-object reference.
- Parameters:
objPtrPtr – Address of a retained object pointer, possibly NULL.
newObjPtr – Borrowed replacement object, or NULL to clear the field. Identical pointers are a no-op. Otherwise retains the new object before storing it and releasing the old reference. Does not copy contents, evaluate scripts or change internal numeric data.
-
static void SetElemDataPairOptionObjects(Element *elemPtr, Tcl_Obj *dataObjPtr)
Retain paired data and derive coherent X/Y option representations.
- Parameters:
elemPtr – Element whose dataObjPtr, xObjPtr and yObjPtr are replaced.
dataObjPtr – Borrowed, already validated even-length coordinate list. Builds new X/Y lists using the original element objects, preserving expression spellings instead of reconstructing them from doubles. Retains all three results through ReplaceElemOptionObject. Invalid list structure or failure to assemble output is an internal Tcl_Panic, not a recoverable user error. Must run only after successful data validation; does not evaluate expressions.
-
void Rbc_SyncElemDataOptionObjects(Element *elemPtr)
Synchronize retained coordinate options after successful data commit.
- Parameters:
elemPtr – Configured element with even, still-valid option arguments. Processes non-overridden initial defaults in data/X/Y order, then explicit arguments in caller order. A data occurrence sets coherent data/X/Y objects; an independent X or Y clears data and replaces that coordinate representation. Pins initial objects while replacing fields, then releases those temporary references. Does not rebuild numeric arrays or evaluate expressions. Call while optionsConfigured still identifies first configuration when applicable.
-
void Rbc_FreeElemStylesTransaction(Graph *graphPtr, ElemStylesTransaction *transactionPtr)
Release uncommitted palette and zero the transaction.
Safe after commit or a failed prepare. Does not free the transaction record.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live component resources on its Tk thread.
transactionPtr – [inout] Required initialized or already-cleared transaction; releases only candidates still owned by it.
-
int Rbc_PrepareElemStylesTransaction(Graph *graphPtr, Element *elemPtr, Rbc_Uid penType, size_t styleSize, ElemStylesTransaction *transactionPtr)
Stage palette without replacing live element resources.
Processes repeated explicit options in caller order, including invalid earlier values. Returns TCL_OK with candidates, or TCL_ERROR after releasing candidates and zeroing the transaction. On success, commit or free the transaction.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live component resources on its Tk thread.
elemPtr – [in] Borrowed element with the pending even-length option/value array and effective option objects.
penType – [in] Retained interface argument, currently unused; palette parsing checks pens against the element class.
styleSize – [in] Byte size of the concrete style record, including its PenStyle prefix.
transactionPtr – [out] Required fresh transaction storage; initialized here. Do not pass a transaction still owning candidates.
-
void Rbc_CommitElemStylesTransaction(Graph *graphPtr, Element *elemPtr, ElemStylesTransaction *transactionPtr)
Commit staged palette and release replaced resources.
Unstaged options remain unchanged. Complete all other validation before committing; this operation does not provide rollback.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live component resources on its Tk thread.
elemPtr – [inout] Borrowed live element receiving successfully staged resources.
transactionPtr – [inout] Successfully prepared transaction; committed candidate ownership transfers to the element and candidate pointers are cleared.
-
static void CommitElemVector(Element *elemPtr, ElemVector *destPtr, ElemVector *candidatePtr)
Data observation and value presentation
The documentation-only scope distinguishes private names such as GetIndex from
similarly named helpers in other C files. It does not change C symbols.
- group Element data and value-label internals
Borrowed arrays, notifications and source-value presentation.
Functions
-
static int GetElemArrayByteCount(Tcl_Interp *interp, Tcl_Size count, size_t elementSize, size_t *byteCountPtr)
Validate element-array multiplication before allocation.
- Parameters:
interp – Interpreter receiving an overflow/size diagnostic.
count – Nonnegative logical element count.
elementSize – Positive byte size of one element.
byteCountPtr – [out] Receives the product only on success.
- Returns:
TCL_OK on representable multiplication, TCL_ERROR otherwise. Zero count is valid and yields zero bytes. Does not allocate memory or validate arithmetic used by the caller to compute count.
-
int Rbc_ValidateValueCommand(Tcl_Interp *interp, Tcl_Obj *commandObjPtr)
Validate the list structure of an optional value-label command prefix.
- Parameters:
interp – Interpreter for list-syntax errors.
commandObjPtr – Borrowed prefix object; NULL and empty lists are accepted.
- Returns:
TCL_OK for valid structure, TCL_ERROR otherwise. Does not resolve the command name, execute it, or guarantee that later evaluation succeeds. An empty prefix selects ordinary format-based labels.
-
int Rbc_GetValueOffset(Tcl_Interp *interp, Tcl_Obj *objPtr, Point2D *offsetPtr)
Parse exactly two signed integer pixel offsets transactionally.
- Parameters:
interp – Interpreter for list/number diagnostics.
objPtr – Borrowed two-element list.
offsetPtr – [out] Receives both coordinates only after both integers parse.
- Returns:
TCL_OK on success; TCL_ERROR leaves the entire point unchanged. Uses Tcl_GetIntFromObj, not screen-unit conversion or expression evaluation. Negative values are permitted; the resulting ints are stored as doubles.
-
Tcl_Obj *Rbc_GetElementValueLabel(Element *elemPtr, Tcl_Obj *commandObjPtr, const char *format, int show, Tcl_Size index, double x, double y)
Obtain a referenced label object from fallback formatting or a callback.
- Parameters:
elemPtr – Live element with graph, interpreter, window and name.
commandObjPtr – Optional borrowed command-prefix list.
format – Validated fallback printf format or NULL.
show – Coordinate selection; SHOW_NONE suppresses callback evaluation.
index – Original source index passed to the command.
x – Source X value.
y – Source Y value.
- Returns:
Tcl object with one owned reference; caller must Tcl_DecrRefCount it. Copies bounded fallback text first. A nonempty prefix is duplicated and invoked globally with graph path, element name, index, X and Y appended. Successful text is retained without the fallback buffer limit; errors go to the background and retain fallback text. Saves/restores the enclosing interpreter state. Does not preserve drawing records against callback mutation: callbacks must not mutate drawing state or enter nested event loops.
-
int Rbc_ValidateValueFormat(Tcl_Interp *interp, const char *format)
Validate a printf format that receives one double argument.
- Parameters:
interp – Interpreter receiving a format diagnostic on error.
format – Borrowed NUL-terminated format; NULL selects the default later.
- Returns:
TCL_OK when accepted, TCL_ERROR otherwise. Permits literal-only text, escaped percent and at most one a/A/e/E/f/F/g/G conversion with optional lowercase l. Limits format length, width and precision to VALUE_FORMAT_LIMIT. Rejects dynamic width/precision and incompatible argument types. Does not format a value or guarantee untruncated output in every buffer.
-
static void FormatValueLabel(char *buffer, size_t bufferSize, const char *format, int show, double x, double y)
Format selected source coordinates into a bounded fallback buffer.
- Parameters:
buffer – Writable storage of bufferSize bytes.
bufferSize – Capacity including terminator; zero performs no writes.
format – Previously validated format, or NULL for percent-g formatting.
show – SHOW_X, SHOW_Y, SHOW_BOTH or a value producing empty text.
x – Source X value.
y – Source Y value. Formats X/Y independently with one double each; BOTH separates results by a comma. Truncation remains terminated and a truncated X prevents Y append. Negative snprintf results clear the affected output. Performs no Tcl callback and does not validate the format; validation must precede this helper.
-
static void SyncElemVector(ElemVector *vPtr)
Refresh a data slot’s borrowed vector storage and cached extrema.
- Parameters:
vPtr – Slot whose vecPtr identifies a live real vector. Copies length, capacity, numeric-array pointer and range from the source. Does not acquire a reference, install callbacks, record a changed interval or schedule redraw. The source vector retains ownership of its numeric array.
-
static void FindRange(ElemVector *vPtr)
Compute finite extrema for a literal element data slot.
- Parameters:
vPtr – Initialized slot with storage for its nonnegative nValues. Returns without changing cached extrema for empty or NULL storage. Otherwise ignores nonfinite values; an all-nonfinite array yields DBL_MAX and -DBL_MAX. Does not compute a positive minimum, despite the historical comment. Does not change the array, allocate memory or notify observers.
-
double Rbc_FindElemVectorMinimum(ElemVector *vPtr, double minLimit)
Find a finite sample at or above a supplied lower bound.
- Parameters:
vPtr – Slot with valid storage for every value counted by nValues.
minLimit – Lower bound and fallback value when no usable minimum is found.
- Returns:
Smallest qualifying value, or minLimit if the accumulator remains DBL_MAX. A sole qualifying DBL_MAX value is therefore indistinguishable from no match. Does not modify cached extrema or filter minLimit itself.
-
static void RecordElemVectorChange(ElemVector *vPtr, int haveRange, Tcl_Size first, Tcl_Size last)
Accumulate a pending source-change interval conservatively.
- Parameters:
vPtr – Initialized element data slot.
haveRange – Nonzero when first/last describe a precise changed range.
first – Inclusive first source index, valid when haveRange is nonzero.
last – Inclusive last source index, valid when haveRange is nonzero. First notification initializes the pending state. Precise intervals are merged by their outer bounds; unknown/full changes set changeAll and clear endpoints. Later precise updates cannot narrow a pending full change. Does not validate indices, fetch data, consume the pending state or request redraw.
-
static void VectorChangedProc(Tcl_Interp *interp, ClientData clientData, Rbc_VectorNotify notify)
Refresh or invalidate a stable element slot during vector notification.
- Parameters:
interp – Interpreter supplied by the vector notification service.
clientData – Stable ElemVector field whose owning element remains live.
notify – UPDATE or DESTROY; other values take the update path. During update, reads the client-specific changed range inside its valid callback scope, records it and refreshes source storage. Destruction records a full change and clears clientId, valueArr and nValues, but does not zero every cached field. Marks axes and mapping dirty; requests backing-store redraw only when neither hidden nor plotHidden. Never draws synchronously. The update path assumes its registered client ID still resolves successfully.
-
void Rbc_SyncElementVectors(Graph *graphPtr)
Refresh pending named-vector inputs before synchronous layout/export.
Refresh element arrays with pending vector updates before layout.
Refresh pending named-vector inputs before synchronous layout/export.
Does not deliver notifications or run Tcl callbacks. Marks affected mapping and axis ranges dirty; covers coordinates, weights and error vectors.
- Parameters:
graphPtr – Live graph with initialized element registry. Visits registered elements, including hidden ones, and checks common X/Y, weight and six error slots. Pending clients refresh borrowed storage and record a full change, marking mapping, axes and backing store dirty. Does not consume queued notifications, run their callbacks, process events or independently schedule an idle redraw. Literal inputs and nonpending clients are untouched.
-
static int EvalExprListObj(Tcl_Interp *interp, Tcl_Obj *listObjPtr, Tcl_Size *nElemPtr, double **arrayPtr)
Evaluate a Tcl list into a newly owned double array.
- Parameters:
interp – Interpreter for list parsing, expression evaluation and errors.
listObjPtr – Borrowed list object valid throughout evaluation.
nElemPtr – [out] Cleared first; receives the list length on success.
arrayPtr – [out] Cleared first; receives storage to release with ckfree.
- Returns:
TCL_OK on success, TCL_ERROR after releasing partial allocation. Empty input yields zero/NULL. Uses checked byte counts and Tcl_AttemptAlloc. Each entry is a Tcl expression, not merely a literal double: commands and traces can run. The borrowed list-element array is not snapshotted here; callers must not assume staging alone protects it or owner lifetimes across reentry.
-
static int ParseElemVectorPairsObj(Tcl_Interp *interp, Element *elemPtr, Tcl_Obj *objPtr, ElemVector *xCandidatePtr, ElemVector *yCandidatePtr)
Split evaluated alternating coordinates into two owned candidate slots.
- Parameters:
interp – Interpreter for parsing and allocation diagnostics.
elemPtr – Live owner recorded in both candidates.
objPtr – Borrowed list of alternating X/Y expressions.
xCandidatePtr – [out] Fresh slot, zeroed before parsing.
yCandidatePtr – [out] Distinct fresh slot, zeroed before parsing.
- Returns:
TCL_OK with both arrays and extrema prepared; TCL_ERROR with temporary arrays released. Caller may free both slots after either result. Evaluates the entire list before rejecting odd length. Thus evaluation side effects may already have occurred when odd input fails. Allocates a temporary flat array then separate X/Y arrays; empty input leaves both arrays NULL. Never treats this paired list as a named-vector reference.
-
static int GetIndex(Tcl_Interp *interp, Tcl_Size nPoints, const char *string, Tcl_Size *indexPtr)
Resolve end or an integer expression against the element point count.
- Parameters:
interp – Interpreter for expression and range diagnostics.
nPoints – Point count captured by the caller before expression evaluation.
string – Borrowed NUL-terminated index text.
indexPtr – [out] Receives the validated Tcl_Size index only on success.
- Returns:
TCL_OK on success, TCL_ERROR for empty data, evaluation/conversion failure or an out-of-range index. Only exact end is special. Other input uses Tcl_ExprObj followed by Tcl_GetSizeIntFromObj and can execute commands/traces. Bounds are captured before evaluation; caller owns callback lifetime and any needed revalidation if data changes during evaluation.
-
static int ClosestErrorValue(const ElemVector *vectorPtr, Tcl_Size index, double *valuePtr)
Read one finite, current error-data sample without synchronizing it.
- Parameters:
vectorPtr – Borrowed error-data slot.
index – Source index to inspect.
valuePtr – [out] Assigned only if a valid sample is available.
- Returns:
Nonzero on success; zero for pending vector updates, invalid index, NULL storage or nonfinite data. Does not dereference storage while a vector notification is pending. No allocation, callbacks or graph changes occur.
-
static int AppendClosestErrors(Tcl_Interp *interp, Element *elemPtr, Tcl_Size index, Tcl_Obj *resultObjPtr)
Collect available source error values in a private result dictionary.
- Parameters:
interp – Interpreter for dictionary errors.
elemPtr – Live selected element with error slots.
index – Selected original source index.
resultObjPtr – Unshared result dictionary owned by the caller.
- Returns:
TCL_OK after collection; TCL_ERROR on dictionary failure. For each axis, a nonempty symmetric vector takes precedence; an unusable sample does not fall back to explicit bounds. Otherwise both low/high values must be usable. Reports source values, not translated bar positions. Copies values into owned Tcl objects without variable writes or script evaluation. The caller must finish all metadata collection before publishing any array fields.
-
static int GetElemArrayByteCount(Tcl_Interp *interp, Tcl_Size count, size_t elementSize, size_t *byteCountPtr)
Lifecycle and display dispatch
These contracts cover registry ownership, option rollback, staged teardown and normal/active rendering. The namespace below is documentation-only.
- group Element lifecycle and display dispatch
Registry ownership, option rollback, teardown and viewport-scoped rendering.
Functions
-
static int NameToElement(Graph *graphPtr, Tcl_Obj *nameObj, Element **elemPtrPtr)
Look up an element by its exact registry name.
Returns TCL_OK and a borrowed record in elemPtrPtr, or TCL_ERROR with a graph-interpreter diagnostic. Failure leaves the output pointer unchanged. Hidden and non-displayed elements remain eligible; no reference is retained.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
nameObj – [in] Borrowed exact element-name object.
elemPtrPtr – [out] Required output receiving a borrowed registry element only on success.
-
static int InitElementOptions(Graph *graphPtr, Element *elemPtr)
Initialize Tk-managed element options from component resources.
Repeated calls after success are no-ops. Uses the normalized resource name and class Element. On failure frees partially initialized options and the option table; constructor-owned resources remain for the concrete destructor. Returns TCL_OK or TCL_ERROR. Does not construct derived drawing resources.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
elemPtr – [inout] Borrowed live element belonging to graphPtr; resource requirements are described above.
-
static int ConfigureElementOptions(Graph *graphPtr, Element *elemPtr, Tcl_Size objc, Tcl_Obj *const objv[], int *maskPtr)
Apply Tk options and validate concrete derived state transactionally.
Requires initialized options. Exposes the option mask and borrowed original arguments only during concrete configuration. Trackgraphs require a valid track and a Y axis owned by it; ordinary graphs reject nonempty track names. Concrete configuration must stage all fallible work before live-state commit. Failure restores Tk options while preserving the error diagnostic. Success commits the track, sets optionsConfigured and optionally writes maskPtr. Clears transient argument pointers on both post-conversion exit paths.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
elemPtr – [inout] Borrowed live element belonging to graphPtr; resource requirements are described above.
objc – [in] Even number of option/value entries in objv.
objv – [in] Borrowed even-length option/value vector; exposed only during concrete configuration.
maskPtr – [out] Optional output receiving the Tk change mask on success.
-
static void ReleaseElementResources(Graph *graphPtr, Element *elemPtr)
Release derived and Tk-owned resources once, retaining the record.
Clears borrowed configuration context, then invokes the concrete destructor even if option initialization failed. Frees initialized Tk options afterward, so derived GCs are released before their colors, fonts and bitmaps. Requires the owning graph’s resource-release context, including a usable Tk window for bitmap options. Does not remove registry or display-list entries.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
elemPtr – [inout] Borrowed live element belonging to graphPtr; resource requirements are described above.
-
void Rbc_ReleaseElementTkResources(Graph *graphPtr)
Release resources for every registered element before window teardown.
Includes hidden and non-displayed elements. Each release is idempotent through tkResourcesReleased; element records, names and registry entries survive this pass. The graph and its Tk window must remain valid throughout traversal.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
-
static void DestroyElement(Graph *graphPtr, Element *elemPtr)
Remove one element and defer its record release while preserved.
Removes bindings and global-legend references, releases concrete and Tk resources, then removes all matching display-list links and the optional registry entry. A displayed non-hidden element requests RESET_WORLD/redraw. Frees the owned name; record storage survives only existing Tcl_Preserve scopes. Released resources and registry identity are no longer usable. Callers destroying the whole registry clear hashPtr before this call.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
elemPtr – [inout] Owned element to remove; identity and resources become invalid even if record storage is preserved.
-
static int CreateElement(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[], Rbc_Uid classUid)
Construct, register and configure an element from command arguments.
Requires a dispatcher-validated argument vector with the name at objv[3]. Rejects duplicate names, leading hyphens and unsupported trackgraph types. Registers the concrete record before option initialization; any initialization or configuration failure destroys it and returns TCL_ERROR. Success prepends it to the display list, marks mapping and axes dirty, queues redraw if visible, and returns its name as the Tcl result. Defaults pass through concrete configuration even when no explicit options are supplied.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.
classUid – [in] Interned concrete element class selecting the constructor.
-
static int RebuildDisplayList(Graph *graphPtr, Tcl_Obj *newListObj)
Replace display membership and order from a Tcl list of names.
Malformed list syntax returns TCL_ERROR before changing the display list. Otherwise hides all registered elements, appends each recognized name in input order and unhides it. Unknown names are ignored and their diagnostics cleared. Repeated names retain only their first occurrence. Returns TCL_OK, sets RESET_WORLD and schedules redraw; registry ownership is unchanged.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
newListObj – [in] Borrowed Tcl list of desired display names in drawing order.
-
void Rbc_DestroyElements(Graph *graphPtr)
Destroy all registered elements and their container structures.
Clears each record’s hashPtr before destruction so the registry traversal remains intact. Then deletes the element and tag tables and display chain. This is final teardown, not an idempotent reset or reusable initialization. Resource release must occur in the graph’s valid Tk teardown sequence.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
-
void Rbc_MapElements(Graph *graphPtr)
Map visible display-list elements whose geometry is dirty.
Resets bar stacks for trackgraphs or modes other than MODE_INFRONT. Skips hidden and plotHidden records; MAP_ALL or MAP_ITEM selects each remaining mapping call. Enters and restores the owning track viewport around dispatch, then clears MAP_ITEM. Screen mapping sets GRAPH_CHANGED; export mapping does not. The caller owns layout sequencing and graph-wide flag cleanup.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
-
static void DrawClippedTrackElement(Graph *graphPtr, Drawable drawable, Element *elemPtr, int active)
Draw a complete normal or active element within a screen track clip.
Requires a non-NULL track and an already entered track viewport. Intersects inclusive track bounds with drawable graph dimensions and skips empty bounds. Dispatches only when the renderer supplies a drawable, then balances clip and renderer lifetime. Clipping includes native raised bar borders.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
drawable – [in] Borrowed compatible screen drawable receiving mapped geometry.
elemPtr – [inout] Borrowed live element belonging to graphPtr; resource requirements are described above.
active – [in] Nonzero dispatches the active overlay; zero dispatches normal drawing.
-
void Rbc_DrawElements(Graph *graphPtr, Drawable drawable)
Draw visible elements in display-list order using mapped geometry.
Skips hidden, plotHidden and collapsed track regions. Enters and restores each track viewport; scrolled tracks and track bars additionally clip the complete callback. Does not remap data or manage element lifetime across callbacks.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
drawable – [in] Borrowed compatible screen drawable receiving mapped geometry.
-
void Rbc_DrawActiveElements(Graph *graphPtr, Drawable drawable)
Draw active overlays in display-list order using mapped geometry.
Requires ELEM_ACTIVE in addition to normal visibility and track-size checks. Uses the same viewport and full-callback clipping policy as Rbc_DrawElements, but dispatches drawActiveProc. The caller controls ordering relative to the normal pass and keeps graph, element and mapped resources alive.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
drawable – [in] Borrowed compatible screen drawable receiving mapped geometry.
-
void Rbc_ElementsExport(Graph *graphPtr, Rbc_ExportContext *exportPtr)
Export normal visible elements through the selected export backend.
Dispatches mapped geometry in display-list order, entering and restoring each track viewport. Scrolled tracks and track bars wrap the callback in an export renderer clip. Collapsed tracks are skipped. Only PostScript receives element comments; the geometry dispatch also supports SVG and PDF. Does not own exportPtr or perform layout; errors use the export context.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
exportPtr – [inout] Borrowed export context receiving output and backend error state.
-
void Rbc_ActiveElementsExport(Graph *graphPtr, Rbc_ExportContext *exportPtr)
Export active overlays through the selected export backend.
Uses the visibility, track viewport and clipping policy of Rbc_ElementsExport with an additional ELEM_ACTIVE check and exportActiveProc dispatch. Emits active-element comments only for PostScript. The caller owns the export context and ordering of normal and active passes.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
exportPtr – [inout] Borrowed export context receiving output and backend error state.
-
int Rbc_GraphUpdateNeeded(Graph *graphPtr)
Test visible display-list X/Y vector clients for pending notification.
Returns 1 on the first pending X or Y client, otherwise 0. Does not deliver notifications, synchronize arrays, mark geometry or schedule redraw. This is not an exhaustive dirty-state test: it does not inspect weights, error inputs, concrete polar inputs or elements outside the visible list.
- Parameters:
graphPtr – [inout] Borrowed owning graph; required live-window and mapped-state conditions are described above.
-
static int NameToElement(Graph *graphPtr, Tcl_Obj *nameObj, Element **elemPtrPtr)
Line geometry and resource lifecycle
These contracts cover line, strip and polar mapping storage and pen resources. See Element data and dispatch for the reset and teardown boundaries. The scope is documentation-only.
- group Line geometry and resource lifecycle
Private mapping, cache ownership and line-family pen/element lifecycle.
Functions
-
static void ClearPalette(Rbc_Chain *palette)
Clear palette counts without releasing storage.
Zeros each style’s symbol, strip and X/Y error-bar counts. Array pointers and pen references remain unchanged; the owning line releases shared geometry.
- Parameters:
palette – [inout] Valid chain of line-style records; only their geometry counts are zeroed, not pointers or pen references.
-
static int ConfigurePen(Graph *graphPtr, Pen *penPtr)
Stage and replace a line pen’s derived drawing resources.
Borrows the graph and pen. Validates option representations and stages colors, shadow and symbol resources before constructing replacement GCs. On conversion failure, frees staged resources and returns TCL_ERROR with an interpreter diagnostic, leaving existing derived resources intact. On success, releases old derived resources and transfers the candidates. The enclosing configuration transaction owns Tk option rollback.
Uses Tk-managed symbol, text and error-bar GCs but a private trace GC, including its dash state. Bitmap symbols retain their mask/background semantics. Does not map geometry or schedule drawing.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the live window, display and interpreter for resource operations.
penPtr – [inout] Live line-pen core with candidate Tk option values installed; derived resources are replaced only after conversion succeeds.
-
static void DestroyPen(Graph *graphPtr, Pen *penPtr)
Release derived line-pen resources.
Frees text-style resources, Tk-managed GCs, the private trace GC, bitmap and mask, and separately retained colors. Clears released fields. Does not free the pen record or its Tk option values; outer pen teardown owns those. Requires the graph display to remain valid.
- Parameters:
graphPtr – [in] Borrowed owning graph whose display remains live while pen drawing resources are released.
penPtr – [inout] Line-pen core whose derived resources are released and cleared; record and Tk option ownership remain with the caller.
-
static void InitPen(LinePen *penPtr, const Tk_OptionSpec *optionSpecs, unsigned int flags)
Initialize a zero-allocated line pen before option setup.
Installs configuration/destruction callbacks, option specifications and baseline symbol, error-bar and value-label settings. Does not zero the whole record, initialize Tk options, or allocate GCs. The initial empty name is borrowed; the factory replaces it with owned storage.
- Parameters:
penPtr – [inout] Caller-owned zero-allocated line pen; initialization does not release any preexisting resources.
optionSpecs – [in] Required persistent Tk option specification table, retained by pointer.
flags – [in] Initial pen flags copied to the core, normally NORMAL_PEN or ACTIVE_PEN.
-
Pen *Rbc_LinePen(const char *penName)
Allocate an unregistered line pen.
The exact name activeLine selects active specifications; all other names select normal specifications. Duplicates the name and returns the embedded Pen pointer. Allocation is asserted. Registry insertion, Tk option initialization and configuration belong to the caller.
- Parameters:
penName – [in] Required NUL-terminated name copied into owned storage; exact activeLine selects active defaults.
-
static int ScaleSymbol(Element *elemPtr, int normalSize)
Compute a bounded odd screen size for symbols.
When symbol scaling is enabled, SCALE_SYMBOL captures current axis ranges as the baseline. Later calls use the smaller finite positive range ratio; invalid ranges or ratios retain unit scaling. May update the baseline and clear SCALE_SYMBOL. Clamps before integer conversion to at least one and at most the smaller graph screen range, then chooses an odd size without exceeding that cap. Does not allocate or invoke Tcl.
- Parameters:
elemPtr – [inout] Live element with current axes and viewport dimensions; baseline ranges and SCALE_SYMBOL may be updated.
normalSize – [in] Unscaled requested symbol size in pixels; final output is bounded to the drawable range and made odd.
-
static void GetScreenPoints(Graph *graphPtr, Line *linePtr, MapInfo *mapPtr)
Build owned mapped points with original source indices.
Initializes the output map to empty; callers must first release any old map storage. Reads finite source points and retains only finite mapped coordinates. Does not clip them to the viewport or synchronize sources. Allocates a break-before array only when retained indices contain gaps.
Transfers the point, index and optional break arrays to the map on success. Checked-size or allocation failure frees candidates and leaves an empty map without an interpreter diagnostic.
- Parameters:
graphPtr – [in] Borrowed graph with the element or track viewport and axis mappings already installed.
linePtr – [in] Borrowed line with synchronized source arrays and assigned axes; no source ownership is transferred.
mapPtr – [out] Fresh nonowning map output; initialized empty, then receives owned parallel arrays to release with ckfree.
-
static void ReducePoints(MapInfo *mapPtr, double tolerance)
Simplify each continuous mapped run without joining gaps.
Borrows the line point map and forwards the tolerance to Rbc_SimplifyLine. Selected points retain original source indices and break flags. Replaces and frees old arrays only after all replacement arrays are available. Invalid counts, size/allocation failures, or unchanged selection leave the original map intact. Does not modify source vectors or report Tcl errors.
- Parameters:
mapPtr – [inout] Caller-owned map with parallel point/index arrays and optional break flags; replaced arrays are freed only after successful reduction.
tolerance – [in] Simplification distance in mapped screen pixels, passed unchanged to Rbc_SimplifyLine.
-
static void GenerateSteps(Graph *graphPtr, Line *linePtr, MapInfo *mapPtr)
Replace a mapped polyline with stepped geometry.
Processes each continuous run independently. Each intermediate point changes data X first while retaining the preceding data Y, accounting for inverted axes. Intermediate and following points use the following source index. Breaks copy the next point without inserting a connecting step.
Transfers newly allocated arrays and frees the old map on success. On size/allocation failure, retains old arrays and changes effective smooth to PEN_SMOOTH_NONE; the requested smoothing option is unchanged.
- Parameters:
graphPtr – [in] Borrowed graph supplying the inversion flag for the mapped coordinate roles.
linePtr – [inout] Owning line whose effective smooth mode falls back to linear if replacement storage cannot be allocated.
mapPtr – [inout] Owned mapped point/index arrays with optional break flags; successful replacement releases the original arrays.
-
static void MapActiveSymbols(Graph *graphPtr, Line *linePtr)
Rebuild visible symbols for explicit active indices.
Releases the previous active point/index arrays first. Filters explicit indices against the current point count, finite source/mapped coordinates and symbol-map extents, preserving selection order and source indices. Whole-element activation is handled elsewhere, not expanded here.
Transfers candidate arrays only if points survive. Checked allocation failure or an empty result leaves no active geometry. Clears ACTIVE_PENDING on every exit, without changing the retained activation selection.
- Parameters:
graphPtr – [in] Borrowed graph with the correct element or track viewport and prepared axis mappings.
linePtr – [inout] Live line with synchronized sources, explicit active indices and configured pens; active geometry is replaced and ACTIVE_PENDING cleared.
-
static void FreeTraces(Line *linePtr)
Release all owned line traces and their chain.
Frees each trace’s point and source-index arrays and the trace record, then destroys the chain and clears its pointer. Does not release source data or other mapped arrays.
- Parameters:
linePtr – [inout] Live line owning a trace chain or NULL; all trace allocations are freed and the chain field is cleared.
-
static void ResetLine(Line *linePtr)
Discard mapped geometry before rebuilding a line.
Releases area/error-band polygons, traces, symbols, strips, explicit active geometry and X/Y error-bar arrays with their source-index maps. Clears palette counts, array pointers, geometry counts and pointMapOmitted. Explicit active indices request remapping through ACTIVE_PENDING.
Retains source data, pens, activation indices and the source decimation cache. This is a geometry reset, not complete element teardown.
- Parameters:
linePtr – [inout] Live line owning mapped arrays and traces; source slots, pens, active selection and decimation cache remain retained.
-
static Tcl_Size FilterErrorBarSegments(Segment2D *segments, Tcl_Size *indices, Tcl_Size count, const unsigned char *selected)
Compact error segments and source indices in place.
Keeps segments whose source index is selected, preserving order and parallel indices, and returns the retained count. All parts of a selected bar, including caps, survive. The caller supplies valid source indices and selection storage; this helper does not check bounds or allocate.
- Parameters:
segments – [inout] Writable array of count mapped segments; retained entries are compacted into its prefix.
indices – [inout] Writable parallel array of count original source indices, each valid for selected.
count – [in] Nonnegative number of initialized entries in both arrays.
selected – [in] Borrowed byte-selection table covering every supplied source index; nonzero retains the corresponding segment.
-
static void FilterLineErrorBars(Line *linePtr, PenStyle **dataToStyle)
Match retained error bars to the symbol selection.
Runs before palette geometry is reordered by MergePens. When symbol limits or reduced-symbol mode require filtering, builds a source-index selection using palette traversal and the shared symbol interval counter. Compacts X/Y error-bar segments with their parallel index arrays.
Borrows a valid data-to-style map. Allocates temporary selection storage with checked byte count and ckalloc, then frees it. Does not resize the segment allocations, change source data, or regenerate geometry.
- Parameters:
linePtr – [inout] Mapped line before palette regrouping; symbol/source indices are valid and X/Y segment counts may shrink.
dataToStyle – [in] Borrowed style-pointer array indexed by every source point used by the symbol map; records belong to the palette.
-
static void DestroyLine(Graph *graphPtr, Element *elemPtr)
Release resources owned by a line, strip or polar element.
Releases named pen references, built-in pen resources, data subscriptions, decimation cache, mapped geometry, palette, tags, activation indices and fill/error-band drawing resources. External source vectors and images are not destroyed.
The common element lifecycle guards this callback against repeated teardown; not every field is cleared here. It owns record/name and Tk option cleanup outside this callback. Requires a live display for drawing-resource release.
- Parameters:
graphPtr – [in] Borrowed owning graph with live display and pen registry throughout element-resource teardown.
elemPtr – [inout] Line-family core being torn down once by the common lifecycle; this call releases contents but not the record or names.
-
Element *Rbc_LineElement(Graph *graphPtr, const char *name, Rbc_Uid classUid)
Allocate an unregistered line-family element.
Returns NULL if record allocation fails. Selects line, polar or strip specifications and the corresponding dispatch table, duplicates name and label, initializes the built-in normal pen and creates the palette. Starts with XY data, no requested smoothing and pending symbol-scale baseline capture. Caller owns registration, Tk option initialization and configuration of the returned embedded Element pointer.
- Parameters:
graphPtr – [in] Borrowed owning graph retained by pointer in the new element; must outlive the element.
name – [in] Required NUL-terminated element name, duplicated for both name and initial label.
classUid – [in] Interned line, polar or strip element class; line/polar have explicit branches and other values select strip specifications.
-
void Rbc_LineFontsChanged(Graph *graphPtr)
Invalidate cached value-label text styles after font changes.
Visits registered line pens and built-in pens of all line, strip and polar elements, including hidden elements. Resets styles with a non-NULL font. Shared named pens are visited through the registry rather than once per element. Borrows a live graph/window; does not itself schedule redraw or layout.
- Parameters:
graphPtr – [inout] Live graph with initialized pen/element registries and Tk window; cached value-label styles are reset.
-
static void ClearPalette(Rbc_Chain *palette)
Line mapping pipeline
These private contracts describe continuous runs, symbol selection, clipping, palette slices and the top-level mapping pass. See Element data and dispatch for ordering. The C namespace below only disambiguates documentation names.
- group Line mapping pipeline
Private continuous-run, clipping, symbol and palette geometry services.
Functions
-
static void FreeMapRun(MapInfo *mapPtr)
Release a temporary map run and clear its record.
Frees owned screen points, source indices and optional break flags, then zeros the complete MapInfo. The record itself remains caller-owned.
- Parameters:
mapPtr – [inout] Initialized caller-owned map, possibly empty; owned arrays are freed and the complete record is zeroed.
-
static int CopyMapRun(const MapInfo *srcPtr, Tcl_Size first, Tcl_Size length, MapInfo *dstPtr)
Copy one continuous source interval into an empty temporary map.
The caller supplies a valid first/length range and an unused destination. Zeros the destination before allocating; does not release previous contents. Copies points and original indices, deliberately omitting break flags because the interval represents one continuous run. Returns FALSE for nonpositive length, byte-count overflow or attempted-allocation failure, cleaning partial storage. Borrows and does not modify the source.
- Parameters:
srcPtr – [in] Borrowed mapped point/index arrays containing the entire requested continuous interval.
first – [in] Zero-based first mapped-point offset; bounds and continuity are caller-validated.
length – [in] Number of mapped entries to copy; nonpositive values fail, and first plus length must fit the source.
dstPtr – [out] Fresh nonowning map, distinct from srcPtr; initialized here and receives owned arrays on TRUE.
-
static void GenerateSplineRuns(Graph *graphPtr, Line *linePtr, MapInfo *mapPtr, int parametric)
Smooth discontinuous geometry one continuous run at a time.
Requires a nonempty map with break flags. Copies each run, applies the selected ordinary or parametric generator to runs of at least three points, then concatenates results with new boundary flags. Individual generator fallbacks retain that run’s copied coordinates. Effective smoothing remains the requested mode if any run succeeds, otherwise PEN_SMOOTH_NONE.
Replaces original map arrays only after all combined storage is ready. Run-copy, size or combined-allocation failure frees temporary storage, retains the original map and sets effective smoothing to PEN_SMOOTH_NONE. Does not change reqSmooth or report an interpreter error.
- Parameters:
graphPtr – [in] Owning graph supplying current mapped plot bounds and orientation.
linePtr – [inout] Owning line element; effective smooth may fall back to none, while reqSmooth is retained.
mapPtr – [inout] Nonempty owned mapped geometry with parallel source indices. Successful replacement frees old arrays; failure retains them.
parametric – [in] Nonzero selects parametric generation for each continuous run; mapPtr must carry breakBefore flags.
-
static double SymbolPadding(LinePen *penPtr, int size)
Return conservative pixel reach for a symbol.
Returns zero for a NULL pen or SYMBOL_NONE, otherwise size plus twice the outline width and two pixels for rounding. Borrows the pen and does not compute exact symbol bounds or allocate storage.
- Parameters:
penPtr – [in] Borrowed symbol pen, or NULL for zero padding.
size – [in] Already scaled symbol size in pixels, used with outline width to bound its reach.
-
static void GetSymbolMapExtents(Graph *graphPtr, Line *linePtr, Extents2D *extsPtr)
Expand mapping extents to retain partially visible symbols.
Starts from Rbc_GraphExtents and expands all sides by the largest padding among palette pens and the active pen. Whole-element activation can reuse normal symbol arrays, so the active pen must contribute. Calls ScaleSymbol, which may capture axis-range baselines. Returns conservative center bounds; actual drawing still requires clipping to the plot viewport.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
linePtr – [inout] Live line with palette and active pens; symbol scaling may update axis-range baselines.
extsPtr – [out] Required conservative symbol-center rectangle in mapped pixels; not a rendering clip.
-
static void MapSymbols(Graph *graphPtr, Line *linePtr, MapInfo *mapPtr)
Copy visible candidate centers and original indices into the line.
Borrows a source-ordered map and filters centers through expanded symbol extents. The caller must have cleared old symbol storage first. Transfers new arrays and count when any centers survive; otherwise frees candidates. Empty input, checked-size failure or attempted-allocation failure leaves existing line fields unchanged. Does not clip the symbol shapes themselves.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
linePtr – [inout] Line whose previous symbol arrays have been released; receives new owned center/index arrays and may update scale baselines.
mapPtr – [in] Borrowed source-ordered mapped points with parallel original indices and optional break flags; not modified.
-
static void FilterReducedSymbols(Line *linePtr, const MapInfo *mapPtr)
Retain original symbol centers that survived trace reduction.
Requires both mappings in source order, before MergePens. Matches both source index and exact screen coordinates, since inserted step/spline points can share an original index. Compacts symbol points and indices in place without changing capacity. Sets pointMapOmitted if any centers are removed so exact picking can search source samples instead.
- Parameters:
linePtr – [inout] Line with source-ordered symbol arrays; compacts them in place and sets pointMapOmitted when any center is removed.
mapPtr – [in] Borrowed reduced trace map in source order with exact coordinates and original indices; no ownership transfer.
-
static void MapStrip(Graph *graphPtr, Line *linePtr, MapInfo *mapPtr)
Build independent clipped segments for a strip element.
Borrows mapped points and skips pairs crossing a break flag. Clips each remaining adjacent pair against graph extents and records the starting point’s source index. Requires old strip storage to be cleared by the caller. Transfers arrays only when segments survive; frees empty candidates. Insufficient points, size failure or attempted-allocation failure leaves line fields unchanged. Does not apply the line trace-direction filter.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
linePtr – [inout] Line whose previous strip arrays have been released; receives owned independent-segment and source-index arrays.
mapPtr – [in] Borrowed source-ordered mapped points with parallel original indices and optional break flags; not modified.
-
static void MergePens(Line *linePtr, PenStyle **dataToStyle)
Group mapped geometry into palette-owned views of line storage.
Requires a nonempty palette. For one style, attaches existing arrays without allocation and permits a NULL dataToStyle. For multiple styles, requires every source index to map to a valid palette style. Validates all byte counts before changing slices, then reorders strips, symbols and X/Y error segments with their parallel original-index arrays.
Preserves order within each style and frees replaced backing arrays. Style pointers borrow slices; the line owns the complete allocations. Size failure returns without mutation; ordinary allocation uses ckalloc. Run source-order filtering before this operation. Trace chains are not reordered here.
- Parameters:
linePtr – [inout] Mapped line with a nonempty palette; arrays may be reordered and replaced, and styles receive borrowed slices.
dataToStyle – [in] Borrowed source-index-to-style array covering every mapped index; may be NULL only for a single-style palette.
-
static int OutCode(Extents2D *extsPtr, Point2D *p)
Classify a finite point relative to a clipping rectangle.
Returns a bit mask for sides strictly outside the rectangle. Points on its edges are inside. Borrows both arguments without mutation; callers supply valid ordered extents and finite coordinates.
- Parameters:
extsPtr – [in] Borrowed finite ordered clipping rectangle, inclusive at its edges.
p – [in] Borrowed finite point to classify, unchanged.
-
static int ClipSegment(Extents2D *extsPtr, int code1, int code2, Point2D *p, Point2D *q)
Clip segment endpoints in place using supplied outcodes.
Borrows a valid rectangle and writable finite endpoints with matching outcodes. Iteratively intersects outside endpoints with rectangle edges. Returns zero for an accepted segment and nonzero for rejection, opposite to a conventional success predicate. May modify endpoints even when the segment is ultimately rejected. Does not allocate or preserve originals.
- Parameters:
extsPtr – [in] Borrowed finite ordered clipping rectangle.
code1 – [in] OutCode value computed for the current p and this rectangle.
code2 – [in] OutCode value computed for the current q and this rectangle.
p – [inout] Writable finite first endpoint, distinct from q; clipping may change it even on rejection.
q – [inout] Writable finite second endpoint, distinct from p; clipping may change it even on rejection.
-
static void SaveTrace(Line *linePtr, Tcl_Size start, Tcl_Size length, MapInfo *mapPtr)
Append an owned copy of a mapped interval to the trace chain.
Caller supplies a valid interval and allocation-safe length. Copies points and source indices; if no index array exists, uses positions in the map. Stores the starting map offset, creates the chain lazily and appends a new trace. Uses ckalloc; FreeTraces owns the resulting arrays and record. Does not transfer or modify the source map.
- Parameters:
linePtr – [inout] Line receiving a newly allocated trace record; its trace chain is created lazily if absent.
start – [in] First mapped offset of a valid interval; retained in the trace as its start.
length – [in] Positive number of mapped entries to copy; caller must ensure allocation-safe sizes and source bounds.
mapPtr – [in] Borrowed source map; indices may be NULL, in which case map offsets become source indices.
-
static double TraceAbscissa(Graph *graphPtr, Line *linePtr, const Point2D *pointPtr)
Return a screen-derived coordinate ordered by increasing data X.
Uses screen X normally and negated screen Y for inverted graphs, then undoes X-axis descending direction. This coordinate is for trace-direction comparisons, not an inverse transform or recovered data value. Borrows all arguments and performs no allocation.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
linePtr – [in] Borrowed line supplying the prepared X axis and its descending flag.
pointPtr – [in] Borrowed finite mapped point in graph-window coordinates.
-
static void MapTraces(Graph *graphPtr, Line *linePtr, MapInfo *mapPtr)
Split and clip a mapped polyline into owned drawable traces.
Requires a nonempty writable map. Break flags prevent testing nonexistent connecting segments. Trace direction is measured in data-X order, including inverted and descending axes. Rejected segments and clipped exits split traces; only runs with at least two points are saved.
Clipping mutates temporary map coordinates. An outside following point is restored after saving an accepted clipped exit, but the map is not generally preserved. SaveTrace copies surviving geometry into line-owned storage. Call fill and source-coordinate filtering before this destructive stage.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
linePtr – [inout] Line with a cleared trace chain receiving copies of surviving clipped runs.
mapPtr – [inout] Nonempty temporary map with writable points and parallel indices; clipping can overwrite coordinates.
-
static void MapLine(Graph *graphPtr, Element *elemPtr)
Rebuild line-family drawing geometry in the current graph viewport.
Borrows the element and graph with axes/viewports prepared by the caller. Refreshes or invalidates pending source-decimation summaries, consumes change metadata and resets old mapped geometry before early exits. Builds the error band, chooses cached/pre-map/full mapping, retains symbol centers, then applies smoothing, density/tolerance reduction and area fill. Dispatches strip segments versus connected traces by element class.
Frees temporary map storage after geometry copies are made. The restricted pre-map path marks pointMapOmitted and attaches the single palette style without a source-sized style map. The general path computes style sizes, maps eligible XY error bars, filters them and finally merges palette slices. Individual helpers define allocation fallbacks; this void operation is not an all-or-nothing transaction and does not emit Tcl diagnostics.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
elemPtr – [inout] Live line-family core with synchronized source arrays and pending change metadata; existing mapped geometry is discarded.
-
static void GetLineExtents(Element *elemPtr, Extents2D *extsPtr)
Compute source-domain bounds for axis ranging.
Initializes empty sentinel extents. Complex data or polar-coordinate input is converted pointwise to Cartesian coordinates and enclosed in a symmetric square using the largest finite-point radius; radius overflow clamps to DBL_MAX. No valid points retain the empty sentinel bounds.
Ordinary XY input uses vector extrema, finding a positive minimum when a log axis requires it, and expands the result for error bars. Does not use smoothed or decimated screen geometry, allocate, or synchronize source data.
- Parameters:
elemPtr – [in] Borrowed line-family core with synchronized source values/extrema, error data and prepared axis policies.
extsPtr – [out] Required source-coordinate bounds, initialized to empty sentinels even when no valid samples exist.
-
static void FreeMapRun(MapInfo *mapPtr)
Line picking and stroke dispatch
See Element data and dispatch for the distinction between point and trace metrics, snapshot metadata collection, and orientation-aware source-range pruning. This namespace only disambiguates private documentation symbols.
- group Line picking and stroke dispatch
Private distance searches, snapshot metadata and screen stroke adapters.
Functions
-
static int SetClosestInfoObj(Tcl_Interp *interp, Tcl_Obj *resultObjPtr, const char *name, Tcl_Obj *valueObjPtr)
Insert a named value into a closest-result dictionary.
Borrows the writable result dictionary and value; Tcl_DictObjPut retains the key/value on success. Allocates the key object and returns the Tcl status. Does not write interpreter variables or invoke their traces. The caller owns result lifetime and must supply an unshared dictionary.
- Parameters:
interp – [inout] Borrowed interpreter for dictionary diagnostics; see Interpreter arguments.
resultObjPtr – [inout] Borrowed unshared result dictionary; inserted fields are retained, and earlier fields survive a later error.
name – [in] Required NUL-terminated dictionary key, copied into a new Tcl string.
valueObjPtr – [in] Borrowed value object; the dictionary acquires a reference on successful insertion.
-
static int SetClosestInfoDouble(Tcl_Interp *interp, Tcl_Obj *resultObjPtr, const char *name, double value)
Append a double-valued closest-result field.
Constructs a Tcl double and delegates dictionary insertion. Returns the insertion status; the result dictionary owns the inserted object on success. Does not format the number through a string or publish an array variable.
- Parameters:
interp – [inout] Borrowed interpreter for dictionary diagnostics; see Interpreter arguments.
resultObjPtr – [inout] Borrowed unshared result dictionary; inserted fields are retained, and earlier fields survive a later error.
name – [in] Required NUL-terminated dictionary key, copied into a new Tcl string.
value – [in] Double value copied into a new Tcl object without string formatting.
-
static int SetClosestInfoString(Tcl_Interp *interp, Tcl_Obj *resultObjPtr, const char *name, const char *value)
Append a string-valued closest-result field.
Copies the NUL-terminated value into a Tcl string and returns dictionary insertion status. Borrows the result dictionary and does not publish variables.
- Parameters:
interp – [inout] Borrowed interpreter for dictionary diagnostics; see Interpreter arguments.
resultObjPtr – [inout] Borrowed unshared result dictionary; inserted fields are retained, and earlier fields survive a later error.
name – [in] Required NUL-terminated dictionary key, copied into a new Tcl string.
value – [in] Required borrowed NUL-terminated value string, copied into a new Tcl object.
-
static int SetClosestInfoPair(Tcl_Interp *interp, Tcl_Obj *resultObjPtr, const char *name, double real, double imag)
Append a real/imaginary pair as a two-element Tcl list.
Creates two Tcl doubles and a list in real, imaginary order, then inserts that list into the borrowed result dictionary. Returns the insertion status. No RBC vector is created and no variable traces are run.
- Parameters:
interp – [inout] Borrowed interpreter for dictionary diagnostics; see Interpreter arguments.
resultObjPtr – [inout] Borrowed unshared result dictionary; inserted fields are retained, and earlier fields survive a later error.
name – [in] Required NUL-terminated dictionary key, copied into a new Tcl string.
real – [in] Real component stored at list index zero.
imag – [in] Imaginary component stored at list index one.
-
static double DistanceToLine(int x, int y, Point2D *p, Point2D *q, Point2D *t)
Measure Euclidean distance from a pixel query to a segment.
Delegates to Rbc_GetClosestPointOnSegment using a double-precision query. Borrows endpoints and writes the nearest segment point to t. Returns the pixel distance, including endpoint clamping, without modifying endpoints.
- Parameters:
x – [in] Horizontal query coordinate in screen pixels.
y – [in] Vertical query coordinate in screen pixels.
p – [in] Borrowed finite first segment endpoint, unchanged.
q – [in] Borrowed finite second segment endpoint, unchanged.
t – [out] Required separate closest-point output in screen pixels; always written for valid finite inputs.
-
static double DistanceToX(int x, int y, Point2D *p, Point2D *q, Point2D *t)
Intersect a segment with the query screen X coordinate.
Returns DBL_MAX without writing t when X is outside the endpoint span. Otherwise writes the intersection and returns its absolute screen Y distance from the query. Near-vertical segments choose the nearer endpoint in Y, with ties choosing q; near-horizontal segments use their constant Y. This is a trace intersection metric, not point-search X distance.
- Parameters:
x – [in] Horizontal query coordinate in screen pixels.
y – [in] Vertical query coordinate in screen pixels.
p – [in] Borrowed finite first segment endpoint, unchanged.
q – [in] Borrowed finite second segment endpoint, unchanged.
t – [out] Required separate closest-point output in screen pixels; unchanged when the query lies outside the relevant endpoint span.
-
static double DistanceToY(int x, int y, Point2D *p, Point2D *q, Point2D *t)
Intersect a segment with the query screen Y coordinate.
Returns DBL_MAX without writing t when Y is outside the endpoint span. Otherwise writes the intersection and returns its absolute screen X distance from the query. Near-horizontal segments choose the nearer endpoint in X, with ties choosing q; near-vertical segments use their constant X. Borrows endpoints and does not allocate.
- Parameters:
x – [in] Horizontal query coordinate in screen pixels.
y – [in] Vertical query coordinate in screen pixels.
p – [in] Borrowed finite first segment endpoint, unchanged.
q – [in] Borrowed finite second segment endpoint, unchanged.
t – [out] Required separate closest-point output in screen pixels; unchanged when the query lies outside the relevant endpoint span.
-
static int ClosestTrace(Graph *graphPtr, Line *linePtr, ClosestSearch *searchPtr, DistanceProc *distProc)
Search connected mapped traces for a strict distance improvement.
Calls the supplied script-free distance function on each consecutive pair. On improvement, stores element, distance, the segment start’s source index and the inverse-mapped closest coordinate in the borrowed search record. Returns TRUE only if it improves the incoming distance; ties retain the previous candidate. Requires current trace geometry and prepared axes.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
linePtr – [in] Borrowed line with current mapped geometry and synchronized source slots; no ownership is transferred.
searchPtr – [inout] Initialized query and best-hit record; only a strictly closer candidate replaces its distance, element, index and coordinate.
distProc – [in] Required script-free segment metric; must write its closest point whenever the returned distance can improve the query.
-
static int ClosestStrip(Graph *graphPtr, Line *linePtr, ClosestSearch *searchPtr, DistanceProc *distProc)
Search independent mapped segments for a closer interpolated hit.
Uses the supplied distance callback and the parallel stripToData array. Commits a strict improvement to the search record, inverse-mapping the hit coordinate and reporting the segment’s retained source index. Returns FALSE without changing the record if no segment improves it. Borrows geometry.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
linePtr – [in] Borrowed line with current mapped geometry and synchronized source slots; no ownership is transferred.
searchPtr – [inout] Initialized query and best-hit record; only a strictly closer candidate replaces its distance, element, index and coordinate.
distProc – [in] Required script-free segment metric; must write its closest point whenever the returned distance can improve the query.
-
static void ClosestMappedPoint(Line *linePtr, ClosestSearch *searchPtr)
Search retained original centers inside the plot rectangle.
Ignores centers outside unpadded graph extents even if part of their symbol could be visible. SEARCH_BOTH uses Euclidean distance; SEARCH_X and SEARCH_Y use absolute screen X and Y distances respectively. Strict improvements retain source indices and recover data coordinates from the source adapter. Requires current mapped arrays and source data; does not synchronize them.
- Parameters:
linePtr – [in] Borrowed line with current mapped geometry and synchronized source slots; no ownership is transferred.
searchPtr – [inout] Initialized query and best-hit record; only a strictly closer candidate replaces its distance, element, index and coordinate.
-
static void ClosestSourcePoint(Graph *graphPtr, Line *linePtr, ClosestSearch *searchPtr)
Search original samples when mapped centers were omitted.
Maps finite source samples on demand and applies the same viewport and point-distance rules as ClosestMappedPoint. May build/use the decimation cache to restrict the source interval, then commits only a strict improvement. Reads source data without invoking Tcl callbacks.
Candidate pruning uses the screen coordinate onto which data X maps: SEARCH_X normally, SEARCH_Y when inverted, or SEARCH_BOTH in either orientation. Other directional queries must search the full source range.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
linePtr – [inout] Live line with synchronized source arrays and current mapping state; source picking may allocate or replace cache summaries.
searchPtr – [inout] Initialized query and best-hit record; only a strictly closer candidate replaces its distance, element, index and coordinate.
-
static void ClosestPoint(Graph *graphPtr, Line *linePtr, ClosestSearch *searchPtr)
Dispatch exact point picking according to map completeness.
Uses retained mapped centers unless pointMapOmitted requests an original source search. Borrows all inputs and updates the search record only through the selected helper. The source path may allocate a decimation cache.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
linePtr – [inout] Live line with synchronized source arrays and current mapping state; source picking may allocate or replace cache summaries.
searchPtr – [inout] Initialized query and best-hit record; only a strictly closer candidate replaces its distance, element, index and coordinate.
-
static void ClosestLine(Graph *graphPtr, Element *elemPtr, ClosestSearch *searchPtr)
Select point or interpolated picking for a line-family element.
SEARCH_AUTO selects traces only with more than one point and positive normal-pen trace width. Point mode uses ClosestPoint; trace mode chooses an intersection or Euclidean metric and dispatches strip versus connected geometry by element class. Directional trace searches fall back to points when no segment improves the incoming result; SEARCH_BOTH does not. Requires current geometry and the owning graph/track viewport.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
elemPtr – [inout] Live line-family element with current geometry and sources; source picking may rebuild its cache.
searchPtr – [inout] Initialized query and best-hit record; only a strictly closer candidate replaces its distance, element, index and coordinate.
-
static int AppendLineParamClosestInfo(Graph *graphPtr, Line *linePtr, const ClosestSearch *searchPtr, Tcl_Obj *resultObjPtr)
Append a safe source-index parameter value when available.
Omits param without error while a named parameter vector has pending notification, lengths differ, storage is absent, or the hit index is invalid. Otherwise inserts the value at the reported source index, even for an interpolated geometric hit. Does not interpolate the parameter, synchronize the vector, or publish interpreter variables. Returns dictionary status.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the interpreter for dictionary diagnostics.
linePtr – [in] Borrowed line with current mapped geometry and synchronized source slots; no ownership is transferred.
searchPtr – [in] Borrowed completed hit with original source index and plotted Cartesian coordinate; not modified.
resultObjPtr – [inout] Borrowed unshared result dictionary; inserted fields are retained, and earlier fields survive a later error.
-
static int LineClosestInfo(Graph *graphPtr, Element *elemPtr, const ClosestSearch *searchPtr, Tcl_Obj *resultObjPtr)
Collect optional line/strip parameter metadata.
Delegates to AppendLineParamClosestInfo using the borrowed hit record and writable result dictionary. No array traces run during this collection phase. The common closest handler owns later publication and dictionary lifetime.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the interpreter for dictionary diagnostics.
elemPtr – [in] Borrowed line-family core with current geometry, sources and configured pens.
searchPtr – [in] Borrowed completed hit with original source index and plotted Cartesian coordinate; not modified.
resultObjPtr – [inout] Borrowed unshared result dictionary; inserted fields are retained, and earlier fields survive a later error.
-
static int PolarClosestInfo(Graph *graphPtr, Element *elemPtr, const ClosestSearch *searchPtr, Tcl_Obj *resultObjPtr)
Collect polar or Smith metadata from the plotted hit coordinate.
Appends optional source-index param first. Finite Cartesian hit coordinates produce radius, a nonnegative radian angle normalized below a full turn, and source dataFormat. A zero radius produces zero angle. Nonfinite hit coordinates omit these fields without error.
Smith representation additionally inserts gamma and z0, then normalized and physical impedance/admittance when their conversion succeeds. Impedance scales by z0 and admittance divides by z0. Metadata describes the geometric hit, except param which follows the source index. Returns the first Tcl dictionary error without rolling back preceding fields. Does not publish variables or invoke application callbacks.
- Parameters:
graphPtr – [in] Borrowed owning graph supplying the interpreter for dictionary diagnostics.
elemPtr – [in] Borrowed line-family core with current geometry, sources and configured pens.
searchPtr – [in] Borrowed completed hit with original source index and plotted Cartesian coordinate; not modified.
resultObjPtr – [inout] Borrowed unshared result dictionary; inserted fields are retained, and earlier fields survive a later error.
-
static void DrawTraces(Graph *graphPtr, Drawable drawable, Line *linePtr, LinePen *penPtr)
Draw connected traces through one screen stroke context.
Borrows the pen and line geometry. Begins a trace stroke using GC, color, width and dashes, resolving default off-dash color to the trace color. Draws every stored polyline and ends the context. A NULL context silently skips drawing. Geometry and pen ownership remain with the element.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
linePtr – [in] Borrowed line with current mapped geometry and synchronized source slots; no ownership is transferred.
penPtr – [in] Borrowed configured line pen; colors, GCs, bitmap and text resources remain owned by the pen.
-
static void DrawRenderedStrips(Graph *graphPtr, Drawable drawable, LinePen *penPtr, const Segment2D *segments, Tcl_Size count)
Draw independent segments through one screen stroke context.
Borrows the pen and segment array for the duration of the call. Resolves default off-dash color, begins a strip stroke, submits the segment batch and ends the context. A NULL context skips the batch. Does not remap geometry or retain the array beyond the call.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
penPtr – [in] Borrowed configured line pen; colors, GCs, bitmap and text resources remain owned by the pen.
segments – [in] Borrowed array of count mapped segments, unchanged and not retained after drawing.
count – [in] Nonnegative number of readable entries in the supplied geometry array.
-
static int SetClosestInfoObj(Tcl_Interp *interp, Tcl_Obj *resultObjPtr, const char *name, Tcl_Obj *valueObjPtr)
Line symbol and output dispatch
See Element data and dispatch for sampling, renderer fallback and label lifetime rules. These are private adapters; the namespace below is documentation-only.
- group Line symbol and output dispatch
Private screen/export adapters, palette sampling and label lifetimes.
Functions
-
static int GetRenderedSymbolShape(SymbolType type, int size, Rbc_RenderShape *shape)
Build an origin-centered geometric symbol template.
Zeros the caller-owned shape and fills circle, polygon or independent segment geometry using native proportions and integer rounding. Returns FALSE for unsupported types, including bitmap and none; such output is not a usable template. Borrows no persistent storage and performs no allocation.
-
static int DrawRenderedPoints(Graph *graphPtr, Drawable drawable, LinePen *penPtr, int size, Tcl_Size count, const Point2D *points, int targetWidth, int targetHeight)
Handle tiny Cairo symbols as filled points.
Returns FALSE unless Cairo is selected and size is below three, or when context creation fails, allowing fallback. A missing effective fill color or nonpositive count is successfully handled without drawing. Resolves default fill to trace color and uses explicit drawable dimensions when supplied. Draws all centers without symbol-interval filtering, then ends the context.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
penPtr – [in] Borrowed configured line pen; colors, GCs, bitmap and text resources remain owned by the pen.
size – [in] Symbol size in mapped pixels, already scaled and bounded by the caller.
count – [in] Nonnegative number of readable entries in the supplied geometry array.
points – [in] Borrowed array of count mapped points; retained only for this call.
targetWidth – [in] Positive explicit drawable width, or zero to use the graph target.
targetHeight – [in] Positive explicit drawable height when targetWidth is positive; otherwise zero.
-
static int DrawRenderedBitmapSymbols(Graph *graphPtr, Drawable drawable, Line *linePtr, LinePen *penPtr, int size, Tcl_Size nPoints, const Point2D *points, int targetWidth, int targetHeight)
Draw a Cairo bitmap-symbol pass with shared scaled resources.
Requires Cairo, a bitmap symbol, size at least three, positive count and an effective foreground. Scales bitmap and optional mask once. Transparent background uses the bitmap itself as mask. Releases temporary pixmaps after context creation; renderer setup captures the required image data.
Returns FALSE on ineligibility or setup failure for caller fallback. Submits selected centers in batches of 256, advancing the shared symbol counter only for plot drawing with a positive interval. Explicit drawable targets bypass that interval. Ends the context and returns TRUE after handling the pass.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
linePtr – [inout] Live line supplying the shared symbol interval/counter; plot drawing advances the counter, explicit targets bypass it.
penPtr – [in] Borrowed configured line pen; colors, GCs, bitmap and text resources remain owned by the pen.
size – [in] Symbol size in mapped pixels, already scaled and bounded by the caller.
nPoints – [in] Nonnegative number of readable point entries.
points – [in] Borrowed array of nPoints mapped centers in the destination coordinate system.
targetWidth – [in] Positive explicit drawable width, or zero to use the graph target.
targetHeight – [in] Positive explicit drawable height when targetWidth is positive; otherwise zero.
-
static int DrawRenderedSymbols(Graph *graphPtr, Drawable drawable, Line *linePtr, LinePen *penPtr, int size, Tcl_Size nSymbolPts, const Point2D *symbolPts)
Draw geometric Cairo symbols in fill and outline passes.
Returns FALSE for non-Cairo, tiny/unsupported shapes or failed context creation. Resolves default colors from the trace pen. Segment symbols omit fill and retain a hairline outline even at configured width zero.
Each pass starts from the same counter so fill and outline select identical centers. Uses batches of 256 and advances the line counter once for the whole input when an interval is active. Ends the context and returns TRUE; geometry and pen resources remain borrowed.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
linePtr – [inout] Live line supplying the shared symbol interval/counter; drawing may advance the counter.
penPtr – [in] Borrowed configured line pen; colors, GCs, bitmap and text resources remain owned by the pen.
size – [in] Symbol size in mapped pixels, already scaled and bounded by the caller.
nSymbolPts – [in] Nonnegative number of readable symbol-center entries, and of parallel indices when supplied.
symbolPts – [in] Borrowed array of nSymbolPts mapped centers; remains unchanged and is not retained after drawing.
-
static void DrawRenderedErrorBars(Graph *graphPtr, Drawable drawable, LinePen *penPtr, const Segment2D *segments, Tcl_Size count)
Submit solid screen error-bar segments through a stroke context.
Resolves default error-bar color to trace color and uses at least unit width for renderer stroke setup while retaining the native GC. Begins and ends one segment context; NULL context skips drawing. Borrows all arrays and pen resources and does not apply symbol sampling here.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
penPtr – [in] Borrowed configured line pen; colors, GCs, bitmap and text resources remain owned by the pen.
segments – [in] Borrowed array of count mapped segments, unchanged and not retained after drawing.
count – [in] Nonnegative number of readable entries in the supplied geometry array.
-
static void DrawSymbolsUnclipped(Graph *graphPtr, Drawable drawable, Line *linePtr, LinePen *penPtr, int size, Tcl_Size nSymbolPts, Point2D *symbolPts)
Dispatch native symbol drawing and retain its sampling counter.
Builds a temporary native style from the pen’s GCs, bitmap, mask, interval and counter. Submits borrowed centers through a native symbol context, ends it and copies the updated style counter back to the line. Does not establish a plot clip; callers must supply an appropriate target/clip.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
linePtr – [inout] Live line supplying the shared symbol interval/counter; drawing may advance the counter.
penPtr – [in] Borrowed configured line pen; colors, GCs, bitmap and text resources remain owned by the pen.
size – [in] Symbol size in mapped pixels, already scaled and bounded by the caller.
nSymbolPts – [in] Nonnegative number of readable symbol-center entries, and of parallel indices when supplied.
symbolPts – [in] Borrowed array of nSymbolPts mapped centers; remains unchanged and is not retained after drawing.
-
static void DrawSymbols(Graph *graphPtr, Drawable drawable, Line *linePtr, LinePen *penPtr, int size, Tcl_Size nSymbolPts, Point2D *symbolPts)
Draw plot symbols with renderer fallbacks and boundary clipping.
Skips empty arrays and SYMBOL_NONE. Tries tiny Cairo points, Cairo bitmaps and Cairo geometric symbols in order. If none handles the pass, bounds the plot rectangle by the drawable and checks conservative symbol padding.
Wholly interior native batches draw directly. Boundary batches use a screen clip context and its target drawable, then end clip and context. Empty clips skip drawing. Borrows centers and pen resources; helpers may advance the line’s shared sampling counter.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
linePtr – [inout] Live line supplying the shared symbol interval/counter; drawing may advance the counter.
penPtr – [in] Borrowed configured line pen; colors, GCs, bitmap and text resources remain owned by the pen.
size – [in] Symbol size in mapped pixels, already scaled and bounded by the caller.
nSymbolPts – [in] Nonnegative number of readable symbol-center entries, and of parallel indices when supplied.
symbolPts – [in] Borrowed array of nSymbolPts mapped centers; remains unchanged and is not retained after drawing.
-
static void DrawSymbol(Graph *graphPtr, Drawable drawable, Element *elemPtr, int x, int y, int size, int width, int height)
Draw one legend sample into an explicitly sized drawable.
Uses the normal pen to draw a trace sample and optional centered symbol. The trace uses two adjacent segments, with a native legend-line fallback if context creation fails. Symbols try tiny points, bitmap rendering and geometric templates before native fallback. Does not establish a plot clip or remap source data; width/height describe the legend target.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
elemPtr – [inout] Live line-family element supplying its normal pen; native fallback can update its symbol counter.
x – [in] Legend sample center X in target pixels.
y – [in] Legend sample center Y in target pixels.
size – [in] Symbol size in mapped pixels, already scaled and bounded by the caller.
width – [in] Positive width of the legend drawable in pixels.
height – [in] Positive height of the legend drawable in pixels.
-
static void DrawValues(Graph *graphPtr, Drawable drawable, Line *linePtr, LinePen *penPtr, Tcl_Size nSymbolPts, Point2D *symbolPts, const Tcl_Size *pointToData, Tcl_Size interval, Tcl_Size offset)
Render sampled value labels at mapped centers on screen.
Borrows point and parallel source-index arrays. Applies interval/offset selection and unpadded viewport filtering before obtaining source values. Rbc_GetElementValueLabel returns one retained Tcl object per label; this routine releases it even when empty. Offset positions outside integer range are skipped; accepted coordinates are converted to integers for screen text.
Owns and ends one text context. Label commands can run Tcl: callers must keep drawing records, arrays and pens stable, and callbacks must not mutate drawing state or enter nested event processing. This loop adds no lifetime or reentrancy guard.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
linePtr – [in] Borrowed line with synchronized source slots and current viewport; owner and arrays must survive every label callback.
penPtr – [in] Borrowed value-label pen; formatting objects and text resources must remain stable during callbacks.
nSymbolPts – [in] Nonnegative number of readable symbol-center entries, and of parallel indices when supplied.
symbolPts – [in] Borrowed nSymbolPts mapped centers, stable throughout callbacks; screen or export mapping must match the destination.
pointToData – [in] Borrowed parallel array of nSymbolPts original source indices, stable throughout label callbacks.
interval – [in] Sampling interval; values at most one select every center.
offset – [in] Nonnegative number of preceding centers in the palette traversal, used to continue label sampling across slices.
-
static void DrawActiveLine(Graph *graphPtr, Drawable drawable, Element *elemPtr)
Draw explicit active points or the whole active element.
Returns when there is no active pen. Positive active count refreshes pending active geometry and draws its symbols/labels only. Negative count draws the whole mapped trace or strip plus symbols/labels; zero draws nothing. Uses the scaled active symbol size. Does not draw fills or error bars. Value-label callbacks have the same stability requirements as DrawValues.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
elemPtr – [inout] Live mapped line-family core; active geometry and symbol-scale baselines may be refreshed. Keep resources stable during label callbacks.
-
static int DrawRenderedFill(Graph *graphPtr, Drawable drawable, const Point2D *points, Tcl_Size count, XColor *foreground, XColor *background, GC gc, Rbc_Tile tile, Pixmap stipple, double opacity)
Attempt a Cairo tile or pattern fill before native fallback.
Returns FALSE outside Cairo. A supplied tile takes precedence: obtains its photo block and delegates tile drawing, without trying the pattern if that fails. With no tile, None stipple declines the operation; missing foreground is recovered from the native GC. PATTERN_SOLID becomes no renderer stipple. Forwards pattern opacity; tile transparency comes from the image itself. Borrows geometry/resources and returns whether the renderer handled the fill.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
points – [in] Borrowed mapped polygon of count vertices; clipping and mapping are caller responsibilities.
count – [in] Nonnegative number of readable entries in the supplied geometry array.
foreground – [in] Borrowed resolved fill color, or NULL to recover the foreground from gc.
background – [in] Borrowed optional pattern background color; NULL selects transparent stippling.
gc – [in] Borrowed native fill GC used to recover a missing foreground; must be valid if that fallback is needed.
tile – [in] Borrowed tile client, or NULL; a supplied tile takes precedence over pattern and opacity.
stipple – [in] Borrowed pattern bitmap, PATTERN_SOLID, or None to decline an untiled fill.
opacity – [in] Validated finite pattern opacity in 0..1; tile drawing instead uses the image transparency.
-
static Tcl_Size SymbolInterval(Line *linePtr)
Compute the shared screen/export symbol sampling interval.
Returns zero when no positive requested maximum exists. Otherwise sums palette symbol counts and returns integer division by the requested maximum. Zero and one both select all centers in normal use. This is a density interval, not a strict maximum-count guarantee. Does not mutate the line.
- Parameters:
linePtr – [in] Borrowed line with current per-style symbol counts and requested maximum; no counters are changed.
-
static void DrawNormalLine(Graph *graphPtr, Drawable drawable, Element *elemPtr)
Draw mapped fills, strokes and palette annotations on screen.
Draws area then error-band polygons, followed by palette strip strokes or the normal-pen connected traces. Initializes shared symbol interval/counter, then draws each style’s enabled error bars, symbols and value labels. Styles without symbols still advance the interval counter; label offsets track the parallel source-index slices. Resets symbolInterval on completion.
Borrows mapped geometry and configured resources. Label callbacks require stable drawing state; this function does not protect iteration from mutation.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
drawable – [in] Borrowed compatible window or pixmap destination; coordinates use its drawing origin.
elemPtr – [inout] Live mapped line-family core; symbol interval/counter change during traversal. Keep arrays, palette and pens stable during label callbacks.
-
static void SymbolsExport(Graph *graphPtr, Rbc_ExportContext *exportPtr, LinePen *penPtr, int size, Tcl_Size nSymbolPts, Point2D *symbolPts, Tcl_Size interval, Tcl_Size *counterPtr)
Export sampled symbols using a resolved renderer symbol style.
Borrows pen and center arrays, skipping none/empty symbols. Resolves default colors and passes bitmap/mask and size to an export-symbol context. For interval greater than one, requires a writable counter, advances it for every input and submits selected centers. Otherwise submits the full batch without touching the counter, which may be NULL. Ends the context.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
exportPtr – [inout] Borrowed document output context; geometry must already match its export mapping. This call does not end the document.
penPtr – [in] Borrowed configured line pen; colors, GCs, bitmap and text resources remain owned by the pen.
size – [in] Symbol size in mapped pixels, already scaled and bounded by the caller.
nSymbolPts – [in] Nonnegative number of readable symbol-center entries, and of parallel indices when supplied.
symbolPts – [in] Borrowed array of nSymbolPts mapped centers; remains unchanged and is not retained after drawing.
interval – [in] Sampling interval; values at most one select every center.
counterPtr – [inout] Sampling position across preceding batches; required for interval greater than one, otherwise unused and may be NULL.
-
static void SymbolExport(Graph *graphPtr, Rbc_ExportContext *exportPtr, Element *elemPtr, double x, double y, int size)
Export a normal-pen legend sample.
Emits an optional trace segment spanning twice the supplied size, with trace width increased by two and butt/miter stroke settings, then exports one centered symbol without sampling. Borrows the pen and export context; does not use the screen legend’s two-segment construction.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
exportPtr – [inout] Borrowed document output context; geometry must already match its export mapping. This call does not end the document.
elemPtr – [in] Borrowed line-family core with current geometry, sources and configured pens.
x – [in] Legend center X in export-mapped coordinates.
y – [in] Legend center Y in export-mapped coordinates.
size – [in] Symbol size in mapped pixels, already scaled and bounded by the caller.
-
static Rbc_RenderContext *BeginLineExport(Rbc_ExportContext *exportPtr, LinePen *penPtr)
Create an export stroke context for a line pen.
Uses trace color, width and dashes with butt caps and miter joins, then sets the optional off-dash background. Returns the renderer context for the caller to end. Does not own the pen or alter mapped geometry.
- Parameters:
exportPtr – [inout] Borrowed document output context; geometry must already match its export mapping. This call does not end the document.
penPtr – [in] Borrowed configured line pen; colors, GCs, bitmap and text resources remain owned by the pen.
-
static void TracesExport(Rbc_ExportContext *exportPtr, Line *linePtr, LinePen *penPtr)
Export all connected traces through one pen stroke context.
Begins a line export context, submits each borrowed trace polyline in chain order and ends the context. Does not resample, remap or take ownership of trace arrays; export preparation must supply the desired geometry.
- Parameters:
exportPtr – [inout] Borrowed document output context; geometry must already match its export mapping. This call does not end the document.
linePtr – [in] Borrowed line with current mapped geometry and synchronized source slots; no ownership is transferred.
penPtr – [in] Borrowed configured line pen; colors, GCs, bitmap and text resources remain owned by the pen.
-
static void ValuesExport(Rbc_ExportContext *exportPtr, Line *linePtr, LinePen *penPtr, Tcl_Size nSymbolPts, Point2D *symbolPts, const Tcl_Size *pointToData, Tcl_Size interval, Tcl_Size offset)
Export sampled labels using double-precision mapped positions.
Applies the same interval/offset, viewport and source-value filtering as screen labels. Creates one output context and releases each retained label object after use. Exports center plus offset without screen integer conversion.
Label callbacks may execute Tcl and require stable element, pen and mapping storage. Does not guard against callback mutation or nested event processing. Ends the output context; owns neither the export destination nor input arrays.
- Parameters:
exportPtr – [inout] Borrowed document output context; geometry must already match its export mapping. This call does not end the document.
linePtr – [in] Borrowed line with synchronized source slots and current viewport; owner and arrays must survive every label callback.
penPtr – [in] Borrowed value-label pen; formatting objects and text resources must remain stable during callbacks.
nSymbolPts – [in] Nonnegative number of readable symbol-center entries, and of parallel indices when supplied.
symbolPts – [in] Borrowed nSymbolPts mapped centers, stable throughout callbacks; screen or export mapping must match the destination.
pointToData – [in] Borrowed parallel array of nSymbolPts original source indices, stable throughout label callbacks.
interval – [in] Sampling interval; values at most one select every center.
offset – [in] Nonnegative number of preceding centers in the palette traversal, used to continue label sampling across slices.
-
static void ActiveLineExport(Graph *graphPtr, Rbc_ExportContext *exportPtr, Element *elemPtr)
Export explicit active symbols or whole-element highlighting.
With an active pen, positive active count refreshes pending active geometry and exports symbols/labels. Negative count exports available strips/traces, symbols and labels for the whole element. Zero count or absent pen emits nothing. Uses scaled active size and no symbol sampling. Does not export active fills/error bars. Label callbacks require stable drawing resources.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
exportPtr – [inout] Borrowed document output context; geometry must already match its export mapping. This call does not end the document.
elemPtr – [inout] Live mapped line-family core; active geometry and symbol-scale baselines may be refreshed. Keep resources stable during label callbacks.
-
static void NormalLineExport(Graph *graphPtr, Rbc_ExportContext *exportPtr, Element *elemPtr)
Export mapped fills, strokes and palette annotations in order.
Exports area then error-band polygons through fill contexts, including tile, pattern and opacity policy handled by the backend. Exports palette strip strokes or normal-pen connected traces, then enabled error bars, symbols and labels per style. Shares a local symbol interval/counter across styles and keeps label source-index offsets aligned with palette slices.
Borrows geometry already prepared for export; does not disable decimation or remap here. Backend-specific fill behavior remains in the renderer. Value-label callbacks require stable drawing state throughout traversal.
- Parameters:
graphPtr – [in] Borrowed owning graph with the element or track viewport and axis mappings already installed.
exportPtr – [inout] Borrowed document output context; geometry must already match its export mapping. This call does not end the document.
elemPtr – [in] Borrowed line-family core already mapped for export; all geometry, palette and pen storage must remain stable during label callbacks.
-
static int GetRenderedSymbolShape(SymbolType type, int size, Rbc_RenderShape *shape)
Line configuration and smoothing
See Element data and dispatch for staged configuration, resampling boundaries and the reference-impedance validation boundary. This namespace disambiguates private names only.
- group Line configuration and smoothing
Private configuration orchestration, resampling and scalar adapters.
Functions
-
static int IsLinePenPrefix(const char *string, Tcl_Size length, const char *fullName)
Recognize a nonempty case-sensitive prefix of a pen keyword.
Compares the supplied byte length with the full keyword and then strncmp. Borrows both strings; returns FALSE for empty or overlong prefixes. Does not perform abbreviation disambiguation against other keywords.
- Parameters:
string – [in] Borrowed prefix bytes, readable for length bytes when the length passes the keyword bounds check.
length – [in] Prefix byte count; nonpositive or longer-than-keyword counts return FALSE.
fullName – [in] Borrowed NUL-terminated complete keyword.
-
static int GetLinePenColorFromObj(Tcl_Interp *interp, Tk_Window tkwin, Tcl_Obj *objPtr, int allowNull, XColor **colorPtrPtr)
Resolve a nullable pen color or the default-color sentinel.
NULL/empty input succeeds with NULL only when allowNull is true. A nonempty prefix of defcolor produces COLOR_DEFAULT without acquiring a Tk color. Other strings acquire a Tk color reference for the caller to release through FreeLinePenColor. On error returns TCL_ERROR with a diagnostic and leaves the output pointer unchanged. Does not retain the input Tcl object.
- 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 color name or defcolor prefix; NULL and empty inputs follow allowNull.
allowNull – [in] Nonzero permits a NULL result for empty input; zero reports an error.
colorPtrPtr – [out] Required result slot for NULL, COLOR_DEFAULT or an acquired Tk color; unchanged on error.
-
static void ClearLineVectorChanges(Line *linePtr)
Consume recorded X/Y source-change metadata.
Clears pending/all flags and changed bounds in the element’s X and Y slots. Does not deliver or cancel vector notifications, replace values, or clear metadata in other slots. Mapping calls this after handling cache refresh.
- Parameters:
linePtr – [inout] Live line whose X/Y pending-change flags and bounds are cleared after cache handling.
-
static int ComplexDivide(double nr, double ni, double dr, double di, double *realPtr, double *imagPtr)
Divide finite complex inputs using a denominator component ratio.
Chooses the larger denominator component to form the ratio. Returns FALSE for nonfinite inputs, zero denominator or nonfinite computed output. Early rejection leaves outputs unchanged; final finiteness rejection can leave computed nonfinite outputs, so callers must honor the return value. This formulation does not guarantee overflow-free arithmetic for all finite extreme inputs. Borrows scalar inputs and writes only the output doubles.
- Parameters:
nr – [in] Real numerator component.
ni – [in] Imaginary numerator component.
dr – [in] Real denominator component; the complex denominator must be nonzero.
di – [in] Imaginary denominator component.
realPtr – [out] Required real-quotient destination, distinct from imagPtr; consume only on TRUE.
imagPtr – [out] Required imaginary-quotient destination, distinct from realPtr; consume only on TRUE.
-
static int GammaToNormalizedImpedance(double gammaReal, double gammaImag, double *resistancePtr, double *reactancePtr)
Convert reflection coefficient to normalized impedance.
Computes (1 + gamma)/(1 - gamma) through ComplexDivide, except exact (+1, 0), which succeeds with (HUGE_VAL, 0) for an open circuit. TRUE therefore does not imply finite output. Failure follows ComplexDivide output rules. No physical reference-impedance scaling is performed here.
- Parameters:
gammaReal – [in] Real component of the dimensionless reflection coefficient.
gammaImag – [in] Imaginary component of the dimensionless reflection coefficient.
resistancePtr – [out] Required real-part output in normalized units; may be positive infinity on a successful singular case. Consume only on TRUE.
reactancePtr – [out] Required separate imaginary-part output in normalized units; consume only on TRUE.
-
static int GammaToNormalizedAdmittance(double gammaReal, double gammaImag, double *conductancePtr, double *susceptancePtr)
Convert reflection coefficient to normalized admittance.
Computes (1 - gamma)/(1 + gamma) through ComplexDivide, except exact (-1, 0), which succeeds with (HUGE_VAL, 0) for a short circuit. TRUE therefore does not imply finite output. Physical admittance scaling belongs to the caller; failed division outputs must not be consumed.
- Parameters:
gammaReal – [in] Real component of the dimensionless reflection coefficient.
gammaImag – [in] Imaginary component of the dimensionless reflection coefficient.
conductancePtr – [out] Required real-part output in normalized units; may be positive infinity on a successful singular case. Consume only on TRUE.
susceptancePtr – [out] Required separate imaginary-part output in normalized units; consume only on TRUE.
-
static int Round(double x)
Round a bounded double to an integer with halfway cases away from zero.
Adds or subtracts one half and casts to int. Caller must provide a finite value whose adjusted result is representable; this helper neither clamps nor reports overflow. Used for native-compatible screen geometry.
- Parameters:
x – [in] Finite value whose adjustment by plus or minus one half remains representable as int; no overflow check is performed.
-
static double PixelAbscissa(Graph *graphPtr, const Point2D *pointPtr)
Select the physical screen coordinate along mapped data X.
Returns screen X normally and screen Y when inverted. Does not undo axis descending direction or perform an inverse transform. Borrows both inputs.
- Parameters:
graphPtr – [in] Borrowed graph supplying only the inversion flag.
pointPtr – [in] Borrowed mapped point in graph-window pixels.
-
static double PixelOrdinate(Graph *graphPtr, const Point2D *pointPtr)
Select the screen coordinate perpendicular to mapped data X.
Returns screen Y normally and screen X when inverted. Pixel buckets use its extrema to preserve the visible envelope. Does not change sign or recover data coordinates.
- Parameters:
graphPtr – [in] Borrowed graph supplying only the inversion flag.
pointPtr – [in] Borrowed mapped point in graph-window pixels.
-
static double MapLineDataAbscissa(Graph *graphPtr, Line *linePtr, double x)
Map a source X value to its physical screen coordinate.
Uses horizontal axis mapping normally and vertical mapping when inverted, with the element’s X axis and current graph viewport. Borrows graph/line state; does not validate the source or establish the viewport.
- Parameters:
graphPtr – [in] Borrowed graph with the active viewport and inversion state already installed.
linePtr – [in] Borrowed line supplying its prepared X axis.
x – [in] Raw data-X value, not a screen coordinate or logarithmic exponent.
-
static void GenerateSpline(Graph *graphPtr, Line *linePtr, MapInfo *mapPtr)
Resample a continuous run as a function of mapped data X.
Requires a nonempty map with valid source indices and no internal breaks. Natural/quadratic smoothing uses screen X normally or screen Y when inverted. Reflects decreasing abscissas into increasing canonical coordinates without reordering source indices. Retains every knot and adds visible pixel samples; inserted samples inherit the starting knot’s source index.
Commits replacement arrays only after interpolation succeeds. Size/allocation or evaluator failures preserve the input and set effective smoothing to none. Early exits for fewer than three points, nonmonotonic/equal abscissas, an invisible interval or empty screen span leave both input and effective mode unchanged. Thus the effective flag alone does not prove smoothing occurred. Does not alter reqSmooth or report Tcl errors; break handling belongs to GenerateSplineRuns.
- Parameters:
graphPtr – [in] Owning graph supplying current mapped plot bounds and orientation.
linePtr – [inout] Owning line element; effective smooth may fall back to none, while reqSmooth is retained.
mapPtr – [inout] Nonempty owned mapped geometry with parallel source indices. Successful replacement frees old arrays; failure retains them.
-
static void GenerateParametricSpline(Graph *graphPtr, Line *linePtr, MapInfo *mapPtr)
Resample a continuous run by source interval and local parameter.
Requires nonempty finite mapped geometry with parallel source indices and no internal breaks. Retains knots and adds samples approximately every two pixels along visible portions of original straight segments. Evaluation parameters identify the source interval and its normalized position; inserted samples report the interval’s starting source index.
Selects natural, quadratic or Catmull-Rom evaluation from effective smooth. Replaces point/index arrays only after successful evaluation. Size, allocation, capacity or evaluator failure frees candidates, retains original arrays and sets effective smoothing to none, leaving reqSmooth unchanged. Sample density uses the original segments, not an adaptive bound on the curved result.
- Parameters:
graphPtr – [in] Owning graph supplying current mapped plot bounds and orientation.
linePtr – [inout] Owning line element; effective smooth may fall back to none, while reqSmooth is retained.
mapPtr – [inout] Nonempty owned mapped geometry with parallel source indices. Successful replacement frees old arrays; failure retains them.
-
static int ConfigureLine(Graph *graphPtr, Element *elemPtr)
Prepare and commit line-family derived configuration state.
Borrows a live element with Tk option candidates already installed and the changed-option mask/argument order available. Validates opacity and data-mode restrictions; stages common data, complex data, parameters, pens, axes, state, tags, styles, scalars and fill resources as required. Validates prospective parameter lengths and error-band smoothing, then configures the built-in pen.
Validates polar reference impedance before configuring the embedded pen or transferring staged state. Commits non-data transactions, synchronizes the first palette pen, then commits staged data. Successful completion sets mapping flags. The enclosing caller restores Tk options on error.
Error cleanup releases still-owned staged resources and returns TCL_ERROR. It does not undo already committed derived state, restore Tk options itself, or make application callbacks during parsing generally reentrant.
- Parameters:
graphPtr – [inout] Borrowed owning graph; staged resource operations use its live window and interpreter, and commits may update graph state.
elemPtr – [inout] Live line-family core with Tk candidates and changed-option metadata installed; caller owns rollback of those Tk values on error.
-
static int IsLinePenPrefix(const char *string, Tcl_Size length, const char *fullName)
Data records and member contracts
These records describe stored state and resource ownership. Their presence in the reference does not make private layouts part of the installed C API.
-
struct ElementOpSpec
Typed command dispatch entry with shared argument validation metadata.
Public Members
-
Rbc_OpSpecHeader header
Operation name, total argument bounds and usage suffix.
-
RbcGrElementOp *proc
Typed command handler for this operation.
-
Rbc_OpSpecHeader header
-
struct ElemAxisTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
-
struct ElemDataTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
Public Members
-
unsigned int stagedMask
Bit mask selecting staged replacements to commit or release.
-
ElemVector x
Replacement X-data descriptor staged for commit or abort.
-
ElemVector y
Replacement Y-data descriptor staged for commit or abort.
-
ElemVector w
Replacement weight-data descriptor staged for commit or abort.
-
ElemVector xError
Replacement symmetric X-error data staged for commit or abort.
-
ElemVector xHigh
Replacement explicit X-high data staged for commit or abort.
-
ElemVector xLow
Replacement explicit X-low data staged for commit or abort.
-
ElemVector yError
Replacement symmetric Y-error data staged for commit or abort.
-
ElemVector yHigh
Replacement explicit Y-high data staged for commit or abort.
-
ElemVector yLow
Replacement explicit Y-low data staged for commit or abort.
-
unsigned int stagedMask
-
struct ElemPenTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
-
struct ElemStateTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
-
struct ElemStylesTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
-
struct ElemTagsTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
Implementation selectors
-
enum Smoothing
Selects construction of the mapped trace; the final value terminates the smoothing-name map.
Values:
-
enumerator PEN_SMOOTH_NONE
-
enumerator PEN_SMOOTH_STEP
-
enumerator PEN_SMOOTH_NATURAL
-
enumerator PEN_SMOOTH_QUADRATIC
-
enumerator PEN_SMOOTH_CATROM
-
enumerator PEN_SMOOTH_LAST
-
enumerator PEN_SMOOTH_NONE
-
enum LineDecimation
Selects full or automatically reduced screen geometry; source indices still refer to original data.
Values:
-
enumerator LINE_DECIMATE_NONE
-
enumerator LINE_DECIMATE_AUTO
-
enumerator LINE_DECIMATE_NONE
-
enum SymbolType
Selects the concrete point-symbol geometry or bitmap used by a line pen.
Values:
-
enumerator SYMBOL_NONE
-
enumerator SYMBOL_SQUARE
-
enumerator SYMBOL_CIRCLE
-
enumerator SYMBOL_DIAMOND
-
enumerator SYMBOL_PLUS
-
enumerator SYMBOL_CROSS
-
enumerator SYMBOL_SPLUS
-
enumerator SYMBOL_SCROSS
-
enumerator SYMBOL_TRIANGLE
-
enumerator SYMBOL_ARROW
-
enumerator SYMBOL_BITMAP
-
enumerator SYMBOL_NONE
-
enum LineDataMode
Distinguishes separate coordinate inputs from complex-vector input.
Values:
-
enumerator LINE_DATA_XY
-
enumerator LINE_DATA_COMPLEX
-
enumerator LINE_DATA_XY
-
enum LineSymbolPoints
Selects original or reduced points for symbol placement.
Values:
-
enumerator LINE_SYMBOL_POINTS_ALL
-
enumerator LINE_SYMBOL_POINTS_REDUCED
-
enumerator LINE_SYMBOL_POINTS_ALL
-
enum LineAreaClose
Selects how an area-fill polygon closes around its mapped trace.
Values:
-
enumerator LINE_AREA_BASELINE
-
enumerator LINE_AREA_CHORD
-
enumerator LINE_AREA_ORIGIN
-
enumerator LINE_AREA_BASELINE
-
enum LineDataCoordinates
Identifies the coordinate interpretation applied to line inputs.
Values:
-
enumerator LINE_COORDINATES_CARTESIAN
-
enumerator LINE_COORDINATES_POLAR
-
enumerator LINE_COORDINATES_CARTESIAN
-
enum LineComplexDataFormat
Selects how complex samples are interpreted on a Smith chart.
Values:
-
enumerator LINE_CDATA_GAMMA
-
enumerator LINE_CDATA_IMPEDANCE
-
enumerator LINE_CDATA_ADMITTANCE
-
enumerator LINE_CDATA_GAMMA
-
enum LineBandMode
Chooses the error dimension used to construct the band, or disables band construction.
Values:
-
enumerator LINE_BAND_NONE
-
enumerator LINE_BAND_Y
-
enumerator LINE_BAND_X
-
enumerator LINE_BAND_NONE
-
enum LineScalarOption
Selects a scalar field while validating requested line options before commit.
Values:
-
enumerator LINE_SCALAR_OPTION_NONE
-
enumerator LINE_SCALAR_OPTION_MAX_SYMBOLS
-
enumerator LINE_SCALAR_OPTION_SMOOTH
-
enumerator LINE_SCALAR_OPTION_TRACE
-
enumerator LINE_SCALAR_OPTION_NONE
-
enum LineAreaOption
Distinguishes the area pattern and tile resources staged by line configuration.
Values:
-
enumerator LINE_AREA_OPTION_NONE
-
enumerator LINE_AREA_OPTION_PATTERN
-
enumerator LINE_AREA_OPTION_TILE
-
enumerator LINE_AREA_OPTION_NONE
-
enum ElemDataOption
Identifies a paired or individual data slot while replaying element configuration arguments in order.
Values:
-
enumerator ELEM_DATA_OPTION_NONE
-
enumerator ELEM_DATA_OPTION_PAIRS
-
enumerator ELEM_DATA_OPTION_WEIGHTS
-
enumerator ELEM_DATA_OPTION_X
-
enumerator ELEM_DATA_OPTION_Y
-
enumerator ELEM_DATA_OPTION_X_ERROR
-
enumerator ELEM_DATA_OPTION_X_HIGH
-
enumerator ELEM_DATA_OPTION_X_LOW
-
enumerator ELEM_DATA_OPTION_Y_ERROR
-
enumerator ELEM_DATA_OPTION_Y_HIGH
-
enumerator ELEM_DATA_OPTION_Y_LOW
-
enumerator ELEM_DATA_OPTION_NONE
-
enum ElemPenOption
Selects the normal or active pen reference being staged.
Values:
-
enumerator ELEM_PEN_OPTION_NONE
-
enumerator ELEM_PEN_OPTION_ACTIVE
-
enumerator ELEM_PEN_OPTION_NORMAL
-
enumerator ELEM_PEN_OPTION_NONE