Shared and X11 native backend C reference

These declarations in rbcRenderNative.h are private backend services. Components use rbcRender.h instead. See Native renderer internals for platform behavior and ownership that cannot be inferred from a function signature.

The entries retain implementation-specific parameter contracts. Inputs described as borrowed must remain live through the call, or through batch destruction when retained by a constructor. Counts and dimensions are documented individually; short-coordinate conversion is not a general overflow check.

Trace batches

The X11 constructor and destructor contracts are included with the platform implementation below. See Native renderer internals for the shared lifetime contract and Windows acquisition/restoration requirements. Start with rbcNativeX11.Rbc_NativeBeginTrace(), submit rbcNativeX11.Rbc_NativePolyline(), and release with rbcNativeX11.Rbc_NativeEndTrace(). Independent strips use rbcNativeX11.Rbc_NativeStrips() without a retained trace context.

Clip stacks

Rbc_NativeClip *Rbc_NativeCreateClip(Graph *graphPtr, Drawable drawable, GC copyGC, int useDC)

Create a native rectangular clip stack without pushing a clip.

Borrows graph, base drawable and any supplied copy GC. A missing copy GC is acquired lazily and owned by the stack. A nonzero final argument permits platform DC clipping; otherwise use scratch targets. Keep graph dimensions stable while the stack is live: scratch pixmaps are cached per nesting depth.

Returns:

Owned stack, to be released with Rbc_NativeDestroyClip.

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

  • drawable – [in] Borrowed target, kept valid until the returned context is released.

  • copyGC – [in] Borrowed copy GC, or NULL to acquire one lazily and let the stack own it.

  • useDC – [in] Nonzero permits platform DC clipping; zero selects scratch targets.

void Rbc_NativePushClip(Rbc_NativeClip *clip, int x, int y, int width, int height)

Push an intersection with the parent clip and graph drawable bounds.

Arguments after the stack are x, y, width and height in absolute widget pixels. Nonpositive sizes create an empty frame. Query Rbc_NativeClipDrawable after every push; None means empty or failed output, and drawing must be skipped. Every push still requires a pop. A scratch target is seeded from its parent and preserves absolute coordinates.

Parameters:
  • clip – [inout] Live non-NULL clip stack with its borrowed resources intact.

  • x – [in] Absolute left edge in widget pixels.

  • y – [in] Absolute top edge in widget pixels.

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

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

void Rbc_NativePopClip(Rbc_NativeClip *clip)

Finish the active clip and restore its parent target.

Copies the visible scratch rectangle back, or restores/releases platform DC state. An empty stack is a no-op. Frame/workspace allocations are retained for reuse until destruction; borrowed drawables are not freed.

Parameters:
  • clip – [inout] Live non-NULL clip stack with its borrowed resources intact.

void Rbc_NativeDestroyClip(Rbc_NativeClip *clip)

Unwind and free a live native clip stack.

Pops remaining frames (committing their output), frees all cached scratch pixmaps and frame records, and releases only an internally acquired copy GC. Requires a non-NULL stack and live borrowed graph/display resources.

Parameters:
  • clip – [in] Live non-NULL clip stack; destroyed by this call.

Shared drawing implementation

The source contracts below describe conversion, temporary storage, GC mutations and fallback behavior. These helpers consume mapped geometry; they do not own component resources or perform graph layout.

group Shared native drawing helpers

Private backend services operating on already mapped geometry.

Functions

static void DrawSegments(Display *display, Drawable drawable, GC gc, const Segment2D *segments, Tcl_Size nSegments)

Draw independent segments in bounded X requests.

Borrows the display, drawable, GC and input array. Ignores absent display/ segments or nonpositive counts. Allocates one request-sized XSegment buffer; clips endpoints to signed-short protocol bounds before truncating to short. Returns without drawing if capacity or allocation fails; frees workspace. This protocol clipping does not replace the owning component plot clip.

