Export orchestration C reference

These interfaces are private. See Export orchestration and document ownership for ownership, format policy and the distinction between ending export mode and restoring screen layout.

Document context

void Rbc_ExportInit(Rbc_ExportContext *exportPtr, Rbc_ExportBackend backend, Tcl_Interp *interp, Tk_Window tkwin, int decorations)

Initialize fresh caller-owned export storage.

Zero the record, borrow interp and tkwin, and select the embedded DString as the append destination. Call only on an uninitialized or already freed record; this does not release an earlier document. Font embedding starts disabled. The caller supplies backend state and any alternate buffer after this call.

Parameters:
  • exportPtr – [out] Caller-owned fresh or previously freed record; existing resources are not released.

  • backend – [in] Document backend selected for subsequent renderer dispatch.

  • interp – [in] Interpreter borrowed for the entire export; see Interpreter arguments.

  • tkwin – [in] Window borrowed for screen metrics and resources throughout export.

  • decorations – [in] Whether traversal includes decorative backgrounds, borders and separators.

int Rbc_ExportError(Rbc_ExportContext *exportPtr, const char *message)

Retain the first export failure without replacing later diagnostics.

Parameters:
  • exportPtr – Initialized, borrowed context.

  • message – Borrowed static string; it is neither copied nor freed.

Returns:

TCL_ERROR. This helper does not set the interpreter result.

void Rbc_ExportFree(Rbc_ExportContext *exportPtr)

Release document-local font data and the embedded DString.

Does not free the caller’s context, backendData, or an alternate buffer. The format owner must release backend resources separately. No renderer context may still be using these resources.

Parameters:
  • exportPtr – [inout] Initialized context whose font cache and embedded storage are released; backend cleanup is separate.

void Rbc_ExportAppend(Rbc_ExportContext *exportPtr, ...)

Append a NULL-terminated sequence of C strings to the current buffer.

The initialized context borrows buffer; callers must keep that DString alive. This helper neither checks nor clears an existing export error.

Parameters:
  • exportPtr – [inout] Initialized document context with a live current output buffer.

  • ... – [in] NUL-terminated strings followed by a pointer-valued NULL sentinel; embedded NULs terminate each string.

void Rbc_ExportFormat(Rbc_ExportContext *exportPtr, const char *format, ...)

Append printf-formatted text to the current document buffer.

Uses temporary heap storage when the local formatting buffer is too small. A formatting failure records a static export error; it does not set the Tcl result. The caller must check the context’s error before delivering output.

Parameters:
  • exportPtr – [inout] Initialized document context with a live current output buffer.

  • format – [in] Borrowed printf format string.

  • ... – [in] Arguments matching the format conversions; referenced strings remain valid during formatting.

Graph command and traversal

int Rbc_InitGraphExportOptions(Graph *graphPtr, const Rbc_GraphExportFormat *format)

Initialize the named SVG/PDF option-database component.

Borrow the graph and format policy. Specifications must store concrete pixel or boolean values in native Graph integer fields, without retained Tk resources. The temporary option table is freed on success and failure.

Parameters:
  • graphPtr – [inout] Borrowed graph; caller keeps the record alive throughout the operation.

  • format – [in] Borrowed immutable format policy with integer-backed option fields and valid callbacks.

Returns:

TCL_OK, or TCL_ERROR for invalid options or negative dimensions. Failure is graph-initialization failure, not a rollback transaction.

int Rbc_GraphExportOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[], const Rbc_GraphExportFormat *format)

Dispatch SVG/PDF cget, configure and output operations.

The enclosing widget command must preserve graph lifetime across callbacks. Requires objv[2] to exist and contain the operation. Option parsing stages all values before committing; successful output options stay configured even if rendering or file delivery later fails. Output remaps at export size, restores screen layout when callback state permits, and then delivers the complete document. Backend and shared context cleanup run on every path.

Parameters:
  • graphPtr – [inout] Borrowed graph; caller keeps the record alive throughout the operation.

  • interp – [inout] Result and diagnostic interpreter; see Interpreter arguments.

  • objc – [in] Full command argument count, at least three.

  • objv – [in] Borrowed full command vector; objv[2] is cget, configure or output; see Tcl command arguments.

  • format – [in] Borrowed immutable format policy with integer-backed option fields and valid callbacks.

Returns:

TCL_OK or TCL_ERROR with an interpreter diagnostic.

void Rbc_ExportBeginGraph(Graph *graphPtr)

Mark a graph as exporting, using requested size for unset dimensions.

