Technischer Artikel

PDFium Library Config: Warum Brotli Skia gegen AGG tauscht

Wer BrotliEnabled oder IsolatePerDocument einschaltet, hebt FPDF_LIBRARY_CONFIG auf eine Version, in der PDFium m_RendererType wörtlich liest; ein Wrapper, der AGG als „default“ einträgt, schaltet einen Skia-Build also stumm auf den AGG-Renderer um, ohne jeden Fehler. In PDFium Component for Delphi lässt TPdfLibraryConfiguration den Default-Renderer beim eigenen Default der DLL, und eine Skia- oder Fontations-Anfrage, die die DLL nicht erfüllen kann, wirft eine abfangbare EPdfError, statt den Prozess zu töten

Die beiden Fallen scheitern auf gegensätzliche Weise. Die erste produziert Seiten, die gut aussehen — nur eben von einem anderen Rasterizer gerendert, mit leicht anderem Anti-Aliasing und leicht anderen Textkanten als in dem Build, den Sie ausgeliefert und getestet haben. Die zweite meldet sich laut, indem sie den Host-Prozess aus der nativen Initialisierung heraus abwürgt. Beide stammen aus derselben Quelle: einer versionierten C-Struktur, deren Felder erst zählen, wenn die Versionsnummer es sagt, und deren Nullwerte nicht „unset“ sind, sondern echte Entscheidungen

Wie entscheidet FPDF_LIBRARY_CONFIG, welchen Renderer PDFium benutzt?

FPDF_InitLibraryWithConfig befragt m_RendererType nur, wenn das Version-Feld der Struktur 4 oder höher ist, und ab dieser Version verwendet es den Wert genau so, wie er geschrieben ist. Unter Version 4 ignoriert PDFium das Feld und nimmt den Build-Default, der in Builds mit PDF_USE_SKIA Skia ist und sonst überall AGG

Jedes spätere Feld folgt demselben Muster. Die Struktur wuchs eine Fähigkeit nach der anderen, und jede Fähigkeit kam zusammen mit einer neuen Versionsnummer. PDFium Component baut die native Struktur in LoadLibrary aus Ihrer TPdfLibraryConfiguration und hebt die Version nur so weit, wie die gesetzten Optionen es verlangen

StrukturversionFeld, das sie hinzufügtGesetzt durch
2m_pIsolate, m_v8EmbedderSlotImmer geschrieben; V8Isolate, V8EmbedderSlot
3m_pPlatformV8Platform nicht nil
4m_RendererTypeRenderer anders als prpDefault
5m_FontLibraryTypeFontBackend anders als pfbpDefault
6m_BrotliEnabledBrotliEnabled = True
7m_IsolatePerDocumentIsolatePerDocument = True

Die Falle sitzt in den letzten zwei Zeilen. Versionen sind kumulativ: Eine Version-6-Struktur ist auch eine Version-4- und eine Version-5-Struktur, PDFium liest also m_RendererType und m_FontLibraryType, obwohl Sie nur nach Brotli gefragt haben. Was auch immer in diesen zwei Feldern gerade steht, wird zum Renderer und Font-Backend — ob Sie sie wählen wollten oder nicht

PDFium Component FPDF_LIBRARY_CONFIG-Versionstreppe von Version 2 bis Version 7, die zeigt, welche TPdfLibraryConfiguration-Option m_RendererType, m_FontLibraryType, m_BrotliEnabled und m_IsolatePerDocument hinzufügt, und warum kumulative Versionen ein genulltes Renderer-Feld auf jedem Build zu einer bewussten AGG-Entscheidung machen statt zu einem Unset-Wert
Jede Option hebt die Strukturversion, und jedes frühere Feld bleibt live, die Null in m_RendererType kommt bei PDFium also als explizite AGG-Anfrage an

Warum kann das Einschalten von Brotli den Renderer auf AGG umstellen?

