Renderer C reference

These declarations are private implementation interfaces, not installed APIs. Callers must obey the capabilities of the constructor they selected; generic operation names do not imply that every context implements them.

Parameter directions follow C calling conventions. Context arguments refer to a specific constructor family; mutable context state does not imply ownership of borrowed graph, document, image or font resources. See Rendering architecture and contracts for batch lifetimes and scope pairing.

Screen adapters and Cairo attempts have different result contracts. Native one-shot adapters retain the supplied GC behavior, including the explicitly documented origin/clip mutations. Cairo attempt helpers return a fallback flag; context constructors return an owned context or their documented failure value. See Native renderer internals and Cairo surfaces and drawing contexts for call sequences and coordinate conventions.

Component-facing interface

Private graph rendering interface used by mapped components.

Geometry is in mapped widget/display coordinates, not axis data coordinates. Contexts and their borrowed resources must stay on the owning Tk thread. A constructor defines the supported operations; unsupported callbacks are not automatic fallbacks. Check nullable constructor results before drawing. End each allocated context exactly once with Rbc_RenderEnd(). Document tokens, drawables, GCs and component-owned resources remain borrowed.

This header is not installed and does not define the public vector ABI. See license.terms for redistribution terms.

Defines

RBC_RENDER_ARROW_POINTS

Native-only screen details borrow the exact GC, preserving XOR and dash semantics.

Arrow points include the repeated closing vertex. Text backgrounds consume four outline points and add the anchor before integer conversion.

RBC_RENDER_BITMAP_OUTLINE_POINTS

Maximum vertices in a mapped bitmap background outline.

Enums

enum Rbc_RenderArcStyle

Ellipse in mapped display coordinates.

Zero degrees points right; positive sweeps turn counterclockwise. |extent| >= 360 is one closed ellipse, without a radial seam. The renderer constructs the complete path under the context’s clip; callers must not clip/flatten it first. Geometry transforms do not scale stroke width, dashes, or fill patterns. This is a private C interface.

Values:

enumerator RBC_RENDER_ARC_OPEN
enumerator RBC_RENDER_ARC_CHORD
enumerator RBC_RENDER_ARC_PIESLICE
enum Rbc_RenderSymbolType

Semantic symbol descriptions for export; colors are resolved by the caller.

Values:

enumerator RBC_RENDER_SYMBOL_SQUARE
enumerator RBC_RENDER_SYMBOL_CIRCLE
enumerator RBC_RENDER_SYMBOL_DIAMOND
enumerator RBC_RENDER_SYMBOL_PLUS
enumerator RBC_RENDER_SYMBOL_CROSS
enumerator RBC_RENDER_SYMBOL_SPLUS
enumerator RBC_RENDER_SYMBOL_SCROSS
enumerator RBC_RENDER_SYMBOL_TRIANGLE
enumerator RBC_RENDER_SYMBOL_ARROW
enumerator RBC_RENDER_SYMBOL_BITMAP
enumerator RBC_RENDER_SYMBOL_NONE
enum Rbc_RenderShapeType

Screen-space symbol template; segment vertices are endpoint pairs.

Values:

enumerator RBC_RENDER_CIRCLE
enumerator RBC_RENDER_POLYGON
enumerator RBC_RENDER_SEGMENTS
enum Rbc_RenderStrokeKind

Native/Cairo element strokes.

The GC is borrowed, including its existing clip, dashes and raster operation. TRACES supports Polyline; STRIPS and SEGMENTS support Segments, retaining their respective native batching. Only these operations and End are valid on the returned context. Other screen capabilities continue to use Begin/BeginFill and native fallbacks.

Values:

enumerator RBC_RENDER_STROKE_TRACES
enumerator RBC_RENDER_STROKE_STRIPS
enumerator RBC_RENDER_STROKE_SEGMENTS

Functions

Tcl_Size Rbc_RenderPolygonPointLimit(Graph *graphPtr)

Mapping-time polygon capacity for the selected output.

TCL_SIZE_MAX means no request-size bound; zero means no polygon can be submitted. Components reserve space for closure/clipping and preserve shared samples when splitting. This query needs no drawing context and allocates no resources.

Parameters:
  • graphPtr – [in] Borrowed owning graph with current mapped geometry, kept alive through the operation or context lifetime.

void Rbc_RenderScreenTextBackground(Graph *graphPtr, Drawable drawable, GC gc, const Point2D *outline, const Point2D *anchor)

Fill a four-corner native text background.

Caller supplies representable mapped geometry and the required clip; this adapter does not impose a plot clip.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • gc – [in] Borrowed configured GC; raster operation, dash and clip state remain caller-selected.

  • outline – [in] Four borrowed outline vertices relative to anchor.

  • anchor – [in] Borrowed mapped text anchor added before conversion to signed-short coordinates.

void Rbc_RenderScreenArrowHead(Graph *graphPtr, Drawable drawable, GC gc, const Point2D *points)

Scan-convert a native arrowhead without rounding its vertices first.

Spans are bounded by graph dimensions and signed-short limits. The enclosing screen clip supplies track clipping.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • gc – [in] Borrowed configured GC; raster operation, dash and clip state remain caller-selected.

  • points – [in] Borrowed finite array of RBC_RENDER_ARROW_POINTS vertices, including the repeated closing vertex.

void Rbc_RenderScreenLegendLine(Graph *graphPtr, Drawable drawable, GC gc, int x, int y, int size)

Draw two independent native legend sample lines.

The rows are y and y+1. Each native line restarts its dash pattern.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • gc – [in] Borrowed configured GC; raster operation, dash and clip state remain caller-selected.

  • x – [in] Destination X coordinate in pixels.

  • y – [in] Destination Y coordinate in pixels.

  • size – [in] Half-length of each sample line in pixels; endpoints are x-size and x+size.

void Rbc_RenderScreenLegendBar(Graph *graphPtr, Drawable drawable, GC gc, int x, int y, int size)

Fill a native legend square with a local stipple origin.

This does not restore a nonzero previous origin. The caller must use a GC compatible with that postcondition.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • gc – [inout] Borrowed fill GC; its tile/stipple origin is changed during drawing and reset to (0,0) afterward.

  • x – [in] Destination X coordinate in pixels.

  • y – [in] Destination Y coordinate in pixels.

  • size – [in] Nonnegative side length of the sample square in pixels.

void Rbc_RenderScreenRun(Graph *graphPtr, Drawable drawable, void *data, Tcl_Size count, Rbc_RenderRunProc *proc)

Present a synchronous run through one platform drawing target.

On Windows, attempts a shared DC wrapper and falls back to the original drawable if unavailable. The callback runs before this function returns. This is not a Tcl evaluation boundary.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • data – [in] Borrowed callback-specific batch data; NULL suppresses the run.

  • count – [in] Number of run items; nonpositive values suppress the callback.

  • proc – [in] Required synchronous callback; must not retain the temporary target or destroy borrowed drawing resources.

void Rbc_RenderScreenBitmapRun(Graph *graphPtr, Drawable drawable, Pixmap bitmap, GC gc, int width, int height, const Rbc_RenderPosition *positions, Tcl_Size count)

Present opaque, unmasked bitmap copies with platform fallback.

Nonpositive counts draw nothing. A declined optimized batch is replayed in full, so masked or XOR copies are not supported. Source bitmap, positions and GC remain caller-owned.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • bitmap – [in] Borrowed one-bit source bitmap with the supplied width and height.

  • gc – [inout] Borrowed GXcopy-compatible GC; fallback clears its clip mask and resets clip origin to (0,0).

  • width – [in] Positive source bitmap width in pixels.

  • height – [in] Positive source bitmap height in pixels.

  • positions – [in] Borrowed integer destination origins, one per copy; NULL suppresses drawing.

  • count – [in] Number of array entries, not bytes.

Rbc_RenderTarget *Rbc_RenderBeginMarkerPass(Graph *graphPtr, Drawable *drawablePtr)

Try to acquire a shared Cairo marker-pass target; NULL leaves the original drawable usable.

Parameters:
  • graphPtr – [inout] Owning graph; a successful acquisition installs a temporary render target until EndMarkerPass.

  • drawablePtr – [inout] Required pointer to the original destination; replaced by a temporary drawable only on success.

void Rbc_RenderEndMarkerPass(Rbc_RenderTarget *target)

Present and release a marker-pass target; NULL is accepted.

Parameters:
  • target – [inout] Owned target returned by BeginMarkerPass, consumed here; NULL is accepted. The replacement drawable is invalid afterward.

Rbc_RenderContext *Rbc_RenderBeginScreenText(Tk_Window tkwin, Drawable drawable)

Screen text uses Tk for native and Cairo graphs alike.

Supports Text, TextLayout, TextSize and End only. The window, drawable and cached layout are borrowed; existing integer positions and clipping are retained. Reuse a context for a label batch. TextSize returns the rotated layout extent.

Parameters:
  • tkwin – [in] Borrowed Tk window providing text resources, kept alive until End.

  • drawable – [in] Borrowed destination drawable in mapped widget coordinates, kept valid through context release.

void Rbc_RenderTextLayout(Rbc_RenderContext *ctx, TextLayout *layout, TextStyle *style, int x, int y)

Draw a borrowed cached text layout through a screen text context.

Parameters:
  • ctx – [inout] Live context created for screen text; its constructor must support this operation.

  • layout – [in] Borrowed cached text layout.

  • style – [inout] Caller-provided text style with live font/GC resources; no ownership transfer.

  • x – [in] Mapped horizontal position in destination coordinates.

  • y – [in] Mapped vertical position in destination coordinates.

void Rbc_RenderTextSize(Rbc_RenderContext *ctx, const char *string, TextStyle *style, int x, int y, Dim2D *size)

Draw screen text and return its rotated layout extent.

Parameters:
  • ctx – [inout] Live context created for screen text; its constructor must support this operation.

  • string – [in] Borrowed NUL-terminated text.

  • style – [inout] Caller-provided text style with live font/GC resources.

  • x – [in] Mapped horizontal position in destination coordinates.

  • y – [in] Mapped vertical position in destination coordinates.

  • size – [out] Required caller-owned output for the rotated text extent.

Rbc_RenderContext *Rbc_RenderBeginScreenRaster(Graph *graphPtr, Drawable drawable)

Screen raster contexts support TkImage, MappedBitmap, Pixmap and End only.

Cairo is attempted for photos/bitmaps; native fallback preserves Tk image types and GC masks. The context borrows its drawable and all input resources. Scaling/rotation remain in component mapping, outside presentation.

Parameters:
  • graphPtr – [in] Borrowed owning graph with current mapped geometry, kept alive through the operation or context lifetime.

  • drawable – [in] Borrowed destination drawable in mapped widget coordinates, kept valid through context release.

void Rbc_RenderMappedBitmap(Rbc_RenderContext *ctx, const Rbc_RenderRectangle *r, const Rbc_RenderBitmapStyle *style)

Present a mapped bitmap through a screen raster context, retaining native fallback.

Parameters:
  • ctx – [inout] Live context created for screen raster presentation; its constructor must support this operation.

  • r – [in] Borrowed mapped destination rectangle.

  • style – [in] Borrowed bitmap/mask/style resources valid through this synchronous call.

void Rbc_RenderPixmap(Rbc_RenderContext *ctx, Pixmap pixmap, GC gc, const Rbc_RenderRectangle *r)

