Coordinate mapping C reference
These private helpers borrow their graph, axes and track records. Callers prepare current layout and retain the records throughout the operation. See Axes, mapping and track viewports for coordinate conventions and scoped viewport usage.
Parameter directions use C calling conventions. Raw data, axis-space coordinates, normalized fractions and widget pixels are distinct inputs; the helper-stage table in Axes, mapping and track viewports links the internal range implementations in Axis control C reference.
Data and screen coordinates
-
double Rbc_HMap(Graph *graphPtr, Axis *axisPtr, double x)
Map a data value to a horizontal widget coordinate.
Uses the owning track’s full world extent when the axis has a track; otherwise uses the graph offset and range. Does not clip, round, update layout, or execute Tcl. Descending direction is applied after normalization.
- Parameters:
graphPtr – [in] Borrowed graph with current ranges and layout.
axisPtr – [in] Borrowed axis selecting the range, log scale and direction.
x – [in] Data value, before logarithmic conversion.
- Returns:
Double-precision pixel coordinate, or NAN for nonfinite input, invalid logarithmic input or failed normalization.
-
double Rbc_VMap(Graph *graphPtr, Axis *axisPtr, double y)
Map a data value to a vertical widget coordinate.
Uses the owning track’s full world extent when the axis has a track; otherwise uses the graph offset and range. Does not clip, round, update layout, or execute Tcl. Descending direction is applied after normalization.
- Parameters:
graphPtr – [in] Borrowed graph with current ranges and layout.
axisPtr – [in] Borrowed axis selecting the range, log scale and direction.
y – [in] Data value, before logarithmic conversion.
- Returns:
Double-precision pixel coordinate, or NAN for nonfinite input, invalid logarithmic input or failed normalization.
-
Point2D Rbc_Map2D(Graph *graphPtr, double x, double y, Axis2D *pairPtr)
Map a data-coordinate pair to widget pixels without clipping.
Inversion swaps which screen direction receives each logical axis. Axis ownership selects track geometry without entering a temporary track scope. Does not update layout, round coordinates, or execute Tcl.
- Parameters:
graphPtr – [in] Borrowed graph with current ranges and layout.
x – [in] X data value.
y – [in] Y data value.
pairPtr – [in] Borrowed pair containing non-NULL X and Y axes.
- Returns:
Point2D in widget coordinates; invalid components may be NAN.
-
Point2D Rbc_InvMap2D(Graph *graphPtr, double x, double y, Axis2D *pairPtr)
Map widget pixels back to logical data coordinates.
Coordinates outside the plot are extrapolated rather than clipped. Log conversion returns NAN outside the supported DBL_MIN to DBL_MAX interval. The caller must check results for finiteness. Does not update layout or execute Tcl, and does not acquire ownership of graph or axes.
- Parameters:
graphPtr – [in] Borrowed graph with current ranges and layout.
x – [in] Horizontal widget coordinate.
y – [in] Vertical widget coordinate.
pairPtr – [in] Borrowed pair containing non-NULL X and Y axes.
- Returns:
Point2D in data coordinates, undoing inversion and axis direction.
Track layout and viewport scopes
-
struct RbcTrackViewport
Saved graph viewport for one paired track-entry scope.
Stack storage owned by the caller. Holds borrowed track identity and copies of graph extents, scales and padding; it neither retains nor frees resources. Restore in reverse entry order when nesting scopes.
Public Members
-
int top
Saved plot top in widget pixels.
-
int bottom
Saved plot bottom in widget pixels.
-
int range
Saved vertical mapping span in pixels.
-
int offset
Saved vertical mapping origin in pixels.
-
int pad1
Saved top padding in pixels.
-
int pad2
Saved bottom padding in pixels.
-
int left
Saved plot left in widget pixels.
-
int right
Saved plot right in widget pixels.
-
int hRange
Saved horizontal mapping span in pixels.
-
int hOffset
Saved horizontal mapping origin in pixels.
-
int hPad1
Saved left padding in pixels.
-
int hPad2
Saved right padding in pixels.
-
double scale
Saved reciprocal vertical mapping span.
-
double hScale
Saved reciprocal horizontal mapping span.
-
int top
-
void Rbc_LayoutTracks(Graph *graphPtr)
Compute full and visible track rectangles from the current plot.
Updates track extents and resets axis offsets. Fitted tracks distribute the available stacking range by minima and weights; scrolling tracks use their requested sizes and minima. Export computes a clamped offset without writing it back to the screen’s trackOffset. Does not draw or execute Tcl.
- Parameters:
graphPtr – Borrowed graph with current plot geometry and track settings.
-
void Rbc_EnterTrack(Graph *graphPtr, RbcTrack *track, RbcTrackViewport *saved)
Temporarily select a track viewport for clipping and component work.
Uses visible bounds for clipping and full world bounds for the stacking direction’s offset and scale, clearing padding in that direction. Inversion changes the stacking direction from vertical to horizontal. NULL still saves state and changes activeTrack. Always pair with Rbc_LeaveTrack, including on early returns. Does not install a renderer clip or provide lifetime protection.
- Parameters:
graphPtr – Borrowed graph whose viewport fields are temporarily changed.
track – Borrowed track, or NULL to select no active track.
saved – Caller-owned storage receiving the previous viewport.
-
void Rbc_LeaveTrack(Graph *graphPtr, const RbcTrackViewport *saved)
Restore the graph fields saved by a matching Rbc_EnterTrack call.
Restores active track, plot bounds, offsets, ranges, scales and padding. Does not undo other graph mutations, layout work or renderer clipping.
- Parameters:
graphPtr – Same live graph used on entry.
saved – Intact saved viewport, restored in reverse order of nesting.
The graph layout entry point is documented in Graph lifecycle C reference.
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 ElemComplexVector
Complex element data from an owned list allocation or a borrowed RBC vector.
Public Members
-
Rbc_Vector *vecPtr
Borrowed source vector, or NULL for list-owned storage.
-
Rbc_Complex *valueArr
Complex values; borrowed from vecPtr or owned for list input.
-
Tcl_Size nValues
Number of valid complex values.
-
Tcl_Size arraySize
Allocated capacity for list-owned storage.
-
Rbc_VectorId clientId
Owned observer token for vector input; does not preserve vector lifetime.
-
Rbc_Vector *vecPtr
-
struct Line
Line/strip/polar element with data sources, mapping caches and presentation state.
Public Members
-
LineErrorBand errorBand
Embedded band options, resources and polygon cache.
-
Tcl_Obj *areaPatternObjPtr
Tk option-managed Tcl representation for area pattern; released with the owning option state.
-
Tcl_Obj *areaTileObjPtr
Tk option-managed Tcl representation for area tile; released with the owning option state.
-
Tcl_Obj *maxSymbolsObjPtr
Tk option-managed Tcl representation for max symbols; released with the owning option state.
-
Tcl_Obj *smoothObjPtr
Tk option-managed Tcl representation for smooth; released with the owning option state.
-
Tcl_Obj *traceObjPtr
Tk option-managed Tcl representation for trace; released with the owning option state.
-
Tcl_Obj *cDataObjPtr
Tk option-managed Tcl representation for c data; released with the owning option state.
-
Tcl_Obj *paramObjPtr
Tk option-managed Tcl representation for param; released with the owning option state.
-
ElemComplexVector z
Complex data source and observer state.
-
ElemVector param
Parameter-vector source used for complex interpolation.
-
LineDataMode dataMode
Real-pair or complex-input mode.
-
LineComplexDataFormat cDataFormat
Interpretation of complex input values.
-
LineDataCoordinates dataCoordinates
Interpretation of real input pairs.
-
double z0
Reference impedance for Smith transformations.
-
double rTolerance
Tolerance to reduce the number of points displayed.
-
LineSymbolPoints symbolPoints
Source samples eligible for normal symbols.
-
LineDecimation decimate
Requested screen decimation policy.
-
LineDecimateCache decimateCache
Owned source-block summaries for screen decimation.
-
int pointMapOmitted
Nonzero when screen mapping intentionally omits complete symbol/source maps.
-
XColor *fillFgColor
Area-fill foreground color.
-
XColor *fillBgColor
Area-fill background color.
-
GC fillGC
Owned native area-fill GC.
-
LineAreaClose areaClose
Closure of the mapped fill polygon.
-
double areaOpacity
Cairo solid fill opacity, from zero to one.
-
Pixmap fillStipple
Stipple for fill area.
-
Tcl_Size nFillPts
Number of area-fill polygon vertices.
-
Tcl_Size nSymbolPts
Number of points.
-
Tcl_Size *symbolToData
Contains indices of data points.
It’s first used to map pens to the visible points to sort them by pen style, and later to find data points from the index of a visible point.
-
Tcl_Size nActivePts
Number of mapped active-symbol positions.
-
Tcl_Size *activeToData
Contains indices of data points.
It’s first used to map pens to the visible points to sort them by pen style, and later to find data points from the index of a visible point.
-
int reqMaxSymbols
Requested maximum normal-symbol count.
-
Tcl_Size symbolInterval
Sampling interval used to limit normal symbols.
-
Tcl_Size symbolCounter
Running point counter for symbol sampling.
-
int penDir
Indicates if a change in the pen direction should be considered a retrace (line segment is not drawn).
-
Rbc_Chain *traces
List of traces (a trace is a series of contiguous line segments).
New traces are generated when either the next segment changes the pen direction, or the end point is clipped by the plotting area.
-
Segment2D *strips
Holds the the line segments of the element trace.
The segments are grouped by pen style.
-
Tcl_Size nStrips
Number of line segments to be drawn.
-
Tcl_Size *stripToData
Pen to visible line segment mapping.
-
LineErrorBand errorBand
-
struct LineAreaTransaction
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.
-
Pixmap stipple
Retained replacement stipple bitmap staged for commit or abort.
-
Rbc_Tile tile
Retained replacement tile token staged for commit or abort.
-
GC gc
New native fill GC staged for commit or abort.
-
unsigned int stagedMask
-
struct LineBandPolygon
Owned linked polygon for a mapped error-band region.
Public Members
-
Tcl_Size count
Number of vertices.
-
struct LineBandPolygon *nextPtr
Next owned polygon, or NULL.
-
Tcl_Size count
-
struct LineComplexDataTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
Public Members
-
int staged
Nonzero when the transaction contains a replacement to commit or release.
-
ElemComplexVector z
Replacement complex-data descriptor staged for commit or abort.
-
LineDataMode mode
Validated mode selector staged for commit or abort.
-
int staged
-
struct LineErrorBand
Error-band options and owned mapped polygons.
Public Members
-
int mode
Band display/axis mode selector.
-
Tcl_Obj *patternObjPtr
Tk option-managed Tcl representation for pattern; released with the owning option state.
-
Tcl_Obj *tileObjPtr
Tk option-managed Tcl representation for tile; released with the owning option state.
-
XColor *foreground
Configured band foreground color.
-
XColor *background
Configured band background color.
-
double opacity
Fill opacity from zero to one.
-
Pixmap stipple
Retained stipple bitmap, or None.
-
Rbc_Tile tile
Retained image tile token, or NULL.
-
GC gc
Owned native band fill GC.
-
LineBandPolygon *polygons
Owned linked mapped polygons.
-
int mode
-
struct LineParamTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
Public Members
-
int staged
Nonzero when the transaction contains a replacement to commit or release.
-
ElemVector param
Replacement interpolation-parameter data staged for commit or abort.
-
int staged
-
struct LinePen
Concrete line/strip pen with symbol, trace, error-stroke and label resources.
Public Members
-
Tcl_Obj *dashesObjPtr
Tk option-managed Tcl representation for dashes; released with the owning option state.
-
Tcl_Obj *errorBarColorObjPtr
Tk option-managed Tcl representation for error bar color; released with the owning option state.
-
Tcl_Obj *errorBarWidthObjPtr
Tk option-managed Tcl representation for error bar width; released with the owning option state.
-
Tcl_Obj *errorBarCapObjPtr
Tk option-managed Tcl representation for error bar cap; released with the owning option state.
-
Tcl_Obj *fillObjPtr
Tk option-managed Tcl representation for fill; released with the owning option state.
-
Tcl_Obj *lineWidthObjPtr
Tk option-managed Tcl representation for line width; released with the owning option state.
-
Tcl_Obj *offDashObjPtr
Tk option-managed Tcl representation for off dash; released with the owning option state.
-
Tcl_Obj *outlineObjPtr
Tk option-managed Tcl representation for outline; released with the owning option state.
-
Tcl_Obj *outlineWidthObjPtr
Tk option-managed Tcl representation for outline width; released with the owning option state.
-
Tcl_Obj *pixelsObjPtr
Tk option-managed Tcl representation for pixels; released with the owning option state.
-
Tcl_Obj *showErrorBarsObjPtr
Tk option-managed Tcl representation for show error bars; released with the owning option state.
-
Tcl_Obj *showValuesObjPtr
Tk option-managed Tcl representation for show values; released with the owning option state.
-
Tcl_Obj *symbolObjPtr
Tk option-managed Tcl representation for symbol; released with the owning option state.
-
Tcl_Obj *valueRotateObjPtr
Tk option-managed Tcl representation for value rotate; released with the owning option state.
-
Tcl_Obj *valueShadowObjPtr
Tk option-managed Tcl representation for value shadow; released with the owning option state.
-
int traceWidth
Trace stroke width in pixels.
-
Rbc_Dashes traceDashes
Trace dash lengths and phase.
-
XColor *traceColor
Trace foreground color.
-
XColor *traceOffColor
Off-dash background color, or NULL.
-
GC traceGC
Owned native trace GC.
-
int errorBarShow
Bit mask selecting X and Y error bars.
-
int errorBarLineWidth
Error stroke width in pixels.
-
int errorBarCapWidth
Requested error cap width in pixels; mapping resolves automatic widths.
-
XColor *errorBarColor
Configured error color; COLOR_DEFAULT requests the element fallback.
-
GC errorBarGC
Owned GC for native error strokes.
-
int valueShow
Bit mask selecting X and Y coordinates in labels.
-
char *valueFormat
Option-managed numeric format string.
-
Tcl_Obj *valueCommandObjPtr
Tk option-managed Tcl representation for value command; released with the owning option state.
-
Tcl_Obj *valueOffsetObjPtr
Tk option-managed Tcl representation for value offset; released with the owning option state.
-
Tcl_Obj *dashesObjPtr
-
struct LinePenStyle
Mapped per-style line/strip geometry and error strokes.
-
struct LineScalarTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
-
struct LineTrace
One mapped contiguous trace with source-index correspondence.
-
struct MapInfo
Temporary mapped points and source indices for a trace pass.
-
struct ParsedSymbol
Temporary parsed symbol resources before option commit.
Public Members
-
SymbolType type
Symbol selector.
-
Pixmap bitmap
Acquired symbol bitmap, or None.
-
Pixmap mask
Acquired symbol mask, or None.
-
SymbolType type
-
struct SmoothingInfo
Static mapping from smoothing option name to selector.
-
struct Symbol
Line-symbol shape, dimensions and native drawing resources.
Public Members
-
SymbolType type
Type of symbol to be drawn/printed.
-
int size
Requested size of symbol in pixels.
-
XColor *outlineColor
Outline color.
-
int outlineWidth
Width of the outline.
-
GC outlineGC
Outline graphics context.
-
XColor *fillColor
Normal fill color.
-
GC fillGC
Fill graphics context.
-
Pixmap bitmap
Bitmap to determine foreground/background pixels of the symbol.
-
Pixmap mask
Bitmap representing the transparent pixels of the symbol.
-
SymbolType type