Axes, mapping and track viewports
Mapping converts logical data coordinates into double-precision widget coordinates. Renderers consume that geometry;
they do not choose axis ranges or track ownership. The private interfaces described here are implemented in
rbcGrAxis.c and rbcGrTrack.c. See Coordinate mapping C reference for their contracts and Rendering architecture and contracts for the
later drawing boundary.
Registry ownership and command dispatch are described in Axis ownership and commands.
Preparing geometry
Rbc_LayoutGraph() performs pending work in dependency order:
Reset axis ranges when
RESET_AXESis set.Lay out margins when
LAYOUT_NEEDEDis set, checking whether a label callback invalidated the graph before continuing.When both plot ranges exceed one pixel, map axes when
MAP_WORLDis set, then map elements, markers, the grid and local legends.
These stages are distinct from painting. The low-level coordinate helpers do not run layout on behalf of their
callers. Successful layout can leave mapping pending when the plot is too small. Do not draw or pick stale axis geometry
just because a previous layout existed. See Graph lifecycle and redisplay for the callback lifetime rules and the existing
Rbc_LayoutGraph() contract.
Rbc_ResetAxes initializes data limits, asks visible contributing elements for
extents and accumulates those extents into their selected X and Y axes. Bar frequency and stack state are prepared
before collecting extents. Requested limits, scrolling limits and linear or logarithmic scaling then determine the axis
ranges. The operation requests subsequent geometry, layout and mapping work; it does not itself produce a complete
rendered graph.
Axis.valueRange holds accumulated data bounds. Axis.axisRange is the range used by the mapping helpers,
including the effects of axis scaling and limit policy. On a logarithmic axis its mapping coordinates are base-10
exponents. Do not substitute requested limits or raw data bounds for the prepared mapping range.
Coordinate conventions
Rbc_HMap() maps one data value in the horizontal screen direction; Rbc_VMap() maps one in the vertical
direction. They reject nonfinite inputs and nonpositive logarithmic inputs with NAN. After logarithmic conversion
when required, they normalize through the prepared axis range. Descending axes reverse the normalized fraction.
For an ordinary finite linear range, the mapping is equivalent to:
After replacing \(u\) by \(1-u\) for descending axes, horizontal mapping is \(x = o_x + u r_x\), while vertical mapping is \(y = o_y + (1-u)r_y\). The vertical reversal accounts for screen Y increasing downward. The implementation also handles ranges whose subtraction overflows using half-scaled arithmetic; avoid duplicating the simple formula in a component and losing that protection.
Rbc_Map2D() chooses which helper receives each logical axis:
Orientation |
Screen X |
Screen Y |
|---|---|---|
Ordinary |
X data through the X axis |
Y data through the Y axis |
Inverted |
Y data through the Y axis |
X data through the X axis |
Inversion does not exchange the logical identity of the axes. Rbc_InvMap2D() reverses this mapping and returns
logical X/Y values. It extrapolates outside plot bounds rather than clipping them. Its logarithmic conversion checks the
supported DBL_MIN to DBL_MAX interval and may return NAN. Consumers must check finiteness before converting
coordinates to integers or passing geometry to drawing code.
Mapping is not clipping, rounding or picking. A finite mapped point can be outside the plot, and different renderers retain their own integer conversion rules. Elements retain original data indices separately so reduced drawing geometry does not replace the identity used by closest-point queries.
Full tracks and visible tracks
Each track has two rectangles, both expressed in widget-coordinate space:
Fields |
Purpose |
|---|---|
|
Full track extent after layout and scrolling, possibly outside the plot. |
|
Intersection of that extent with the graph’s plot viewport. |
Rbc_LayoutTracks() distributes fitted tracks using minima and weights. With track scrolling enabled, requested
sizes and minima establish the full extent and the scroll offset positions it within the viewport. Inverted graphs stack
tracks horizontally. Track-owned axes map against the full world extent, not the visible intersection. Otherwise
scrolling a track partly out of view would rescale its data rather than simply hide the displaced portion. Shared axes
use the graph’s mapping offsets and ranges.
Axis ownership is sufficient for coordinate transforms. Component operations that depend on graph-level clipping, reduction or drawing fields additionally use a paired viewport scope:
RbcTrackViewport saved;
Rbc_EnterTrack(graphPtr, track, &saved);
/* Work with this track's viewport. */
Rbc_LeaveTrack(graphPtr, &saved);
Entry saves both directions but changes only the stacking direction’s bounds, scale and padding, along with
activeTrack. Visible bounds supply clipping limits while full world bounds supply offsets and ranges. Entry with a
NULL track still changes the active-track state and must be paired with leave. Nested scopes need separate saved
records and restoration in reverse order. These helpers neither install a renderer clip nor preserve object lifetime;
cleanup on every return path remains the caller’s responsibility.
During axis mapping, rbcGrAxisPresentation.Rbc_MapAxes() first lays out tracks, then walks margin axes. Track
axes accumulate their own axis offsets, allowing multiple local axes. Completely clipped tracks are skipped. Axis
geometry uses the full track rectangle so its placement remains stable while scrolling; visible bounds still govern
later clipping.
Temporary export layouts
Document export can change graph dimensions and remap the same component records. GRAPH_EXPORT prevents temporary
layout from being announced as an ordinary screen view change. Track layout also avoids committing its export-clamped
offset to the stored screen scroll position.
SVG and PDF use rbcGraphExportCommands.OutputGraphExport() in rbcGrExport.c. It saves screen dimensions,
lays out the requested export size, generates the document, then restores dimensions and requests another
layout. Immediate screen remapping is attempted only while the window exists and axis formatting has not invalidated
it. A prior export error is preserved across that restoration attempt; a restoration error can fail an otherwise
successful export.
PostScript retains its separate preamble and document orchestration in rbcGrPs.c. The shared
Rbc_ExportEndGraph() clears export state, returns to window dimensions and schedules remapping/redraw when the
window still exists. Do not assume this helper alone synchronously restores every geometry cache. New export paths
must account for failure and callback-driven destruction as well as successful output.
Useful regression coverage
Mapping changes should exercise ordinary and inverted layouts, descending and logarithmic axes, extreme finite ranges, tiny plot sizes and multiple axes. Track tests should include partial scrolling, reordering, local-axis transforms and independent renderer clipping. Export tests need resized output followed by restored screen transforms and geometry. A visually plausible image alone does not prove that picking, inverse transforms and cached layout agree.
Axis-space helper contracts
The public mapping entry points accept data values, but the numerical helpers beneath them operate in axis space. For a logarithmic axis that means base-ten exponents. Passing raw logarithmic data to an axis-space helper skips a required conversion; applying a logarithm twice is equally incorrect.
Helper |
Input and responsibility |
|---|---|
Accumulates raw element bounds into |
|
Stores axis-space endpoints and cached range/scale without sorting or validating them; tiny spans use a unit cached range. |
|
Converts axis-space values to normalized fractions, without direction reversal, logarithms or clipping. |
|
Apply axis direction and graph/track world geometry to already-converted values. The vertical helper also accounts for downward screen Y. |
|
Reverse screen scaling and direction, interpolate axis space, then convert logarithmic exponents back to raw data. |
InterpolateAxisValue accepts fractions outside [0,1]; it
extrapolates rather than clips. InRange is the separate finite-range test with its
small normalized tolerance. AxisIsHorizontal combines logical axis
identity with inversion; it does not change ownership or the axis class.
LogAxisValue supports normal positive doubles from DBL_MIN through
DBL_MAX and rejects exponents outside that interval with NAN. It deliberately does not promise subnormal
results. MakeLogRange accepts a raw data value and writes two raw positive
limits; it is not an exponent-output routine.
AdjustViewport operates on a normalized offset and view/world size
ratio. When the view exceeds the world, its allowed offsets differ from the usual 0..1-windowSize interval. Callers
establish finite valid scroll state first; this helper does not validate axes or refresh geometry.
All these routines borrow their graph/axis records and perform no Tcl evaluation. Their low-level nature does not make stale layout safe: callers must prepare layout first, check nonfinite results before integer conversion, then apply geometry and renderer clipping at their respective boundaries.