Copy a mapped pixmap through a screen raster context using the borrowed GC.

Parameters:
  • ctx – [inout] Live context created for screen raster presentation; its constructor must support this operation.

  • pixmap – [in] Borrowed source pixmap.

  • gc – [in] Borrowed copy GC, including its clip/mask state.

  • r – [in] Borrowed mapped copy rectangle.

void Rbc_RenderScreenBorder(Tk_Window tkwin, Drawable drawable, Tk_3DBorder border, int x, int y, int width, int height, int borderWidth, int relief, int fill)

Draw native relief decoration, optionally filling its interior.

Uses native Tk shading for both native and Cairo graphs. No allocated renderer context escapes this call.

Parameters:
  • tkwin – [in] Borrowed live Tk window supplying display and drawing resources.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • border – [in] Borrowed Tk border supplying shading colors.

  • x – [in] Destination X coordinate in pixels.

  • y – [in] Destination Y coordinate in pixels.

  • width – [in] Rectangle width in pixels; caller supplies a nonnegative value.

  • height – [in] Rectangle height in pixels; caller supplies a nonnegative value.

  • borderWidth – [in] Border thickness in pixels.

  • relief – [in] Tk relief constant.

  • fill – [in] Nonzero selects filled decoration; zero draws only the border.

void Rbc_RenderScreenRectangle(Tk_Window tkwin, Drawable drawable, GC gc, Rbc_Tile tile, int x, int y, int width, int height)

Fill a native decoration rectangle with a tile or GC.

Parameters:
  • tkwin – [in] Borrowed live Tk window supplying display and drawing resources.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • gc – [in] Borrowed fill GC, required when tile is NULL; otherwise ignored.

  • tile – [in] Optional borrowed tile taking precedence over gc; uses its existing origin.

  • x – [in] Destination X coordinate in pixels.

  • y – [in] Destination Y coordinate in pixels.

  • width – [in] Rectangle width in pixels; caller supplies a nonnegative value.

  • height – [in] Rectangle height in pixels; caller supplies a nonnegative value.

void Rbc_RenderScreenSegments(Tk_Window tkwin, Drawable drawable, GC gc, const Segment2D *segments, Tcl_Size count)

Draw independent native segments even on Cairo graphs.

Preserves the GC raster operation, including XOR. The native helper bounds protocol coordinates and batches requests; this adapter does not create a geometry context.

Parameters:
  • tkwin – [in] Borrowed live Tk window supplying display and drawing resources.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • gc – [in] Borrowed configured GC; raster operation, dash and clip state remain caller-selected.

  • segments – [in] Borrowed mapped endpoint pairs, valid for count Segment2D records.

  • count – [in] Number of array entries, not bytes.

void Rbc_RenderScreenCopyArea(Tk_Window tkwin, Drawable source, Drawable destination, GC gc, int srcX, int srcY, unsigned int width, unsigned int height, int dstX, int dstY)

Copy completed pixels for backing-store restoration or presentation.

Caller supplies compatible drawables and GC and controls clipping and presentation order. No ownership changes.

Parameters:
  • tkwin – [in] Borrowed live Tk window supplying display and drawing resources.

  • source – [in] Borrowed source drawable.

  • destination – [in] Borrowed destination drawable.

  • gc – [in] Borrowed configured GC; raster operation, dash and clip state remain caller-selected.

  • srcX – [in] Source rectangle X coordinate in pixels.

  • srcY – [in] Source rectangle Y coordinate in pixels.

  • width – [in] Rectangle width in pixels; caller supplies a nonnegative value.

  • height – [in] Rectangle height in pixels; caller supplies a nonnegative value.

  • dstX – [in] Destination rectangle X coordinate in pixels.

  • dstY – [in] Destination rectangle Y coordinate in pixels.

void Rbc_RenderScreenFocus(Tk_Window tkwin, Drawable drawable, GC gc, int width)

Draw the native Tk focus highlight.

Parameters:
  • tkwin – [in] Borrowed live Tk window supplying display and drawing resources.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • gc – [in] Borrowed configured GC; raster operation, dash and clip state remain caller-selected.

  • width – [in] Focus highlight thickness in pixels, passed to Tk_DrawFocusHighlight.

Rbc_RenderContext *Rbc_RenderBeginFill(Graph *graphPtr, Drawable drawable, const Rbc_RenderFillStyle *style)

Fill contexts support FillPolygon/FillRectangles/FillArc and End.

Screen creation may return NULL for native fallback; export does not require Cairo.

Parameters:
  • graphPtr – [in] Borrowed owning graph with current mapped geometry, kept alive through the operation or context lifetime.

  • drawable – [in] Borrowed destination drawable in mapped widget coordinates, kept valid through context release.

  • style – [in] Required fill policy; referenced colors and stipple remain borrowed until End. NULL return requires caller-selected fallback.

Rbc_RenderContext *Rbc_RenderBeginExportFill(Graph *graphPtr, Rbc_ExportContext *exportPtr, const Rbc_RenderFillStyle *style)

Create a document fill context borrowing export state and style resources.

Parameters:
  • graphPtr – [in] Borrowed owning graph with current mapped geometry, kept alive through the operation or context lifetime.

  • exportPtr – [in] Borrowed live document state; caller owns document setup, completion and I/O.

  • style – [in] Required fill policy copied by value; referenced Tk resources remain borrowed until End.

void Rbc_RenderSetFillTile(Rbc_RenderContext *ctx, Rbc_Tile tile)

Supply a tile after BeginExportFill; PostScript keeps its background fallback.

Parameters:
  • ctx – [inout] Live context created for export fill; its constructor must support this operation.

  • tile – [in] Borrowed tile retained for this fill context; PostScript retains its background fallback.

void Rbc_RenderFillPolygon(Rbc_RenderContext *ctx, const Point2D *points, Tcl_Size count)

Fill a mapped polygon; fewer than three points draw nothing.

Parameters:
  • ctx – [inout] Live context created for polygon fill; its constructor must support this operation.

  • points – [in] Borrowed mapped point array, accessible for count entries during this call.

  • count – [in] Number of point records, not bytes.

void Rbc_RenderFillRectangles(Rbc_RenderContext *ctx, const Rbc_RenderRectangle *rectangles, Tcl_Size count)

Fill mapped rectangles; nonpositive counts draw nothing.

Parameters:
  • ctx – [inout] Live context created for rectangle fill; its constructor must support this operation.

  • rectangles – [in] Borrowed mapped rectangle array, accessible for count entries during this call.

  • count – [in] Number of rectangle records, not bytes.

void Rbc_RenderArc(Rbc_RenderContext *ctx, const Rbc_RenderArcGeometry *arc)

Use a stroke context for Arc and a fill context for FillArc.

FillArc ignores OPEN. Non-finite/degenerate geometry draws nothing. Screen contexts may be unavailable (native renderer); callers retain their native fallback.

Parameters:
  • ctx – [inout] Context supporting arc strokes, or NULL to draw nothing.

  • arc – [in] Borrowed ellipse geometry; invalid fields draw nothing. Valid geometry is copied and normalized before dispatch.

void Rbc_RenderFillArc(Rbc_RenderContext *ctx, const Rbc_RenderArcGeometry *arc)

Fill a normalized mapped ellipse segment; open arcs draw nothing.

Parameters:
  • ctx – [inout] Context supporting arc fills, or NULL to draw nothing.

  • arc – [in] Borrowed ellipse geometry; invalid fields draw nothing. Valid geometry is copied and normalized before dispatch.

Rbc_RenderContext *Rbc_RenderBeginNativeSymbols(Graph *graphPtr, Drawable drawable, Rbc_RenderNativeSymbolStyle *style, int size)

Create a native SymbolPoints/End context.

Returns an owned context; release exactly once with Rbc_RenderEnd. This adapter does not take ownership of graph or drawing resources.

Parameters:
  • graphPtr – [in] Borrowed live graph; keep it valid until Rbc_RenderEnd.

  • drawable – [in] Borrowed destination drawable; keep it valid until Rbc_RenderEnd.

  • style – [inout] Borrowed symbol style and its resources, retained by pointer until End; drawing updates its sampling counter.

  • size – [in] Symbol size in screen pixels, passed unchanged to native symbol drawing.

Rbc_RenderContext *Rbc_RenderBeginBars(Graph *graphPtr, Drawable drawable, const Rbc_RenderBarStyle *style)

Create a native FillRectangles/End context.

Returns an owned context; release exactly once with Rbc_RenderEnd. This adapter does not take ownership of graph or drawing resources. The caller may discard the style record after construction. Native bevel and fill behavior are retained.

Parameters:
  • graphPtr – [in] Borrowed live graph; keep it valid until Rbc_RenderEnd.

  • drawable – [in] Borrowed destination drawable; keep it valid until Rbc_RenderEnd.

  • style – [in] Required bar-style record copied by value; its GC, border and stipple resources remain borrowed until End.

Rbc_RenderContext *Rbc_RenderBeginNativeFill(Graph *graphPtr, Drawable drawable, GC gc, Rbc_Tile tile, Pixmap stipple)

Create a native FillPolygon/End context.

Returns an owned context; release exactly once with Rbc_RenderEnd. This adapter does not take ownership of graph or drawing resources.

Parameters:
  • graphPtr – [in] Borrowed live graph; keep it valid until Rbc_RenderEnd.

  • drawable – [in] Borrowed destination drawable; keep it valid until Rbc_RenderEnd.

  • gc – [in] Borrowed native GC, including its raster operation and clipping; keep it valid until Rbc_RenderEnd.

  • tile – [in] Borrowed tile, or NULL for the GC/stipple path.

  • stipple – [in] Non-None enables GC polygon filling when tile is NULL. None does not select solid filling; not acquired or freed here.

Rbc_RenderContext *Rbc_RenderBeginNativeSegments(Graph *graphPtr, Drawable drawable, GC gc)

Create a native Segments/End context.

Returns an owned context; release exactly once with Rbc_RenderEnd. This adapter does not take ownership of graph or drawing resources. Preserves the supplied GC raster operation, including XOR, and its installed clip.

Parameters:
  • graphPtr – [in] Borrowed live graph; keep it valid until Rbc_RenderEnd.

  • drawable – [in] Borrowed destination drawable; keep it valid until Rbc_RenderEnd.

  • gc – [in] Borrowed native GC, including its raster operation and clipping; keep it valid until Rbc_RenderEnd.

Rbc_RenderContext *Rbc_RenderBeginNativeArc(Graph *graphPtr, Drawable drawable, GC gc, const Point2D *fillPoints, Tcl_Size fillCount, const Segment2D *segments, Tcl_Size count)

Create a native Arc/FillArc/End context.

Returns an owned context; release exactly once with Rbc_RenderEnd. This adapter does not take ownership of graph or drawing resources. Keep both arrays alive until End and consistent with the analytic geometry passed to Arc/FillArc. The native adapter draws these arrays rather than remapping the ellipse.

Parameters:
  • graphPtr – [in] Borrowed live graph; keep it valid until Rbc_RenderEnd.

  • drawable – [in] Borrowed destination drawable; keep it valid until Rbc_RenderEnd.

  • gc – [in] Borrowed native GC, including its raster operation and clipping; keep it valid until Rbc_RenderEnd.

  • fillPoints – [in] Borrowed mapped, clipped fill polygon; may be NULL when fillCount is zero.

  • fillCount – [in] Nonnegative number of fill points.

  • segments – [in] Borrowed mapped, clipped outline segments; may be NULL when count is zero.

  • count – [in] Nonnegative number of outline segments.

