Technischer Artikel

PDF-Schriftersetzung in Delphi mit PDFium steuern

Ein Lieferschein, der an einem Windows-Arbeitsplatz erzeugt wurde, nennt Arial in seinem Font-Dictionary, trägt kein Font-Programm und sieht an jedem Arbeitsplatz dort in Ordnung aus. In einem Debian-Container gerastert, zieht dieselbe Datei jedes Glyph aus einer anderen Sans-Serif. Der Text beginnt noch dort, wo er soll, denn die Glyph-Positionen kommen aus dem /Widths-Array, das im PDF liegt, aber die Buchstabenformen ändern sich, der Abstand wirkt ungleichmäßig, wo die Konturen des Ersatzes schmaler sind als die Breiten, in denen sie sitzen, und ein Zeichen, das der Ersatz nicht hat, hinterlässt ein Loch. Der Renderer ist nicht schuld. Das Dokument hat die Wahl der Schrift demjenigen überlassen, der es rendert, und diese Wahl lässt sich im eigenen Code treffen, indem man Schriftbytes mitliefert, die mit der Anwendung ausgeliefert werden

ISO 32000-1 erlaubt das. Die 14 Standardschriften aus §9.6.2.2 dürfen immer allein namentlich referenziert werden, und jede andere simple Schrift kann un eingebettet bleiben, solange ihr Dictionary und Font-Descriptor (§9.8) Metriken und Flags beschreiben. PDF/A verbietet es rundheraus (ISO 19005-1 §6.3.4 verlangt, dass jedes Font-Programm eingebettet wird), was eine Menge darüber sagt, wie verlässlich Schriften ohne Einbettung sind, sobald eine Datei die Maschine verlässt, die sie geschrieben hat

Eine Delphi-PDF, die eine nicht eingebettete Arial-Schrift nennt, rendert auf drei Maschinen unter dem Standard-Host-Mapper unterschiedlich, aber identisch, sobald PDFium gebündelte Schriftbytes von einem IPdfSystemFontProvider erhält
PDFium fragt Font-Bytes an, wann immer ein Dokument eine Schrift benennt, die es nicht einbettet; der Provider ersetzt die maschinenweise geratene Zuordnung des Host-Mappers durch Bytes, die Sie selbst ausliefern

Warum nicht einfach die Schriften auf dem Server installieren?

Manchmal reicht es, die Schriften zu installieren. In drei häufigen Situationen bricht das weg. Eine Schriftlizenz erlaubt vielleicht die Desktop-Verwendung, aber keine Installation auf einem Server, der Dokumente automatisch rendert. Container-Images werden oft neu gebaut, und eine von Hand hineinkopierte Schrift verschwindet mit dem nächsten Deployment. Regulierte Workflows wollen einen Rendering-Stack, der aus Artefakten unter Versionskontrolle reproduzierbar ist, und ein systemweiter Schriftordner gehört nicht dazu

Es gibt auch einen Mittelweg. TPdfLibraryConfiguration.UserFontPaths, übergeben an ConfigurePdfLibrary, bevor die Bibliothek lädt, sagt PDFiums nativem Mapper, welche Ordner nach Font-Dateien durchsucht werden. Die Liste ersetzt die Plattform-Vorgaben, statt sie zu ergänzen, und unter Windows schaltet sie zusätzlich die GDI-Schrift Enumeration ab, also nehmen Sie den Systemschrift-Ordner auf, wenn Dokumente weiterhin installierte Schriften brauchen. Welcher Datei bei einer Anfrage gewinnt, entscheidet der Mapper weiterhin nach seinen eigenen Trefferregeln. Wenn Sie genau wissen wollen, welche Bytes „Arial, bold, kyrillischer Zeichensatz“ beantworten, muss diese Entscheidung in lesbarem Code leben, und genau das gibt Ihnen ein System-Font-Provider

Einen IPdfSystemFontProvider installieren, bevor PDFium lädt

PDFium Component stellt Schriftzuordnung über ein Interface mit einer Methode bereit. IPdfSystemFontProvider.ResolveFont erhält einen TPdfSystemFontRequest mit FaceName, Weight, Italic, Charset und PitchFamily und antwortet mit einem TPdfSystemFontData-Record, der den Face-Namen, die vollständigen TrueType-, OpenType- oder TrueType-Collection-Bytes, einen Zeichensatz und einen TTCIndex hält. Die Rückgabe von False lehnt die Anfrage ab