Die naheliegende Abbildung schreibt für prpDefault FPDF_RENDERERTYPE_AGG in m_RendererType, und dann zwingt jede Konfiguration, die die Struktur auf Version 6 oder 7 hebt, einem Skia-Build AGG auf. Die pdfium.dll- und pdfium.v8.dll-Runtimes, die mit der Komponente kommen, sind Skia-Builds, diese Abbildung träfe also das Default-Deployment, nicht irgendein exotisches

Die Abbildung sieht harmlos aus. Bei Version 2 oder 3 wird das Feld nie gelesen, prpDefault bedeutet also wirklich „was die DLL eben tut“. Sobald BrotliEnabled (Version 6) oder IsolatePerDocument (Version 7) ins Spiel kommt, macht derselbe Code aus „keine Präferenz“ eine explizite AGG-Anfrage. Nichts scheitert. PDFium initialisiert normal, rendert jede Seite und liefert keinen Fehlercode, denn aus seiner Sicht hat der Aufrufer nach AGG gefragt und AGG bekommen

Ein Pixel-Hash macht den Tausch dort sichtbar, wo Screenshots versagen. Das Rendern der ersten Seite desselben Beispieldokuments unter drei Konfigurationen ergibt:

  • Default-Konfiguration: Hash 502D77C3711B4ACF
  • BrotliEnabled = True mit prpDefault als FPDF_RENDERERTYPE_AGG geschrieben: Hash F75B5EB4728ADE87
  • Explizites prpAgg: Hash F75B5EB4728ADE87, identisch zum Brotli-Lauf

PDFium Component löst das über die öffentliche Funktion PdfNativeRendererType, die eine TPdfRendererPreference auf den Wert auflöst, der in m_RendererType landet. prpAgg und prpSkia mappen eins zu eins. prpDefault mappt auf Skia, wenn die geladene DLL FPDF_RenderPageSkia exportiert, und sonst auf AGG. Dieser Export wird unter derselben PDF_USE_SKIA-Bedingung kompiliert wie der Skia-Default selbst, er ist also die eine Build-Eigenschaft, die man von außerhalb der DLL beobachten kann. Mit dieser Auflösung produziert die Brotli-Konfiguration denselben Hash wie die Default-Konfiguration

PDFium Component Pixel-Hash-Vergleich: der Default-Skia-Render-Hash 502D77C3711B4ACF, eine BrotliEnabled-Konfiguration mit prpDefault als AGG, die einem expliziten prpAgg-Lauf mit Hash F75B5EB4728ADE87 entspricht, und PdfNativeRendererType, das prpDefault über den FPDF_RenderPageSkia-Export zurück zum ursprünglichen Skia-Hash auflöst
Ein Pixel-Hash erwischt, was Screenshots verbergen: Mit dem Default als AGG geschrieben rendert Brotli jede Seite mit AGG, während der aufgelöste Default zur unangetasteten Konfiguration passt

Das Font-Backend hat das Problem nicht. m_FontLibraryType wird ab Version 5 gelesen, und sein Nullwert, FPDF_FONTBACKENDTYPE_FREETYPE, ist auch dann PDFiums Default, wenn das Feld gar nicht gelesen wird. FreeType für pfbpDefault zu schreiben reproduziert den nativen Default also exakt. Nullwerte sind nicht immer falsch, sie sind nur nie automatisch richtig

Der Startup-Code, den man natürlich schreiben würde, tut, was er sagt:

uses
  PDFium;

procedure ConfigurePdfiumAtStartup;
var
  Config: TPdfLibraryConfiguration;