Rbc_RenderContext *Rbc_RenderBeginNativePolygonBatch(Graph *graphPtr, Drawable drawable, GC gc, Tcl_Size maxPoints)

Create a native polygon-fill batch context.

Returns an owned context; release exactly once with Rbc_RenderEnd. This adapter does not take ownership of graph or drawing resources. A missing platform batch or failed batch allocation falls back to ordinary native polygon filling. The context itself is still returned and must be ended.

Parameters:
  • graphPtr – [in] Borrowed live graph; keep it valid until Rbc_RenderEnd.

  • drawable – [in] Borrowed destination drawable; keep it valid until Rbc_RenderEnd.

  • gc – [in] Borrowed native GC, including its raster operation and clipping; keep it valid until Rbc_RenderEnd.

  • maxPoints – [in] Maximum vertex count for each submitted polygon; use a positive representable capacity.

Rbc_RenderContext *Rbc_RenderBeginExportSymbol(Graph *graphPtr, Rbc_ExportContext *exportPtr, const Rbc_RenderSymbolStyle *style)

Export symbol contexts support SymbolPoints and End.

Screen shape batching retains its existing interface. Contexts borrow bitmap/color resources. Finish each symbol batch before starting another (the prolog is shared).

Parameters:
  • graphPtr – [in] Borrowed owning graph with current mapped geometry, kept alive through the operation or context lifetime.

  • exportPtr – [in] Borrowed live document state; caller owns document setup, completion and I/O.

  • style – [in] Required symbol description copied by value; bitmap and color resources remain borrowed until End.

Rbc_RenderContext *Rbc_RenderBeginExportBarSymbol(Graph *graphPtr, Rbc_ExportContext *exportPtr, const Rbc_RenderFillStyle *style, int size)

Create a document bar-symbol context; finish this batch before another symbol batch.

Parameters:
  • graphPtr – [in] Borrowed owning graph with current mapped geometry, kept alive through the operation or context lifetime.

  • exportPtr – [in] Borrowed live document state; caller owns document setup, completion and I/O.

  • style – [in] Required fill policy copied by value; referenced resources remain borrowed until End.

  • size – [in] Legend swatch size in mapped display units.

void Rbc_RenderSymbolPoints(Rbc_RenderContext *ctx, const Point2D *centers, Tcl_Size count)

Draw symbols at mapped centers; native sampling may update the borrowed style counter.

Parameters:
  • ctx – [inout] Live context created for native or export symbol batches; its constructor must support this operation.

  • centers – [in] Borrowed mapped symbol centers; native sampling may update the context-associated style counter.

  • count – [in] Number of centers; nonpositive counts draw nothing.

Rbc_RenderContext *Rbc_RenderBeginExportOutput(Rbc_ExportContext *exportPtr)

Export presentation primitives.

Output contexts borrow the export state and Tk resources. PlotBegin/PlotEnd must be paired; End releases only the context. Document setup, trailers and I/O remain with each backend command.

Parameters:
  • exportPtr – [in] Borrowed live document state; caller owns document setup, completion and I/O.

void Rbc_RenderText(Rbc_RenderContext *ctx, char *string, TextStyle *style, double x, double y)

Draw text through an export-output or screen-text context.

Parameters:
  • ctx – [inout] Live context created for screen text or export output; its constructor must support this operation.

  • string – [in] Borrowed NUL-terminated text; ownership is not transferred.

  • style – [inout] Caller-provided text style and live resources; backend text preparation may update style state.

  • x – [in] Mapped horizontal position in destination coordinates.

  • y – [in] Mapped vertical position in destination coordinates.

void Rbc_RenderTkImage(Rbc_RenderContext *ctx, Tk_Image image, double x, double y)

Non-photo image fallback; the legacy PostScript backend omits these images.

Parameters:
  • ctx – [inout] Live context created for screen raster or export output; its constructor must support this operation.

  • image – [in] Borrowed live Tk image.

  • x – [in] Mapped horizontal position in destination coordinates.

  • y – [in] Mapped vertical position in destination coordinates.

void Rbc_RenderPhotoImage(Rbc_RenderContext *ctx, Tk_PhotoHandle photo, double x, double y)

Write a borrowed Tk photo through an export-output context.

Parameters:
  • ctx – [inout] Live context created for export output; its constructor must support this operation.

  • photo – [in] Borrowed live Tk photo handle.

  • x – [in] Mapped horizontal position in destination coordinates.

  • y – [in] Mapped vertical position in destination coordinates.

void Rbc_RenderWindow(Rbc_RenderContext *ctx, Tk_Window tkwin, double x, double y)

Capture a borrowed Tk window through an export-output context, subject to backend policy.

Parameters:
  • ctx – [inout] Live context created for export output; its constructor must support this operation.

  • tkwin – [in] Borrowed live Tk window to capture, subject to backend export policy.

  • x – [in] Mapped horizontal position in destination coordinates.

  • y – [in] Mapped vertical position in destination coordinates.

void Rbc_RenderBackgroundPolygon(Rbc_RenderContext *ctx, const XColor *color, const Point2D *points, Tcl_Size count)

Paint a mapped background polygon through an export-output context.

Parameters:
  • ctx – [inout] Live context created for export output; its constructor must support this operation.

  • color – [in] Borrowed resolved background color.

  • points – [in] Borrowed mapped point array, accessible for count entries during this call.

  • count – [in] Number of point records, not bytes.

void Rbc_RenderBorder(Rbc_RenderContext *ctx, Tk_3DBorder border, double x, double y, int width, int height, int borderWidth, int relief, int fill)

Draw a border through an export-output context.

Parameters:
  • ctx – [inout] Live context created for export output; its constructor must support this operation.

  • border – [in] Borrowed live Tk border resource.

  • x – [in] Mapped horizontal position in destination coordinates.

  • y – [in] Mapped vertical position in destination coordinates.

  • width – [in] Rectangle width in display units.

  • height – [in] Rectangle height in display units.

  • borderWidth – [in] Border thickness in display units.

  • relief – [in] Tk relief value.

  • fill – [in] Nonzero requests filling as well as border drawing.

void Rbc_RenderClearRectangle(Rbc_RenderContext *ctx, double x, double y, int width, int height)

Clear a mapped rectangle through an export-output context.

Parameters:
  • ctx – [inout] Live context created for export output; its constructor must support this operation.

  • x – [in] Mapped horizontal position in destination coordinates.

  • y – [in] Mapped vertical position in destination coordinates.

  • width – [in] Rectangle width in display units.

  • height – [in] Rectangle height in display units.

void Rbc_RenderBackgroundRectangles(Rbc_RenderContext *ctx, const XColor *color, const Rbc_RenderRectangle *rectangles, Tcl_Size count)

Paint mapped background rectangles through an export-output context.

Parameters:
  • ctx – [inout] Live context created for export output; its constructor must support this operation.

  • color – [in] Borrowed resolved background color.

  • rectangles – [in] Borrowed mapped rectangle array, accessible for count entries during this call.

  • count – [in] Number of rectangle records, not bytes.

void Rbc_RenderPlotBegin(Rbc_RenderContext *ctx, Tk_Font font, double x, double y, int width, int height, const XColor *background)

Open an export plot scope; pair with PlotEnd before releasing the context.

Parameters:
  • ctx – [inout] Live context created for export output; its constructor must support this operation.

  • font – [in] Borrowed font used by backend plot setup.

  • x – [in] Mapped horizontal position in destination coordinates.

  • y – [in] Mapped vertical position in destination coordinates.

  • width – [in] Rectangle width in display units.

  • height – [in] Rectangle height in display units.

  • background – [in] Borrowed background color used by backend plot setup.

void Rbc_RenderPlotEnd(Rbc_RenderContext *ctx)

Close the export plot scope opened by PlotBegin.

Parameters:
  • ctx – [inout] Live context created for export output with an outstanding PlotBegin scope; its constructor must support this operation.

Rbc_RenderContext *Rbc_RenderBeginScreenClip(Graph *graphPtr, Drawable drawable, GC copyGC, int useDC)

Create an owned native screen clip stack.

Only ClipBegin, ClipEnd, ClipDrawable and End are supported. Fetch the current target after each push; None means empty or failed coverage. Absolute coordinates and bitmap masks are preserved. ClipEnd commits drawing to the parent target; End balances outstanding pushes and releases the context.

See also

Rbc_RenderEnd

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive until Rbc_RenderEnd releases the returned context.

  • drawable – [in] Borrowed destination in mapped display coordinates, kept valid until context release.

  • copyGC – [in] Borrowed pixel-copy GC, or NULL to create a private GC.

  • useDC – [in] Nonzero requests the Windows DC clip path; other scopes use scratch pixmaps.

Returns:

Owned clip context to release with Rbc_RenderEnd; graph and drawable remain borrowed.

Drawable Rbc_RenderClipDrawable(Rbc_RenderContext *ctx)

Query the current target of a screen clip stack.

Requery after changing the clip stack; do not retain a temporary target after popping its scope.

Parameters:
  • ctx – [in] Live context returned by Rbc_RenderBeginScreenClip.

Returns:

Borrowed current drawable, or None for empty or failed coverage.

void Rbc_RenderClipBegin(Rbc_RenderContext *ctx, int x, int y, int width, int height)

Nest a rectangular clip without painting a background.

Supported by screen clip scopes, Cairo geometry contexts and export contexts.

Parameters:
  • ctx – [inout] Live context created for rectangular clipping; its constructor must support this operation.

  • x – [in] Mapped horizontal position in destination coordinates.

  • y – [in] Mapped vertical position in destination coordinates.

  • width – [in] Rectangle width in display units.

  • height – [in] Rectangle height in display units.

void Rbc_RenderClipEnd(Rbc_RenderContext *ctx)

Pop one rectangular clip; an empty stack is a no-op.

Screen clip contexts commit their drawing to the parent target on pop. The common dispatcher decrements nesting before calling the backend.

See also

Rbc_RenderEnd

Parameters:
  • ctx – [in] Live context with clip support.

void Rbc_RenderBitmapMask(Rbc_RenderContext *ctx, Display *display, Pixmap bitmap, double x, double y, int width, int height, const XColor *color, int background)

Emit a bitmap mask through an export-output context.

Parameters:
  • ctx – [inout] Live context created for export output; its constructor must support this operation.

  • display – [in] Borrowed display owning the bitmap.

  • bitmap – [in] Borrowed bitmap to emit as a mask.

  • x – [in] Mapped horizontal position in destination coordinates.

  • y – [in] Mapped vertical position in destination coordinates.

  • width – [in] Rectangle width in display units.

  • height – [in] Rectangle height in display units.

  • color – [in] Borrowed paint color.

  • background – [in] Backend background/foreground pass selector; preserve the component-provided value.

Rbc_RenderContext *Rbc_RenderBeginStroke(Graph *graphPtr, Drawable drawable, GC gc, Rbc_RenderStrokeKind kind, const XColor *color, double width, const Rbc_Dashes *dashes, const XColor *offColor)