Parameters:
  • display – [in] Borrowed live display, or NULL to skip drawing.

  • drawable – [in] Borrowed destination drawable compatible with the window/display; no ownership is transferred.

  • gc – [in] Borrowed configured GC compatible with the destination drawable.

  • segments – [in] Borrowed array of nSegments double-coordinate segments, or NULL to skip drawing.

  • nSegments – [in] Segment count; nonpositive counts draw nothing.

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

Fill a rectangle with the historical native relief adjustment.

Borrows the window and border. For raised/sunken borders wider than one pixel and rectangles larger than two pixels, draws the outer four lines, shrinks the rectangle and delegates the remainder to Tk. X11 uses the default GC for one outer shade; Windows uses the corresponding border GC. Does not allocate or release the borrowed border GCs.

Parameters:
  • tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.

  • drawable – [in] Borrowed destination drawable compatible with the window/display; no ownership is transferred.

  • border – [in] Borrowed Tk 3D border on the window display; border GCs are neither retained nor freed.

  • x – [in] Left destination coordinate in pixels; coordinate arithmetic must remain representable.

  • y – [in] Top destination coordinate in pixels; coordinate arithmetic must remain representable.

  • width – [in] Positive rectangle width in pixels; endpoint arithmetic must remain representable.

  • height – [in] Positive rectangle height in pixels; endpoint arithmetic must remain representable.

  • borderWidth – [in] Positive requested bevel width in pixels, bounded before use by the caller.

  • relief – [in] Tk relief passed to the final Tk fill; raised/sunken may receive the historical outer-layer adjustment.

void Rbc_NativeText(Tk_Window tkwin, Drawable drawable, const char *string, TextStyle *style, int x, int y)

Draw text through the existing Tk-based text service.

Borrows string and style for the call. Retains native font selection, rotation, anchors, padding and active/disabled styling in Rbc_DrawText. No text resource is retained by this wrapper.

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

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

  • string – [in] Borrowed NUL-terminated text, consumed during this call.

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

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

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

void Rbc_NativeTextLayout(Tk_Window tkwin, Drawable drawable, TextLayout *layout, TextStyle *style, int x, int y)

Draw an already constructed text layout.

Borrows layout and style; delegates to Rbc_DrawTextLayout without rebuilding or freeing the cached layout.

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

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

  • layout – [in] Borrowed cached text layout; no ownership transfer.

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

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

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

void Rbc_NativeTextSize(Tk_Window tkwin, Drawable drawable, const char *string, TextStyle *style, int x, int y, Dim2D *size)

Draw text and return its rotated dimensions.

Delegates to Rbc_DrawText2 using borrowed text/style and caller-provided size storage. Axis-limit placement uses these dimensions for later labels.

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

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

  • string – [in] Borrowed NUL-terminated text, consumed during this call.

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

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

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

  • size – [out] Required caller-owned storage receiving the rotated text extent.

void Rbc_NativeBitmap(Graph *graphPtr, Drawable drawable, const Rbc_RenderRectangle *r, const Rbc_RenderBitmapStyle *style)

Paint a mapped bitmap and optional background polygon.

Borrows mapped rectangle and style resources. Converts the supplied bounded background point array to short coordinates and fills it as Convex. Installs the bitmap mask and destination-relative clip origin on the private bitmap GC, then copies plane one. Leaves that clip state installed; does not retain or free bitmap/mask resources. Caller must honor the fixed outline capacity.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

  • r – [in] Borrowed destination rectangle; its dimensions select the source extent starting at (0,0).

  • style – [in] Borrowed bitmap style; backgroundCount must fit RBC_RENDER_BITMAP_OUTLINE_POINTS. Its private GC clip state is modified.

void Rbc_NativeImage(Drawable drawable, Tk_Image image, int x, int y)

Redraw a complete Tk image at a mapped position.

Queries the borrowed image size and delegates image-type drawing and alpha handling to Tk_RedrawImage. Does not scale, retain or free the image.

Parameters:
  • drawable – [in] Borrowed destination drawable in mapped pixel coordinates.

  • image – [in] Borrowed live Tk image; its entire current extent is redrawn.

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

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

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

Copy a native drawable rectangle using the supplied GC.

