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

RbcTrack *activeTrack

Borrowed previously active track, or NULL.

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.

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.

Element *elemPtr

Borrowed owning element receiving data-change notifications.

struct Line

Line/strip/polar element with data sources, mapping caches and presentation state.

Public Members

Element core

Common Element prefix; must remain first.

LinePen builtinPen

Embedded default line pen owned by this element.

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.

Smoothing reqSmooth

Requested smoothing function to use for connecting the data points.

Smoothing smooth

Smoothing function used.

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.

Rbc_Tile fillTile

Tile for fill area.

Pixmap fillStipple

Stipple for fill area.

Tcl_Size nFillPts

Number of area-fill polygon vertices.

Point2D *fillPts

Array of points used to draw polygon to fill area under the curve.

Point2D *symbolPts

Holds the screen coordinates of all the data points for the element.

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.

Point2D *activePts

Owned mapped active-symbol positions in display pixels.

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.

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.

struct LineBandPolygon

Owned linked polygon for a mapped error-band region.

Public Members

Point2D *points

Owned polygon vertices in display pixels.

Tcl_Size count

Number of vertices.

struct LineBandPolygon *nextPtr

Next owned polygon, or NULL.

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.

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.

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.

struct LinePen

Concrete line/strip pen with symbol, trace, error-stroke and label resources.

Public Members

Pen core

Common Pen prefix; must remain first.

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.

Symbol symbol

Embedded symbol appearance and drawing resources.

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.

Point2D valueOffset

Label anchor displacement in pixels.

TextStyle valueStyle

Label text style; its GC belongs to the pen.

struct LinePenStyle

Mapped per-style line/strip geometry and error strokes.

Public Members

Weight weight

Weight range where this pen is valid.

LinePen *penPtr

Pen used to draw symbols, traces, error bars, segments, etc.

Segment2D *xErrorBars

Point to start of this pen’s X-error bar segments in the element’s array.

Segment2D *yErrorBars

Point to start of this pen’s Y-error bar segments in the element’s array.

Tcl_Size xErrorBarCnt

of error bars for this pen.

Tcl_Size yErrorBarCnt

of error bars for this pen.

int errorBarCapWidth

Length of the cap ends on each error bar.

int symbolSize

Size of the pen’s symbol scaled to the current graph size.

Point2D *symbolPts

Points to start of array for this pen.

Tcl_Size nSymbolPts

of points for this pen.

Segment2D *strips

Points to start of the line segments for this pen.

Tcl_Size nStrips

of line segments for this pen.

struct LineScalarTransaction

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.

int maxSymbols

Requested normal-symbol limit staged for commit or abort.

Smoothing smooth

Validated smoothing selector staged for commit or abort.

int penDir

Validated trace direction selector staged for commit or abort.

struct LineTrace

One mapped contiguous trace with source-index correspondence.

Public Members

Tcl_Size start

Index into the X-Y coordinate arrays indicating where trace starts.

Tcl_Size nScreenPts

Number of points in the continuous trace.

Point2D *screenPts

Array of screen coordinates (allocated) representing the trace.

Tcl_Size *symbolToData

Reverse mapping of screen coordinate indices back to their data coordinates.

struct MapInfo

Temporary mapped points and source indices for a trace pass.

Public Members

Point2D *screenPts

Array of transformed coordinates.

Tcl_Size nScreenPts

Number of coordinates.

Tcl_Size *indices

Maps segments/traces to data points.

unsigned char *breakBefore

Optional break flags parallel to screenPts; nonzero starts a new trace.

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.

struct SmoothingInfo

Static mapping from smoothing option name to selector.

Public Members

char *name

Borrowed option name.

Smoothing value

Smoothing 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.