Una bolla di consegna prodotta su una scrivania Windows nomina Arial nel suo dizionario font, non porta alcun programma font, e sembra a posto in ogni viewer su quella scrivania. Rasterizzato dentro un container Debian, lo stesso file disegna ogni glifo da un sans serif diverso. Il testo parte ancora dove dovrebbe, perché le posizioni dei glifi vengono dall'array /Widths memorizzato nel PDF, ma le forme delle lettere cambiano, la spaziatura sembra irregolare ovunque i contorni del sostituto siano più stretti delle larghezze in cui siedono, e un carattere che al sostituto manca lascia un buco. Il renderer non ha colpa. Il documento ha lasciato la scelta del font a chiunque lo renderizzi, e quella scelta può essere fatta nel vostro codice fornendo byte di font che spedite insieme all'applicazione
ISO 32000-1 lo permette. I 14 font standard del §9.6.2.2 possono sempre essere referenziati per solo nome, e qualsiasi altro font semplice può restare non incorporato purché il suo dizionario e il font descriptor (§9.8) descrivano metriche e flag. PDF/A lo vieta del tutto (ISO 19005-1 §6.3.4 richiede che ogni programma font sia incorporato), il che la dice lunga su quanto siano affidabili i font per solo nome una volta che un file lascia la macchina che lo ha scritto
Perché non installare semplicemente i font sul server?
A volte installare i font basta. Si rompe in tre situazioni comuni. Una licenza font può permettere l'uso desktop ma non l'installazione su un server che renderizza documenti in automatico. Le immagini container vengono ricostruite spesso, e un font copiato a mano sparisce con il deployment successivo. I workflow regolamentati vogliono lo stack di rendering riproducibile da artefatti sotto controllo di versione, e una cartella font a livello di macchina non è uno di questi
C'è anche un passo intermedio. TPdfLibraryConfiguration.UserFontPaths, passato tramite ConfigurePdfLibrary prima che la libreria si carichi, dice al mapper nativo di PDFium quali cartelle scansionare in cerca di file font. L'elenco sostituisce i default della piattaforma invece di aggiungervisi, e su Windows spegne anche l'enumerazione dei font GDI, quindi includete la cartella font di sistema se i documenti hanno ancora bisogno di font installati. Il mapper decide comunque quale file vince per una data richiesta, con le proprie regole di matching. Quando dovete sapere esattamente quali byte rispondono a "Arial, bold, charset cirillico", quella decisione deve vivere in codice che potete leggere, ed è quello che vi dà un system font provider
Installare un IPdfSystemFontProvider prima che PDFium si carichi
PDFium Component espone la mappatura dei font attraverso un'interfaccia con un solo metodo. IPdfSystemFontProvider.ResolveFont riceve un TPdfSystemFontRequest che porta FaceName, Weight, Italic, Charset e PitchFamily, e risponde con un record TPdfSystemFontData che contiene il nome del face, i byte completi TrueType, OpenType o TrueType Collection, un charset e un TTCIndex. Restituire False declina la richiesta
ConfigureSystemFontProvider deve girare prima che la libreria venga caricata. PDFium prende il suo font mapper una volta sola, durante l'inizializzazione, quindi il componente solleva EPdfError ("Configure the system font provider before loading PDFium") se Loaded è già true. Molte chiamate caricano la libreria su richiesta, comprese le probe delle funzionalità, quindi mettete la configurazione proprio in cima all'avvio. Il provider qui sotto costruisce una tabella di lookup e legge ogni file font nel costruttore; dopo, ResolveFont si limita a leggere:
uses
System.SysUtils, System.Classes, System.IOUtils, PDFium;
type
TBundledFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
private
FKeys: TStringList; // ordinata una volta nel costruttore, poi in sola lettura
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);
// Un alias: riporta la famiglia davvero servita, così la policy la vede
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); // da 600 in su servito come 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; // numero del face dentro una collezione .ttc
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);
// Solo ora aprite i documenti; la prima chiamata che ha bisogno di PDFium lo carica
end;
Le chiavi della tabella in questo esempio sono volutamente ingenue. I documenti reali scrivono la stessa famiglia in diversi modi, quindi loggate Request.FaceName da un batch rappresentativo prima di congelare la tabella; il wrapper di registrazione più in basso produce esattamente quell'elenco. Anche la soglia di peso è una scelta: FXFONT_FW_NORMAL vale 400 e FXFONT_FW_BOLD vale 700 nella unit FPdfExtensions, e una richiesta semibold a 600 deve cadere da una parte o dall'altra
Cosa decidono davvero i flag della policy
Ogni richiesta segue lo stesso ordine. Il componente controlla prima la propria cache, poi chiama il vostro provider, poi convalida la risposta. Una risposta accettata viene messa in cache e consegnata a PDFium. Una risposta declinata o rifiutata va al mapper della piattaforma restituito da FPDF_GetDefaultSystemFontInfo, ma solo quando AllowDefaultFallback è attivo; altrimenti la richiesta viene contata come fallita e PDFium procede senza il vostro font
La convalida in sé è breve. Un FontData vuoto viene rifiutato, e così qualsiasi cosa più lunga di MaxFontBytes. Un FaceName vuoto nella risposta viene riempito con il nome richiesto. Con AllowFaceSubstitution spento, viene rifiutato anche un nome di face riportato che differisce da quello richiesto (confrontato senza distinguere maiuscole e minuscole). Quel controllo legge il nome che riportate e nient'altro. Un provider che serve byte di Liberation Sans riportando "Arial" passa liscio, ed è per questo che l'esempio riporta la famiglia reale per il suo alias Helvetica: con il flag spento, una richiesta Helvetica a cui si risponde con "Arial" viene rifiutata e finisce in RejectedProviderResponses
L'indice TTC viene controllato in un punto diverso. PDFium chiede spesso una tabella sfnt alla volta, come cmap o glyf, e il componente risponde a quelle query percorrendo la directory delle tabelle dei byte che avete restituito. Per una collezione parte dalla directory selezionata da TTCIndex; un indice oltre il numero di font nell'header ttcf, o un indice diverso da zero su un file a font singolo, fa sì che quelle query di tabella non restituiscano nulla. Il percorso della directory riconosce TrueType (0x00010000 e true), OpenType con contorni CFF (OTTO) e collezioni (ttcf). I file WOFF e WOFF2 vanno decompressi in sfnt semplice prima che il provider li restituisca
TPdfSystemFontPolicy.Default accende entrambi i flag, con un tetto di 64 MB per font e 32 voci di cache. Va bene per un provider distribuito poche famiglie alla volta, dove tutto ciò che non avete ancora mappato continua a renderizzare come prima. Una build di audit dovrebbe spegnere entrambi i flag. Le lacune affiorano allora come fallimenti contati e sostituzioni rifiutate, e un fallback hit non può più nascondere una famiglia che il set di font ha dimenticato
Quale thread chiama ResolveFont?
ResolveFont gira su qualunque thread stia caricando o renderizzando la pagina che ha bisogno del font, che non è necessariamente il thread principale. Il componente protegge la propria cache e i propri contatori con una sezione critica, ma non tiene quel lock mentre il vostro metodo gira. Se la vostra applicazione renderizza su thread in background, qualsiasi stato che il provider modifica dopo la costruzione ha bisogno di una guardia propria
Le eccezioni sono la seconda cosa da tenere dentro il metodo. Il componente cattura tutto ciò che sfugge a ResolveFont al confine con la libreria nativa e lo tratta come richiesta declinata, quindi la richiesta prosegue verso il fallback o il fallimento. Affidarsi a questo trasforma un bug nel vostro codice di mappatura in un font servito in silenzio da qualcun altro. Il wrapper qui sotto registra ogni miss sotto lock e tiene le eccezioni locali, il che vi dà anche l'elenco dei nomi di face da aggiungere alla tabella:
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; // loggalo qui; non lasciarlo arrivare a PDFium
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;
Tenete il recorder tramite una variabile interfaccia oltre che tramite la variabile oggetto. Il componente conserva il proprio riferimento all'interfaccia, e ClearSystemFontProvider lo rilascia; se era l'ultimo riferimento, l'oggetto se ne va con lui e una semplice variabile di classe ora punta a memoria liberata. Per scoprire quali font un documento referenzia prima che avvenga qualsiasi rendering, l'elenco per documento in analizzare le proprietà dei font PDF mostra fianco a fianco i font incorporati e quelli non incorporati
Dimensionare la cache dei font
Le richieste di mappatura si ripetono di continuo durante il rendering, quindi le risposte accettate vengono messe in cache. La chiave di cache copre il nome del face (senza distinguere maiuscole e minuscole), peso, flag corsivo, charset e famiglia di pitch, e quando si raggiunge MaxCacheEntries viene espulsa la voce usata meno di recente. Un valore di 0 spegne il caching, quindi ogni richiesta raggiunge il vostro provider e viene convalidata di nuovo. Un valore negativo, o un MaxFontBytes pari a zero o minore, fa sollevare a ConfigureSystemFontProvider "Invalid system font provider policy"
Il conteggio delle voci dice poco sulla memoria quando una singola collezione CJK può superare i 20 MB. Per un budget in byte, ConfigureSystemFontCacheGovernor collega un TPdfCacheGovernor della unit FPdfCache, creato con un numero massimo di byte e condiviso con le altre cache del componente. Anche questo va impostato prima che la libreria si carichi. A ogni voce in cache viene addebitata l'intera lunghezza dei suoi dati font, quindi una collezione da 20 MB che risponde a richieste per quattro charset diversi conta quattro volte sul budget anche se il vostro provider restituisce ogni volta lo stesso array. Quando il governor rifiuta una prenotazione il font viene comunque servito, solo non messo in cache. Tenete vivo l'oggetto governor finché UnloadLibrary non ha girato, visto che le voci in cache tengono prenotazioni contro di lui
Dimostrare la mappatura in produzione
GetSystemFontProviderStatistics restituisce un record TPdfSystemFontStatistics. Configured e Installed dicono se un provider è impostato e se è stato consegnato a PDFium. MapRequests conta ogni richiesta di mappatura, e CacheHits, ProviderHits e DefaultFallbackHits mostrano come è stata soddisfatta. FailedRequests conta quelle a cui nessuno ha risposto e RejectedProviderResponses le risposte che la policy ha rifiutato. I campi restanti tracciano le letture a livello di tabella (FontDataRequests), gli handle font attivi, i font in cache, i byte in cache e le espulsioni
Un'esecuzione di conformità legge i contatori dopo il batch, poi scarica. UnloadLibrary scollega il provider da PDFium, rilascia il mapper della piattaforma e svuota la cache prima di spegnere PDFium, e si rifiuta di girare mentre ci sono ancora documenti aperti. ClearSystemFontProvider viene per ultimo; solleva se PDFium è ancora caricato, e azzera i contatori, quindi leggeteli prima:
var
Recorder: TRecordingFontProvider;
RecorderRef: IPdfSystemFontProvider; // tiene vivo l'oggetto
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 e RenderCorpus sono vostri; il batch deve
// chiudere ogni documento che apre prima che UnloadLibrary giri
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; // scollega il provider, poi spegne PDFium
ClearSystemFontProvider; // permesso solo una volta scaricato PDFium
if (Stats.FailedRequests > 0) or (Stats.RejectedProviderResponses > 0) then
raise Exception.Create('Font set incomplete:' + sLineBreak +
Recorder.MissedFaces);
end;
Con il fallback spento, DefaultFallbackHits resta a zero e ogni lacuna finisce in FailedRequests, spesso insieme a RejectedProviderResponses quando il provider ha risposto ma la policy ha rifiutato il nome o la dimensione. In una build di produzione con il fallback acceso, la stessa lacuna si sposta in DefaultFallbackHits, ed è quello il contatore da mettere su un grafico: un aumento dopo che un nuovo cliente inizia a mandare documenti significa che una famiglia non coperta dal vostro set di font ora viene renderizzata con quello che offre l'host. Le regole di threading per il resto del componente seguono la disciplina del render lock descritta a parte
La stessa istanza di libreria gestisce provisioning dei font, rendering ed estrazione del testo su Delphi, C++Builder e Lazarus, e la pagina di PDFium Component per Delphi copre edizioni e deployment della libreria nativa