ConfigureSystemFontProvider muss laufen, bevor die Bibliothek geladen ist. PDFium nimmt seinen Font-Mapper genau einmal, während der Initialisierung, daher wirft die Komponente EPdfError („Configure the system font provider before loading PDFium“), wenn Loaded bereits true ist. Viele Aufrufe laden die Bibliothek bei Bedarf, auch die Feature-Prüfungen, also setzen Sie die Konfiguration ganz an den Anfang des Startvorgangs. Der Provider unten baut eine Lookup-Tabelle und liest jede Font-Datei in seinem Konstruktor; danach liest ResolveFont nur noch:

uses
  System.SysUtils, System.Classes, System.IOUtils, PDFium;

type
  TBundledFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
  private
    FKeys: TStringList;           // im Konstruktor einmal sortiert, danach nur lesend
    FFonts: array of TBytes;
    FFaces: array of WString;
    class function KeyFor(const Face: string; Bold, Italic: Boolean): string; static;
    procedure AddFont(const Face: string; Bold, Italic: Boolean;
      const ReportedFace, FileName, FontDir: string);
  public
    constructor Create(const FontDir: string);
    destructor Destroy; override;
    function ResolveFont(const Request: TPdfSystemFontRequest;
      out Font: TPdfSystemFontData): Boolean;
  end;

class function TBundledFontProvider.KeyFor(const Face: string;
  Bold, Italic: Boolean): string;
begin
  Result := LowerCase(Face) + '|' + IntToStr(Ord(Bold)) + IntToStr(Ord(Italic));
end;

procedure TBundledFontProvider.AddFont(const Face: string; Bold, Italic: Boolean;
  const ReportedFace, FileName, FontDir: string);
var
  I: Integer;
begin
  I := Length(FFonts);
  SetLength(FFonts, I + 1);
  SetLength(FFaces, I + 1);
  FFonts[I] := TFile.ReadAllBytes(TPath.Combine(FontDir, FileName));
  FFaces[I] := WString(ReportedFace);
  FKeys.AddObject(KeyFor(Face, Bold, Italic), TObject(NativeInt(I)));
end;

constructor TBundledFontProvider.Create(const FontDir: string);
begin
  inherited Create;
  FKeys := TStringList.Create;
  FKeys.Sorted := True;
  FKeys.Duplicates := dupError;
  AddFont('Arial', False, False, 'Arial', 'arial.ttf', FontDir);
  AddFont('Arial', True,  False, 'Arial', 'arialbd.ttf', FontDir);
  // Ein Alias: die tatsächlich gelieferte Familie melden, damit die Policy sie sieht
  AddFont('Helvetica', False, False, 'Arial', 'arial.ttf', FontDir);
end;

destructor TBundledFontProvider.Destroy;
begin
  FKeys.Free;
  inherited;
end;

function TBundledFontProvider.ResolveFont(const Request: TPdfSystemFontRequest;
  out Font: TPdfSystemFontData): Boolean;
var
  Index: Integer;
begin
  Font := Default(TPdfSystemFontData);
  Result := FKeys.Find(KeyFor(string(Request.FaceName),
    Request.Weight >= 600, Request.Italic), Index);   // ab 600 als bold geliefert
  if not Result then
    Exit;
  Index := Integer(NativeInt(FKeys.Objects[Index]));
  Font.FaceName := FFaces[Index];
  Font.FontData := FFonts[Index];
  Font.Charset := Request.Charset;
  Font.TTCIndex := 0;                // Face-Nummer innerhalb einer .ttc-Collection
end;

procedure ConfigureFonts(const FontDir: string; Audit: Boolean);
var
  Policy: TPdfSystemFontPolicy;
begin
  Policy := TPdfSystemFontPolicy.Default;
  Policy.AllowDefaultFallback := not Audit;
  Policy.AllowFaceSubstitution := not Audit;
  Policy.MaxFontBytes := 32 * 1024 * 1024;
  Policy.MaxCacheEntries := 64;
  ConfigureSystemFontProvider(TBundledFontProvider.Create(FontDir), Policy);
  // Erst jetzt Dokumente öffnen; der erste Aufruf, der PDFium braucht, lädt es
end;

Die Tabellenschlüssel in diesem Sample sind bewusst naiv. Echte Dokumente schreiben dieselbe Familie auf mehrere Arten, also loggen Sie Request.FaceName aus einem repräsentativen Batch, bevor Sie die Tabelle einfrieren; der Recording-Wrapper weiter unten erzeugt genau diese Liste. Die Gewichtsschwelle ist ebenfalls eine Entscheidung: FXFONT_FW_NORMAL ist 400 und FXFONT_FW_BOLD ist 700 in der Unit FPdfExtensions, und eine Semibold-Anfrage mit 600 muss auf die eine oder andere Seite fallen