Requires a live Tk window. Does not perform layout or preserve old dimensions. Pair with Rbc_ExportEndGraph on all paths; this flag is not a nesting counter.

Parameters:
  • graphPtr – [inout] Graph with a live window; dimensions and GRAPH_EXPORT may change.

void Rbc_ExportEndGraph(Graph *graphPtr)

Clear export mode and schedule screen remapping if the window survives.

With a live window, replace graph dimensions by actual Tk dimensions, replace flags with MAP_WORLD and schedule redraw. Does not remap immediately or restore a saved flag set. With a destroyed window, only clear GRAPH_EXPORT.

Parameters:
  • graphPtr – [inout] Retained graph record after export; tkwin may be NULL after callback destruction.

int Rbc_ExportGraph(Graph *graphPtr, Rbc_ExportContext *exportPtr)

Traverse mapped graph components into an initialized document context.

Borrow both arguments; the caller owns layout, GRAPH_EXPORT state, graph lifetime, document framing and final delivery. Each temporary renderer context is ended here. Track components retain their own scope and clipping. Crosshairs are not exported. No screen geometry restoration is performed.

Parameters:
  • graphPtr – [inout] Retained graph already laid out for export; caller owns export mode and callback lifetime protection.

  • exportPtr – [inout] Initialized document context with a live current output buffer.

Returns:

TCL_OK, or TCL_ERROR on invalid callback state or a recorded export error. Successful traversal does not imply successful format finalization.

SVG and PDF command helpers and format adapters

The policy record and internal helpers below implement the transaction described in Export orchestration and document ownership. The concrete adapters own document framing, while shared services own configuration, geometry restoration and delivery.

group SVG/PDF graph command internals

Functions

static int *ExportOptionField(Graph *graphPtr, int offset)

Address one native integer option field within a borrowed graph.

Requires an offset for a correctly aligned int member of Graph. Returns a borrowed pointer valid only while the graph is alive. Does not validate the offset or allocate storage; format policies are trusted private data.

Parameters:
  • graphPtr – [in] Live graph containing the requested integer field.

  • offset – [in] Byte offset of an aligned native int member of Graph.

static Tcl_Obj *ExportOptionValue(Graph *graphPtr, const Tk_OptionSpec *spec)

Copy an integer-backed export option into a new Tcl object.

Borrows the graph and concrete option specification. Returns a new object at reference count zero, using internalOffset to locate the int field. Boolean options are reported as integer zero or one, not original spelling.

Parameters:
  • graphPtr – [in] Graph whose current option value is read.

  • spec – [in] Concrete option specification; internalOffset selects an int member.

static Tcl_Obj *ExportOptionInfo(Graph *graphPtr, const Tk_OptionSpec *spec)

Build the standard option-description list for one export field.

Borrows graph and spec, reads the current integer value, and passes its new object to Rbc_GetComponentOptionInfo. Returns a new, unreferenced description object. Does not retain the graph, specification or Tk table.

Parameters:
  • graphPtr – [in] Graph whose current option value is read.

  • spec – [in] Concrete option specification supplying names, default and integer offset.

static int SetExportOptions(Graph *graphPtr, Tcl_Interp *interp, const Rbc_GraphExportFormat *format, Tcl_Size objc, Tcl_Obj *const objv[])

Stage all SVG/PDF option values before committing the configuration.

Requires concrete pixel/boolean options backed by native Graph ints. Allocates and frees a temporary settings array; arguments and format are borrowed. Rejects odd argument counts, unknown or ambiguous options, invalid values and negative dimensions with TCL_ERROR. No field changes before all conversions succeed. Repeated valid options use the last value, but an invalid earlier occurrence still fails. Unsupported specification types are programming errors and panic. Returns TCL_OK after committing.

Parameters:
  • graphPtr – [inout] Borrowed graph; caller keeps the record alive throughout the operation.

  • interp – [inout] Result and diagnostic interpreter; see Interpreter arguments.

  • format – [in] Borrowed immutable format policy with integer-backed option fields and valid callbacks.

  • objc – [in] Number of entries in the option/value slice; zero is allowed.

  • objv – [in] Borrowed option/value pairs starting at index zero, without command words; see Tcl command arguments.

static int WriteExportDocument(Tcl_Interp *interp, const Rbc_GraphExportFormat *format, Tcl_Obj *fileName, Tcl_Obj *document)

Write an already-built document through the Tcl filesystem API.