Create a batch for element traces, strips or independent segments.

Attempts Cairo first, then the native path. Returns NULL when the target or native trace setup cannot be used. The caller handles that failure. For native drawing, the supplied GC retains its raster operation and clip. TRACES permits Polyline; STRIPS and SEGMENTS permit Segments. End the successful context once with Rbc_RenderEnd().

Parameters:
  • graphPtr – [in] Borrowed owning graph with current mapped geometry, kept alive through the operation or context lifetime.

  • drawable – [in] Borrowed destination drawable in mapped widget coordinates, kept valid through context release.

  • gc – [in] Borrowed native fallback GC retaining raster operation, dashes and clipping.

  • kind – [in] TRACES permits Polyline; STRIPS and SEGMENTS permit Segments.

  • color – [in] Borrowed stroke color for Cairo; native fallback uses the supplied GC.

  • width – [in] Stroke width in display units; not scaled with geometry.

  • dashes – [in] Borrowed dash specification, or NULL for a solid stroke.

  • offColor – [in] Optional borrowed off-dash color.

Rbc_RenderContext *Rbc_RenderBegin(Graph *graphPtr, Drawable drawable, const XColor *colorPtr, double width, const Rbc_Dashes *dashesPtr, const XColor *offColorPtr)

Try to create a Cairo geometry context; NULL requests caller-selected native fallback.

Parameters:
  • graphPtr – [in] Borrowed owning graph with current mapped geometry, kept alive through the operation or context lifetime.

  • drawable – [in] Borrowed destination drawable in mapped widget coordinates, kept valid through context release.

  • colorPtr – [in] Borrowed stroke color required by Cairo setup.

  • width – [in] Stroke width in display units.

  • dashesPtr – [in] Borrowed dash specification, or NULL for solid.

  • offColorPtr – [in] Optional borrowed off-dash color.

Rbc_RenderContext *Rbc_RenderBeginExport(Rbc_ExportContext *exportPtr, const XColor *color, int lineWidth, const Rbc_Dashes *dashes, int capStyle, int joinStyle)

Export stroke context: Polyline, Segments, Arc, LineStyle, DashBackground and End only.

Available without Cairo; borrows export state and dispatches to its backend.

Parameters:
  • exportPtr – [in] Borrowed live document state; caller owns document setup, completion and I/O.

  • color – [in] Borrowed stroke color; backend-specific omission policy applies for NULL.

  • lineWidth – [in] Stroke width in display units.

  • dashes – [in] Borrowed dash specification, or NULL for solid.

  • capStyle – [in] X/Tk line cap style.

  • joinStyle – [in] X/Tk line join style.

int Rbc_RenderGCForeground(Graph *graphPtr, GC gc, XColor *color)

Query a GC foreground color for Cairo setup; return false if unavailable.

Parameters:
  • graphPtr – [in] Borrowed owning graph with current mapped geometry, kept alive through the operation or context lifetime.

  • gc – [in] Borrowed GC to query.

  • color – [out] Caller-owned XColor storage for the resolved foreground on success.

void Rbc_RenderPoints(Rbc_RenderContext *ctx, const Point2D *points, Tcl_Size count)

Draw mapped points using a Cairo geometry context.

Parameters:
  • ctx – [inout] Live context created for Cairo geometry; its constructor must support this operation.

  • points – [in] Borrowed mapped point array, accessible for count entries during this call.

  • count – [in] Number of point records, not bytes.

void Rbc_RenderPolyline(Rbc_RenderContext *ctx, const Point2D *points, Tcl_Size count)

Submit a mapped trace to a context supporting polyline operations.

Parameters:
  • ctx – [inout] Live context created for polyline drawing; its constructor must support this operation.

  • points – [in] Borrowed mapped point array, accessible for count entries during this call.

  • count – [in] Number of point records, not bytes.

void Rbc_RenderSegments(Rbc_RenderContext *ctx, const Segment2D *segments, Tcl_Size count)

Submit independent mapped segments to a supporting context.

Parameters:
  • ctx – [inout] Live context created for independent segment drawing; its constructor must support this operation.

  • segments – [in] Borrowed mapped endpoint pairs, accessible for count records during this call.

  • count – [in] Number of Segment2D records, not number of endpoints.

void Rbc_RenderLineStyle(Rbc_RenderContext *ctx, int capStyle, int joinStyle)

Set cap and join style on a supporting Cairo or export stroke context.

Parameters:
  • ctx – [inout] Live context created for Cairo or export stroke styling; its constructor must support this operation.

  • capStyle – [in] X/Tk line cap style.

  • joinStyle – [in] X/Tk line join style.

void Rbc_RenderDashBackground(Rbc_RenderContext *ctx, const XColor *color)

Set the off-dash color on a supporting Cairo or export stroke context.

Parameters:
  • ctx – [inout] Live context created for Cairo or export stroke styling; its constructor must support this operation.

  • color – [in] Optional borrowed off-dash color.

void Rbc_RenderSymbols(Rbc_RenderContext *ctx, const Rbc_RenderShape *shape, const Point2D *centers, Tcl_Size count, const XColor *fillColor, int outline)

Draw shape-template symbols using a Cairo geometry context.

Parameters:
  • ctx – [inout] Live context created for Cairo geometry; its constructor must support this operation.

  • shape – [in] Borrowed screen-space symbol template; its points describe polygon vertices or endpoint pairs.

  • centers – [in] Borrowed mapped center array.

  • count – [in] Number of center records.

  • fillColor – [in] Optional borrowed fill color; NULL suppresses filling.

  • outline – [in] Nonzero requests outlining with the context stroke color.

void Rbc_RenderEnd(Rbc_RenderContext *ctx)

Unwind remaining clip scopes and destroy an allocated context.

The context is invalid after this call. Backend-owned temporary resources are released; borrowed graph, document, GC and image resources are not. PlotBegin/PlotEnd scopes must already be balanced. Stack-based one-shot screen adapters manage their own lifetime and must not be passed here.

Parameters:
  • ctx – [in] Live, non-NULL context returned by a renderer constructor.

int Rbc_RenderArea(Graph *graphPtr, Drawable drawable, const Point2D *points, Tcl_Size count, const XColor *foreground, const XColor *background, Pixmap stipple)

Attempt an opaque Cairo polygon fill.

Equivalent to Rbc_RenderAreaOpacity with opacity 1.0. Fewer than three vertices decline the attempt.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • points – [in] Borrowed mapped polygon vertices, valid for count entries during this call.

  • count – [in] Number of array entries, not bytes.

  • foreground – [in] Borrowed foreground color; NULL declines the Cairo attempt.

  • background – [in] Optional borrowed background color; NULL leaves unpainted pattern bits transparent.

  • stipple – [in] Borrowed one-bit fill pattern, or None for a solid fill.

Returns:

Nonzero when handled (including documented empty no-ops); zero requests caller-selected native fallback.

int Rbc_RenderAreaOpacity(Graph *graphPtr, Drawable drawable, const Point2D *points, Tcl_Size count, const XColor *foreground, const XColor *background, Pixmap stipple, double opacity)

Attempt a Cairo polygon fill with solid-fill opacity.

Fewer than three vertices decline the attempt. Uses the plot clip and even-odd polygon filling; stipple pixels retain their own alpha and widget-relative origin.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • points – [in] Borrowed mapped polygon vertices, valid for count entries during this call.

  • count – [in] Number of array entries, not bytes.

  • foreground – [in] Borrowed foreground color; NULL declines the Cairo attempt.

  • background – [in] Optional borrowed background color; NULL leaves unpainted pattern bits transparent.

  • stipple – [in] Borrowed one-bit fill pattern, or None for a solid fill.

  • opacity – [in] Solid-fill alpha in [0,1]; ignored when stipple is not None.

Returns:

Nonzero when handled (including documented empty no-ops); zero requests caller-selected native fallback.

int Rbc_RenderTileArea(Graph *graphPtr, Drawable drawable, const Point2D *points, Tcl_Size count, const Tk_PhotoImageBlock *block)

Attempt a polygon filled with a repeating photo tile.

Uses the plot clip and a toplevel-relative pattern origin. On a Cairo graph, fewer than three vertices decline the attempt; an empty photo block is handled without painting, preserving tile precedence.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • points – [in] Borrowed mapped polygon vertices, valid for count entries during this call.

  • count – [in] Number of array entries, not bytes.

  • block – [in] Borrowed readable photo block, including valid pitch, channel offsets and pixel storage.

Returns:

Nonzero when handled (including documented empty no-ops); zero requests caller-selected native fallback.

int Rbc_RenderPhoto(Graph *graphPtr, Drawable drawable, const Tk_PhotoImageBlock *block, int x, int y)

Attempt to paint a mapped photo block once.

Uses the plot clip without scaling or rotation. An empty block on a Cairo graph is a handled no-op. Pixel conversion is temporary; the caller retains its photo and block storage.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • block – [in] Borrowed readable photo block, including valid pitch, channel offsets and pixel storage.

  • x – [in] Destination X coordinate in pixels.

  • y – [in] Destination Y coordinate in pixels.

Returns:

Nonzero when handled (including documented empty no-ops); zero requests caller-selected native fallback.

int Rbc_RenderRectangles(Graph *graphPtr, Drawable drawable, const Rbc_RenderRectangle *rectangles, Tcl_Size count, const XColor *foreground, const XColor *background, Pixmap stipple, double opacity)

Attempt a Cairo rectangle batch with group opacity.

Nonpositive counts decline the attempt. Nonpositive rectangle dimensions are skipped. Uses the plot clip; opacity is applied once to the composed batch, not separately at each overlap.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • rectangles – [in] Borrowed mapped rectangle array, valid for count records.

  • count – [in] Number of array entries, not bytes.

  • foreground – [in] Borrowed foreground color; NULL declines the Cairo attempt.

  • background – [in] Optional borrowed background color; NULL leaves unpainted pattern bits transparent.

  • stipple – [in] Borrowed one-bit fill pattern, or None for a solid fill.

  • opacity – [in] Group alpha in [0,1], applied to solid and stippled rectangles together.

Returns:

Nonzero when handled (including documented empty no-ops); zero requests caller-selected native fallback.

Rbc_RenderContext *Rbc_RenderBeginDrawable(Graph *graphPtr, Drawable drawable, int width, int height, const XColor *color, double lineWidth, const Rbc_Dashes *dashes, const XColor *offColor)

Attempt a Cairo context covering an explicit drawable extent.

Uses the full drawable rectangle instead of the plot clip. Supports the Cairo geometry operations; release a successful context with Rbc_RenderEnd.

See also

Rbc_RenderBegin

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive until Rbc_RenderEnd releases the returned context.

  • drawable – [in] Borrowed destination in mapped display coordinates, kept valid until context release.

  • width – [in] Positive destination width in pixels.

  • height – [in] Positive destination height in pixels.

  • color – [in] Borrowed required stroke color.

  • lineWidth – [in] Stroke width in display units.

  • dashes – [in] Borrowed dash specification, or NULL for solid.

  • offColor – [in] Optional borrowed off-dash color.

Returns:

Owned context, or NULL when unavailable or dimensions are nonpositive.

int Rbc_RenderLegendBar(Graph *graphPtr, Drawable drawable, int width, int height, const Rbc_RenderRectangle *r, const XColor *foreground, const XColor *background, Pixmap stipple, double opacity)