Borrows both drawables, window and GC; passes source/destination coordinates and unsigned dimensions to XCopyArea. Does not change the supplied GC or introduce a separate plot clip.

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

  • source – [in] Borrowed source drawable compatible with destination and gc.

  • destination – [in] Borrowed destination drawable.

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

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

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

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

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

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

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

void Rbc_NativePixmap(Graph *graphPtr, Drawable drawable, Pixmap pixmap, GC gc, const Rbc_RenderRectangle *r)

Copy a pixmap from its origin into a mapped rectangle.

Borrows graph, pixmap and GC. Uses rectangle dimensions and destination position with Rbc_NativeCopyArea; the pixmap is neither scaled nor freed.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

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

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

  • r – [in] Borrowed destination rectangle; its dimensions select the source extent starting at (0,0).

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

Draw or fill a native relief border.

The fill flag chooses Fill3DRectangle; otherwise uses Rbc_Draw3DRectangle. Borrows window/border and preserves the two paths’ different fill semantics. Decorations may use this service even when element geometry uses Cairo.

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

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

  • border – [in] Borrowed Tk border supplying relief shading resources.

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

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

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

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

  • borderWidth – [in] Relief border thickness in pixels.

  • relief – [in] Tk relief constant.

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

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

Fill a native rectangle with a tile or the supplied GC.

A non-NULL borrowed tile takes precedence and uses Rbc_TileRectangle with its existing origin. Otherwise calls XFillRectangle after converting sizes to unsigned integers. Callers supply valid nonnegative dimensions.

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

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

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

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

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

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

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

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

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

Draw the Tk focus highlight.

Borrows the live window and configured GC; delegates width handling and painting to Tk_DrawFocusHighlight.

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

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

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

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

void Rbc_NativeSegments(Graph *graphPtr, Drawable drawable, GC gc, const Segment2D *segments, Tcl_Size count)

Draw graph segments through the shared bounded segment helper.

Borrows graph, drawable, GC and mapped segments. DrawSegments owns temporary conversion storage and handles protocol clipping and request batching.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

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

  • segments – [in] Borrowed mapped endpoint pairs; readable for the supplied segment count.

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

static int Round(double x)

Round a representable symbol coordinate away from zero at ties.

Adds or subtracts one half before conversion to int. Requires a finite value whose adjusted result fits int; this is not a general range check.

Parameters:
  • x – [in] Finite coordinate whose adjustment by plus or minus one half fits int; no range check occurs.

void Rbc_NativeSymbolPoints(Graph *graphPtr, Drawable drawable, Rbc_RenderNativeSymbolStyle *style, int size, Tcl_Size nSymbolPts, const Point2D *symbolPts)

Draw mapped symbol centers using native shape batches.

Borrows graph, points and style resources; shape-specific temporary buffers and scaled bitmaps are released before return. For size below three, draws all centers as points with fillGC and bypasses symbol type/interval handling. Larger symbols use circle/square platform batches, segment crosses, polygon templates or scaled bitmaps. Interval-aware branches advance style->counter for examined centers, including skipped ones. Bitmap symbols mutate outline GC clip state. Requires valid mapped coordinates and a nonnegative count.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

  • style – [inout] Borrowed symbol style; interval-aware branches advance its counter for examined centers.

  • size – [in] Mapped symbol size in pixels; sizes below three select the point-only path.

  • nSymbolPts – [in] Nonnegative number of mapped symbol centers.

  • symbolPts – [in] Borrowed mapped center array with nSymbolPts entries.

void Rbc_NativeFillPolygon(Graph *graphPtr, Drawable drawable, GC gc, Rbc_Tile tile, Pixmap stipple, const Point2D *points, Tcl_Size count)

Fill a tiled or stippled native polygon.

Rejects absent points, unavailable tile pixmaps and unsupported point counts. Owns temporary short-coordinate points. A tile takes precedence and its origin is reset through Rbc_SetTileOrigin before drawing. Otherwise a non-None stipple selects Complex XFillPolygon using the already configured GC. With neither tile nor stipple this helper intentionally draws nothing.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

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

  • tile – [in] Optional borrowed tile taking precedence; its origin is reset for the graph before drawing.

  • stipple – [in] Non-None enables the configured GC polygon fill when no tile is supplied; None alone does not select solid filling.

  • points – [in] Borrowed mapped polygon vertices with count entries.

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