Borrows the format, filename and document objects. Opens with mode w, applies the format encoding and translation, then writes the object. Owns and closes the channel on every path after open. Preserves an earlier channel/write error across cleanup; otherwise propagates close failure. TCL_OK clears the interpreter result. This is not atomic replacement: an open or delivery failure may leave an empty or partial destination.

Parameters:
  • interp – [inout] Result and diagnostic interpreter; see Interpreter arguments.

  • format – [in] Policy supplying channel encoding, translation and diagnostic label.

  • fileName – [in] Borrowed Tcl filesystem path; opening with w may truncate it.

  • document – [in] Complete borrowed document object, kept alive through writing and closing.

static int OutputGraphExport(Graph *graphPtr, Tcl_Interp *interp, const Rbc_GraphExportFormat *format, Tcl_Obj *fileName)

Build SVG/PDF, restore screen layout and deliver only on success.

Borrows the graph and format; NULL fileName requests a Tcl result. Owns a stack export context and takes a reference to any document returned by documentProc. Saves screen dimensions, applies positive configured sizes and invokes the builder only after successful layout. Ends export mode, restores saved dimensions and remaps if the window and formatting state permit. Preserves an earlier error across restoration; a restoration error replaces success. Releases the document, backend state and shared storage on every path. freeProc must accept an uninitialized backend. The enclosing widget command protects graph lifetime across callbacks. Returns TCL_OK or TCL_ERROR; persistent export options are not restored.

Parameters:
  • graphPtr – [inout] Borrowed graph; caller keeps the record alive throughout the operation.

  • interp – [inout] Result and diagnostic interpreter; see Interpreter arguments.

  • format – [in] Borrowed immutable format policy with integer-backed option fields and valid callbacks.

  • fileName – [in] Borrowed destination path, or NULL to return the document as the Tcl result.

static void MarginsExport(Graph *graphPtr, Rbc_ExportContext *exportPtr)

Emit graph margins, optional border, margin legend, title and axes.

Borrows a graph with mapped export geometry and an initialized context. Creates and ends a temporary renderer context. Decorations control margin background and plot border, not legend/title/axis inclusion. Components supply their own visibility rules. Does not return status; the enclosing traversal inspects the accumulated export error after rendering.

Parameters:
  • graphPtr – [in] Live graph with mapped export dimensions, margins and component resources.

  • exportPtr – [inout] Initialized document context with a live current output buffer.

static int SvgDocument(Graph *graphPtr, Rbc_ExportContext *token, Tcl_Obj **documentPtr)

Frame SVG, traverse components and finalize font definitions.

Requires mapped export geometry and an initialized SVG token. Borrows graph and token; documentPtr is written only on TCL_OK with a new string object at reference count zero. Emits pixel dimensions and matching viewBox. Finalizes fonts only after successful traversal; appends the closing tag even on failure, but publishes no partial document. Reports font errors through the token interpreter. The shared caller owns geometry restoration, document reference management and context cleanup.

Parameters:
  • graphPtr – [inout] Retained graph mapped at the requested export size, with a live window at entry.

  • token – [inout] Initialized SVG context receiving content, font resources and errors.

  • documentPtr – [out] Receives a new string object at reference count zero only on success; unchanged on failure.

int Rbc_InitSvgOptions(Graph *graphPtr)

Initialize the graph’s named SVG option component.

Borrows the graph and delegates to Rbc_InitGraphExportOptions using the static format policy. Returns TCL_OK or TCL_ERROR. Intended for graph initialization; failure is not a rollback transaction on an existing configuration. No Tk option-table resources remain retained afterward.

Parameters:
  • graphPtr – [inout] Borrowed graph; caller keeps the record alive throughout the operation.

int Rbc_SvgOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Dispatch the graph svg command through shared export services.

Requires objv[2] to name the operation and a live graph protected by the enclosing widget command. Borrows all arguments and delegates cget, configure and output to Rbc_GraphExportOp. Returns its Tcl status and result; this adapter neither retains the graph nor owns backend cleanup.

Parameters:
  • graphPtr – [inout] Borrowed graph; caller keeps the record alive throughout the operation.

  • interp – [inout] Result and diagnostic interpreter; see Interpreter arguments.

  • objc – [in] Full widget command argument count, at least three.

  • objv – [in] Borrowed command vector with the export operation at index two; see Tcl command arguments.

static int PdfDocument(Graph *graphPtr, Rbc_ExportContext *token, Tcl_Obj **documentPtr)

Initialize the PDF builder, traverse components and serialize bytes.