begin
  // Muss laufen, bevor irgendetwas die native Bibliothek lädt
  Config := TPdfLibraryConfiguration.Default;
  Config.BrotliEnabled := True;   // hebt FPDF_LIBRARY_CONFIG auf Version 6
  // Renderer bleibt prpDefault: aufgelöst zu Skia auf Builds, die
  // FPDF_RenderPageSkia exportieren, sonst zu AGG auf AGG-only-Builds
  // UserFontPaths ersetzt die Plattform-Font-Ordner, also auch den
  // Windows-Font-Ordner listen, wenn Dokumente Systemfonts finden sollen
  SetLength(Config.UserFontPaths, 2);
  Config.UserFontPaths[0] := 'C:\ProgramData\MyApp\Fonts';
  Config.UserFontPaths[1] := 'C:\Windows\Fonts';
  ConfigurePdfLibrary(Config);
end;

UserFontPaths ist eine Ersetzungsliste, kein Zusatz. Sobald sie mindestens einen Ordner hält, scannt PDFium nur diese Ordner und wirft die Plattform-Defaults weg: /usr/share/fonts und Freunde unter Linux, die drei Library/Fonts-Ordner unter macOS. Unter Windows ist die Änderung größer als ein Pfadtausch, denn PDFium hört auf, installierte Fonts über GDI zu enumerieren, und liest die Fontdateien stattdessen aus den gelisteten Ordnern. Eine Liste, die nur den Anwendungsordner nennt, überlässt also jedes Dokument, das auf Arial oder Times New Roman baut, der Substitution — deshalb ergänzt das Beispiel den Windows-Font-Ordner (in echtem Code mit GetWindowsDirectory auflösen, nicht das Laufwerk hart kodieren)

Denken Sie daran, dass BrotliEnabled PDF-2.0-/BrotliDecode-Streams nur dann dekodierbar macht, wenn die DLL selbst mit PDF_ENABLE_BROTLI gebaut wurde. Das Flag ist eine Anfrage, auf einem Build ohne Brotli-Unterstützung wirkt es nicht. TPdfLibraryConfiguration.Hardened ist dasselbe wie Default, nur mit AllowMachineTime = False, was Dokument-JavaScript das Lesen der echten Uhr verwehrt; ein vernünftiger Startpunkt für serverseitige Verarbeitung nicht vertrauenswürdiger Dateien

Was passiert, wenn man ein Backend anfragt, das die DLL nicht enthält?

PDFium liefert keinen Fehler für einen Renderer oder Font-Backend, der im Build fehlt: FPDF_InitLibraryWithConfig scheitert an einem nativen CHECK, der sich unter Windows als Breakpoint-Exception äußert und ohne strukturierten Exception-Handler um den Aufruf den Prozess beendet. Der Header sagt es explizit und warnt, dass ein nicht unterstützter Wert „will similarly fail with an immediate crash“

Die zwei konkreten Fälle: ein AGG-only-Build, der FPDF_RENDERERTYPE_SKIA bekommt, und ein Build ohne Fontations, der FPDF_FONTBACKENDTYPE_FONTATIONS bekommt. Die mitgelieferte Skia-Runtime gehört zur zweiten Gruppe: Sie rendert mit Skia, nutzt aber FreeType für Fonts. Die Anfrage von prpSkia zusammen mit pfbpFontations gegen sie produzierte auf Delphi-Seite eine External exception 80000003. Und wenn Debugger oder Exception-Handler sie zufällig fangen, ist die Lage trotzdem unwiederbringlich:

  • PDFium bleibt halb initialisiert zurück
  • Die prozessweite Konfiguration ist bereits versiegelt, ConfigurePdfLibrary lehnt also eine korrigierte Konfiguration ab
  • Ein Wiederholungsversuch mit anderer Konfiguration im selben Prozess ist nicht mehr möglich

Das ist das Gegenstück zum Brotli-Tausch. Dort hielt das Feld einen Wert, den niemand gewählt hatte, und PDFium nahm ihn still hin. Hier hält das Feld einen Wert, den der Aufrufer bewusst gewählt hat, und PDFium lässt darüber keine Diskussion zu. Beides sind Probleme, die ein Wrapper vor dem nativen Aufruf lösen muss, denn danach bleibt nichts mehr zum Abfangen übrig