void Rbc_NativeBars(Graph *graphPtr, Drawable drawable, const Rbc_RenderBarStyle *penPtr, const Rbc_RenderRectangle *rectangles, Tcl_Size nRects)

Fill mapped bar rectangles, then draw relief borders.

Borrows graph, style and rectangles. Positive fillOpacity enables native filling; this helper does not alpha-blend fractional opacity. Packs eligible rectangles into request-sized XRectangle batches, flushing before wider int-argument fallback calls. Attempts platform border batching before per-rectangle relief fallback. Allocation/capacity failure in the fill path returns before borders. Requires valid mapped geometry and configured GCs.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

  • penPtr – [in] Borrowed bar style and its live color, border and GC resources.

  • rectangles – [in] Borrowed mapped rectangle array with the supplied rectangle count.

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

void Rbc_NativeArcStroke(Graph *graphPtr, Drawable drawable, GC gc, const Segment2D *segments, Tcl_Size count)

Join contiguous arc segments into native polylines.

Requires nonnegative count, valid mapped segments and representable sizes. Zero count is a no-op. Exact endpoint equality joins adjacent segments; gaps start separate XDrawLines calls. Owns point and per-run XPoint buffers, with short-coordinate conversion. Outer allocation failure skips all drawing; per-run failure skips that run. Unlike DrawSegments, does not protocol-clip or split a run to the X request-size limit.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

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

  • segments – [in] Borrowed mapped arc segments; consecutive equal endpoints join a run. Caller bounds each run for native conversion/request limits.

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

Drawable Rbc_NativeClipDrawable(Rbc_NativeClip *clip)

Return the active clip target or the base drawable.

Requires a live non-NULL stack. None means the active frame is empty or failed; callers must skip drawing but still pop that frame. The target is borrowed and must not outlive its frame/stack.

Parameters:
  • clip – [in] Live non-NULL clip stack with its borrowed resources intact.

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

Draw independent native segments without a Graph argument.

Uses the borrowed window display and the same DrawSegments conversion, protocol clipping, temporary storage and request batching as graph segments.

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

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

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

  • segments – [in] Borrowed mapped endpoint pairs; readable for the supplied segment count.

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

void Rbc_NativeArrowHead(Graph *graphPtr, Drawable drawable, GC gc, const Point2D *arrow)

Scan-convert a five-vertex arrowhead at integer pixel centers.

Borrows the mapped arrow and GC. Keeps doubles until selecting covered pixels; rounding vertices first distorts narrow diagonal necks. Half-open edges count shared vertices once. Clips spans to graph and signed-short bounds, then sends batches of at most 128 one-pixel-high rectangles. Requires finite geometry; the enclosing renderer retains track clipping.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

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

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

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

Fill a four-corner text background polygon.

Borrows outline, anchor and GC. Adds the anchor before short conversion and fills with Convex/CoordModeOrigin. Requires four mapped outline points; does not impose a plot clip or retain point storage.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

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

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

  • anchor – [in] Borrowed mapped text anchor added to each outline vertex before short conversion.

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

Draw a two-row legend line sample.

Uses two independent XDrawLine requests, preserving the original dash restart on each row. Borrows graph, target and configured GC.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

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

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

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

  • size – [in] Half-length of each horizontal sample line; rows are y and y+1.

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

Draw a square legend fill sample with a local pattern origin.

Sets the borrowed GC tile/stipple origin to the sample position, fills the square, then resets that origin to zero. Does not restore a nonzero previous origin; callers must use the established legend GC contract.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

  • gc – [inout] Borrowed fill GC; stipple origin is set to (x,y) then reset to (0,0).

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

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

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

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

Draw a run of opaque bitmap copies with platform fallback.

