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
| Strukturversion | Feld, das sie hinzufügt | Gesetzt durch |
|---|---|---|
| 2 | m_pIsolate, m_v8EmbedderSlot | Immer geschrieben; V8Isolate, V8EmbedderSlot |
| 3 | m_pPlatform | V8Platform nicht nil |
| 4 | m_RendererType | Renderer anders als prpDefault |
| 5 | m_FontLibraryType | FontBackend anders als pfbpDefault |
| 6 | m_BrotliEnabled | BrotliEnabled = True |
| 7 | m_IsolatePerDocument | IsolatePerDocument = 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
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 mitprpDefaultalsFPDF_RENDERERTYPE_AGGgeschrieben: HashF75B5EB4728ADE87- Explizites
prpAgg: HashF75B5EB4728ADE87, 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
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,
ConfigurePdfLibrarylehnt 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, dasPdfNativeRendererTypebenutzt. 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
skrifaundread-fonts(auchread_fonts). Der Scan läuft nur, wennpfbpFontationsangefragt 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
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
- 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, wasLoadLibrarytut, statt eine fest zu kodieren - Version hoch genug, Nullfeld bedeutet etwas. Die Version auf 6 heben, und jedes Feld bis Version 6 ist jetzt live.
FillCharnulltm_RendererTypeaufFPDF_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
ConfigurePdfLibraryeinmal auf, bevor irgendetwas die DLL lädt; jede Fähigkeitsabfrage oder jeder Dokument-Ladevorgang versiegelt sie - Lassen Sie
RendereraufprpDefault, außer Sie brauchen einen bestimmten Rasterizer; er löst sich bei jeder Strukturversion auf den Build-Default auf - Benutzen Sie
PdfNativeRendererTypemitGetSkiaRenderCapabilities.PageRender, um zu loggen, welcher Renderer wirklich aktiv ist - Erwarten Sie
EPdfError, keinen Absturz, fürprpSkiaauf einer AGG-only-DLL oderpfbpFontationsauf einer Nicht-Fontations-DLL - Nach einer Fähigkeitsablehnung ist
PdfLibraryConfigurationSealedFalse, 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.LoadLibraryundPDFium.Loadedmit dem Unit-Namen, um Namenskollisionen mit Win32 undTComponentzu 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