Wie PDFium Component Skia und Fontations vorprüft

LoadLibrary validiert die Konfiguration, nachdem die DLL-Exporte gebunden sind und bevor FPDF_InitLibraryWithConfig aufgerufen wird, und macht aus einem nicht unterstützten Renderer oder Font-Backend eine EPdfError mit einer Meldung, die die betroffene Einstellung und die Alternativen nennt. Die DLL wird entladen und die Konfiguration entsiegelt, der Aufrufer kann also andere Einstellungen wählen und erneut laden

Die Entscheidung selbst wohnt in der reinen Funktion PdfLibraryConfigurationSupportError, die die Konfiguration plus zwei Booleans nimmt, die den Build beschreiben, und einen leeren String zurückgibt, wenn die Kombination sicher ist. Weil sie keinen nativen Zustand anfasst, kann man sie aus eigenen Tests mit jeder Fähigkeitskombination aufrufen. Innerhalb von LoadLibrary kommen die zwei Booleans aus unterschiedlichen Beweisarten, und sie verdienen unterschiedliches Vertrauen:

  • Skia wird über das Vorhandensein des FPDF_RenderPageSkia-Exports erkannt, dasselbe Signal, das PdfNativeRendererType benutzt. Export und Skia-Renderer werden unter einer Bedingung kompiliert, der Check ist also exakt
  • Fontations hat keinen eigenen Export. Seine einzige Spur sind die Rust-Font-Crates, die es in die Binärdatei zieht; PDFium Component durchsucht deshalb die geladene Bibliotheksdatei nach den Crate-Namen skrifa und read-fonts (auch read_fonts). Der Scan läuft nur, wenn pfbpFontations angefragt wird, und eine nicht lesbare Datei zählt als „kein Fontations“

Der Fontations-Check ist eine Heuristik und kann in eine Richtung falsch liegen: Ein Fontations-Build, dem jeder dieser Strings ausgestrieben wurde, würde abgelehnt, obwohl er funktionieren könnte. Dieser Trade war bewusst. Eine falsche Ablehnung kostet Sie eine Exception, die Sie abfangen können, und einen Rückfall auf FreeType. Eine falsche Annahme kostet Sie den Prozess

Das Entsieeln zählt so viel wie der Check. LoadLibrary versiegelt die Konfiguration ganz am Anfang des Ladens; ohne das Zurücksetzen würde eine Fähigkeitsablehnung ConfigurePdfLibrary jeden Wiederholungsversuch mit EPdfError „PDFium library configuration is already sealed“ beantworten lassen. Der Ablehnungspfad ruft zuerst UnloadLibrary; sein FPDF_DestroyLibrary-Aufruf ist an der Stelle sicher, weil PDFium noch nicht initialisiert ist und sofort zurückkehrt. Andere Ladefehler, etwa eine fehlende DLL oder ein Architektur-Mismatch, behalten die Versiegelung, eine Retry-Schleife muss also beide auseinanderhalten:

uses
  SysUtils, PDFium;

function StartPdfiumPreferringSkia: TPdfRendererPreference;
var
  Config: TPdfLibraryConfiguration;
begin
  Config := TPdfLibraryConfiguration.Default;
  Config.Renderer := prpSkia;
  ConfigurePdfLibrary(Config);
  try
    PDFium.LoadLibrary;   // unit-qualifiziert: Windows.LoadLibrary trägt denselben Namen
    Result := prpSkia;
  except
    on E: EPdfError do
    begin
      // Eine Fähigkeitsablehnung entlädt die DLL und entsiegelt die Konfiguration.
      // Eine DLL, die gar nicht erst lud, bleibt versiegelt: Retrying hilft nicht
      if PdfLibraryConfigurationSealed then
        raise;
      Config.Renderer := prpAgg;
      ConfigurePdfLibrary(Config);
      PDFium.LoadLibrary;
      Result := prpAgg;
    end;
  end;
end;