Attempt a Cairo legend swatch with a sample-local pattern origin.

Uses the full drawable clip; stipple restarts at the sample top-left corner. For an eligible Cairo graph, nonpositive sample dimensions are a handled no-op.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • width – [in] Positive destination drawable width in pixels.

  • height – [in] Positive destination drawable height in pixels.

  • r – [in] Borrowed sample rectangle in destination coordinates.

  • foreground – [in] Borrowed foreground color; NULL declines the Cairo attempt.

  • background – [in] Optional borrowed background color; NULL leaves unpainted pattern bits transparent.

  • stipple – [in] Borrowed one-bit fill pattern, or None for a solid fill.

  • opacity – [in] Group alpha in [0,1], including stipple paint.

Returns:

Nonzero when handled (including documented empty no-ops); zero requests caller-selected native fallback.

int Rbc_RenderBitmap(Graph *graphPtr, Drawable drawable, const Rbc_RenderRectangle *r, Pixmap bitmap, Pixmap mask, const XColor *foreground, const XColor *background, const Point2D *polygon, Tcl_Size nPoints)

Attempt a mapped Cairo bitmap with optional rotated background.

Uses the plot clip. A polygon with at least three vertices and a background color supplies the rotated background; otherwise the bitmap background policy applies. Source bits are converted before painting. For an eligible Cairo graph, nonpositive rectangle dimensions are a handled no-op.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive throughout this synchronous operation.

  • drawable – [in] Borrowed destination in mapped display coordinates.

  • r – [in] Borrowed mapped rectangle; its dimensions also specify the source bitmap extent.

  • bitmap – [in] Borrowed one-bit bitmap; None declines the attempt.

  • mask – [in] Optional borrowed one-bit visibility mask, or None.

  • foreground – [in] Borrowed foreground color; NULL declines the Cairo attempt.

  • background – [in] Optional borrowed background color; NULL leaves unpainted pattern bits transparent.

  • polygon – [in] Borrowed mapped background polygon, or NULL when absent.

  • nPoints – [in] Number of background polygon vertices; use zero when no polygon is supplied.

Returns:

Nonzero when handled (including documented empty no-ops); zero requests caller-selected native fallback.

Rbc_RenderContext *Rbc_RenderBeginBitmapSymbols(Graph *graphPtr, Drawable drawable, Pixmap bitmap, Pixmap mask, int width, int height, const XColor *foreground, const XColor *background, int targetWidth, int targetHeight)

Convert a bitmap once for a Cairo symbol batch.

Source bitmap pixels are copied into an owned pattern. End the returned context with Rbc_RenderEnd.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive until Rbc_RenderEnd releases the returned context.

  • drawable – [in] Borrowed destination in mapped display coordinates, kept valid until context release.

  • bitmap – [in] Borrowed one-bit source bitmap; None declines the attempt.

  • mask – [in] Optional borrowed one-bit visibility mask, or None.

  • width – [in] Positive source bitmap width in pixels.

  • height – [in] Positive source bitmap height in pixels.

  • foreground – [in] Borrowed foreground color; NULL declines the Cairo attempt.

  • background – [in] Optional borrowed background color; NULL leaves unpainted pattern bits transparent.

  • targetWidth – [in] Positive selects the explicit drawable clip; zero selects the graph plot clip.

  • targetHeight – [in] Positive explicit drawable height when targetWidth is positive; otherwise ignored.

Returns:

Owned bitmap-symbol context, or NULL requesting native fallback.

void Rbc_RenderBitmapSymbols(Rbc_RenderContext *ctx, const Point2D *centers, Tcl_Size count)

Paint a prepared bitmap at mapped symbol centers in input order.

Converts each center to int before subtracting half the bitmap size. Does not resample or repeat pixels; nonpositive counts paint nothing. The context remains owned by the caller.

Parameters:
  • ctx – [inout] Live non-NULL context returned by Rbc_RenderBeginBitmapSymbols.

  • centers – [in] Borrowed mapped center array, valid for count entries.

  • count – [in] Number of array entries, not bytes.

Auxiliary types

struct Rbc_RenderRectangle

Keep bar geometry in full-width widget coordinates.

Public Members

int x

Rectangle origin X in widget pixels.

int y

Rectangle origin Y in widget pixels.

int width

Rectangle width in pixels.

int height

Rectangle height in pixels.

struct Rbc_RenderBitmapStyle

Mapped bitmap paint policy; all referenced resources remain component-owned.

A rotated opaque background is already clipped/mapped by the component; mask then refers to the bitmap itself, as in the legacy drawing path.

Public Members

Pixmap bitmap

Borrowed one-bit source bitmap; None means absent.

Pixmap mask

Borrowed optional bitmap mask; None means absent.

GC gc

Borrowed foreground GC.

GC fillGC

Borrowed fill/background GC; absent means no fill.

const XColor *foreground

Borrowed foreground color; NULL means absent.

const XColor *background

Borrowed background color; NULL means absent.

const Point2D *backgroundPoints

Borrowed mapped polygon for a rotated opaque background.

Tcl_Size backgroundCount

Number of backgroundPoints entries; at most RBC_RENDER_BITMAP_OUTLINE_POINTS.

struct Rbc_RenderFillStyle

Fill policy shared by screen and export.

backgroundOnly preserves the legacy PostScript fallback for image-tiled areas.

Public Members

const XColor *foreground

Borrowed foreground color; NULL means absent.

const XColor *background

Borrowed background color; NULL means absent.

Pixmap stipple

Borrowed one-bit stipple; None selects a solid fill.

double opacity

Solid polygon opacity; PostScript ignores it.

int backgroundOnly

Nonzero requests the legacy background-only fill fallback.

struct Rbc_RenderArcGeometry

Value-only ellipse geometry; dispatch normalizes a copy and rejects non-finite or degenerate input.

Public Members

double cx

Ellipse center X in mapped display coordinates.

double cy

Ellipse center Y in mapped display coordinates.

double rx

Positive horizontal radius in display units.

double ry

Positive vertical radius in display units.

double start

Start angle in degrees, measured counterclockwise from the rightward direction.

double extent

Signed sweep in degrees; absolute values of at least 360 select a full ellipse.

Rbc_RenderArcStyle style

Open curve, endpoint chord or center-connected sector.

struct Rbc_RenderSymbolStyle

Export symbol policy copied into a context; referenced colors and pixmaps remain borrowed.

Public Members

Rbc_RenderSymbolType type

Semantic symbol shape.

int size

Symbol size in display pixels.

int outlineWidth

Outline width in display pixels.

const XColor *outlineColor

Borrowed outline color; NULL suppresses the outline.

const XColor *fillColor

Borrowed fill color; NULL suppresses the fill.

Pixmap bitmap

Borrowed one-bit source bitmap; None means absent.

Pixmap mask

Borrowed optional bitmap mask; None means absent.

struct Rbc_RenderNativeSymbolStyle

Borrowed native symbol resources.

Sampling state is returned through counter; preserve it across batches belonging to the same element.

Public Members

Rbc_RenderSymbolType type

Semantic symbol shape.

int outlineWidth

Outline width in pixels.

GC outlineGC

Borrowed outline GC; absent means no outline.

GC fillGC

Borrowed fill/background GC; absent means no fill.

Pixmap bitmap

Borrowed one-bit source bitmap; None means absent.

Pixmap mask

Borrowed optional bitmap mask; None means absent.

Tcl_Size interval

Positive values enable interval sampling; nonpositive values draw every supplied center.

Tcl_Size counter

Mutable point counter; preserve across batches of the same element.

struct Rbc_RenderBarStyle

Copied bar paint policy; the element retains ownership of all Tk resources.

Public Members

Tk_3DBorder border

Borrowed Tk border supplying fill and relief colors.

XColor *fgColor

Borrowed resolved foreground color.

GC gc

Borrowed fill GC, including stipple and raster state.

Pixmap stipple

Borrowed fill stipple; None means no stipple.

int borderWidth

Border thickness in pixels.

int relief

Tk relief selector.

double fillOpacity

Fill alpha used by capable backends; native fallback retains its opaque behavior.

struct Rbc_RenderShape

Small value-only symbol geometry record shared by drawing backends.

Public Members

Rbc_RenderShapeType type

Circle, polygon or independent-segment geometry selector.

double radius

Circle radius in display units, used for circle shapes.

int nPoints

Number of initialized entries in points, bounded by twelve.

Point2D points[12]

Symbol-local vertex offsets; segment endpoints are stored in pairs.

typedef int Rbc_RenderPosition[2]

Full-width integer x/y, never XPoint shorts.

typedef void Rbc_RenderRunProc(void *data, Drawable drawable, Tcl_Size count)

Synchronous native batch callback; no argument is retained by the renderer.

Must preserve graph and drawing-resource lifetime and must not retain the target.

Param data:

[in] Borrowed batch-specific data supplied to Rbc_RenderScreenRun.

Param drawable:

[in] Borrowed platform target, valid only until the callback returns.

Param count:

[in] Number of items in data to present.

typedef struct Rbc_RenderTarget Rbc_RenderTarget

The context typedef names the backend record documented below. It is rendered there once, rather than indexing both the typedef and struct under the same C identifier.

Backend dispatch

struct Rbc_RenderContext

Prefix embedded first in every allocated backend context.

Constructors initialize the entire allocation. Rbc_RenderEnd() unwinds clips and calls ops->end, which releases backend state and the allocation. Borrowed graph/document resources must remain alive until that completes.

Public Members

const Rbc_RenderOps *ops

Borrowed immutable dispatch table.

Graph *graphPtr

Borrowed graph, or NULL for contexts that do not need it.

unsigned int clipDepth

Outstanding rectangular clip scopes.

struct Rbc_RenderOutputOps

Presentation callbacks selected by each constructor.

Every callback receives a live context of its constructor-selected family as the first argument. Input arrays and Tk resources are borrowed for the synchronous call unless the member contract says otherwise. The context and its target must remain live throughout the operation; callbacks do not own the graph or document. Coordinates are already mapped, not graph data values.

NULL members mark unsupported capabilities, not successful no-ops or fallback requests. The common presentation dispatchers do not test for NULL members. A populated table is not permission to use every member on every context: constructors must also initialize the state required by the chosen callback.

Public Members

void (*text)(Rbc_RenderContext*, char *string, TextStyle *style, double x, double y)

Present text through the selected output backend.

Screen-text and document-output contexts borrow the NUL-terminated string and text style for the call. Coordinates are mapped display units; native presentation truncates them to integers. The text service may refresh style GC state; document callbacks append output.

See also

Rbc_RenderText

void (*photo)(Rbc_RenderContext*, Tk_PhotoHandle photo, double x, double y)

Emit a photo image into document output.

Document-output contexts borrow the photo handle and consume its current pixels synchronously. The mapped origin does not request resampling. No image ownership is transferred.

void (*window)(Rbc_RenderContext*, Tk_Window tkwin, double x, double y)

Capture a window for document output when enabled.

Document-output contexts borrow the live Tk window and mapped origin. Capture may allocate temporary raster storage; the window remains caller-owned. Export policy can suppress window capture.

See also

Rbc_RenderWindow

void (*backgroundPolygon)(Rbc_RenderContext*, const XColor *color, const Point2D *points, Tcl_Size count)