Was die Policy-Flags tatsächlich entscheiden

Jede Anfrage läuft in derselben Reihenfolge. Die Komponente prüft zuerst ihren Cache, ruft dann Ihren Provider auf und validiert dann die Antwort. Eine akzeptierte Antwort wird zwischengespeichert und an PDFium gereicht. Eine abgelehnte oder verworfene Antwort geht an den Plattform-Mapper aus FPDF_GetDefaultSystemFontInfo, aber nur wenn AllowDefaultFallback an ist; sonst zählt die Anfrage als fehlgeschlagen, und PDFium macht ohne Ihre Schrift weiter

Die Validierung selbst ist kurz. Leere FontData werden abgewiesen, und alles, was länger ist als MaxFontBytes, ebenfalls. Ein leerer FaceName in der Antwort wird mit dem angeforderten Namen aufgefüllt. Bei ausgeschaltetem AllowFaceSubstitution wird auch ein gemeldeter Face-Name, der vom angeforderten abweicht (Groß-/Kleinschreibung egal), abgewiesen. Diese Prüfung liest nur den Namen, den Sie melden, und sonst nichts. Ein Provider, der Liberation-Sans-Bytes liefert, während er „Arial“ meldet, kommt durch, weshalb das Sample für seinen Helvetica-Alias die echte Familie meldet: Mit ausgeschaltetem Flag wird eine Helvetica-Anfrage, die mit „Arial“ beantwortet wird, abgewiesen und landet in RejectedProviderResponses

PDFium-Component-Validierungstore prüfen leere Daten, MaxFontBytes-Größe und Face-Substitution, bevor Bytes PDFium erreichen; AllowDefaultFallback entscheidet zwischen Host-Fallback und abgewiesener Anfrage
Validierung läuft innerhalb der Komponente, bevor irgendeine Provider-Bytes PDFium erreichen; mit ausgeschaltetem Fallback zählt eine nicht gemappte Anfrage einmal in FailedRequests, und PDFium zeichnet den Text mit seiner eingebauten Ersatzschrift

Der TTC-Index wird an anderer Stelle geprüft. PDFium fragt oft eine sfnt-Tabelle nach der anderen ab, etwa cmap oder glyf, und die Komponente beantwortet diese Abfragen, indem sie das Tabellenverzeichnis der von Ihnen zurückgegebenen Bytes durchläuft. Bei einer Collection startet sie vom Verzeichnis, das TTCIndex wählt; ein Index hinter der Schriftzahl im ttcf-Header oder ein von null verschiedener Index auf einer Einzelschrift-Datei lässt diese Tabellenabfragen leer ausgehen. Der Verzeichnisgang erkennt TrueType (0x00010000 und true), OpenType mit CFF-Konturen (OTTO) und Collections (ttcf). WOFF- und WOFF2-Dateien müssen in schlichtes sfnt entpackt werden, bevor der Provider sie zurückgibt

TPdfSystemFontPolicy.Default schaltet beide Flags an, mit einer Deckelung von 64 MB pro Schrift und 32 Cache-Einträgen. Das passt zu einem Provider, der nach und nach ein paar Familien dazu bekommt, bei dem alles noch Unmapped so weiterrendert wie bisher. Ein Audit-Build sollte beide Flags abschalten. Lücken zeigen sich dann als gezählte Fehlschläge und abgewiesene Substitutionen, und ein Fallback-Treffer kann keine Familie mehr verstecken, die das Schriftset vergessen hat

Welcher Thread ruft ResolveFont auf?

ResolveFont läuft auf dem Thread, der die Seite lädt oder rendert, die die Schrift braucht, also nicht zwangsläufig auf dem Hauptthread. Die Komponente sichert ihren eigenen Cache und ihre Zähler mit einer Critical Section ab, hält dieses Lock aber nicht, während Ihre Methode läuft. Rendert Ihre Anwendung auf Background-Threads, braucht jeder Zustand, den der Provider nach der Konstruktion ändert, einen eigenen Schutz

