Articolo tecnico

Sostituzione dei font PDF in Delphi con PDFium

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

Un PDF Delphi che nomina un font Arial non incorporato si renderizza diversamente su tre macchine sotto il mapper host predefinito ma identicamente una volta che PDFium riceve i byte del font in bundle da un IPdfSystemFontProvider
PDFium chiede i byte del font ogni volta che un documento nomina un font che non incorpora; il provider sostituisce il tirare a indovinare macchina per macchina del mapper host con byte che spedite voi stessi

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

I gate di convalida di PDFium Component controllano dati vuoti, dimensione MaxFontBytes e sostituzione del face prima che i byte raggiungano PDFium, con AllowDefaultFallback che decide tra fallback host e richiesta fallita
La convalida gira dentro il componente prima che qualsiasi byte del provider raggiunga PDFium; con il fallback spento, una richiesta non mappata viene contata una volta in FailedRequests e PDFium disegna il testo con il proprio font sostitutivo integrato

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

GetSystemFontProviderStatistics divide le richieste di mappatura font PDFium in successi cache, provider e fallback in un'esecuzione di conformità Delphi che solleva quando compaiono DefaultFallbackHits o FailedRequests
Il record di statistiche trasforma la sostituzione dei font in qualcosa su cui un'esecuzione di conformità può fare asserzioni; qualsiasi fallback o richiesta fallita significa che il documento richiedeva un font che l'insieme non include

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