Paint a document background polygon.

Document-output contexts borrow the color and count mapped vertices for this call. This explicit color operation does not replace the context fill policy. Count measures vertices, not bytes.

void (*border)(Rbc_RenderContext*, Tk_3DBorder border, double x, double y, int width, int height, int borderWidth, int relief, int fill)

Draw a relief border and optional interior.

Screen-decoration or document-output contexts borrow the Tk border. Origin, dimensions and border width use display pixels; relief is a Tk relief selector and fill enables the interior. Native drawing uses the supplied window target; export emits its representation.

See also

Rbc_RenderBorder

void (*clearRectangle)(Rbc_RenderContext*, double x, double y, int width, int height)

Clear a rectangle in document output.

Document-output contexts receive a mapped origin and pixel dimensions. Clearing follows the selected document backend, not a portable framebuffer erase or a change to the context paint policy.

void (*backgroundRectangles)(Rbc_RenderContext*, const XColor *color, const Rbc_RenderRectangle *rectangles, Tcl_Size count)

Paint document rectangles with an explicit background color.

Document-output contexts borrow the color and count rectangle records. Rectangles use mapped pixel geometry. The array and color are consumed synchronously and are not retained.

void (*plotBegin)(Rbc_RenderContext*, Tk_Font font, double x, double y, int width, int height, const XColor *background)

Open a document plot scope.

Document-output contexts borrow the font and optional background, and receive mapped bounds in pixels. Backend graphics state or output groups may be opened. Pair with plotEnd; this scope is separate from the rectangular clipDepth stack.

void (*plotEnd)(Rbc_RenderContext*)

Close the matching document plot scope.

Requires a preceding plotBegin on the same document-output context. Emits the backend scope closure without releasing the context or changing common clipDepth.

void (*bitmapMask)(Rbc_RenderContext*, Display *display, Pixmap bitmap, double x, double y, int width, int height, const XColor *color, int background)

Emit a one-bit bitmap mask into document output.

Document-output contexts borrow the display, bitmap and color for synchronous readback/emission. Origin and extent use mapped pixels; background selects the background-mask convention. Temporary image storage does not transfer ownership of the input bitmap.

void (*image)(Rbc_RenderContext*, Tk_Image image, double x, double y)

Present a Tk image on a screen-raster context.

Borrows the image for synchronous presentation at a mapped origin. The adapter can try Cairo for supported photos and otherwise use native Tk drawing. It does not retain the image or perform component mapping.

void (*textLayout)(Rbc_RenderContext*, TextLayout*, TextStyle*, int, int)

Draw a cached layout through native screen text.

Screen-text contexts borrow the layout and mutable TextStyle; integer coordinates use the captured destination. Does not rebuild or free the layout. Style GC state may be refreshed.

void (*textSize)(Rbc_RenderContext*, const char*, TextStyle*, int, int, Dim2D*)

Draw native screen text and report its rotated extent.

Screen-text contexts borrow the string and mutable TextStyle and write the required caller-owned Dim2D output. Integer coordinates use the captured target. This operation draws; it is not a measurement-only query.

void (*mappedBitmap)(Rbc_RenderContext*, const Rbc_RenderRectangle*, const Rbc_RenderBitmapStyle*)

Present a mapped bitmap with its component paint policy.

Screen-raster contexts borrow the rectangle and bitmap style, including GCs, pixmaps and colors. Geometry is already mapped; the adapter tries the configured renderer before its native fallback. No resource is retained beyond the call.

void (*pixmap)(Rbc_RenderContext*, Pixmap, GC, const Rbc_RenderRectangle*)

Copy a mapped pixmap onto the screen target.

Screen-raster contexts borrow the pixmap, GC and mapped rectangle. Copies the selected extent from source origin zero using caller-selected GC semantics; does not scale the source.

See also

Rbc_RenderPixmap

void (*screenRectangle)(Rbc_RenderContext*, GC, Rbc_Tile, int, int, int, int)

Fill a native screen rectangle with an optional tile.

Screen-decoration contexts borrow the GC and tile; integer origin and dimensions use widget pixels. Native tile and stipple-origin behavior is preserved. This callback is also used when the graph selects Cairo.

void (*focus)(Rbc_RenderContext*, GC, int)

Draw the native window focus highlight.

Screen-decoration contexts borrow the GC and receive highlight thickness in pixels. Uses the captured window/drawable and native Tk behavior even for a Cairo graph.

void (*copyArea)(Rbc_RenderContext*, Drawable, GC, int, int, unsigned int, unsigned int, int, int)

Copy completed screen pixels between borrowed drawables.

Screen-decoration contexts capture the destination; arguments provide the source, GC, integer source/destination origins and unsigned pixel extents. Preserves GC raster and clipping behavior and does not rerender geometry.

void (*textBackground)(Rbc_RenderContext*, GC, const Point2D*, const Point2D*)

Fill a native text-marker background polygon.

Screen-detail contexts borrow the GC, four outline vertices and mapped anchor. The anchor is added before native integer conversion. No independent track/plot clip is introduced.

void (*arrowHead)(Rbc_RenderContext*, GC, const Point2D*)

Scan-convert a native arrowhead.

Screen-detail contexts borrow the GC and RBC_RENDER_ARROW_POINTS finite mapped vertices, including the repeated closing point. Preserves span batching and the enclosing clip; the vertex array is not retained.

void (*legendLine)(Rbc_RenderContext*, GC, int, int, int)

Draw a native line legend sample.

Screen-detail contexts borrow the GC and integer center/half-length. Emits two rows at y and y+1; each row restarts the native dash pattern. Uses the captured target without retaining the GC.

void (*legendBar)(Rbc_RenderContext*, GC, int, int, int)

Draw a native bar legend sample.

Screen-detail contexts borrow the fill GC and receive integer origin/side length. The native operation establishes a local stipple origin and resets it to zero, rather than restoring an arbitrary previous origin.

void (*run)(Rbc_RenderContext*, void*, Tcl_Size, Rbc_RenderRunProc*)

Execute a synchronous native drawing run.

Screen-detail contexts borrow callback data and the run procedure. Count is an item count. The procedure may use the supplied drawable only during the call and must preserve graph/resource lifetime; the backend retains neither data nor procedure.

void (*bitmapRun)(Rbc_RenderContext*, Pixmap, GC, int, int, const Rbc_RenderPosition*, Tcl_Size)

Present a batch of native bitmap markers.

Screen-detail contexts borrow the bitmap, GC and count integer positions. Width and height describe the bitmap extent in pixels. Preserves native DC batching and mask/opaque-bitmap behavior; no input array is retained.

struct Rbc_RenderOps

Geometry dispatch and lifetime operations for one context family.

Populate only supported operations. Dispatch generally calls them directly; a caller using the wrong context family can dereference a NULL callback. Clip callbacks implement backend state; the common layer owns clipDepth. Every callback receives its live constructor-selected context first. Geometry arrays are borrowed for the synchronous call and counts measure records, not bytes. Backend operation tables are immutable and remain live for all contexts that reference them. No operation implicitly changes the context family.

Public Members

void (*polyline)(Rbc_RenderContext*, const Point2D*, Tcl_Size)

Stroke one connected mapped trace.

Trace-capable stroke or document contexts borrow count Point2D vertices for the call. The backend owns batching and integer conversion; separate calls are separate paths. Common dispatch does not check for a NULL callback.

void (*segments)(Rbc_RenderContext*, const Segment2D*, Tcl_Size)

Stroke independent mapped endpoint pairs.

Segment/strip-capable stroke, native decoration or document contexts borrow count Segment2D records. Each record is independent; backend batching preserves the selected native or document semantics.

void (*lineStyle)(Rbc_RenderContext*, int, int)

Update stroke cap and join state.

Stroke-capable contexts receive X cap/join selectors. The callback translates or emits the backend state; it neither replaces the context nor takes ownership of any resource.

void (*dashBackground)(Rbc_RenderContext*, const XColor*)

Set or disable the off-dash stroke underlay.

Stroke-capable contexts borrow the color for the call; NULL disables the underlay. Implementations copy or emit the color and retain the current dash pattern.

void (*fillPolygon)(Rbc_RenderContext*, const Point2D*, Tcl_Size)

Fill a mapped polygon using the context policy.

Fill-capable contexts borrow count vertices for the call. The common wrapper ignores fewer than three points; a dispatched call requires a live context; backend fill rule, pattern, opacity and fallback remain constructor-specific.

void (*fillRectangles)(Rbc_RenderContext*, const Rbc_RenderRectangle*, Tcl_Size)

Fill mapped rectangle records using the context policy.

Fill or bar contexts borrow count rectangles. The common wrapper suppresses nonpositive counts; a dispatched call requires a live context. Bar contexts can add relief borders; a generic fill callback does not imply bar styling.

void (*symbolPoints)(Rbc_RenderContext*, const Point2D*, Tcl_Size)

Present symbols at mapped centers.

Symbol contexts borrow count center points; type and paint resources come from construction. Native sampling can update the borrowed style counter. The common wrapper suppresses nonpositive counts; a dispatched call requires a live context.

const Rbc_RenderOutputOps *output

Borrow the immutable presentation-operation table.

NULL means this context has no presentation family. A non-NULL table still contains NULL members for unsupported capabilities; callers must select a constructor supporting the specific operation. The context never frees this table.

void (*end)(Rbc_RenderContext*)

Release an owned context and its backend resources.

Rbc_RenderEnd unwinds common rectangular clips before invoking this callback. The callback releases owned graphics state and the context allocation, while borrowed graph, document and style resources survive. Stack-based one-shot contexts have no destructor and must not be ended.

See also

Rbc_RenderEnd

void (*arc)(Rbc_RenderContext*, const Rbc_RenderArcGeometry*)

Stroke normalized ellipse geometry.

Arc-capable stroke contexts borrow a normalized local geometry copy for this call. Rbc_RenderArc rejects non-finite or degenerate geometry before dispatch. The callback constructs the path under the current clip without retaining the copy.

See also

Rbc_RenderArc

void (*fillArc)(Rbc_RenderContext*, const Rbc_RenderArcGeometry*)

Fill a normalized closed ellipse segment.

Arc-capable fill contexts borrow a normalized local geometry copy. Rbc_RenderFillArc suppresses OPEN style and invalid geometry before dispatch. The context fill policy supplies paint; the geometry copy is not retained.

void (*clipBegin)(Rbc_RenderContext*, int, int, int, int)

Push an intersecting rectangular backend clip.

Clip-capable contexts receive integer mapped origin and pixel dimensions. The common dispatcher increments clipDepth before calling; the callback manages backend state only. Native clip contexts can select a scratch target. Pair each push with clipEnd.

void (*clipEnd)(Rbc_RenderContext*)

Restore the previous backend clip state.

Invoked only for an outstanding common clip scope; the dispatcher decrements clipDepth before calling. The backend restores or copies back its saved state without changing the common counter. Rbc_RenderEnd unwinds remaining scopes.

Each operation-table member has a separate contract and link target. The first callback argument is the live context selected by its constructor; a non-NULL operation table alone does not establish that every callback is supported. In particular, Rbc_RenderOps.output is an optional table, and its individual entries can also be NULL. See Rendering architecture and contracts for the constructor capability matrix.

