Delphi / Free Pascal

The RustPdf unit wraps the rust-pdf C core with idiomatic, handle-owning classes. It covers the whole product surface: vector graphics, embedded/subset fonts & Unicode text, paragraphs, images, PDF/A (1b–3a + A-4/4e/4f), tagged/accessible output, attachments, AcroForm fields, manipulation, text extraction, encryption and digital signatures. One unit compiles under both Delphi (10.x+, Windows/macOS/Linux) and Free Pascal (3.2+).

Download

The binding ships as one versioned archive: the RustPdf.pas unit, the native library for each platform (lib/<os-arch>/), a sample and an INSTALL.txt. Basic PDF generation works immediately as a free trial; the corporate features unlock with a license token.

Prefer to build from source? make delphi-dist assembles the same archive. Using Boss? The repo is boss install-able. After unzipping, drop the matching native library next to your executable (matching the app's bitness on Windows). Full steps are in the bundled INSTALL.txt and the Installation section below.

Installation

The binding is a single source unit, RustPdf.pas, with no native build step and no headers to install. It loads the shared library (libpdf_ffi) built from the Rust core at run time, so there is no fixed link name. Add the binding directory to your unit search path:

uses RustPdf;   // add bindings/delphi to the unit search path (-Fu / Project Options)

Build the native library and (optionally) point RUSTPDF_LIB at it:

cargo build -p pdf-ffi                       # → target/debug/libpdf_ffi.{dylib,so,dll}
export RUSTPDF_LIB=/path/to/target/debug/libpdf_ffi.dylib   # optional

The loader searches, in order: $RUSTPDF_LIB; the library next to the executable or in the current directory (the deployment layout); target/debug and target/release walking up from those dirs (the dev tree); then the bare platform name via the OS loader. Compile a console program with Free Pascal:

fpc -Mdelphi -Fubindings/delphi hello.dpr

or with Delphi's command-line compiler:

dcc64 -Ubindings/delphi hello.dpr

Verify the library loads:

Writeln(Pdf.Version);   // native library version, e.g. 0.4.8

Quick start

A one-page document with a filled rectangle, saved to disk:

program hello;
{$IFDEF FPC}{$MODE DELPHI}{$H+}{$CODEPAGE UTF8}{$ENDIF}
uses RustPdf;
var
  Doc: TPdfDocument;
begin
  Doc := TPdfDocument.Create;          // A4 by default
  try
    Doc.AddPage;
    Doc.FillRgb(0.86, 0.20, 0.18);
    Doc.Rect(72, 640, 200, 120);       // x, y, width, height (points)
    Doc.Fill;
    Doc.SaveToFile('out.pdf');
  finally
    Doc.Free;
  end;
end.

Most methods return the document, so calls chain:

var
  Doc: TPdfDocument;
  Font: Integer;
  Data: TBytes;
begin
  Doc := TPdfDocument.Create;
  try
    Font := Doc.AddFontFile('Roboto-Regular.ttf');
    Doc.AddPage
       .FillRgb(0.1, 0.1, 0.12).Rect(0, 800, 595, 42).Fill
       .ShowText(Font, 24, 72, 740, 'Olá, açúcar — café');
    Data := Doc.ToBytes;               // in-memory bytes instead of a file
  finally
    Doc.Free;
  end;
end;

Licensing & activation

Basic generation (everything above) is always free. The corporate features (PDF/A, digital signatures/PAdES, encryption, accessibility) require an active license token. Without one, those calls raise ERustPdf and produce no output.

Activation needs no rebuild. Easiest is an environment variable, auto-activated the first time a corporate feature is used:

export RUSTPDF_LICENSE="010f0000…"           # the token we email you
# or point at a file:
export RUSTPDF_LICENSE_FILE=/etc/rustpdf/license.txt

Or activate explicitly in code:

Pdf.ActivateLicense(Token);   // raises ERustPdf if forged / expired / malformed

Coordinate system

• Units are points (1 pt = 1/72 inch). A4 is 595 × 842, US Letter 612 × 792.
• The origin (0, 0) is the bottom-left corner; y grows upward.
• For text, (x, y) is the baseline of the first glyph.
• Drawing/text always targets the most recently added page.

Threading & concurrency

The core is Send but not Sync: you can build many documents in parallel, but a single handle must never be touched by two threads at once.

• Generate in parallel. Give each thread its own TPdfDocument/TPdfEditable. Independent documents share no state and run concurrently.
• Move between threads. A handle may be created on one thread and used on another.
• Never share a live handle. Two threads calling into the same TPdfDocument at the same time is unsupported; protect it with a TCriticalSection if you must.
• Errors are per-thread. The native last-error is thread-local, so a failure on one thread never clobbers another's. ERustPdf is always raised on the calling thread.
• License is process-global. Pdf.ActivateLicense (or the env var) applies to every thread; activate once at startup.

type
  TRenderThread = class(TThread)
  protected
    procedure Execute; override;
  end;

procedure TRenderThread.Execute;
var
  Doc: TPdfDocument;
begin
  Doc := TPdfDocument.Create;        // one document per thread
  try
    Doc.AddPage.FillRgb(0.1, 0.1, 0.12).Rect(72, 700, 200, 80).Fill;
    Doc.SaveToFile(Format('out-%d.pdf', [ThreadID]));
  finally
    Doc.Free;
  end;
end;

Authoring: create & save

Creates an empty document (A4 default page size). Always pair with try…finally Doc.Free end so the native handle is released.

Pages & vector graphics

Graphics state and path operators mirror PDF's content-stream model. Colors are RGB in 0.0–1.0.

Doc.AddPage;
Doc.StrokeRgb(0.10, 0.45, 0.90).LineWidth(3);
Doc.Rect(72, 600, 300, 160).Stroke;
Doc.FillRgb(0.95, 0.77, 0.06);
Doc.Rect(120, 640, 120, 80).Fill;
Doc.SaveToFile('shapes.pdf');

Fonts & text

Fonts are embedded and subsetted, with HarfBuzz-quality shaping, kerning and full Unicode (Type0/CIDFontType2 with ToUnicode, so text extracts and copies correctly, provided the embedded font covers those characters). Register a font once, then reference it by its integer id.

HeadingLevel (1–6) tags the run as H1–H6 in an accessible document (see Accessibility); leave 0 for ordinary text. Strings cross the boundary as UTF-8.

var Regular: Integer;
…
Regular := Doc.AddFontFile('Roboto-Regular.ttf');
Doc.AddPage;
Doc.ShowText(Regular, 28, 72, 760, 'Invoice #1024');
Doc.ShowText(Regular, 12, 72, 720, '日本語 · Ελληνικά · العربية');
Doc.SaveToFile('text.pdf');

Paragraphs

The paragraph layer wraps, aligns and justifies text inside a fixed width (greedy line breaking using shaped glyph widths).

const
  Intro = 'A long paragraph that wraps to the given width and is justified ' +
          'automatically; extra space is distributed between words.';
…
F := Doc.AddFontFile('Roboto-Regular.ttf');
Doc.AddPage;
Doc.Paragraph(F, 12, 72, 700, 451, Intro, paJustify);
Doc.SaveToFile('paragraph.pdf');

See the TPdfAlign enum for the alignment options.

Images

JPEGs are embedded verbatim (DCTDecode, no re-encode). PNGs are decoded and re-encoded (FlateDecode); alpha becomes an /SMask, palette becomes an Indexed color space. Register an image once, draw it many times.

Logo := Doc.AddImageFile('logo.png');
Doc.AddPage;
Doc.DrawImage(Logo, 72, 680, 160, 90);
Doc.SaveToFile('with_image.pdf');

PDF/A licensed

Produce archival-grade output. Pdfa defaults to A-2b; pass a TPdfaLevel for a specific level. An embedded sRGB ICC profile, output intent, XMP metadata and document /ID are added automatically; A-1b also forces PDF 1.4 and emits a /CIDSet, and A-4 (ISO 19005-4) is based on PDF 2.0.

Doc.Pdfa(palA2B).SetInfo('Q3 Report', 'Acme Inc.', '', '', '');
F := Doc.AddFontFile('Roboto-Regular.ttf');
Doc.AddPage;
Doc.ShowText(F, 20, 72, 760, 'Archival report');
Doc.SaveToFile('report_pdfa.pdf');   // raises ERustPdf without a license granting PDF/A

Accessibility (Tagged PDF / PDF/UA) licensed

Tagged builds a logical structure tree (PDF/UA-1). Combine with Pdfa(palA2A) for archival and accessible output. Use HeadingLevel on ShowText for H1–H6, and Figure(…, Alt) for described images.

Doc.Pdfa(palA2A).Tagged.SetInfo('Accessible report', '', '', '', '');
F := Doc.AddFontFile('Roboto-Regular.ttf');
Doc.AddPage;
Doc.ShowText(F, 26, 72, 760, 'Annual report', 1);   // H1
Doc.ShowText(F, 14, 72, 720, 'Overview', 2);         // H2
Doc.ShowText(F, 11, 72, 690, 'Body paragraph of the section…');
Chart := Doc.AddImageFile('chart.png');
Doc.Figure(Chart, 72, 520, 300, 150, 'Revenue grew 18% year over year');
Doc.SaveToFile('accessible.pdf');

Attachments (PDF/A-3) licensed

PDF/A-3 allows embedding arbitrary source files (e.g. the XML behind an e-invoice). Each attachment carries a MIME type and an TAFRelationship.

Xml := ...;   // TBytes of invoice.xml
Doc.Pdfa(palA3B).SetInfo('E-invoice 1024', '', '', '', '');
F := Doc.AddFontFile('Roboto-Regular.ttf');
Doc.AddPage;
Doc.ShowText(F, 18, 72, 760, 'Invoice 1024');
Doc.AttachFile('invoice.xml', 'text/xml', Xml, afSource, 'Structured invoice data');
Doc.SaveToFile('einvoice.pdf');

ZUGFeRD / Factur-X e-invoices licensed

Turn the document into a ZUGFeRD / Factur-X electronic invoice: the embedded XML (the Cross-Industry Invoice) is attached as factur-x.xml, the file is marked PDF/A-3, and the Factur-X identification is written into the XMP metadata. The visible PDF is the human-readable invoice; the embedded XML is its machine-readable twin. Validates as PDF/A-3 plus Factur-X under veraPDF.

var Xml: TBytes;
…
Xml := TEncoding.UTF8.GetBytes(LoadXmlText);   // your Cross-Industry Invoice XML
Doc.SetInfo('Invoice INV-2026-001', '', '', '', '');
F := Doc.AddFontFile('Roboto-Regular.ttf');
Doc.AddPage;
Doc.ShowText(F, 18, 72, 760, 'Invoice INV-2026-001');
Doc.Facturx(Xml, fxEN16931);
Doc.SaveToFile('einvoice.pdf');   // PDF/A-3 + Factur-X; needs a PDF/A license

See the TFacturxProfile enum for the conformance levels (fxMinimum to fxExtended).

AcroForm fields

Build interactive forms with generated appearance streams (no NeedAppearances). Rectangles are PdfRect(x0, y0, x1, y1); Page is a 0-based page index. Dotted names ('a.b.c') create hierarchical fields.

var Buttons: TRadioButtons;
…
Doc.AddPage;
Doc.TextField('applicant.name', 0, PdfRect(72, 700, 320, 720));
Doc.Checkbox('agree', 0, PdfRect(72, 660, 88, 676), False);
Doc.Dropdown('plan', 0, PdfRect(72, 620, 240, 640), ['Starter', 'Pro', 'Enterprise'], 1);

SetLength(Buttons, 2);
Buttons[0].Rect := PdfRect(72, 580, 88, 596);   Buttons[0].ExportValue := 'monthly';
Buttons[1].Rect := PdfRect(140, 580, 156, 596); Buttons[1].ExportValue := 'annual';
Doc.RadioGroup('billing', 0, Buttons, 1);
Doc.SaveToFile('form.pdf');

Fill and flatten fields later with TPdfEditable.

Hyperlinks free

Add clickable link rectangles to the current page: a web link opens a URL; an internal link jumps to another page (optionally scrolling so a given Top y-coordinate sits at the top of the view).

F := Doc.AddFontFile('Roboto-Regular.ttf');
Doc.AddPage;
Doc.ShowText(F, 14, 72, 760, 'Visit rustpdf.dev (see page 2)');
Doc.LinkUri(PdfRect(72, 756, 320, 776), 'https://rustpdf.dev/');   // web link
Doc.LinkToPage(PdfRect(330, 756, 430, 776), 1, 800);              // jump to page 2
Doc.AddPage;
Doc.SaveToFile('links.pdf');

Rectangles are PdfRect(x0, y0, x1, y1) in points; PageIndex is 0-based. The two-argument LinkToPage jumps without scrolling; the three-argument overload positions Top at the top of the view.

Bookmarks / outline free

Build a navigable document outline. A TPdfBookmark has a title, a target page and an optional Top; nest children with .Child(...). The object owns its children, so freeing the root frees the whole tree. A document with bookmarks opens with the outline pane shown.

var Root: TPdfBookmark;
…
F := Doc.AddFontFile('Roboto-Regular.ttf');
Doc.AddPage; Doc.AddPage; Doc.AddPage;

Root := TPdfBookmark.Create('Chapter 1', 0, 820);
try
  Root.Child(TPdfBookmark.Create('Section 1.1', 1))
      .Child(TPdfBookmark.Create('Section 1.2', 2));
  Doc.AddBookmark(Root);
  Doc.AddBookmark(TPdfBookmark.Create('Chapter 2', 2));
finally
  Root.Free;   // frees the whole tree
end;
Doc.SaveToFile('outline.pdf');

Metadata

Sets the document information dictionary (and, for PDF/A, the matching XMP). Pass an empty string '' for any field you want to leave unset.

Doc.SetInfo('Q3 Report', 'Acme Inc.', 'Quarterly results', 'finance, q3', '');

Manipulation: load an existing PDF

TPdfEditable parses an existing document (classic & xref streams, object streams, all standard filters, RC4/AES decryption) into an editable model. Pages are a flat list; the page tree is rebuilt on output.

var Ed: TPdfEditable;
…
Ed := TPdfEditable.LoadFromFile('in.pdf');
try
  Writeln(Ed.PageCount);
finally
  Ed.Free;
end;

// encrypted input:
Ed := TPdfEditable.LoadFromFile('secured.pdf', 'user-or-owner-pw');
try
  Ed.SaveToFile('plain.pdf');
finally
  Ed.Free;
end;

Pages: merge, split, reorder, rotate

A := TPdfEditable.LoadFromFile('a.pdf');
B := TPdfEditable.LoadFromFile('b.pdf');
try
  A.Merge(B);                       // a now has a's pages followed by b's
  A.RotatePage(0, 90);
  A.ReorderPages([2, 1, 0]);
  A.SaveToFile('merged.pdf');
finally
  A.Free; B.Free;
end;

Metadata, overlay & form fill

Ed := TPdfEditable.LoadFromFile('form.pdf');
try
  Ed.SetInfo('Title', 'Filled form');
  Found := Ed.FillTextField('applicant.name', 'Jane Doe');
  Writeln('filled: ', Found, ' | title: ', Ed.GetInfo('Title'));
  Ed.SaveToFile('filled.pdf');
finally
  Ed.Free;
end;

Form fill & flatten free

Fill the fields of an existing AcroForm and (optionally) flatten them: filling generates a fresh appearance stream (no NeedAppearances), and flattening bakes every widget's appearance into the page content and removes the interactive form entirely.

var Names: TPdfStringArray; I: Integer;
…
Ed := TPdfEditable.LoadFromFile('form.pdf');
try
  Names := Ed.FieldNames;                  // ['applicant.name', 'agree', 'plan', …]
  for I := 0 to High(Names) do
    Writeln(Names[I]);
  Ed.FillTextField('applicant.name', 'Jane Doe');
  Ed.SetCheckbox('agree', True);
  Ed.SetRadio('billing', 'annual');
  Ed.SetChoice('plan', 'Pro');
  Ed.FlattenForms;                         // optional: make it non-editable
  Ed.SaveToFile('filled.pdf');
finally
  Ed.Free;
end;

Watermarks free

Stamp a diagonal text watermark or a centered image watermark across every page, drawn semi-transparently over the existing content. Text uses the standard Helvetica font, so keep it to WinAnsi (Latin-1) for stamps like "CONFIDENTIAL". Set OpaqueBackground := True to white out a band behind the text instead of stamping over the content; pass RotationDeg to rotate the image watermark.

Ed := TPdfEditable.LoadFromFile('report.pdf');
try
  Ed.WatermarkText('CONFIDENTIAL', 64, 0.5, 0.5, 0.5, 0.25, 45, False);
  Ed.WatermarkImageFile('stamp.png', 200, 80, 0.30, 30);   // rotated 30°
  Ed.SaveToFile('stamped.pdf');
finally
  Ed.Free;
end;

Positioned drawing free

Stamp a single page in place: fill a rectangle and/or drop a line of text at exact coordinates. Coordinates are in the page's visible space (origin lower-left, y up), so content lands where a viewer sees it regardless of the page's /Rotate; RotationDeg rotates the text counter-clockwise about its anchor. Text uses the standard Helvetica font (keep it WinAnsi / Latin-1). Both return whether the page existed.

A typical use is masking a spot with an opaque white box, then writing a value over it. The optional Align (paLeft, paRight, paCenter, paJustify) on PlaceText shifts the start point along the baseline so the text is left/right/center-aligned about (X, Y). MaskedText does the mask-then-write in one call: it fills the box [X, Y, X+Width, Y+Height] in the background colour (each 0..1; defaults to white), then writes the text in the text colour (defaults to black) horizontally aligned per Align and vertically centered in the box. DrawImage takes raw JPEG/PNG image bytes and places the image with its lower-left corner at (X, Y) scaled to Width × Height points. The trailing FontId/Anchor/VAlign/Padding parameters are covered in Stamping fonts, anchors & paragraphs below.

var Data: TBytes;
    G: TPageGeometry;
    Ed: TPdfEditable;
begin
  Data := TFile.ReadAllBytes('invoice.pdf');
  G := Pdf.MeasurePage(Data, 0);                       // read the page geometry first
  Ed := TPdfEditable.Load(Data);
  try
    Ed.FillRect(0, 400, G.Height - 60, 120, 18, 1, 1, 1, 1);   // mask: opaque white
    Ed.PlaceText(0, 404, G.Height - 56, 'PAID', 12, 0, 0.5, 0, 0);
    Ed.DrawImage(0, TFile.ReadAllBytes('logo.png'), 404, G.Height - 120, 120, 48, 0);
    Ed.Save('stamped.pdf');
  finally
    Ed.Free;
  end;
end;

Stamping fonts, anchors & paragraphs free

The stamping primitives above also accept an embedded font, explicit vertical anchors, and a word-wrapping paragraph variant. See the interactive positioning guide for a visual tour of every anchor.

Embedded stamping fonts

Register a TrueType/OpenType font on the editable document and pass its id as the FontId parameter of PlaceText, MaskedText or PlaceParagraph. The font is embedded as a subset, so stamped text renders with the real glyphs and metrics (full Unicode, not just WinAnsi). FontId = -1 keeps the built-in Helvetica.

var FId: Integer;
…
FId := Ed.AddFontFile('Roboto-Regular.ttf');
Ed.PlaceText(0, 72, 700, 'Olá — texto Unicode', 14, 0, 0, 0, 0, paLeft, FId);

Vertical anchors (TVerticalAnchor)

PlaceText and PlaceParagraph take an Anchor saying what Y means. vaBaseline is the historical PlaceText default. vaTop hangs the text from Y (the baseline lands ascent × Size below it, matching legacy fixed-position layout); vaBottom rests the descender line on Y. vaLineTop/vaLineBottom anchor via the legacy line box (ascent + descent), so a single line and a wrapped paragraph agree vertically; for PlaceParagraph they also use the line-box height as the leading basis.

// Baseline exactly where legacy fixed-position layout would put it:
Ed.PlaceText(0, 72, 720, 'hung from the top', 12, 0, 0, 0, 0, paLeft, -1, vaTop);
Ed.PlaceText(0, 72, 640, 'line box bottom', 12, 0, 0, 0, 0, paLeft, -1, vaLineBottom);

MaskedText: vertical alignment & padding

VAlign positions the line inside the box: vlMiddle (default) keeps the historical cap-height centering, vlTop hangs the line from the top edge (top line-alignment in rectangle-based text APIs semantics), vlBottom rests the descender line on the bottom edge. Padding is the horizontal edge inset in points for paLeft/paRight: a negative value keeps the historical min(0.15 × Size, Width / 4), and 0 starts flush with the box edge (legacy PDF libraries DrawString semantics).

// White box, top-aligned text, flush with the left edge:
Ed.MaskedText(0, 100, 240, 200, 42, 'ALIGNED TOP', 12,
              0, 0, 0, 1, 1, 1, paLeft, -1, vlTop, 0);

Wrapped paragraphs

PlaceParagraph breaks Text into lines that fit Width points (greedy, by word; #10 forces a break) and draws them downward from (X, Y). With vaBottom/vaLineBottom the block is bottom-pinned: its bottom rests on Y and it grows upward by its real content height. MaxHeight > 0 is a height ceiling that truncates overflowing lines (with a bottom anchor the last lines stay pinned and the overflow is cut from the top); 0 means unlimited. LineHeight scales the default 1.2 × Size leading, and RotationDeg rotates the laid-out block counter-clockwise about the anchor. PlaceParagraphMeasured additionally reports the number of lines drawn and the consumed block height in points, so you can stack blocks without re-measuring.

var Lines: Integer; Height: Double;
…
// Wrap into a 130 pt column from the top-left corner (72, 700):
Ed.PlaceParagraph(0, 72, 700, 130, 'terms and conditions apply to every order');
// Bottom-pinned block with a 60 pt ceiling, measured:
Ed.PlaceParagraphMeasured(0, 300, 120, 130, 'grows upward from its anchor', 10,
                          0, 0, 0, paLeft, -1, 60, 1.0, vaBottom, 0, Lines, Height);
Writeln(Format('%d lines, %.1f pt used', [Lines, Height]));

Stamp space: visible vs media

ssVisible (the default) interprets coordinates in the page's displayed space, compensating /Rotate so a stamp with RotationDeg = 0 reads upright on screen. ssMedia interprets coordinates and RotationDeg in the raw PDF user space, never composing with the page's /Rotate or crop offset (the raw-coordinate semantics of legacy layout engines). Use ssMedia to reproduce legacy-engine placement on rotated or scanned pages; the setting applies to subsequent FillRect/PlaceText/MaskedText/PlaceParagraph/DrawImage calls. Watermarks and redaction are unaffected.

Ed.SetStampSpace(ssMedia);      // legacy raw-space coordinates from here on
Ed.PlaceText(0, 200, 300, 'MEDIA', 10, 0, 0, 0, 0);
Ed.SetStampSpace(ssVisible);    // back to the default

Image rotation anchor

DrawImage takes a trailing Anchor: iaCorner (default) rotates the image about its own lower-left corner at (X, Y), so a rotated image sweeps around that point; iaBoundingBox lands the rotated image's bounding box with its lower-left at (X, Y) (bounding-box layout semantics: the drawn pixels always sit at or above/right of the anchor; a 90° image occupies [X, X+Height] × [Y, Y+Width]).

Ed.DrawImage(0, Logo, 260, 60, 80, 30, 90, iaBoundingBox);

Redaction licensed

True redaction: the text and graphics whose origin falls inside a rectangle are removed from the content stream (not just covered), so the data is gone from the file and is no longer extractable. Opaque black boxes are then painted over the regions. Returns True when the page index was valid.

Ed := TPdfEditable.LoadFromFile('statement.pdf');
try
  Ed.Redact(0, [PdfRect(60, 590, 400, 620), PdfRect(60, 540, 400, 570)]);
  Ed.SaveToFile('redacted.pdf');     // raises ERustPdf without a license granting redaction
finally
  Ed.Free;
end;

Convert to PDF/A licensed

Convert an existing PDF to archival PDF/A (a basic profile: A-1b, A-2b or A-3b). An sRGB output intent, PDF/A XMP metadata (synced with /Info) and a document /ID are added. Fails if any font is not embedded (PDF/A requires every font embedded) or a level-A profile is requested.

Ed := TPdfEditable.LoadFromFile('in.pdf');
try
  Ed.ConvertToPdfa(palA2B);          // raises ERustPdf if fonts aren't embedded
  Ed.SaveToFile('archival.pdf');     // veraPDF: PDF/A-2b compliant
finally
  Ed.Free;
end;

Optimize & compact

Ed := TPdfEditable.LoadFromFile('big.pdf');
try
  Ed.Optimize.Compact(True);
  Ed.SaveToFile('small.pdf');
finally
  Ed.Free;
end;

Encryption licensed

Apply standard-handler encryption at output. AES-256 (V5/R6) uses OS-CSPRNG keys/IVs.

Ed := TPdfEditable.LoadFromFile('in.pdf');
try
  Ed.Encrypt(encAES256, '', 'owner-secret', True);
  Ed.SaveToFile('secured.pdf');     // raises ERustPdf without an Encryption license
finally
  Ed.Free;
end;

See the TEncryption enum for RC4 / AES-128 / AES-256.

Output & incremental update

Original := ...;   // TBytes of in.pdf
Ed := TPdfEditable.Load(Original);
try
  Ed.SetInfo('Subject', 'reviewed');
  Incremental := Ed.ToBytesIncremental(Original);   // original bytes preserved verbatim
finally
  Ed.Free;
end;

Normalize & downgrade free

Turn a PDF/A or higher-version file back into a plain PDF. StripPdfa removes the PDF/A conformance markers (the output intent and the pdfaid XMP), SetVersion sets the header version, and Normalize does both in one call (strip PDF/A and set the version).

Ed := TPdfEditable.LoadFromFile('archival_pdfa.pdf');
try
  Ed.Normalize(2);                   // strip PDF/A + downgrade to PDF 1.7
  Ed.SaveToFile('plain.pdf');
finally
  Ed.Free;
end;

Digital signatures licensed

Sign a PDF with a PKCS#7 detached signature via an incremental update (the original bytes are preserved). Keys and certificates are passed as DER TBytes. Pades = True switches to PAdES-B-B.

PdfBytes := ...;   // TBytes of contract.pdf
KeyDer   := ...;   // PKCS#8 private key (DER)
CertDer  := ...;   // X.509 certificate (DER)

Signed := Pdf.Sign(PdfBytes, KeyDer, CertDer, 'Approved', 'New York', 'Jane Doe', True);
// Verify in a shell: pdfsig contract.signed.pdf  →  "Signature is Valid."

Deferred / HSM signing licensed

Sign without ever handing the library a private key. When the key lives in an HSM, a cloud KMS, a smartcard or a PKI token (any PKI: eIDAS, AATL, a national CA), you supply the raw RSA signature and the binding builds and embeds the CMS / PKCS#7 container. There are two flavours: a synchronous remote signer callback, and a two-phase begin / complete flow for asynchronous or out-of-band signing.

Model A: remote signer callback

The binding assembles the signed attributes and calls back for the raw RSA PKCS#1 v1.5 signature over their SHA-256 digest. The certificate is passed as DER; the key stays inside your HSM. TPdfRemoteSign is a method pointer (of object, so it can carry state), so the callback is a method of one of your classes. Chain are intermediate certificates (DER), supplied independently of the key.

type
  TMySigner = class
    function SignHash(const DataToSign: TBytes): TBytes;   // call your HSM / KMS / token
  end;
…
var
  Signer: TMySigner;
  Opts: TSigningOptions;
  Signed: TBytes;
begin
  Signer := TMySigner.Create;
  try
    Opts := SigningOptions;        // zero-initialised record
    Opts.Reason := 'Approved';
    Opts.Pades  := True;           // PAdES-B-B
    Signed := Pdf.SignWith(PdfBytes, CertDer, Signer.SignHash, [IntermediateDer], Opts);
  finally
    Signer.Free;
  end;
end;

Model B: two-phase begin / complete

For an asynchronous signer or a detached workflow, phase 1 prepares the PDF with a placeholder and returns the exact bytes the signature covers; you sign the digest out of band and build the CMS container; phase 2 embeds it. A TSigningSession exposes Document (the prepared PDF), Bytes (the bytes covered by the signature), Hash (their SHA-256, the value a remote signer signs) and Complete(Container), which embeds a finished DER CMS / PKCS#7 container and returns the final signed PDF. Free the session with .Free.

var
  Session: TSigningSession;
  Container, Signed: TBytes;
begin
  Session := Pdf.BeginSigning(PdfBytes);   // or BeginSigning(PdfBytes, Opts)
  try
    Container := BuildCmsContainer(Session.Hash);   // sign the digest remotely, assemble DER CMS
    Signed := Session.Complete(Container);          // = Pdf.CompleteSignature(Session.Document, Container)
  finally
    Session.Free;
  end;
end;

Inspect existing signature fields

Before signing, list the signature fields already present in the document. An empty result means the document is unsigned.

var F: TSignatureField;
…
for F in Pdf.ListSignatures(PdfBytes) do
  Writeln(F.Name, ' signed: ', F.Signed);

TSigningOptions

Both models accept an optional TSigningOptions record; build a zero-initialised one with the SigningOptions helper, then set the fields you need.

TCertify

TSignaturePolicy

A PAdES-EPES signature-policy identifier. OID is the policy OID (dotted-decimal); Hash is the policy document hash (TBytes); HashAlgorithmOID is the hash algorithm OID (empty means SHA-256); URI is an optional SPURI qualifier pointing to where the policy can be retrieved.

Timestamp & DSS (PAdES LTV) licensed

Build long-term-validation signatures offline. AddDss appends a Document Security Store (/DSS with certs/CRLs, PAdES-B-LT); Timestamp appends an RFC 3161 document timestamp (/DocTimeStamp, PAdES-B-LTA).

// B-LT: embed validation material (caller supplies DER certs/CRLs)
Lt := Pdf.AddDss(Signed, [CertDer], [CrlDer]);

// B-LTA: add a document timestamp signed by a TSA key/cert
Lta := Pdf.Timestamp(Lt, TsaKeyDer, TsaCertDer);

Network timestamp (PAdES AD-RT)

To stamp with a real network TSA instead of a local key, the binding exposes a transport-agnostic flow: you do the HTTP POST, the library handles the PDF and RFC 3161 plumbing. Phase 1 prepares the document; build a TSA request, POST it, extract the token, then embed it.

var
  Session: TTimestampSession;
  Imprint, Req, Resp, Token, Lta: TBytes;
begin
  Session := Pdf.BeginTimestamp(Signed);
  Imprint := Sha256(Session.Tbs);                  // hash the bytes the timestamp covers
  Req := Pdf.TimestampRequest(Imprint);            // RFC 3161 TimeStampReq (DER)
  Resp := HttpPost('https://freetsa.org/tsr', Req, 'application/timestamp-query');
  Token := Pdf.TimestampTokenFromResponse(Resp);   // extract the TimeStampToken
  Lta := Pdf.CompleteSignature(Session.Document, Token);
end;

Free public TSAs work: FreeTSA (https://freetsa.org/tsr) and DigiCert (http://timestamp.digicert.com). The integrator performs the HTTP POST; the binding builds the request and embeds the returned token.

Validate signatures licensed

Validate every signature in a PDF: each report recomputes the /ByteRange digest, parses the CMS, and checks that the cryptographic signature is valid, that the messageDigest matches the covered bytes, and whether the signature covers the whole document.

Object Pascal ships no bundled JSON parser, so the binding returns the report as the raw JSON array text: VerifySignaturesJson gives back the verbatim JSON string (a UTF8String) for you to parse with your preferred JSON unit. The string '[]' means the document is unsigned. Signature validation is a licensed feature: this call requires an active license (signatures) even when the document is unsigned. It is not available on the free tier.

Each array entry is an object with field_name, sub_filter, signer, covers_whole_document, digest_valid, signature_valid, is_valid and byte_range. Each report now also carries the signer-certificate detail: issuer, serial_number, valid_from, valid_to, algorithm (e.g. SHA256withRSA), signing_time, cert_count and has_timestamp. field_name and signer may be empty, and any of the certificate fields may be null, when absent.

var Json: UTF8String;
…
Data := ...;   // TBytes of contract.signed.pdf
Json := Pdf.VerifySignaturesJson(Data);
if Json = '[]' then
  Writeln('document is unsigned')
else
  Writeln(string(Json));   // hand the JSON to your parser of choice

Text & image extraction

Extract a document's text, mapping shown glyph codes back to Unicode through each font's ToUnicode map, with space/line inference. ExtractPageText does the same for a single page (0-based), raising ERustPdf (psInvalidArgument) if the page is out of range. Raster images can be pulled out too: JPEGs are written verbatim as .jpg, everything else as .png. The output directory is created automatically if it does not already exist. ExtractImagesToDir returns how many images were written.

var N: NativeUInt;
…
Data := ...;   // TBytes of report.pdf
Writeln(Pdf.ExtractText(Data));
Writeln(Pdf.ExtractPageText(Data, 0));   // just the first page

N := Pdf.ExtractImagesToDir(Data, 'out_images/');   // count of images written
Writeln(Format('wrote %d image(s)', [Int64(N)]));

Positional text search free

Find every occurrence of a query string and get back each match with its bounding box, so you can highlight, redact or link the located text. FindText returns a TTextHits array of TTextHit records; the search is case-insensitive unless you pass CaseSensitive := True. See the PDF text search concept page for background.

Each TTextHit carries Page (0-based), Text, and X, Y, Width, Height in PDF points with the box origin at the lower-left corner.

var
  Hits: TTextHits;
  Hit: TTextHit;
begin
  Data := ...;   // TBytes of report.pdf
  Hits := Pdf.FindText(Data, 'Invoice');
  for Hit in Hits do
    Writeln(Format('page %d  "%s"  [%.1f %.1f %.1f %.1f]',
      [Hit.Page, Hit.Text, Hit.X, Hit.Y, Hit.Width, Hit.Height]));
end;

Page geometry free

Read each page's size, rotation and boxes without modifying the file. Width/Height ignore /Rotate; RotatedWidth/RotatedHeight are the dimensions a viewer actually shows. Sizes are in PDF points (72 per inch).

Each TPageGeometry has Page (0-based), Width, Height, Rotation (0/90/180/270), RotatedWidth, RotatedHeight, and the MediaBox/CropBox as a TPdfRect (X0, Y0, X1, Y1 with Width/Height methods).

var Data: TBytes;
    G: TPageGeometry;
begin
  Data := TFile.ReadAllBytes('report.pdf');
  G := Pdf.MeasurePage(Data, 0);
  WriteLn(Format('page %d: %.1f x %.1f pt, rotate %d', [G.Page, G.Width, G.Height, G.Rotation]));
  WriteLn(Format('visible: %.1f x %.1f pt', [G.RotatedWidth, G.RotatedHeight]));
end;

Document inspection free

Get a non-mutating overview of a PDF, its version, PDF/A level (if any) and encryption posture, without decrypting or rewriting it. Handy for triage before deciding how to process a file.

TPdfOverview carries Version (e.g. '1.7'), PdfaLevel (e.g. '2b', or empty if not PDF/A), Encrypted, Encryption ('None', 'RC4', 'AES-128' or 'AES-256'), RequiresPassword, and PageCount.

var O: TPdfOverview;
begin
  O := Pdf.Inspect(TFile.ReadAllBytes('report.pdf'));
  WriteLn(Format('PDF %s, %d page(s)', [O.Version, O.PageCount]));
  WriteLn(Format('PDF/A: %s, encryption: %s', [O.PdfaLevel, O.Encryption]));
  if O.RequiresPassword then WriteLn('needs a password to open');
end;

Render a page to an image licensed

Rasterize a page to a PNG image. A native Rust renderer (built on tiny-skia, with no headless browser) interprets the page content stream, painting real glyph outlines, vector graphics, images, color and transparency. Page rendering is a Pro feature; page_count is free.

Data := ReadBytes('report.pdf');
WriteLn(Pdf.PageCount(Data), ' page(s)');
Png := Pdf.RenderPageToPng(Data, 0, 150.0);
WriteBytes('page1.png', Png);

Enums

TPdfaLevel

TPdfAlign

TVerticalAnchor

TVerticalAlign

TStampSpace

TImageAnchor

TAFRelationship

TEncryption

TFacturxProfile

Error handling

Every failing native call raises ERustPdf (a Exception) carrying the Status (a TPdfStatus) and the library's last-error message. License failures (missing/expired/forged token, or a feature the token doesn't grant) surface here too. Token activation failures carry the dedicated license status code (12); a gated build, sign or encrypt call instead reports that operation’s own status (for example Serialize = 4 or Sign = 10) with the same “requires a valid license” message.

try
  Doc.Pdfa.SetInfo('x', '', '', '', '');
  Doc.AddPage;
  Doc.SaveToFile('out.pdf');
except
  on E: ERustPdf do
    Writeln('failed: ', E.Message, ' (status ', Ord(E.Status), ')');
end;

Utilities