Ignores absent positions or nonpositive counts. Tries the platform opaque batch first, then clears GC clip mask/origin and replays all positions with XCopyPlane if declined. Requires unmasked GXcopy-compatible input so replay after partial optimized failure is safe. Borrows all resources and leaves fallback GC clipping cleared; do not use for masked or XOR runs.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

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

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

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

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

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

  • count – [in] Number of run items; nonpositive counts suppress drawing.

struct NativeClipFrame

Reusable clip depth with absolute bounds and optional scratch target.

Previous/next link owned frames. Parent/drawable are borrowed targets; scratch is owned until stack destruction. Platform state follows the allocation.

Public Members

struct NativeClipFrame *previous

Previous cached clip frame; NULL at the base depth.

struct NativeClipFrame *next

Next cached clip frame; owned by the clip stack.

Drawable parent

Borrowed parent target before entering this clip.

Drawable drawable

Selected output target; None denotes an empty output.

Pixmap scratch

Owned reusable offscreen pixmap, or None for direct clipping.

int left

Absolute left clip bound in widget pixels.

int top

Absolute top clip bound in widget pixels.

int right

Absolute right clip bound in widget pixels.

int bottom

Absolute bottom clip bound in widget pixels.

int platformActive

Nonzero requires platform unclip, including partial initialization.

struct Rbc_NativeClip

Native clip stack borrowing a graph and base drawable.

Owns cached frames and only a lazily acquired copy GC. Active identifies the current depth; dimensions and borrowed resources stay valid until destruction.

Public Members

Graph *graphPtr

Borrowed graph whose dimensions and display remain valid.

Drawable drawable

Borrowed base target when no clip frame is active.

GC copyGC

Borrowed caller GC, or lazily allocated GC when ownGC is set.

int ownGC

Nonzero when the clip stack owns copyGC.

int useDC

Nonzero permits direct platform clipping.

NativeClipFrame *first

First frame in the owned reusable depth chain.

NativeClipFrame *active

Current depth; NULL when no clip is active.

X11 platform implementation

These source contracts describe the X11 implementation. The common interface also has Windows implementations with different resource and batching rules.

group X11 native backend

Private X11 implementation of the shared native backend interface.

Functions

Tcl_Size Rbc_NativePolygonPointLimit(Graph *graphPtr)

Return the raw X11 polygon request capacity.

Uses XPoint request sizing for the borrowed graph display. Component clipping allowances are not subtracted here; this is not a promise that any polygon can be split safely.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

void Rbc_NativePolyline(Rbc_NativeTrace *ctx, const Point2D *screenPts, Tcl_Size nPoints)

Draw a connected trace in request-sized X11 chunks.

Borrows context and mapped points; NULL context/points, fewer than two points or insufficient capacity are no-ops. Converts directly to short coordinates. Each continuation repeats the previous endpoint, using the extra workspace slot reserved by BeginTrace. Separate requests preserve connectivity but do not carry an explicit accumulated dash offset. GC state remains borrowed.

Parameters:
  • ctx – [inout] Live native trace context returned by Rbc_NativeBeginTrace; NULL is accepted.

  • screenPts – [in] Borrowed mapped polyline vertices with nPoints entries; NULL suppresses drawing.

  • nPoints – [in] Number of polyline vertices; fewer than two draws nothing.

void Rbc_NativeStrips(Graph *graphPtr, Drawable drawable, GC gc, const Segment2D *segments, Tcl_Size nSegments)

Delegate independent X11 strips to shared segment drawing.

Rbc_NativeSegments handles protocol clipping, conversion and request batching. No additional context or resource is acquired here.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

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

  • segments – [in] Borrowed mapped endpoint pairs; readable for the supplied segment count.

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

Rbc_NativeTrace *Rbc_NativeBeginTrace(Graph *graphPtr, Drawable drawable, GC gc)

Allocate X11 trace state and point workspace together.

Allocate a reusable native polyline batch.

Borrows graph, drawable and configured GC. Reserves request capacity minus one as the base chunk size, plus one continuation endpoint slot. Returns NULL for insufficient capacity, size overflow or allocation failure. Release the owned allocation with Rbc_NativeEndTrace.