Rbc_RenderOps.end consumes owned heap contexts after common clip unwinding. Stack-based one-shot screen adapters must not use it. Rectangular clip callbacks implement backend state only; the common dispatcher owns the nesting counter.

Common screen adapters

These private callbacks implement the constructor families described in Rendering architecture and contracts. A populated operation table alone does not establish that a particular constructor initialized every callback’s required state. Each callback’s parameter description identifies the required family. Destructors consume heap contexts; synchronous decoration/detail contexts can be stack-based and must not be passed to them. See Rendering architecture and contracts for the internal adapter call relationships.

group Screen dispatch internals

Private adapters selected by capability-specific constructors.

Graphs, styles, drawables and component geometry remain borrowed.

Functions

static void NativeText(Rbc_RenderContext *ctx, char *string, TextStyle *style, double x, double y)

Draw native text at integer-truncated screen coordinates.

Borrows the exact window/drawable captured by BeginScreenText and the text style. Requires finite int-representable coordinates. Does not round, retain the string or select Cairo even on a Cairo graph.

Parameters:
  • ctx – [inout] Screen-text context created by Rbc_RenderBeginScreenText.

  • string – [in] Borrowed NUL-terminated text consumed synchronously.

  • style – [inout] Borrowed text style and live font/GC resources; the text service may refresh GC state.

  • x – [in] Finite int-representable X coordinate; truncated to int before native drawing.

  • y – [in] Finite int-representable Y coordinate; truncated to int before native drawing.

static void NativeTextLayout(Rbc_RenderContext *ctx, TextLayout *layout, TextStyle *style, int x, int y)

Draw a caller-owned cached layout on the captured native text target.

Preserves integer coordinates and delegates font/bitmap work to the native backend. The layout, style and window must remain live for the call.

Parameters:
  • ctx – [inout] Screen-text context created by Rbc_RenderBeginScreenText.

  • layout – [in] Borrowed cached text layout; not rebuilt or freed here.

  • style – [inout] Borrowed text style and live font/GC resources; the text service may refresh GC state.

  • x – [in] Destination X coordinate in display units.

  • y – [in] Destination Y coordinate in display units.

static void NativeTextSize(Rbc_RenderContext *ctx, const char *string, TextStyle *style, int x, int y, Dim2D *size)

Draw and measure text using the native text service.

Borrows text/style and writes the requested size through the backend. This is not a measurement-only adapter; it uses the captured destination.

Parameters:
  • ctx – [inout] Screen-text context created by Rbc_RenderBeginScreenText.

  • string – [in] Borrowed NUL-terminated text consumed synchronously.

  • style – [inout] Borrowed text style and live font/GC resources; the text service may refresh GC state.

  • x – [in] Destination X coordinate in display units.

  • y – [in] Destination Y coordinate in display units.

  • size – [out] Required caller-owned storage for rotated text dimensions.

static void NativeTextEnd(Rbc_RenderContext *ctx)

Free the screen-text adapter record.

Owns no font, window, layout or drawable. Called after common clip unwinding; text contexts themselves expose no clip operations.

Parameters:
  • ctx – [in] Owned screen-text context consumed by this call.

static void ScreenMappedBitmap(Rbc_RenderContext *ctx, const Rbc_RenderRectangle *r, const Rbc_RenderBitmapStyle *style)

Try the configured bitmap renderer before native presentation.

Uses the explicit foreground or queries the borrowed GC. With a usable color, tries Rbc_RenderBitmap and returns when handled; otherwise delegates the unchanged style to Rbc_NativeBitmap. Does not retain bitmap/mask/color resources or establish an independent clipping scope.

Parameters:
  • ctx – [inout] Screen-raster context created by Rbc_RenderBeginScreenRaster.

  • r – [in] Borrowed mapped destination rectangle; dimensions also select the source extent.

  • style – [in] Borrowed bitmap/mask/color style; native fallback changes the private bitmap GC clip state.

static void ScreenTkImage(Rbc_RenderContext *ctx, Tk_Image image, double x, double y)

Present a Tk image with a Cairo photo attempt and native fallback.

On a Cairo graph, resolves the image name to a photo and borrows its block only during Rbc_RenderPhoto. Other images or failed attempts use the native Tk image path. Coordinates truncate to int; no surface/DC is retained by this adapter across Tk image redraw.

Parameters:
  • ctx – [inout] Screen-raster context created by Rbc_RenderBeginScreenRaster.

  • image – [in] Borrowed live Tk image; its current full extent is presented.

  • x – [in] Finite int-representable X coordinate; truncated to int before native drawing.

  • y – [in] Finite int-representable Y coordinate; truncated to int before native drawing.

static void ScreenPixmap(Rbc_RenderContext *ctx, Pixmap pixmap, GC gc, const Rbc_RenderRectangle *r)

Copy a borrowed pixmap using native presentation.

Delegates the mapped rectangle and GC unchanged. A Cairo graph still uses this path because the input contains completed native pixels.

Parameters:
  • ctx – [inout] Screen-raster context created by Rbc_RenderBeginScreenRaster.

  • pixmap – [in] Borrowed source pixmap readable from (0,0) over the rectangle extent.

  • gc – [in] Borrowed configured GC with the required clip, raster operation and drawing style.

  • r – [in] Borrowed mapped destination rectangle; dimensions also select the source extent.

static void ScreenRasterEnd(Rbc_RenderContext *ctx)

Free the screen-raster adapter record.

Does not release any caller-owned Tk image, pixmap, mask, GC or graph.

Parameters:
  • ctx – [in] Owned screen-raster context consumed by this call.

static void ScreenBorder(Rbc_RenderContext *ctx, Tk_3DBorder border, double x, double y, int width, int height, int borderWidth, int relief, int fill)

Draw a native Tk border or relief rectangle.

Truncates double origins to int and preserves size, fill and relief flags. Called through a synchronous stack decoration context; owns no resources.

Parameters:
  • ctx – [inout] Synchronous stack screen adapter with graph/window and destination fields initialized.

  • border – [in] Borrowed Tk border supplying relief colors.

  • x – [in] Finite int-representable X coordinate; truncated to int before native drawing.

  • y – [in] Finite int-representable Y coordinate; truncated to int before native drawing.

  • width – [in] Nonnegative rectangle or bitmap width in pixels.

  • height – [in] Nonnegative rectangle or bitmap height in pixels.

  • borderWidth – [in] Border thickness in pixels.

  • relief – [in] Tk relief constant.

  • fill – [in] Nonzero fills the interior; zero draws only the relief border.

static void ScreenRectangle(Rbc_RenderContext *ctx, GC gc, Rbc_Tile tile, int x, int y, int width, int height)

Fill an integer rectangle through the native rectangle service.

Borrows GC and optional tile and preserves their backend-specific behavior. Does not select Cairo or retain resources after the call.

Parameters:
  • ctx – [inout] Synchronous stack screen adapter with graph/window and destination fields initialized.

  • gc – [in] Borrowed fill GC, required only when tile is NULL.

  • tile – [in] Optional borrowed tile taking precedence over gc; existing origin is preserved.

  • x – [in] Destination X coordinate in display units.

  • y – [in] Destination Y coordinate in display units.

  • width – [in] Nonnegative rectangle or bitmap width in pixels.

  • height – [in] Nonnegative rectangle or bitmap height in pixels.

static void ScreenSegments(Rbc_RenderContext *ctx, const Segment2D *segments, Tcl_Size count)

Draw native screen segments with the complete borrowed GC.

Preserves raster operation, clip, dash and cap settings. Used for overlays including XOR; ordinary Cairo compositing is not an equivalent substitute.

Parameters:
  • ctx – [inout] Synchronous stack screen adapter with graph/window and destination fields initialized.

  • segments – [in] Borrowed mapped endpoint pairs, readable for count Segment2D records.

  • count – [in] Number of geometry records, not bytes.

static void ScreenCopyArea(Rbc_RenderContext *ctx, Drawable source, GC gc, int srcX, int srcY, unsigned int width, unsigned int height, int dstX, int dstY)

Copy completed pixels to the captured destination.

Borrows both drawables and the GC, preserving integer source/destination coordinates and dimensions. Does not rerender geometry or choose Cairo.

Parameters:
  • ctx – [inout] Synchronous stack screen adapter with graph/window and destination fields initialized.

  • source – [in] Borrowed source drawable compatible with the destination captured by ctx.

  • gc – [in] Borrowed configured GC with the required clip, raster operation and drawing style.

  • srcX – [in] Source rectangle X coordinate in pixels.

  • srcY – [in] Source rectangle Y coordinate in pixels.

  • width – [in] Nonnegative rectangle or bitmap width in pixels.

  • height – [in] Nonnegative rectangle or bitmap height in pixels.

  • dstX – [in] Destination rectangle X coordinate in pixels.

  • dstY – [in] Destination rectangle Y coordinate in pixels.

static void ScreenFocus(Rbc_RenderContext *ctx, GC gc, int width)

Draw a native focus decoration on the captured target.

Borrows window and GC; the native backend owns the exact focus geometry. The adapter neither changes graph geometry nor retains resources.

Parameters:
  • ctx – [inout] Synchronous stack screen adapter with graph/window and destination fields initialized.

  • gc – [in] Borrowed configured GC with the required clip, raster operation and drawing style.

  • width – [in] Native focus highlight thickness in pixels.

static void NativeClipBegin(Rbc_RenderContext *ctx, int x, int y, int width, int height)

Push a native rectangular clip frame.

Uses the owned native clip stack. Common dispatch has already incremented clipDepth. Callers obtain the resulting target through Rbc_RenderClipDrawable and must skip drawing for None while still balancing the frame.

Parameters:
  • ctx – [inout] Screen-clip context with a live owned nativeClip stack.

  • x – [in] Destination X coordinate in display units.

  • y – [in] Destination Y coordinate in display units.

  • width – [in] Clip width; nonpositive values push an empty frame.

  • height – [in] Clip height; nonpositive values push an empty frame.

static void NativeClipEnd(Rbc_RenderContext *ctx)

Pop and commit the current native clip frame.

Common dispatch decrements clipDepth first. Backend handling restores native state or copies scratch pixels to the parent; no geometry is redrawn here.

Parameters:
  • ctx – [inout] Screen-clip context with a live owned nativeClip stack; common depth was already decremented.

static void ScreenClipEnd(Rbc_RenderContext *ctx)

Destroy the owned native clip stack and its adapter.

Invoked by Rbc_RenderEnd after common clip-depth unwinding. Borrowed graph, base drawable and copy GC remain caller-owned.

Parameters:
  • ctx – [in] Owned screen-clip context consumed here, including its nativeClip stack.

static void NativePolyline(Rbc_RenderContext *ctx, const Point2D *points, Tcl_Size count)

Submit one polyline to the retained native trace batch.

Requires a trace context initialized by Rbc_NativeBeginTrace. Borrows the point array for this call; backend scratch storage and any DC survive until End. Do not use the shared operation table as permission to call this on a segments-only context whose trace pointer is NULL.

Parameters:
  • ctx – [inout] Native trace context with nativeTrace initialized by Rbc_NativeBeginTrace.

  • points – [in] Borrowed mapped point array, readable for count entries.

  • count – [in] Number of geometry records, not bytes.

static void NativeStrips(Rbc_RenderContext *ctx, const Segment2D *segments, Tcl_Size count)

