PDF builder C reference

These private services are declared in rbcExport.h and implemented in rbcPdf.c. See PDF resource builder and serialization for the single-use lifecycle and resource numbering conventions. They are independent of Cairo.

void Rbc_PdfBegin(Rbc_ExportContext *token, double scale, int height)

Attach a fresh single-page PDF builder and begin its content transform.

Allocates backendData and appends a graphics-state save and transform to the current buffer. Does not clear earlier content or free an earlier backend. The owner must call Rbc_PdfFree, including after rendering failure.

Parameters:
  • token – Initialized export context with no existing backendData.

  • scale – Caller-validated conversion from screen pixels to PDF points.

  • height – Target height in screen pixels, used for the Y-axis flip.

double Rbc_PdfScale(Rbc_ExportContext *token)

Read a stored PDF page metric without changing builder state.

Parameters:
  • token – [in] Live export context with an initialized PDF builder; backendData must not be NULL.

Returns:

Pixel-to-point scale recorded by Rbc_PdfBegin. Does not query Tk, infer current graph dimensions or validate the stored metric.

int Rbc_PdfHeight(Rbc_ExportContext *token)

Read a stored PDF page metric without changing builder state.

Parameters:
  • token – [in] Live export context with an initialized PDF builder; backendData must not be NULL.

Returns:

Page height in display pixels recorded by Rbc_PdfBegin. Does not query Tk, infer current graph dimensions or validate the stored metric.

int Rbc_PdfResource(Rbc_ExportContext *token, char kind, const char *body, Tcl_Size length)

Intern a copied PDF object body within the current document.

Does not parse or validate PDF syntax. Binary bodies require explicit lengths. Resource numbers are meaningful only within this builder. Allocation uses Tcl’s non-recoverable allocation functions rather than an error return.

Parameters:
  • token – Live PDF builder.

  • kind – Resource category; part of the interning key.

  • body – Borrowed object-body bytes, copied for a new entry.

  • length – Explicit byte count, or negative for a NUL-terminated string.

Returns:

Stable object number, starting at six; identical kind/bytes reuse it.

void Rbc_PdfSetResource(Rbc_ExportContext *token, int id, const char *body, Tcl_Size length)

Replace a reserved object’s body without changing its ID or category.

Used to resolve font placeholders after character collection. Copies the new body and discards the previous one; does not validate id or re-intern the result. An ID shared through earlier interning names the same object for every reference, so placeholders intended to differ must be distinct.

Parameters:
  • token – Live PDF builder.

  • id – Existing object number returned by this builder, at least six.

  • body – Borrowed replacement bytes, not aliased with the destination body.

  • length – Byte count, or negative for a NUL-terminated string.

int Rbc_PdfStream(Rbc_ExportContext *token, char kind, const char *dictionary, const char *bytes, Tcl_Size length)

Wrap binary payload bytes in a PDF stream and intern the object.

Temporarily redirects buffer, emits Length, copies the payload, restores buffer and frees temporary storage. Adds no compression or encoding; supplied dictionary filters must match the supplied bytes. The returned ID does not imply that the context has no previously recorded export error.

Parameters:
  • token – Live PDF builder with a valid current buffer.

  • kind – Category passed to Rbc_PdfResource.

  • dictionary – Borrowed NUL-terminated dictionary entries without delimiters.

  • bytes – Borrowed readable payload; embedded NULs are allowed.

  • length – Nonnegative payload byte count supplied by the caller.

Returns:

Resource object number for the constructed stream body.

Tcl_Obj *Rbc_PdfDocument(Rbc_ExportContext *token, int width, int height)

Finalize fonts and serialize one PDF document into a binary Tcl object.

Appends the final graphics-state restore to content and serializes PDF 1.4 objects, classic xref and trailer. Restores the original buffer pointer and frees temporary serialization storage. Resources/content remain owned by the context. This is a single-use finalizer, not an idempotent query or retry API. No file is opened. The caller checks export diagnostics and owns result delivery/reference management.

Parameters:
  • token – Live PDF export context with completed drawing in its buffer.

  • width – Page width in screen pixels.

  • height – Page height in screen pixels.

Returns:

New byte-array object at reference count zero, or NULL on failure.

void Rbc_PdfFree(Rbc_ExportContext *token)

Release PDF resources and clear backendData; an absent builder is safe.

Frees copied resource bodies, the resource array and builder. Does not free fontData, content storage, an alternate buffer or the token itself. Finish all renderer/font operations before releasing their builder.

Parameters:
  • token – Borrowed export context with PDF or NULL backendData.

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 PdfResource

Owned PDF resource body; document skeleton objects reserve IDs 1 through 5.

Public Members

char kind

Resource category used for lookup and serialization.

Tcl_DString body

Owned serialized resource bytes.

struct PdfDocument

Document-owned PDF resource registry and page coordinate conversion.

Public Members

PdfResource **resources

Owned array of owned resource records.

int count

Number of initialized resources.

int capacity

Allocated resource-pointer capacity.

int height

Page height in unscaled display pixels.

double scale

Display-pixel to PDF-point scale.