Allocate X11 trace state and point workspace together.

Borrows graph, drawable and configured GC until Rbc_NativeEndTrace. Owns point workspace; Windows also acquires a DC and selects owned pen/brush resources for the batch. Geometry supplied to subsequent calls is consumed synchronously. This is a backend service, not a component constructor.

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

  • drawable – [in] Borrowed target, kept valid until the returned context is released.

  • gc – [in] Borrowed configured GC, kept valid until the returned batch is released.

Returns:

Owned context, or NULL when request capacity or allocation prevents it.

void Rbc_NativeEndTrace(Rbc_NativeTrace *ctx)

Free the X11 trace allocation.

Release a native trace batch; NULL is accepted.

Accepts NULL. Does not free the borrowed graph, drawable or GC and does not flush or synchronize the X server.

Free the X11 trace allocation.

Windows restores the previously selected pen/brush before deleting the batch-owned objects and releasing its DC state. Frees context/workspace without freeing the borrowed GC, drawable or graph.

Parameters:
  • ctx – [in] Owned trace context consumed by this call; NULL is accepted.

static int Round(double x)

Round a representable coordinate away from zero at ties.

Adds or subtracts one half before int conversion. Requires finite input within int range. This local helper is currently unused by X11 drawing.

Parameters:
  • x – [in] Finite coordinate whose adjustment by plus or minus one half fits int; no range check occurs.

void Rbc_NativeCircles(Display *display, Drawable drawable, Rbc_RenderNativeSymbolStyle *style, Tcl_Size nSymbolPts, const Point2D *symbolPts, int radius)

Draw selected circle symbols in X11 arc batches.

Owns one XArc array sized for all input centers, then submits request-sized chunks with fill before outline per chunk. Positive interval advances the style counter for every examined center. Converts centers to short before subtracting radius; diameter becomes unsigned short. Nonpositive count, size overflow, allocation failure or unusable request capacity skips output. Borrows style GCs and requires mapped coordinates and valid radius.

Parameters:
  • display – [in] Borrowed display owning the drawable and GC resources.

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

  • style – [inout] Borrowed symbol style; interval-aware branches advance its counter for examined centers.

  • nSymbolPts – [in] Nonnegative number of mapped symbol centers.

  • symbolPts – [in] Borrowed mapped center array with nSymbolPts entries.

  • radius – [in] Circle radius in pixels; caller supplies representable center/radius arithmetic.

void Rbc_NativeSquares(Display *display, Drawable drawable, Rbc_RenderNativeSymbolStyle *style, Tcl_Size nSymbolPts, const Point2D *symbolPts, int r)

Draw selected square symbols in X11 rectangle batches.

Owns a temporary array sized for all centers, then emits bounded requests with fill before outline per chunk. Positive interval advances the mutable style counter for every center examined. Subtracts radius before short conversion, unlike circles; diameter becomes unsigned short. Nonpositive count, size overflow, allocation failure or unusable capacity skips output.

Parameters:
  • display – [in] Borrowed display owning the drawable and GC resources.

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

  • style – [inout] Borrowed symbol style; interval-aware branches advance its counter for examined centers.

  • nSymbolPts – [in] Nonnegative number of mapped symbol centers.

  • symbolPts – [in] Borrowed mapped center array with nSymbolPts entries.

  • r – [in] Square half-size in pixels; caller supplies representable center/radius arithmetic.

int Rbc_NativePolygonPointCount(Display *display, Tcl_Size nPoints)

Validate a single X11 polygon request length.

Returns the int count only when at least three vertices fit both INT_MAX and the display request limit. Otherwise returns zero. Does not partition a polygon or inspect its geometry.

Parameters:
  • display – [in] Borrowed display owning the drawable and GC resources.

  • nPoints – [in] Number of polygon vertices, including any repeated closing point.

void Rbc_NativeBarRectangles(Graph *graphPtr, Drawable drawable, const Rbc_RenderBarStyle *penPtr, XRectangle *rectangles, int nRects)