Requires mapped export geometry and an initialized PDF token. Computes points per pixel from horizontal screen pixel/mm dimensions, and supplies the graph height to the builder. Borrows graph and token; on TCL_OK stores a new byte-array object at reference count zero in documentPtr. Traversal failure skips serialization; serializer failure stores NULL and reports the recorded token error. The shared caller releases backend resources even after failure, restores geometry and owns result delivery.

Parameters:
  • graphPtr – [inout] Retained graph mapped at the requested export size, with a live window at entry.

  • token – [inout] Initialized PDF context receiving content, font resources and errors.

  • documentPtr – [out] Receives a new byte-array object at reference count zero on success, NULL on serializer failure; unchanged on traversal failure.

int Rbc_InitPdfOptions(Graph *graphPtr)

Initialize the graph’s named PDF option component.

Borrows the graph and delegates to Rbc_InitGraphExportOptions using the static format policy. Returns TCL_OK or TCL_ERROR. Intended for graph initialization; failure is not a rollback transaction on an existing configuration. No Tk option-table resources remain retained afterward.

Parameters:
  • graphPtr – [inout] Borrowed graph; caller keeps the record alive throughout the operation.

int Rbc_PdfOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Dispatch the graph pdf command through shared export services.

Requires objv[2] to name the operation and a live graph protected by the enclosing widget command. Borrows all arguments and delegates cget, configure and output to Rbc_GraphExportOp. Returns its Tcl status and result; this adapter neither retains the graph nor owns backend cleanup.

Parameters:
  • graphPtr – [inout] Borrowed graph; caller keeps the record alive throughout the operation.

  • interp – [inout] Result and diagnostic interpreter; see Interpreter arguments.

  • objc – [in] Full widget command argument count, at least three.

  • objv – [in] Borrowed command vector with the export operation at index two; see Tcl command arguments.

struct Rbc_GraphExportFormat
#include <rbcGraph.h>

Static private policy for a named SVG/PDF graph export component.

Strings and option specifications are borrowed for the command lifetime. All option entries must be concrete TK_OPTION_PIXELS or TK_OPTION_BOOLEAN values stored as native Graph ints; offsets are trusted, not range checked. documentProc returns a new object at reference count zero on success and leaves delivery, geometry restoration and context cleanup to the caller. freeProc releases backend-owned state only, may be NULL, and must accept a context with no backend allocation. Shared cleanup releases fonts/storage. Encoding and translation select Tcl channel policy for file delivery.

Public Members

const char *name

Lowercase component and subcommand name.

const char *className

Option-database resource class.

const char *label

Human-readable format label.

const char *optionLabel

Label used in option diagnostics.

const char *operationLabel

Label used in operation diagnostics.

const Tk_OptionSpec *options

Borrowed immutable Tk option specifications.

Rbc_ExportBackend backend

Document backend selector.

int widthOffset

Byte offset of export width in Graph.

int heightOffset

Byte offset of export height in Graph.

int decorationsOffset

Byte offset of the decoration flag in Graph.

int embedFontsOffset

Byte offset of the font-embedding flag in Graph.

const char *encoding

Tcl channel encoding for file output.

const char *translation

Tcl channel newline translation for file output.

int (*documentProc)(Graph*, Rbc_ExportContext*, Tcl_Obj**)

Synchronous serializer; borrows the graph and appends to its output buffer.

void (*freeProc)(Rbc_ExportContext*)

Format-specific resource cleanup callback.

Data records and member contracts

These records describe stored state and resource ownership. Their presence in the reference does not make private layouts part of the installed C API.

struct Rbc_ExportContext

Synchronous document export owner with backend and font caches.

Window and interpreter are borrowed; cleanup releases backend state and font resources.

Public Members

Rbc_ExportBackend backend

Selected document backend.

Tcl_Interp *interp

Borrowed result interpreter.

Tk_Window tkwin

Borrowed live Tk window used to resolve display resources.

Tcl_DString storage

Inline DString storage used when no external buffer is supplied.

Tcl_DString *buffer

Active document buffer; may point to storage or caller-owned storage.

void *backendData

State owned by the backend command (PostScript token or PDF document).

void *fontData

Document-local font cache shared by PDF and SVG.

unsigned int nextResourceId

Document-local SVG definition identifiers.

int decorations

Nonzero includes plot decorations.

int embedFonts

Nonzero requests embedded font programs.

const char *error

First export error, static message.

Implementation selectors

enum Rbc_ExportBackend

Tags the output document so renderer adapters select PostScript, SVG or PDF operations.

Values:

enumerator RBC_EXPORT_POSTSCRIPT
enumerator RBC_EXPORT_SVG
enumerator RBC_EXPORT_PDF