SVG backend C reference
These static helpers belong to rbcRenderSvg.c. They borrow the export token; component callers use the renderer
interface. See SVG definitions and image encoding.
Use SvgStrokeAttributes() and SvgFillPattern() for paint-state contracts, SvgString() for text
escaping, and SvgPhotoBlock() for raster encoding. PNG helpers count bytes; geometry helpers count vertices,
segments or rectangles. Emission is append-only and document errors remain separate from a helper’s return value.
- group SVG backend internals
Private append-only output helpers borrowing the current export context.
Functions
-
static void SvgClipBegin(Rbc_RenderContext *ctx, int x, int y, int width, int height)
Emit a rectangular clip definition and open its clipped group.
Allocates an identifier from the document counter, not heap-owned clip geometry. SvgClipEnd emits the matching group close. Common renderer depth tracking owns pairing and unwind; this helper does not update depth.
- Parameters:
ctx – Live SVG context borrowing the export token.
x – Mapped clip origin X.
y – Mapped clip origin Y.
width – Clip width supplied by the common clip dispatcher.
height – Clip height supplied by the common clip dispatcher.
-
static void SvgClipEnd(Rbc_RenderContext *ctx)
Close one rectangular clip group.
Common renderer clip-depth tracking owns pairing. This appends a closing tag only; it neither updates depth nor closes the separate plot scope.
- Parameters:
ctx – [inout] Live Svg context with a matching rectangular clip scope; common depth is not changed here.
-
static void SvgString(Rbc_ExportContext *token, const char *string, Tcl_Size length)
Append XML-escaped Tcl UTF text to the current export buffer.
Escapes the five XML metacharacters and checks decoded characters for disallowed controls, surrogate values and selected XML noncharacters. Records an export error on invalid content; already appended output is not rolled back. This is not an arbitrary binary-data encoder. Retains no input.
- Parameters:
token – Borrowed initialized export context.
string – Borrowed readable Tcl UTF string.
length – Byte length, or negative for a NUL-terminated string.
-
static void SvgColor(Rbc_ExportContext *token, const XColor *color)
Append an SVG paint value.
A NULL borrowed color emits none. Otherwise the high eight bits of each Tk 16-bit RGB channel form a hexadecimal color; no alpha or allocation is involved.
- Parameters:
token – [inout] Borrowed initialized export document; output and resource/error state may be updated.
color – [in] Optional borrowed Tk color; NULL emits SVG none.
-
static void SvgStrokeAttributes(Rbc_RenderContext *ctx, int underlay)
Append stroke attributes from retained export state.
The underlay uses the off-color and omits dashes. The foreground uses the configured color, width, cap, join and bounded zero-terminated dash array. Both explicitly disable fill.
- Parameters:
ctx – [inout] Live Svg stroke context with configured color, width and dash state.
underlay – [in] Nonzero selects the solid off-dash pass; zero emits foreground stroke attributes.
-
static void SvgPolyline(Rbc_RenderContext *ctx, const Point2D *points, Tcl_Size count)
Emit a connected stroke, optionally over a solid dash background.
Counts below two emit nothing. Each pass repeats the borrowed mapped points without rounding. The solid underlay precedes the dashed foreground; geometry is not retained.
- Parameters:
ctx – [inout] Live Svg stroke context with configured color, width and dash state.
points – [in] Borrowed mapped point array readable for count vertices.
count – [in] Number of geometry records, not bytes.
-
static void SvgSegments(Rbc_RenderContext *ctx, const Segment2D *segments, Tcl_Size count)
Emit independent segments through the polyline adapter.
Each borrowed segment becomes a two-point polyline, with its own underlay/foreground passes. This preserves per-segment painter order rather than batching all underlays first.
- Parameters:
ctx – [inout] Live Svg stroke context with configured color, width and dash state.
segments – [in] Borrowed mapped endpoint pairs readable for count Segment2D records.
count – [in] Number of geometry records, not bytes.
-
static void SvgPolygon(Rbc_ExportContext *token, const Point2D *points, Tcl_Size count, const XColor *color, double opacity)
Emit a solid even-odd polygon.
Fewer than three points emit nothing. Coordinates and opacity are supplied by the caller; NULL color means no paint. This does not add an outline, clamp opacity or retain geometry.
- Parameters:
token – [inout] Borrowed initialized export document; output and resource/error state may be updated.
points – [in] Borrowed mapped point array readable for count vertices.
count – [in] Number of geometry records, not bytes.
color – [in] Borrowed paint color; omission follows this helper’s format-specific policy.
opacity – [in] Fill alpha supplied by the caller; not clamped here.
-
static void SvgFillPolygon(Rbc_RenderContext *ctx, const Point2D *points, Tcl_Size count)
Fill a polygon with the configured solid or pattern style.
Uses black when no foreground is supplied. Stipples and tiles use the context-local pattern definition without applying solid-fill opacity. A zero pattern identifier skips emission.
- Parameters:
ctx – [inout] Live Svg fill context with initialized fillStyle and any required graph/tile resources.
points – [in] Borrowed mapped point array readable for count vertices.
count – [in] Number of geometry records, not bytes.
-
static void SvgArcPath(Rbc_ExportContext *token, const Rbc_RenderArcGeometry *arc)
Append the opening path element and ellipse arc geometry.
Requires normalized mapped geometry from common arc dispatch. Screen Y is inverted relative to mathematical angles. Full revolutions use two arcs and close without a radial seam; partial chord and sector paths close according to style. The caller appends paint attributes and the element terminator.
- Parameters:
token – [inout] Borrowed initialized export document; output and resource/error state may be updated.
arc – [in] Borrowed normalized finite ellipse geometry with positive radii and nonzero extent.
-
static void SvgArc(Rbc_RenderContext *ctx, const Rbc_RenderArcGeometry *arc)
Stroke normalized arc geometry with optional dash underlay.
Repeats the path for the solid off-color and dashed foreground when needed. Geometry remains borrowed; common dispatch validates and normalizes the arc before this callback.
- Parameters:
ctx – [inout] Live Svg stroke context with configured color, width and dash state.
arc – [in] Borrowed normalized finite ellipse geometry with positive radii and nonzero extent.
-
static void SvgFillArc(Rbc_RenderContext *ctx, const Rbc_RenderArcGeometry *arc)
Fill a closed normalized arc using solid paint or a pattern.
Common dispatch excludes open arcs. Pattern definitions own their paint and do not receive solid- fill opacity. A missing pattern skips the path; solid paint uses the configured foreground directly.
- Parameters:
ctx – [inout] Live Svg fill context with initialized fillStyle and any required graph/tile resources.
arc – [in] Borrowed normalized closed ellipse segment; common dispatch excludes open arcs.
-
static void SvgRectangle(Rbc_ExportContext *token, double x, double y, int width, int height, const XColor *color)
Append an unoutlined solid rectangle.
Nonpositive dimensions emit nothing. Double origins are preserved, dimensions are integers and NULL color emits none. No clipping or opacity is added here.
- Parameters:
token – [inout] Borrowed initialized export document; output and resource/error state may be updated.
x – [in] Mapped destination X coordinate in display pixels.
y – [in] Mapped destination Y coordinate in display pixels.
width – [in] Mapped rectangle width in display pixels.
height – [in] Mapped rectangle height in display pixels.
color – [in] Borrowed rectangle color; NULL emits no paint.
-
static void SvgFillRectangles(Rbc_RenderContext *ctx, const Rbc_RenderRectangle *rectangles, Tcl_Size count)
Emit configured rectangle fills in input order.
Skips nonpositive dimensions. Each rectangle may be wrapped in an opacity group and may reuse the context pattern. Pattern failure balances the current group before stopping the batch; previous output is retained.
- Parameters:
ctx – [inout] Live Svg fill context with initialized fillStyle and any required graph/tile resources.
rectangles – [in] Borrowed mapped rectangle array readable for count entries.
count – [in] Number of geometry records, not bytes.
-
static void SvgBitmapRuns(Rbc_ExportContext *token, XImage *bits, XImage *mask, const XColor *color)
Encode set bitmap pixels as horizontal vector runs.
Borrows readable XImages; a supplied mask must cover the same dimensions. NULL color emits nothing. Each row is scanned into unit-height closed subpaths, intersecting bits with the optional mask. Images remain owned by the caller.
- Parameters:
token – [inout] Borrowed initialized export document; output and resource/error state may be updated.
bits – [in] Borrowed readable monochrome XImage supplying set pixels.
mask – [in] Optional borrowed same-sized XImage; only pixels set in both images are emitted.
color – [in] Borrowed paint color; omission follows this helper’s format-specific policy.
-
static int SvgDefineBitmapSymbol(Rbc_RenderContext *ctx)
Read and define one reusable bitmap symbol.
Borrows Tk bitmap handles and owns temporary XImage readbacks. An explicit mask is read only with a fill color and must match bitmap dimensions. Records readback errors, releases images on all acquired paths and caches the document ID and dimensions on success.
- Parameters:
ctx – [inout] Live Svg symbol context with selected symbol style and document resources.
-
static void SvgPngWord(unsigned char *bytes, unsigned int value)
Write one unsigned word in PNG network byte order.
The caller supplies four writable bytes. This only encodes the low 32 bits; it allocates nothing and performs no length validation.
- Parameters:
bytes – [out] Required caller-owned storage for exactly four encoded bytes.
value – [in] Unsigned value whose low 32 bits are encoded.
-
static void SvgPngChunk(Tcl_DString *png, const char *type, const unsigned char *data, Tcl_Size length)
Append one PNG chunk including its CRC.
The caller supplies a four-byte chunk type, nonnegative 32-bit-representable length and readable data for nonempty payloads. The checksum covers type and data. The destination DString remains caller-owned.
- Parameters:
png – [inout] Caller-owned initialized DString receiving the encoded PNG chunk.
type – [in] Exactly four readable ASCII chunk-type bytes.
data – [in] Borrowed chunk payload readable for length bytes; unused for an empty chunk.
length – [in] Nonnegative payload byte count representable in the PNG 32-bit chunk length.
-
static void SvgBase64(Rbc_ExportContext *token, const unsigned char *bytes, Tcl_Size length)
Append padded base64 without line breaks.
Borrows length readable bytes and writes directly to the export buffer in four-character groups. Empty input appends nothing; it neither retains data nor adds a URI prefix.
- Parameters:
token – [inout] Borrowed initialized export document; output and resource/error state may be updated.
bytes – [in] Borrowed byte array readable for length bytes.
length – [in] Nonnegative input byte count, not characters.
-
static void SvgPhotoBlock(Rbc_ExportContext *token, const Tk_PhotoImageBlock *block, double x, double y)
Encode a borrowed Tk photo block as an inline PNG image.
Empty dimensions emit nothing. Checks pixel storage and size limits; assumes RGB offsets/storage are supplied by a valid image producer. Copies straight-alpha RGBA scanlines, compresses with Tcl zlib and appends base64 PNG. A distinct valid alpha offset is used, otherwise alpha is opaque. Temporary Tcl objects and PNG storage are released; interpreter state is restored after compression. Failures record an export error, without rolling back output.
- Parameters:
token – Borrowed export context and interpreter.
block – Readable Tk photo block with valid RGB channel offsets.
x – Image origin in mapped SVG coordinates.
y – Image origin in mapped SVG coordinates.
-
static void SvgColorImage(Rbc_ExportContext *token, Rbc_ColorImage image, double x, double y)
Adapt borrowed Pix32 storage to the PNG encoder.
Checks that the packed row pitch fits int, then describes actual channel offsets in a temporary Tk photo block. Encoding is synchronous; the caller retains ownership of the color image.
- Parameters:
token – [inout] Borrowed initialized export document; output and resource/error state may be updated.
image – [in] Borrowed RBC color image with readable packed pixels; not freed by this helper.
x – [in] Mapped destination X coordinate in display pixels.
y – [in] Mapped destination Y coordinate in display pixels.
-
static void SvgTkImage(Rbc_RenderContext *ctx, Tk_Image image, double x, double y)
Capture a generic Tk image and encode it as PNG.
Uses the shared export raster service, which records capture failures. A successful temporary color image is freed after synchronous encoding, including when encoding records an error.
- Parameters:
ctx – [inout] Live Svg renderer context borrowing the active export document.
image – [in] Borrowed live Tk image; no ownership transfer.
x – [in] Mapped destination X coordinate in display pixels.
y – [in] Mapped destination Y coordinate in display pixels.
-
static unsigned int SvgFillPattern(Rbc_RenderContext *ctx, const XColor *foreground)
Define or reuse this context’s SVG tile/stipple pattern.
The cache is context-local and assumes an unchanged style. Tiles use photo pixels or captured image pixels; stipples use monochrome readback. Definitions append directly to the document and use its resource counter. A nonzero ID does not clear or exclude an encoding error recorded on token.
- Parameters:
ctx – Live SVG context with configured fill style and graph.
foreground – Borrowed color used for stipple foreground runs.
- Returns:
Cached/new pattern ID, or zero for unavailable/empty pattern data.
-
static void SvgSymbolPoints(Rbc_RenderContext *ctx, const Point2D *centers, Tcl_Size count)
Emit bar, bitmap or geometric symbols at borrowed centers.
Bar samples use translated rectangle fills. Bitmap samples lazily define one resource and preserve aspect ratio. Geometric symbols retain shape-specific sizing and rounding; skinny plus/cross symbols have no fill. Caller-provided symbol state remains unchanged.
- Parameters:
ctx – [inout] Live Svg symbol context with selected symbol style and document resources.
centers – [in] Borrowed mapped symbol centers readable for count entries.
count – [in] Number of geometry records, not bytes.
-
int Rbc_SvgFontsFinish(Rbc_ExportContext *token)
Finalize document-local embedded SVG font definitions.
Returns TCL_OK immediately when embedding is disabled. Otherwise renames font references using a content hash and appends font programs in a style definition. Returns TCL_ERROR on font-program failure; discard the incomplete export. Call once after text collection and before closing the SVG document.
- Parameters:
token – [inout] Borrowed SVG export context with its body buffer and collected fallback faces; may be partially modified on failure.
-
static void SvgEmbeddedText(Rbc_RenderContext *ctx, char *string, TextStyle *style, double x, double y)
Emit positioned Unicode spans using embedded fallback faces.
Owns a temporary Tk-derived layout. Resolves glyphs before placement, extends zero-width Tk advances when a real fallback glyph has positive advance, and recomputes justification. Shadow precedes foreground. Registers faces on the shared token and frees layout on early failure or completion; font definitions are finalized separately.
- Parameters:
ctx – [inout] Live Svg renderer context borrowing the active export document.
string – [in] Borrowed NUL-terminated Tcl UTF text consumed during the call.
style – [in] Borrowed text style with live font/color resources; layout and placement follow its fields.
x – [in] Mapped destination X coordinate in display pixels.
y – [in] Mapped destination Y coordinate in display pixels.
-
static void SvgText(Rbc_RenderContext *ctx, char *string, TextStyle *style, double x, double y)
Select embedded or system-font SVG text output.
Nonembedded output evaluates the global Tcl font command, retains its attribute result across interpreter-state restoration, and owns a temporary layout. Escapes family and text, preserving Tk line widths through textLength. State restoration is not a guard against arbitrary mutations by a replaced font command; supplied widget and style resources must remain live.
- Parameters:
ctx – [inout] Live Svg renderer context borrowing the active export document.
string – [in] Borrowed NUL-terminated Tcl UTF text consumed during the call.
style – [in] Borrowed text style with live font/color resources; layout and placement follow its fields.
x – [in] Mapped destination X coordinate in display pixels.
y – [in] Mapped destination Y coordinate in display pixels.
-
static void SvgPhoto(Rbc_RenderContext *ctx, Tk_PhotoHandle photo, double x, double y)
Read a borrowed Tk photo and encode its current pixels.
Missing handles or failed block acquisition record export errors. The block is consumed synchronously by SvgPhotoBlock; no photo reference or pixel storage is retained.
- Parameters:
ctx – [inout] Live Svg renderer context borrowing the active export document.
photo – [in] Borrowed Tk photo handle, read synchronously.
x – [in] Mapped destination X coordinate in display pixels.
y – [in] Mapped destination Y coordinate in display pixels.
-
static void SvgWindow(Rbc_RenderContext *ctx, Tk_Window window, double x, double y)
Capture a mapped window drawable for SVG output.
Unmapped or empty windows emit nothing. A successful native color-image capture is owned temporarily and freed after encoding. The caller owns window lifetime and placement; this does not create or resize widgets.
- Parameters:
ctx – [inout] Live Svg renderer context borrowing the active export document.
window – [in] Borrowed live Tk window; capture does not create or resize it.
x – [in] Mapped destination X coordinate in display pixels.
y – [in] Mapped destination Y coordinate in display pixels.
-
static void SvgBitmapMask(Rbc_RenderContext *ctx, Display *display, Pixmap bitmap, double x, double y, int width, int height, const XColor *color, int background)
Emit a mapped monochrome marker mask as vector runs.
Missing bitmap/color or nonpositive dimensions emit nothing. Owns and releases the XImage readback, records failure, and translates the run group to the supplied origin. The background flag is intentionally unused; the caller selects the color for each pass.
- Parameters:
ctx – [inout] Live Svg renderer context borrowing the active export document.
display – [in] Borrowed display owning the source bitmap.
bitmap – [in] Borrowed one-bit pixmap readable over width by height pixels; None suppresses output.
x – [in] Mapped destination X coordinate in display pixels.
y – [in] Mapped destination Y coordinate in display pixels.
width – [in] Source bitmap width and mapped extent in pixels; nonpositive values emit nothing.
height – [in] Source bitmap height and mapped extent in pixels; nonpositive values emit nothing.
color – [in] Borrowed paint color; omission follows this helper’s format-specific policy.
background – [in] Unused pass selector; the caller supplies the paint color explicitly.
-
static void SvgBackgroundPolygon(Rbc_RenderContext *ctx, const XColor *color, const Point2D *points, Tcl_Size count)
Emit an opaque even-odd background polygon.
Delegates borrowed geometry and color to SvgPolygon. This supplies opacity one and no outline; NULL paint remains none.
- Parameters:
ctx – [inout] Live Svg renderer context borrowing the active export document.
color – [in] Borrowed background color; NULL emits no paint.
points – [in] Borrowed mapped point array readable for count vertices.
count – [in] Number of geometry records, not bytes.
-
static void SvgBorder(Rbc_RenderContext *ctx, Tk_3DBorder border, double x, double y, int width, int height, int borderWidth, int relief, int fill)
Approximate a Tk 3D border with SVG rectangles and polygons.
Borrows the border and forces lazy shadow-color initialization. Optional background fill precedes relief. Flat or too-small borders stop after filling; groove/ridge recurse as two half-width reliefs. Solid relief uses black edges. Dimensions must satisfy caller integer-arithmetic limits.
- Parameters:
ctx – [inout] Live Svg renderer context borrowing the active export document.
border – [in] Borrowed Tk 3D border; lazy shadow-color initialization may occur.
x – [in] Mapped destination X coordinate in display pixels.
y – [in] Mapped destination Y coordinate in display pixels.
width – [in] Mapped rectangle width in display pixels.
height – [in] Mapped rectangle height in display pixels.
borderWidth – [in] Relief thickness in display pixels; caller keeps size arithmetic representable.
relief – [in] Tk relief constant.
fill – [in] Nonzero paints the interior before relief; zero requests edges only.
-
static void SvgClearRectangle(Rbc_RenderContext *ctx, double x, double y, int width, int height)
Paint an opaque white rectangle.
This is SVG background painting, not alpha erasure. Nonpositive dimensions are ignored by SvgRectangle and the temporary white color is consumed synchronously.
- Parameters:
ctx – [inout] Live Svg renderer context borrowing the active export document.
x – [in] Mapped destination X coordinate in display pixels.
y – [in] Mapped destination Y coordinate in display pixels.
width – [in] Mapped rectangle width in display pixels.
height – [in] Mapped rectangle height in display pixels.
-
static void SvgBackgroundRectangles(Rbc_RenderContext *ctx, const XColor *color, const Rbc_RenderRectangle *rectangles, Tcl_Size count)
Paint background rectangles in input order.
A NULL color selects opaque white clearing; otherwise the supplied color is used. Borrowed rectangles are not retained and nonpositive sizes are skipped by the rectangle helper.
- Parameters:
ctx – [inout] Live Svg renderer context borrowing the active export document.
color – [in] Optional borrowed background color; NULL paints using the format clear-background policy.
rectangles – [in] Borrowed mapped rectangle array readable for count entries.
count – [in] Number of geometry records, not bytes.
-
static void SvgPlotBegin(Rbc_RenderContext *ctx, Tk_Font font, double x, double y, int width, int height, const XColor *background)
Paint the plot background and open its plot clip group.
NULL background means white. Emits the document-local fixed rbcPlot identifier and ignores the font argument. This scope is paired by SvgPlotEnd, independently of common rectangular clip-depth tracking.
- Parameters:
ctx – [inout] Live Svg renderer context borrowing the active export document.
font – [in] Unused by this backend; retained for the common plot-operation signature.
x – [in] Mapped destination X coordinate in display pixels.
y – [in] Mapped destination Y coordinate in display pixels.
width – [in] Mapped rectangle width in display pixels.
height – [in] Mapped rectangle height in display pixels.
background – [in] Borrowed plot background color; NULL selects the format’s clear-background policy.
-
static void SvgPlotEnd(Rbc_RenderContext *ctx)
Close the plot group opened by SvgPlotBegin.
Appends one group close without changing common clip depth or finalizing the SVG document. The caller must balance plot and nested clip scopes.
- Parameters:
ctx – [inout] Live Svg context with a matching plot scope; common depth is not changed here.
-
static void SvgClipBegin(Rbc_RenderContext *ctx, int x, int y, int width, int height)
Context storage
-
struct SvgRenderContext
SVG context borrowing a document builder; owns only its context allocation.
Public Members
-
Rbc_RenderExportState exportState
Shared document prefix; must remain first.
-
unsigned int bitmapId
Document identifier for the bitmap symbol definition.
-
int bitmapWidth
Bitmap/pattern width in pixels.
-
int bitmapHeight
Bitmap/pattern height in pixels.
-
Rbc_RenderExportState exportState