Exceptions sind das Zweite, was innerhalb der Methode bleiben sollte. Die Komponente fängt alles, was aus ResolveFont entweicht, an der Grenze zur nativen Bibliothek ab und behandelt es als abgelehnte Anfrage, sodass die Anfrage zu Fallback oder Fehlschlag weiterläuft. Sich darauf zu verlassen macht aus einem Bug in Ihrem Mapping-Code eine Schrift, die stillschweigend von jemand anderem geliefert wird. Der Wrapper unten zeichnet jeden Miss unter einem Lock auf und hält Exceptions lokal, was Ihnen auch gleich die Liste der Face-Namen liefert, die in die Tabelle sollen:

uses
  System.SysUtils, System.Classes, System.SyncObjs, PDFium;

type
  TRecordingFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
  private
    FInner: IPdfSystemFontProvider;
    FLock: TCriticalSection;
    FMisses: TStringList;
  public
    constructor Create(const Inner: IPdfSystemFontProvider);
    destructor Destroy; override;
    function ResolveFont(const Request: TPdfSystemFontRequest;
      out Font: TPdfSystemFontData): Boolean;
    function MissedFaces: string;
  end;

constructor TRecordingFontProvider.Create(const Inner: IPdfSystemFontProvider);
begin
  inherited Create;
  FInner := Inner;
  FLock := TCriticalSection.Create;
  FMisses := TStringList.Create;
  FMisses.Sorted := True;
  FMisses.Duplicates := dupIgnore;
end;

destructor TRecordingFontProvider.Destroy;
begin
  FMisses.Free;
  FLock.Free;
  inherited;
end;

function TRecordingFontProvider.ResolveFont(const Request: TPdfSystemFontRequest;
  out Font: TPdfSystemFontData): Boolean;
begin
  try
    Result := FInner.ResolveFont(Request, Font);
  except
    Result := False;            // hier loggen; nicht bis PDFium durchlassen
  end;
  if Result then
    Exit;
  FLock.Enter;
  try
    FMisses.Add(Format('%s weight=%d italic=%s charset=%d pitch=%d',
      [string(Request.FaceName), Request.Weight,
       BoolToStr(Request.Italic, True), Request.Charset, Request.PitchFamily]));
  finally
    FLock.Leave;
  end;
end;

function TRecordingFontProvider.MissedFaces: string;
begin
  FLock.Enter;
  try
    Result := FMisses.Text;
  finally
    FLock.Leave;
  end;
end;

Halten Sie den Recorder über eine Interface-Variable ebenso wie über die Objektvariable. Die Komponente hält ihre eigene Interface-Referenz, und ClearSystemFontProvider gibt sie ab; war das die letzte Referenz, geht das Objekt mit, und eine schlichte Klassenvariable zeigt auf freigegebenen Speicher. Um vor jedem Rendering herauszufinden, welche Schriften ein Dokument referenziert, listet der Inspektionsweg in Analyse von PDF-Schrifteigenschaften eingebettete und nicht eingebettete Schriften nebeneinander auf

Die Schrift-Cache-Größe bemessen

Zuordnungsanfragen wiederholen sich während des Renderns ständig, daher werden akzeptierte Antworten zwischengespeichert. Der Cache-Schlüssel deckt Face-Name (ohne Groß-/Kleinschreibung), Gewicht, Kursiv-Flag, Zeichensatz und Rasterfamilie ab, und bei erreichter MaxCacheEntries-Grenze wird der am längsten unbenutzte Eintrag verdrängt. Ein Wert von 0 schaltet das Caching ab, sodass jede Anfrage Ihren Provider erreicht und erneut validiert wird. Ein negativer Wert oder ein MaxFontBytes von null oder weniger lässt ConfigureSystemFontProvider „Invalid system font provider policy“ werfen

Eintragszahlen sagen wenig über den Speicher aus, wenn eine einzelne CJK-Collection über 20 MB laufen kann. Für ein Byte-Budget hängt ConfigureSystemFontCacheGovernor einen TPdfCacheGovernor aus der Unit FPdfCache an, erzeugt mit einer maximalen Byte-Zahl und geteilt mit den anderen Caches der Komponente. Auch das muss vor dem Laden der Bibliothek gesetzt werden. Jeder Cache-Eintrag wird mit der vollen Länge seiner Font-Daten belastet, sodass eine 20-MB-Collection, die Anfragen für vier verschiedene Zeichensätze beantwortet, vierfach gegen das Budget zählt, selbst wenn Ihr Provider jedes Mal dasselbe Array zurückgibt. Verweigert der Governor eine Reservierung, wird die Schrift trotzdem geliefert, nur eben nicht gecacht. Halten Sie das Governor-Objekt am Leben, bis UnloadLibrary gelaufen ist, denn die Cache-Einträge halten Reservierungen gegen es