Submit one prepared bar-fill rectangle batch.

Borrows graph, drawable, style GC and XRectangle array. Caller has already validated count and packed coordinates to fit the request; no allocation or additional clipping is performed here.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

  • penPtr – [in] Borrowed bar style and its live color, border and GC resources.

  • rectangles – [in] Borrowed prepacked XRectangle array; caller has bounded count for the platform request.

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

Rbc_NativePolygonBatch *Rbc_NativeBeginPolygonBatch(Graph *graphPtr, Drawable drawable, GC gc, Tcl_Size maxPoints)

Decline the optional fill-only polygon optimization on X11.

Always returns NULL without acquiring resources. The shared caller must use its ordinary polygon path; NULL does not mean an empty clipping region.

Parameters:
  • graphPtr – [in] Borrowed owning graph, kept alive until the returned context is released. Unused by this X11 fallback stub.

  • drawable – [in] Borrowed target, kept valid until the returned context is released. Unused by this X11 fallback stub.

  • gc – [in] Borrowed configured GC, kept valid until the returned batch is released. Unused by this X11 fallback stub.

  • maxPoints – [in] Maximum number of vertices in any polygon submitted to the returned batch. Unused by this X11 fallback stub.

void Rbc_NativeBatchPolygon(Rbc_NativePolygonBatch *batch, const Point2D *points, Tcl_Size count)

Provide the unused X11 polygon-batch interface entry.

No operation. X11 BeginPolygonBatch never returns a context, so callers should select the ordinary drawing path instead.

Parameters:
  • batch – [inout] Live owned polygon batch returned by Rbc_NativeBeginPolygonBatch. Unused by this X11 fallback stub.

  • points – [in] Borrowed mapped polygon vertices with count entries. Unused by this X11 fallback stub.

  • count – [in] Number of input records, not bytes. Unused by this X11 fallback stub.

void Rbc_NativeEndPolygonBatch(Rbc_NativePolygonBatch *batch)

Release storage passed to the X11 polygon-batch endpoint.

Calls ckfree on the argument. No context is normally created by the X11 constructor; this interface exists to match the platform backend contract.

Parameters:
  • batch – [in] Owned polygon batch consumed by this call; Windows requires non-NULL.

void Rbc_NativePolygonSymbols(Display *display, Drawable drawable, Rbc_RenderNativeSymbolStyle *style, const XPoint *polygons, Tcl_Size count, int stride, int vertices)

Fill all polygon symbols, then draw all outlines.

Borrows preconverted polygons and style GCs. Stride includes the closing point and is used for both fill and line requests. Twelve-vertex templates use Complex fill; others use Convex. Interval selection was performed by the shared caller. Does not allocate, clip or split individual polygons.

Parameters:
  • display – [in] Borrowed display owning the drawable and GC resources.

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

  • style – [in] Borrowed symbol style and GCs; caller has already selected the symbol intervals.

  • polygons – [in] Borrowed packed XPoint polygons, with stride points per polygon.

  • count – [in] Nonnegative number of packed polygon records.

  • stride – [in] Points per polygon record, including its repeated closing vertex.

  • vertices – [in] Distinct vertices per polygon; twelve selects the concave plus/cross fill policy.

int Rbc_NativeBarBorders(Graph *graphPtr, Drawable drawable, const Rbc_RenderBarStyle *style, const Rbc_RenderRectangle *rectangles, Tcl_Size count)

Decline optimized bar borders on X11.

Always returns FALSE without drawing. The shared bar helper then draws relief borders individually.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call. Unused by this X11 fallback stub.

  • drawable – [in] Borrowed destination drawable in mapped pixel coordinates. Unused by this X11 fallback stub.

  • style – [in] Borrowed bar style and its live color, border and GC resources. Unused by this X11 fallback stub.

  • rectangles – [in] Borrowed mapped rectangle array with the supplied rectangle count. Unused by this X11 fallback stub.

  • count – [in] Number of mapped bar rectangles. Unused by this X11 fallback stub.

size_t Rbc_NativeClipStateSize(void)