Beachten Sie das explizite PDFium.LoadLibrary. In einer Unit, die auch Windows oder Winapi.Windows benutzt, löst ein unqualifiziertes LoadLibrary zu der Unit auf, die in der uses-Klausel zuletzt steht; ist das die Win32-Funktion, scheitert der parameterlose Aufruf bereits am Compiler mit einer Fehlermeldung zur Argumentanzahl, die nichts über PDFium verrät

PDFium Component LoadLibrary-Vorprüfungsfluss: ConfigurePdfLibrary versiegelt die Konfiguration, der Fähigkeitscheck prüft den FPDF_RenderPageSkia-Export und die skrifa-String-Evidenz, eine nicht unterstützte Anfrage wirft eine abfangbare EPdfError und entsiegelt für den Wiederholungsversuch, während eine DLL, die nie lädt, PdfLibraryConfigurationSealed true lässt
Die Validierung läuft nach dem Binden der Exporte und vor der Initialisierung, ein fehlendes Backend scheitert also als abfangbare EPdfError statt als nativer CHECK, der den Prozess tötet

Validierung, die noch früher passiert

ConfigurePdfLibrary lehnt manche Kombinationen ab, bevor irgendeine DLL im Spiel ist, alles mit EPdfError. Ein explizites FontBackend, eingeschlossen pfbpFreeType, verlangt Renderer = prpSkia, denn PDFium befragt das Font-Backend nur für den Skia-Renderer. IsolatePerDocument verlangt V8Isolate = nil, da PDFium seinen eigenen Isolate pro Dokument erzeugt und bei einem mitgelieferten an einem nativen CHECK scheitert. Leere Strings in UserFontPaths werden abgelehnt. Und jeder Aufruf nach dem ersten Ladeversuch scheitert mit „PDFium library configuration is already sealed“

Diese letzte Regel hat eine praktische Konsequenz: Sie können die DLL nicht erst sondieren und sie danach konfigurieren. GetSkiaRenderCapabilities, V8FeaturesAvailable, das Öffnen eines Dokuments und die meisten anderen Einstiegspunkte rufen intern LoadLibrary auf, was die Konfiguration auf der Stelle versiegelt. Ein späteres UnloadLibrary öffnet sie ebenfalls nicht wieder. Erst konfigurieren, dann laden, dann fragen — genau die Reihenfolge, der eine Diagnostik-Routine folgen sollte:

uses
  SysUtils, PDFium, FPdfView;

function DescribePdfiumState: string;
var
  Config: TPdfLibraryConfiguration;
  Renderer: string;
begin
  Config := GetPdfLibraryConfiguration;   // eine Kopie, gefahrlos zu inspizieren
  if not PDFium.Loaded then
  begin
    if PdfLibraryConfigurationSealed then
      Exit('PDFium failed to load; configuration is sealed');
    Exit('PDFium not loaded; configuration can still change');
  end;
  // Dieselbe Auflösung, die LoadLibrary beim Bau von FPDF_LIBRARY_CONFIG anwandte
  if PdfNativeRendererType(Config.Renderer,
    GetSkiaRenderCapabilities.PageRender) = FPDF_RENDERERTYPE_SKIA then
    Renderer := 'Skia'
  else
    Renderer := 'AGG';
  Result := Format('Renderer=%s Brotli=%s IsolatePerDocument=%s',
    [Renderer, BoolToStr(Config.BrotliEnabled, True),
     BoolToStr(Config.IsolatePerDocument, True)]);
end;

Diese Zeile einmal beim Start zu loggen ist billig, und sie ist das Erste, was Sie in einem Support-Ticket wollen, das von „der Text sieht auf dem Server anders aus“ erzählt. PDFium.Loaded ist aus demselben Grund qualifiziert wie LoadLibrary: Innerhalb einer Formular- oder Komponentenmethode bindet ein nacktes Loaded an TComponent.Loaded

Zwei Arten, wie eine versionierte C-Konfigurationsstruktur schiefgeht

