THotPDF.UseXRefStream Property

THotPDF.UseXRefStream

Emit a PDF 1.5 /Type /XRef cross-reference stream (ISO 32000-1 7.5.8) instead of the textual xref ... trailer sequence.

Delphi syntax:

property UseXRefStream: Boolean;

C++ syntax:

__property bool UseXRefStream;

Description

When UseXRefStream is true, EndDoc writes a single /Type /XRef indirect stream object instead of the legacy textual xref table + trailer + startxref sequence. Entries use /W [1 4 2]: a one-byte type field, a four-byte offset (or compressed-object host number), and a two-byte generation (or compressed-object index). The whole table is FlateDecode-compressed, typically cutting xref overhead by 4-10x on large documents.

XRef streams are a hard prerequisite for the UseObjectStreams feature: only the binary xref stream can encode the type-2 compressed-object entries that point into /Type /ObjStm containers. Switching UseXRefStream off automatically disables UseObjectStreams at save time.

Default value: false (opt-in - keeps the textual xref table for tooling that hard-codes the xref keyword and for maximum compatibility with PDF 1.4 / earlier readers).

Setting UseXRefStream to true on a document whose Version is below PDF 1.5 is silently ignored at save time - the textual xref is emitted instead.

Code Example

HPDF := THotPDF.Create( nil );
try
  HPDF.FileName := 'c:\Output.pdf';
  HPDF.Version := pdf15;          // Required for XRef streams
  HPDF.UseXRefStream := true;     // Emit /Type /XRef instead of xref table
  HPDF.UseObjectStreams := true;  // Optional: also pack objects into /Type /ObjStm
  HPDF.Compression := cmFlateDecode;
  HPDF.BeginDoc;
  HPDF.CurrentPage.TextOut( 100, 100, 0, 'Compact PDF 1.5 output' );
  HPDF.EndDoc;
finally
  HPDF.Free;
end;