Een pakbon die op een Windows-werkplek is gemaakt, benoemt Arial in zijn fontdictionary, bevat geen fontprogramma en ziet er op die werkplek in elke viewer prima uit. Gerasterd binnen een Debian-container trekt hetzelfde bestand elke glyph uit een andere sans serif. De tekst begint nog waar die hoort, want de glyphposities komen uit de /Widths-array die in de PDF staat, maar de lettervormen veranderen, de spacing oogt oneven waar de outlines van het substituut smaller zijn dan de breedtes waarin ze staan, en een teken dat het substituut mist laat een gat na. De renderer is niet de schuldige. Het document droeg de fontkeus over aan wie hem rendert, en die keus kun je in je eigen code maken door fontbytes mee te leveren met de applicatie
ISO 32000-1 staat dit toe. De 14 standaardfonts uit §9.6.2.2 mogen altijd op naam alleen worden gerefereerd, en elke andere simple font mag ongeïnsloten blijven zolang zijn dictionary en fontdescriptor (§9.8) maar metrics en flags beschrijven. PDF/A verbiedt het ronduit (ISO 19005-1 §6.3.4 verplicht elk fontprogramma in te sluiten), wat veel zegt over hoe betrouwbaar fonts op naam alleen zijn zodra een bestand de machine verlaat die hem schreef
Waarom niet gewoon de fonts op de server installeren?
Soms is het installeren van de fonts genoeg. Het breekt in drie veelvoorkomende situaties. Een fontlicentie staat desktopgebruik toe maar geen installatie op een server die automatisch documenten rendert. Containerimages worden vaak opnieuw gebouwd, en een handmatig gekopieerd font verdwijnt met de volgende deployment. Gereguleerde workflows willen de renderstack reproduceerbaar vanuit artefacten onder versiebeheer, en een systeembrede fontmap hoort daar niet bij
Er is ook een tussenstap. TPdfLibraryConfiguration.UserFontPaths, doorgegeven via ConfigurePdfLibrary voordat de library laadt, vertelt de native mapper van PDFium in welke mappen hij naar fontbestanden moet zoeken. De lijst vervangt de platformdefaults in plaats van ze aan te vullen, en op Windows zet hij ook de GDI-fontenumeratie uit, dus neem de systeemfontmap mee als documenten nog geïnstalleerde fonts nodig hebben. De mapper blijft zelf beslissen welk bestand voor een bepaald verzoek wint, volgens zijn eigen matchingregels. Als je precies wilt weten welke bytes "Arial, bold, Cyrillic charset" beantwoorden, moet die beslissing in leesbare code leven, en dat is wat een system font provider je geeft
Een IPdfSystemFontProvider installeren voordat PDFium laadt
PDFium Component stelt fontmapping bloot via één interface met één methode. IPdfSystemFontProvider.ResolveFont ontvangt een TPdfSystemFontRequest met FaceName, Weight, Italic, Charset en PitchFamily, en antwoordt met een TPdfSystemFontData-record met de facenaam, de complete TrueType-, OpenType- of TrueType Collection-bytes, een charset en een TTCIndex. False teruggeven wijst het verzoek af
ConfigureSystemFontProvider moet draaien voordat de library is geladen. PDFium neemt zijn fontmapper één keer, tijdens de initialisatie, dus het component geeft EPdfError ("Configure the system font provider before loading PDFium") als Loaded al true is. Veel aanroepen laden de library on demand, inclusief de feature probes, dus zet de configuratie helemaal bovenaan de opstart. De provider hieronder bouwt een opzoektabel en leest elk fontbestand in zijn constructor; daarna leest ResolveFont alleen nog:
uses
System.SysUtils, System.Classes, System.IOUtils, PDFium;
type
TBundledFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
private
FKeys: TStringList; // éénmaal gesorteerd in de constructor, daarna alleen-lezen
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);
// een alias: meld de familie die echt wordt geleverd, zodat de policy hem kan zien
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); // 600 en hoger geleverd als bold
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; // facenummer binnen een .ttc-collectie
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);
// open documenten pas nu; de eerste aanroep die PDFium nodig heeft, laadt hem
end;
De tabelsleutels in dit voorbeeld zijn bewust naïef. Echte documenten spellen dezelfde familie op verschillende manieren, dus log Request.FaceName uit een representatieve batch voordat je de tabel bevriest; de recording-wrapper verderop levert precies die lijst. De gewichtsdrempel is ook een keuze: FXFONT_FW_NORMAL is 400 en FXFONT_FW_BOLD is 700 in de unit FPdfExtensions, en een semibold-verzoek op 600 moet aan een van beide kanten uitkomen
Wat de policy-flags werkelijk beslissen
Elk verzoek volgt dezelfde volgorde. Het component controleert eerst zijn cache, roept dan je provider aan en valideert dan het antwoord. Een geaccepteerd antwoord wordt gecacht en aan PDFium doorgegeven. Een geweigerd of afgekeurd antwoord gaat naar de platformmapper uit FPDF_GetDefaultSystemFontInfo, maar alleen als AllowDefaultFallback aan staat; anders wordt het verzoek als mislukt geteld en gaat PDFium verder zonder jouw font
De validatie zelf is kort. Lege FontData wordt geweigerd, en net zo alles wat langer is dan MaxFontBytes. Een lege FaceName in het antwoord wordt gevuld met de gevraagde naam. Met AllowFaceSubstitution uit wordt ook een gerapporteerde facenaam die afwijkt van de gevraagde (vergeleken zonder op hoofdletters te letten) geweigerd. Die controle leest de naam die je meldt en niets anders. Een provider die Liberation Sans-bytes levert terwijl hij "Arial" meldt, komt erdoorheen, en dat is waarom het voorbeeld de echte familie meldt voor zijn Helvetica-alias: met de flag uit wordt een Helvetica-verzoek dat met "Arial" wordt beantwoord geweigerd en belandt het in RejectedProviderResponses
De TTC-index wordt op een ander moment gecontroleerd. PDFium vraagt vaak één sfnt-tabel per keer, zoals cmap of glyf, en het component beantwoordt die queries door de tabeldirectory van de bytes die je teruggaf te doorlopen. Bij een collectie begint hij bij de directory die TTCIndex selecteert; een index voorbij het aantal fonts in de ttcf-header, of een index ongelijk aan nul op een single-font bestand, maakt dat die tabelqueries niets teruggeven. De directory-walk herkent TrueType (0x00010000 en true), OpenType met CFF-outlines (OTTO) en collecties (ttcf). WOFF- en WOFF2-bestanden moeten eerst naar kale sfnt worden gedecomprimeerd voordat de provider ze teruggaat
TPdfSystemFontPolicy.Default zet beide flags aan, met een plafon van 64 MB per font en 32 cache-entries. Dat past bij een provider die familie voor familie wordt uitgerold, waarbij alles wat je nog niet gemapped hebt gewoon blijft renderen zoals het rendert. Een audit-build moet beide flags uitzetten. Leemten verschijnen dan als getelde mislukkingen en geweigerde substituties, en een fallback-hit kan geen familie meer verbergen die de fontset vergat
Welke thread roept ResolveFont aan?
ResolveFont draait op de thread die de pagina laadt of rendert die het font nodig heeft, en dat is niet noodzakelijk de hoofdthread. Het component bewaakt zijn eigen cache en tellers met een critical section, maar houdt die lock niet vast terwijl jouw methode draait. Als je applicatie op background threads rendert, heeft elke toestand die de provider na de constructie verandert zijn eigen bewaking nodig
Exceptions zijn het tweede wat je binnen de methode moet houden. Het component vangt alles wat uit ResolveFont ontsnapt op aan de grens met de native library en behandelt het als een geweigerd verzoek, dus het verzoek loopt door naar fallback of mislukking. Daarop vertrouwen maakt van een bug in je mappingcode een font dat stilletjes door iemand anders wordt geleverd. De wrapper hieronder registreert elke miss onder een lock en houdt exceptions lokaal, wat je ook de lijst met facenamen geeft om aan de tabel toe te voegen:
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; // log het hier; laat het niet tot PDFium doordringen
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;
Houd de recorder vast via een interfacevariabele naast de objectvariabele. Het component houdt zelf een interfacereferentie bij, en ClearSystemFontProvider laat haar vallen; was dat de laatste referentie, dan gaat het object mee en wijst een kale class-variabele naar vrijgegeven geheugen. Om te vinden naar welke fonts een document verwijst voordat er wordt gerenderd, laat het overzicht per document in het analyseren van PDF-lettertype-eigenschappen ingesloten en niet-ingesloten fonts naast elkaar zien
De fontcache van maat voorzien
Mappingverzoeken herhalen zich voortdurend tijdens rendering, dus geaccepteerde antwoorden worden gecacht. De cache-sleutel dekt de facenaam (ongeacht hoofdletters), gewicht, italic-flag, charset en pitch family, en bij het bereiken van MaxCacheEntries wordt de minst recent gebruikte entry verwijderd. De waarde 0 zet caching uit, dus elk verzoek bereikt je provider en wordt opnieuw gevalideerd. Een negatieve waarde, of een MaxFontBytes van nul of minder, laat ConfigureSystemFontProvider "Invalid system font provider policy" geven
Entryaantallen zeggen weinig over geheugen als één CJK-collectie voorbij 20 MB kan gaan. Voor een bytebudget koppelt ConfigureSystemFontCacheGovernor een TPdfCacheGovernor uit de unit FPdfCache aan, aangemaakt met een maximaal aantal bytes en gedeeld met de andere caches van het component. Ook die moet worden gezet voordat de library laadt. Elke gecachte entry wordt de volledige lengte van zijn fontdata aangerekend, dus een collectie van 20 MB die verzoeken voor vier verschillende charsets beantwoordt, telt vier keer mee voor het budget, ook al geeft je provider telkens dezelfde array terug. Weigert de governor een reservering, dan wordt het font toch geleverd, alleen niet gecacht. Houd het governor-object in leven tot UnloadLibrary heeft gedraaid, want de gecachte entries houden reserveringen op hem vast
De mapping in productie bewijzen
GetSystemFontProviderStatistics geeft een TPdfSystemFontStatistics-record terug. Configured en Installed zeggen of er een provider is gezet en of die aan PDFium is doorgegeven. MapRequests telt elk mappingverzoek, en CacheHits, ProviderHits en DefaultFallbackHits laten zien hoe ze werden beantwoord. FailedRequests telt de verzoeken die niemand beantwoordde en RejectedProviderResponses de antwoorden die de policy weigerde. De overige velden volgen tabelniveau-lezingen (FontDataRequests), actieve fonthandles, gecachte fonts, gecachte bytes en evictions
Een conformiteitsrun leest de tellers na de batch en laadt dan uit. UnloadLibrary koppelt de provider van PDFium los, geeft de platformmapper vrij en maakt de cache leeg voordat hij PDFium afsluit, en hij weigert te draaien terwijl er nog documenten open zijn. ClearSystemFontProvider komt als laatste; hij geeft een fout als PDFium nog geladen is, en hij reset de tellers, dus lees ze eerst:
var
Recorder: TRecordingFontProvider;
RecorderRef: IPdfSystemFontProvider; // houdt het object in leven
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 en RenderCorpus zijn van jou; de batch moet
// elk geopend document sluiten voordat UnloadLibrary draait
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 de provider los, sluit daarna PDFium af
ClearSystemFontProvider; // alleen toegestaan zodra PDFium is uitgeladen
if (Stats.FailedRequests > 0) or (Stats.RejectedProviderResponses > 0) then
raise Exception.Create('Font set incomplete:' + sLineBreak +
Recorder.MissedFaces);
end;
Met fallback uit blijft DefaultFallbackHits op nul en belandt elke leemte in FailedRequests, vaak naast RejectedProviderResponses wanneer de provider wel antwoordde maar de policy de naam of de grootte weigerde. In een productiebuild met fallback aan schuift dezelfde leemte door naar DefaultFallbackHits, en die teller is degene om bij te houden: een stijging zodra een nieuwe klant documenten begint te sturen betekent dat een familie die je fontset niet dekt nu wordt gerenderd met wat de host toevallig aanbiedt. De threadingregels voor de rest van het component volgen de apart beschreven renderlock-discipline
Dezelfde library-instantie verzorgt fontprovisioning, rendering en tekstextractie in Delphi, C++Builder en Lazarus, en de PDFium Component voor Delphi-pagina behandelt edities en de deployment van de native library