PDF resource builder and serialization
See Document renderer primitives for shared context ownership and the PDF/PostScript primitive contracts, including graphics-state and capture boundaries.
rbcPdf.c owns PDF object bodies and final document assembly. rbcRenderPdf.c emits drawing operators and
registers resources; rbcPdfFont.c resolves document fonts. rbcGrPdf.c selects scale and invokes the builder,
while the shared export command owns layout, delivery and cleanup. See Export orchestration and document ownership and PDF builder C reference.
One export, one builder
After Rbc_ExportInit(), Rbc_PdfBegin() attaches a new rbcGraphExportCommands.PdfDocument() to
backendData. It stores scale/height and appends q plus the initial matrix to the current content buffer. This
maps downward-increasing screen Y to PDF’s page coordinates while converting pixels to physical points. The graph
command calculates scale from Tk’s screen dimensions and physical screen width.
Begin neither clears existing content nor releases an earlier builder. Call it once on a fresh export context. Geometry emitters append content and register resources during the synchronous graph traversal. All renderer contexts must finish before finalization and cleanup.
Rbc_PdfDocument() finalizes document fonts, appends the matching Q and serializes the page. The result is a
new Tcl byte-array object, not Unicode text. The caller manages its references and either returns it or writes it with
binary channel settings. The builder opens no files and performs no channel operations.
Finalization is not an idempotent query: it changes the content buffer and can add or replace resources while finishing fonts. Do not call it twice or retry it against the same partially finalized context. On failure, discard the export and release its resources through the normal cleanup path.
Object numbers and resource categories
The current writer emits a single-page PDF 1.4 document with fixed leading objects:
Object |
Contents |
|---|---|
1 |
Catalog |
2 |
Pages tree with one child |
3 |
Page, scaled |
4 |
Page resource dictionary |
5 |
Drawing content stream |
6 onward |
Registered resource bodies in insertion order |
Rbc_PdfResource() interns the pair of category and exact body bytes. It copies a new body’s bytes into a
resource-owned Tcl_DString; an identical entry reuses its number. The search is linear and storage capacity grows in
blocks of 32 pointers. IDs remain stable as the pointer array grows. Neither source pointers nor caller buffers are
retained.
Categories F, G, I and P populate the page’s Font, ExtGState, XObject and Pattern
dictionaries respectively, with names such as /F6. Other categories are still serialized as objects but are not
automatically listed in those dictionaries. Font support uses D for indirectly referenced objects such as font
programs, mappings and descriptors.
This is byte interning, not semantic PDF deduplication: differently formatted but equivalent dictionaries are different
resources. Explicit lengths are required for binary data; negative resource lengths use strlen. Callers supply valid
PDF syntax and valid sizes. The internal resource API is not a parser for untrusted PDF documents and does not provide
recoverable allocation failure handling or general ID validation.
Reserved resources and streams
Font drawing reserves object IDs before all character codes are known. At finalization, Rbc_PdfFontsFinish() can
append auxiliary objects and replace the reserved bodies through Rbc_PdfSetResource(). Replacement preserves the
ID and category and does not re-intern the new body. Every reference to an interned ID sees the replacement;
placeholders that must remain independent therefore need distinct initial bodies. SetResource assumes a valid
existing ID and copies from nonaliased source storage.
Rbc_PdfStream() assembles dictionary entries, an explicit byte Length, the stream marker, payload and end marker
in a temporary DString. It temporarily redirects token->buffer, restores the previous pointer, then interns the
complete body and frees temporary storage. Embedded NULs are copied with their explicit length. It neither compresses
nor encodes payload bytes; filter entries in the supplied dictionary must describe the actual payload.
The main page content stream uses the same byte-count principle, but is emitted as fixed object 5 during
serialization. Content and resources remain separate until that step. The builder assumes content graphics-state scopes
are balanced apart from the initial save that its final Q closes.
Serialization and errors
Font finalization happens before calculating the total object count. The writer then redirects output to a temporary
document DString, emits the header and objects, and records each object’s byte offset in a Tcl_WideInt array.
Classic xref includes the free object-zero entry and ten-digit offsets for the remaining objects. The trailer points to
the catalog and startxref records the xref position.
An xref position above 9,999,999,999 records an export error instead of emitting an invalid classic table. This bound is a format check, not a promise that the builder supports allocations or resource counts approaching that size. The current implementation does not emit object streams, compressed xref streams, incremental updates or multiple pages.
A byte-array result is created only when serialization has no recorded export error. Temporary offsets/document storage are freed and the original content buffer pointer is restored. Font-finalization failure returns before document assembly. Internal append/format helpers and resource IDs are not individual success signals; callers must honor the export error and finalization result.
With identical content and resource insertion order, the writer’s object layout is deterministic. That does not establish byte identity for an entire export whose upstream font discovery, callbacks or drawing inputs differ.
Cleanup boundaries
Rbc_PdfFree() releases each resource body, each resource record, the pointer array and the builder, then clears
backendData. Calling it with no builder is harmless. It does not release document-local font state or content
storage; Rbc_ExportFree() handles those separately. Neither function destroys the caller’s graph or a
successfully returned byte-array object.
Future writer changes should preserve binary lengths, stable reserved IDs, font-finalization order and buffer restoration on every exit. Useful checks include repeated resource reuse, font placeholder replacement, image payloads containing NUL bytes, empty drawing content and independent repeated exports. These are builder concerns; geometry restoration and file-delivery behavior belong to the shared export orchestration.
Stored geometry queries
Rbc_PdfScale() returns the pixel-to-point conversion supplied at builder creation. Rbc_PdfHeight()
returns the saved page height in display pixels. Neither queries the current graph or Tk window, and neither accepts an
absent builder. These are document metrics, not live widget measurements: resizing or restoring the graph does not
update them. Both require the PDF backend lifetime to continue until the query returns.