Jede versionierte Konfigurationsstruktur — ob FPDF_LIBRARY_CONFIG, ein Win32-cbSize-Record oder eine Plugin-ABI — scheitert auf zwei symmetrische Arten, und ein Wrapper muss sich gegen beide wahren. Die erste: ein Feld füllen, während die Version zu niedrig bleibt. Die zweite: die Version heben, während ein Feld auf einem Nullwert bleibt, den die Bibliothek als bewusste Entscheidung liest

  1. Feld gesetzt, Version zu niedrig. m_BrotliEnabled = 1 in eine Version-2-Struktur schreiben, und PDFium schaut nie hin. Der Aufruf gelingt, und Brotli-Streams bleiben undekodierbar. Die Verteidigung: die Version aus den tatsächlich benutzten Feldern ableiten, was LoadLibrary tut, statt eine fest zu kodieren
  2. Version hoch genug, Nullfeld bedeutet etwas. Die Version auf 6 heben, und jedes Feld bis Version 6 ist jetzt live. FillChar nullt m_RendererType auf FPDF_RENDERERTYPE_AGG, einen echten Renderer, nicht „unset“. Die Verteidigung: jedes Feld, das die gewählte Version abdeckt, mit einem bewussten Wert beschreiben und „default“ gegen den tatsächlichen Build auflösen, statt es anzunehmen

Eine dritte Regel folgt für Werte, die den Aufgerufenen zum Absturz bringen können: Sie vor dem Aufruf gegen das validieren, was die Binärdatei kann, mit der stärksten verfügbaren Evidenz, und im Code wie in der Doku ehrlich sein, wenn diese Evidenz eine Heuristik ist. Ein exportiertes Symbol ist ein Beweis. Ein Crate-Name in der String-Tabelle ist eine gute Vermutung

Kurzreferenz: PDFium Component Library-Konfiguration

  • Rufen Sie ConfigurePdfLibrary einmal auf, bevor irgendetwas die DLL lädt; jede Fähigkeitsabfrage oder jeder Dokument-Ladevorgang versiegelt sie
  • Lassen Sie Renderer auf prpDefault, außer Sie brauchen einen bestimmten Rasterizer; er löst sich bei jeder Strukturversion auf den Build-Default auf
  • Benutzen Sie PdfNativeRendererType mit GetSkiaRenderCapabilities.PageRender, um zu loggen, welcher Renderer wirklich aktiv ist
  • Erwarten Sie EPdfError, keinen Absturz, für prpSkia auf einer AGG-only-DLL oder pfbpFontations auf einer Nicht-Fontations-DLL
  • Nach einer Fähigkeitsablehnung ist PdfLibraryConfigurationSealed False, und Sie dürfen neu konfigurieren; nach einem gescheiterten DLL-Laden bleibt sie True
  • Behandeln Sie die Fontations-Erkennung als Heuristik und halten Sie einen FreeType-Fallback bereit
  • Schreiben Sie PDFium.LoadLibrary und PDFium.Loaded mit dem Unit-Namen, um Namenskollisionen mit Win32 und TComponent zu vermeiden

Scheitert die DLL, bevor die Konfiguration überhaupt relevant wird, beginnen Sie mit PDFium-DLL-Ladefehler in Delphi diagnostizieren, und wie die Komponente auf jeder Plattform die richtige Binärdatei findet, zeigt die native PDFium-Bibliothek auf jedem Ziel laden. Ist der Renderer geklärt, zeigt Render-Cache und sanftes Zoomen, wie man das Seiten-Rendering in einem Viewer schnell hält

PDFium Component umhüllt die PDFium-Engine für Delphi und C++Builder mit Konfigurationsprüfungen wie diesen, sodass native Initialisierung als behandelbare Pascal-Exception scheitert statt als Prozessende. Produktdetails und Downloads finden Sie auf der PDFium Component für Delphi Produktseite