Die Zuordnung im Produktivbetrieb nachweisen

GetSystemFontProviderStatistics gibt einen TPdfSystemFontStatistics-Record zurück. Configured und Installed sagen, ob ein Provider gesetzt ist und ob er an PDFium übergeben wurde. MapRequests zählt jede Zuordnungsanfrage, und CacheHits, ProviderHits und DefaultFallbackHits zeigen, wie sie beantwortet wurden. FailedRequests zählt die Anfragen, die nichts beantwortet hat, und RejectedProviderResponses die Antworten, die die Policy verworfen hat. Die übrigen Felder verfolgen Tabellen-ebene Reads (FontDataRequests), lebende Font-Handles, gecachte Schriften, gecachte Bytes und Verdrängungen

GetSystemFontProviderStatistics teilt PDFium-Schriftmapping-Anfragen in Cache-, Provider- und Fallback-Treffer in einem Delphi-Konformitätslauf, der wirft, sobald DefaultFallbackHits oder FailedRequests auftauchen
Der Statistik-Record macht aus Schriftersetzung etwas, worauf ein Konformitätslauf Behauptungen stellen kann; jeder Fallback oder fehlgeschlagene Aufruf heißt, das Dokument brauchte eine Schrift, die das Set nicht mitbringt

Ein Konformitätslauf liest die Zähler nach dem Batch und entlädt dann. UnloadLibrary koppelt den Provider von PDFium ab, gibt den Plattform-Mapper frei und leert den Cache, bevor es PDFium herunterfährt, und es weigert sich zu laufen, solange Dokumente noch offen sind. ClearSystemFontProvider kommt zuletzt; es wirft, wenn PDFium noch geladen ist, und es setzt die Zähler zurück, also lesen Sie sie zuerst:

var
  Recorder: TRecordingFontProvider;
  RecorderRef: IPdfSystemFontProvider;   // hält das Objekt am Leben
  Policy: TPdfSystemFontPolicy;
  Stats: TPdfSystemFontStatistics;
begin
  Recorder := TRecordingFontProvider.Create(TBundledFontProvider.Create(FontDir));
  RecorderRef := Recorder;
  Policy := TPdfSystemFontPolicy.Default;
  Policy.AllowDefaultFallback := False;
  Policy.AllowFaceSubstitution := False;
  ConfigureSystemFontProvider(RecorderRef, Policy);

  // FontDir, SampleFiles und RenderCorpus sind eigene; der Batch muss
  // jedes geöffnete Dokument schließen, bevor UnloadLibrary läuft
  RenderCorpus(SampleFiles);

  Stats := GetSystemFontProviderStatistics;
  Writeln(Format('requests=%d cache=%d provider=%d fallback=%d',
    [Stats.MapRequests, Stats.CacheHits, Stats.ProviderHits,
     Stats.DefaultFallbackHits]));
  Writeln(Format('rejected=%d failed=%d evictions=%d cachedBytes=%d',
    [Stats.RejectedProviderResponses, Stats.FailedRequests,
     Stats.CacheEvictions, Stats.CachedFontBytes]));

  UnloadLibrary;               // koppelt den Provider ab, fährt dann PDFium herunter
  ClearSystemFontProvider;     // erlaubt erst, sobald PDFium entladen ist

  if (Stats.FailedRequests > 0) or (Stats.RejectedProviderResponses > 0) then
    raise Exception.Create('Font set incomplete:' + sLineBreak +
      Recorder.MissedFaces);
end;

Mit ausgeschaltetem Fallback bleibt DefaultFallbackHits auf null, und jede Lücke landet in FailedRequests, oft neben RejectedProviderResponses, wenn der Provider zwar geantwortet hat, die Policy aber den Namen oder die Größe verworfen hat. In einem Produktiv-Build mit Fallback wandert dieselbe Lücke in DefaultFallbackHits, und dieser Zähler ist der, den man schärt: Ein Anstieg, nachdem ein neuer Kunde anfängt, Dokumente zu schicken, heißt, dass eine Familie, die Ihr Schriftset nicht abdeckt, jetzt mit dem gerendert wird, was der Host hergibt. Die Threading-Regeln für den Rest der Komponente folgen der separat beschriebenen Render-Lock-Disziplin

Dieselbe Bibliotheksinstanz erledigt Schriftbereitstellung, Rendering und Textextraktion über Delphi, C++Builder und Lazarus hinweg, und die PDFium-Component-für-Delphi-Seite deckt Editionen und das Deployment der nativen Bibliothek ab