Report that X11 needs no platform clip payload.

Returns zero. Shared clip frames still own bounds, links and scratch pixmaps; no extra platform state follows the frame.

int Rbc_NativePlatformClip(Graph *graphPtr, Drawable parent, int left, int top, int right, int bottom, void *state, Drawable *drawablePtr)

Decline direct platform clipping on X11.

Returns FALSE and leaves the output drawable untouched. The shared clip stack then creates or reuses its scratch target. This is a fallback signal, not a successfully installed empty clip.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call. Unused by this X11 fallback stub.

  • parent – [in] Borrowed parent drawable whose clipping and pixels must remain live through unclip. Unused by this X11 fallback stub.

  • left – [in] Inclusive left clip edge in absolute pixels. Unused by this X11 fallback stub.

  • top – [in] Inclusive top clip edge in absolute pixels. Unused by this X11 fallback stub.

  • right – [in] Exclusive right clip edge in absolute pixels. Unused by this X11 fallback stub.

  • bottom – [in] Exclusive bottom clip edge in absolute pixels. Unused by this X11 fallback stub.

  • state – [inout] Unused X11 platform payload; no storage is accessed. Unused by this X11 fallback stub.

  • drawablePtr – [inout] Unused output pointer; left unchanged on X11. Unused by this X11 fallback stub.

void Rbc_NativePlatformUnclip(void *state, Drawable drawable)

Provide the unused X11 direct-clip cleanup entry.

No operation; shared scratch clipping handles commit and resource lifetime.

Parameters:
  • state – [inout] Unused X11 platform payload; no storage is accessed. Unused by this X11 fallback stub.

  • drawable – [in] Temporary platform wrapper to release, or None after partial setup; ignored on X11. Unused by this X11 fallback stub.

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

Invoke a native run callback synchronously on its original target.

Calls proc only when data is non-NULL and count is positive. Borrows data and drawable, with no wrapper or DC acquisition. A valid callback is required for nonempty runs; it must not retain temporary drawing resources.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.

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

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

  • count – [in] Number of run items; nonpositive counts suppress drawing.

  • proc – [in] Required synchronous callback for a nonempty run; must not retain the target or destroy drawing resources.

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

Decline optimized opaque bitmap runs on X11.

Always returns FALSE without drawing or modifying GC state. The shared bitmap-run helper performs the complete XCopyPlane fallback.

Parameters:
  • graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call. Unused by this X11 fallback stub.

  • drawable – [in] Borrowed destination drawable in mapped pixel coordinates. Unused by this X11 fallback stub.

  • bitmap – [in] Borrowed one-bit source bitmap, readable over width by height pixels. Unused by this X11 fallback stub.

  • gc – [in] Borrowed opaque GXcopy-compatible GC; masked or XOR copies are outside this interface contract. Unused by this X11 fallback stub.

  • width – [in] Positive source bitmap width in pixels. Unused by this X11 fallback stub.

  • height – [in] Positive source bitmap height in pixels. Unused by this X11 fallback stub.

  • positions – [in] Borrowed array of count integer destination origins. Unused by this X11 fallback stub.

  • count – [in] Number of run items; nonpositive counts suppress drawing. Unused by this X11 fallback stub.

struct Rbc_NativeTrace

Owned X11 trace context with trailing point workspace.

Borrows graph, target and GC; nativeMaxPoints excludes the extra slot used for a repeated continuation endpoint. One allocation owns state and points.

Public Members

Graph *graphPtr

Borrowed owning graph; outlives the batch.

Drawable nativeDrawable

Borrowed destination drawable.

GC nativeGC

Borrowed configured graphics context.

void *nativePoints

Point workspace stored after this record in the same allocation.

int nativeMaxPoints

Maximum vertices per chunk, excluding the continuation slot.

struct Rbc_NativePolygonBatch

Placeholder for the unsupported X11 polygon-batch optimization.

No instance is created by this backend. This is not a Windows DC owner.

Public Members

Display *display

Unused placeholder; this backend never allocates a polygon batch.

See Windows native backend C reference for the separate Windows implementation.