Submit independent strip segments to the native strip path.

Borrows graph, drawable, GC and segment array. Keeps the strip-specific backend batching behavior rather than translating it into joined polylines.

Parameters:
  • ctx – [inout] Native strip context with live graph, drawable and GC fields.

  • segments – [in] Borrowed mapped endpoint pairs, readable for count Segment2D records.

  • count – [in] Number of geometry records, not bytes.

static void NativeSegments(Rbc_RenderContext *ctx, const Segment2D *segments, Tcl_Size count)

Submit independent segments using the borrowed native GC.

Uses the ordinary native segment backend, including its chunking and platform resource handling. Does not own the array or a retained trace batch.

Parameters:
  • ctx – [inout] Native segment-capable context with live graph, drawable and GC fields.

  • segments – [in] Borrowed mapped endpoint pairs, readable for count Segment2D records.

  • count – [in] Number of geometry records, not bytes.

static void NativeEnd(Rbc_RenderContext *ctx)

Release any retained native trace and the stroke adapter.

Rbc_NativeEndTrace accepts NULL for strip/segment contexts. The caller GC, graph and drawable remain borrowed and are not destroyed.

Parameters:
  • ctx – [in] Owned native stroke context consumed here; any retained trace is released.

static void NativeSymbolPoints(Rbc_RenderContext *ctx, const Point2D *points, Tcl_Size count)

Draw symbols with the retained native style and integer size.

The style pointer is borrowed, not copied. Native sampling may update its counter; callers must keep style and referenced resources live until End.

Parameters:
  • ctx – [inout] Native symbol context with borrowed symbol style and mapped size initialized.

  • points – [in] Borrowed mapped point array, readable for count entries.

  • count – [in] Number of geometry records, not bytes.

static void NativeFillPolygon(Rbc_RenderContext *ctx, const Point2D *points, Tcl_Size count)

Dispatch a native fill through a retained batch or ordinary fill path.

Uses the polygon batch when available; otherwise passes the borrowed GC, tile and stipple to Rbc_NativeFillPolygon. A failed or unsupported batch constructor therefore retains the ordinary fill fallback.

Parameters:
  • ctx – [inout] Native fill context with either a retained polygon batch or configured GC/tile/stipple fallback.

  • points – [in] Borrowed mapped point array, readable for count entries.

  • count – [in] Number of geometry records, not bytes.

static void ScreenBarRectangles(Rbc_RenderContext *ctx, const Rbc_RenderRectangle *rects, Tcl_Size count)

Combine an optional Cairo fill with native bar decoration.

Copies the retained bar style locally. When positive-opacity fill is handled by Rbc_RenderRectangles, sets only the local fill opacity to zero before native bars draw relief/borders. Otherwise native bars retain fill ownership. Neither the caller style nor the context copy is modified by this decision.

Parameters:
  • ctx – [inout] Bar context holding a shallow copy of the component bar style.

  • rects – [in] Borrowed mapped bar rectangle array with count entries.

  • count – [in] Number of geometry records, not bytes.

static void NativeArc(Rbc_RenderContext *ctx, const Rbc_RenderArcGeometry *arc)

Draw the native arc from borrowed precomputed segments.

The arc argument has passed common validation but is not consumed here. Uses the arrays retained by BeginNativeArc; callers must keep those arrays consistent with the validated geometry and alive until End.

Parameters:
  • ctx – [inout] Native arc context retaining precomputed mapped stroke segments.

  • arc – [in] Validated analytic arc, unused by this callback; retained mapped arrays must describe the same geometry.

static void NativeFillArc(Rbc_RenderContext *ctx, const Rbc_RenderArcGeometry *arc)

Fill the native arc from its borrowed precomputed polygon.

Ignores the analytic arc argument and delegates retained points to NativeFillPolygon. Common dispatch has already rejected open-arc filling.

Parameters:
  • ctx – [inout] Native arc context retaining precomputed mapped fill vertices and fill style.

  • arc – [in] Validated analytic arc, unused by this callback; retained mapped arrays must describe the same geometry.

static void NativeGeometryEnd(Rbc_RenderContext *ctx)

Release a retained polygon batch and the geometry adapter.

Does not release borrowed symbol style, arc arrays, GC, tile or bar resources. The batch, if present, restores and releases its platform-owned state.

Parameters:
  • ctx – [in] Owned native geometry context consumed here; any polygon batch is released.

static Rbc_RenderContext *BeginNativeGeometry(Graph *graphPtr, Drawable drawable)

Allocate a zeroed native geometry adapter with borrowed graph and target.

Returns an owned context requiring End. The shared table advertises several callbacks, but each specialized constructor populates only its required state. Calling another family’s operation is not supported merely because the shared callback pointer is non-NULL.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive until context release.

  • drawable – [in] Borrowed destination, kept valid until context release.

Returns:

Owned zeroed geometry adapter; the caller must populate its specialized fields before dispatch.

static int NormalizeRenderArc(const Rbc_RenderArcGeometry *arc, Rbc_RenderArcGeometry *normalized)

Validate an ellipse arc and normalize its angle range.

Rejects NULL, nonfinite fields, nonpositive radii, zero extent and invalid closure styles. Copies valid input, reduces start with fmod and clamps sweep to [-360,360]. Negative start values remain negative. Output is only valid on TRUE; this does not clip the ellipse or bound later integer conversions.

Parameters:
  • arc – [in] Borrowed candidate ellipse; NULL and invalid geometry are rejected.

  • normalized – [out] Required caller-owned result; valid only when TRUE is returned.

Returns:

TRUE for valid normalized output; FALSE leaves output unspecified.

static void ScreenTextBackground(Rbc_RenderContext *ctx, GC gc, const Point2D *outline, const Point2D *anchor)

Draw a native text-marker background using mapped geometry.

Borrows outline and anchor; delegates their original conversion order to the native backend rather than converting them separately in this layer.

Parameters:
  • ctx – [inout] Synchronous stack screen adapter with graph/window and destination fields initialized.

  • gc – [in] Borrowed configured GC with the required clip, raster operation and drawing style.

  • outline – [in] Four borrowed text-background vertices relative to anchor.

  • anchor – [in] Borrowed mapped text anchor added before native short conversion.

static void ScreenArrowHead(Rbc_RenderContext *ctx, GC gc, const Point2D *points)

Draw a native arrowhead through scan-converted spans.

Borrows the mapped point array and GC. Retains native span batching and integer conversion policy; no Cairo geometry replacement is attempted.

Parameters:
  • ctx – [inout] Synchronous stack screen adapter with graph/window and destination fields initialized.

  • gc – [in] Borrowed configured GC with the required clip, raster operation and drawing style.

  • points – [in] Borrowed finite closed arrowhead with RBC_RENDER_ARROW_POINTS entries.

static void ScreenLegendLine(Rbc_RenderContext *ctx, GC gc, int x, int y, int size)

Draw a native line legend sample.

Preserves integer geometry and the borrowed GC, including stipple-origin behavior implemented by the native helper.

Parameters:
  • ctx – [inout] Synchronous stack screen adapter with graph/window and destination fields initialized.

  • gc – [in] Borrowed configured GC with the required clip, raster operation and drawing style.

  • x – [in] Destination X coordinate in display units.

  • y – [in] Destination Y coordinate in display units.

  • size – [in] Horizontal sample half-length; rows are y and y+1.

static void ScreenLegendBar(Rbc_RenderContext *ctx, GC gc, int x, int y, int size)

Draw a native bar legend sample.

Borrows graph, GC and target; passes integer geometry to the native helper without changing the graph’s renderer or component options.

Parameters:
  • ctx – [inout] Synchronous stack screen adapter with graph/window and destination fields initialized.

  • gc – [inout] Borrowed fill GC; native drawing resets its stipple origin to (0,0).

  • x – [in] Destination X coordinate in display units.

  • y – [in] Destination Y coordinate in display units.

  • size – [in] Nonnegative square side length in pixels.

static void ScreenRun(Rbc_RenderContext *ctx, void *data, Tcl_Size count, Rbc_RenderRunProc *proc)

Execute a synchronous native marker run.

Borrows callback data and function for the duration of native batching. Nothing is retained after return; backend-specific DC lifetime remains in Rbc_NativeRun. This adapter adds no Tcl callback lifetime protection.

Parameters:
  • ctx – [inout] Synchronous stack screen adapter with graph/window and destination fields initialized.

  • data – [in] Borrowed callback-specific run data; NULL suppresses the run.

  • count – [in] Number of geometry records, not bytes.

  • proc – [in] Synchronous callback; must not retain its temporary target or destroy borrowed drawing resources.

static void ScreenBitmapRun(Rbc_RenderContext *ctx, Pixmap bitmap, GC gc, int width, int height, const Rbc_RenderPosition *positions, Tcl_Size count)

Draw repeated native bitmap positions as one backend run.

Borrows bitmap, GC and position array. Leaves opaque bitmap/DC batching and resource restoration to the native backend.

Parameters:
  • ctx – [inout] Synchronous stack screen adapter with graph/window and destination fields initialized.

  • bitmap – [in] Borrowed one-bit source pixmap readable over width by height pixels.

  • gc – [inout] Borrowed opaque GXcopy-compatible GC; fallback clears its clip mask and origin.

  • width – [in] Nonnegative rectangle or bitmap width in pixels.

  • height – [in] Nonnegative rectangle or bitmap height in pixels.

  • positions – [in] Borrowed array of count integer bitmap destination origins.

  • count – [in] Number of geometry records, not bytes.

struct NativeRenderContext

Shared storage for native screen adapter families.

core is the dispatch prefix. Trace, clip and polygon-batch records are owned; window, drawable, GC, symbol style, tile, stipple and mapped arrays are borrowed. nativeBarStyle is a shallow value copy, not ownership of its referenced resources. Only the selected constructor’s fields are meaningful. Some one-shot callers place this record on the stack and must never pass it to Rbc_RenderEnd.

Public Members

Rbc_RenderContext core

Common dispatch prefix; must remain first.

double symbolSize

Mapped symbol size in pixels.

Rbc_NativeClip *nativeClip

Owned reusable clip stack, or NULL outside clip contexts.

Tk_Window nativeWindow

Borrowed text target, including external legends.

Drawable nativeDrawable

Borrowed destination in widget coordinates.

GC nativeGC

Borrowed GC retaining caller-selected raster, dash and clip state.

Rbc_NativeTrace *nativeTrace

Owned trace batch; released at context end.

Rbc_RenderNativeSymbolStyle *nativeSymbolStyle

Borrowed symbol policy; drawing updates its sampling counter.

Rbc_RenderBarStyle nativeBarStyle

Copied bar policy; referenced Tk resources remain borrowed.

Rbc_Tile nativeTile

Borrowed fill tile, or NULL for an untiled fill.

Pixmap nativeStipple

Borrowed stipple selector; None selects no stipple.

const Point2D *nativeFillPoints

Borrowed mapped arc-fill polygon retained until context end.

Tcl_Size nativeFillCount

Number of retained arc-fill vertices.

const Segment2D *nativeArcSegments

Borrowed mapped arc outline retained until context end.

Tcl_Size nativeArcCount

Number of retained arc-outline segments.

Rbc_NativePolygonBatch *nativePolygonBatch

Owned optional platform polygon batch, or NULL for ordinary drawing.