Artigo Técnico

Controlar a substituição de fontes de PDF no Delphi

A lista de embarque produzida em uma mesa Windows nomeia Arial no dicionário de fontes, não carrega nenhum programa de fonte e parece perfeita em todos os viewers dessa mesa. Rasterizada dentro de um contêiner Debian, o mesmo arquivo desenha cada glifo com um sans serif diferente. O texto continua começando onde deveria, porque as posições dos glifos vêm do array /Widths guardado no PDF, mas as formas das letras mudam, o espaçamento fica desigual onde quer que os contornos do substituto sejam mais estreitos que as larguras em que ele se acomoda, e um caractere que o substituto não tem deixa um buraco. O renderizador não tem culpa. O documento entregou a escolha da fonte a quem o renderiza, e essa escolha pode ser feita no seu próprio código fornecendo os bytes de fonte que você embarca com a aplicação

A ISO 32000-1 permite isso. As 14 fontes padrão da §9.6.2.2 podem sempre ser referenciadas apenas pelo nome, e qualquer outra fonte simples pode ficar não incorporada desde que seu dicionário e seu font descriptor (§9.8) descrevam métricas e flags. PDF/A proíbe de forma absoluta (a ISO 19005-1 §6.3.4 exige que todo programa de fonte seja incorporado), o que diz muito sobre a confiabilidade de fontes apenas por nome depois que um arquivo sai da máquina que o escreveu

Um PDF Delphi nomeando uma fonte Arial não incorporada renderiza diferente em três máquinas sob o mapper de host padrão, mas idêntico assim que o PDFium recebe bytes de fonte empacotados de um IPdfSystemFontProvider
O PDFium pede bytes de fonte toda vez que um documento nomeia uma fonte que não incorpora; o provider substitui o palpite por máquina do mapper do host por bytes que você mesmo envia

Por que não simplesmente instalar as fontes no servidor?

Às vezes instalar as fontes basta. Em três situações comuns, isso desmorona. Uma licença de fonte pode permitir uso em desktop mas não a instalação em um servidor que renderiza documentos automaticamente. Imagens de contêiner são reconstruídas com frequência, e uma fonte copiada à mão desaparece na implantação seguinte. Fluxos de trabalho regulados querem a pilha de renderização reproduzível a partir de artefatos sob controle de versão, e uma pasta de fontes de toda a máquina não é um deles

Há também um passo intermediário. TPdfLibraryConfiguration.UserFontPaths, passada pelo ConfigurePdfLibrary antes de a biblioteca carregar, diz ao mapper nativo do PDFium quais pastas vasculhar em busca de arquivos de fonte. A lista substitui os padrões da plataforma em vez de somar a eles, e no Windows também desliga a enumeração de fontes via GDI, então inclua a pasta de fontes do sistema se documentos ainda precisarem de fontes instaladas. O mapper ainda decide qual arquivo vence para uma dada requisição, segundo suas próprias regras de correspondência. Quando você precisa saber exatamente quais bytes respondem a "Arial, bold, charset cirílico", essa decisão tem de morar em código que você pode ler, e é isso que um system font provider lhe dá

Instalando um IPdfSystemFontProvider antes de o PDFium carregar

O PDFium Component expõe o mapeamento de fontes por meio de uma interface com um único método. O IPdfSystemFontProvider.ResolveFont recebe um TPdfSystemFontRequest carregando FaceName, Weight, Italic, Charset e PitchFamily, e responde com um record TPdfSystemFontData guardando o nome da face, os bytes completos TrueType, OpenType ou TrueType Collection, um charset e um TTCIndex. Retornar False recusa a requisição

O ConfigureSystemFontProvider precisa rodar antes de a biblioteca ser carregada. O PDFium recebe seu font mapper uma única vez, durante a inicialização, então o componente levanta EPdfError ("Configure the system font provider before loading PDFium") se Loaded já for true. Muitas chamadas carregam a biblioteca sob demanda, incluindo as sondas de recurso, então coloque a configuração bem no topo da inicialização. O provider abaixo constrói uma tabela de consulta e lê todos os arquivos de fonte no constructor; depois disso, o ResolveFont apenas lê:

uses
  System.SysUtils, System.Classes, System.IOUtils, PDFium;

type
  TBundledFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
  private
    FKeys: TStringList;           // ordenada uma vez no constructor, somente leitura depois
    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);
  // Um alias: reporte a família realmente servida, para que a policy enxergue
  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 ou mais é servido como 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;                // número da face dentro de uma coleção .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);
  // Só agora abra documentos; a primeira chamada que precisar do PDFium o carrega
end;

As chaves da tabela nesse exemplo são deliberadamente ingênuas. Documentos reais grafam a mesma família de várias formas, então registre o Request.FaceName de um lote representativo antes de congelar a tabela; o wrapper gravador mais abaixo produz exatamente essa lista. O limiar de peso também é uma escolha: FXFONT_FW_NORMAL é 400 e FXFONT_FW_BOLD é 700 na unit FPdfExtensions, e uma requisição semibold em 600 precisa cair de um lado ou do outro

O que as flags de política realmente decidem

Toda requisição segue a mesma ordem. O componente primeiro consulta seu cache, depois chama o seu provider, depois valida a resposta. Uma resposta aceita vai para o cache e é entregue ao PDFium. Uma resposta recusada ou rejeitada vai para o mapper da plataforma devolvido por FPDF_GetDefaultSystemFontInfo, mas somente quando AllowDefaultFallback está ligada; caso contrário, a requisição é contada como falha e o PDFium segue sem a sua fonte

A validação em si é curta. FontData vazio é recusado, e qualquer coisa maior que MaxFontBytes também. Um FaceName vazio na resposta é preenchido com o nome solicitado. Com AllowFaceSubstitution desligada, um nome de face reportado que difere do solicitado (comparado sem diferenciar maiúsculas) também é recusado. Essa checagem lê o nome que você reporta e nada mais. Um provider que serve bytes da Liberation Sans reportando "Arial" passa batido, e é por isso que o exemplo reporta a família real para o seu alias Helvetica: com a flag desligada, uma requisição por Helvetica respondida com "Arial" é recusada e cai em RejectedProviderResponses

Portões de validação do PDFium Component verificam dados vazios, tamanho MaxFontBytes e substituição de face antes de os bytes chegarem ao PDFium, com AllowDefaultFallback decidindo entre fallback de host e uma requisição que falha
A validação roda dentro do componente antes de qualquer byte do provider chegar ao PDFium; com o fallback desligado, uma requisição sem mapeamento é contada uma vez em FailedRequests e o PDFium desenha o texto com sua própria fonte substituta embutida

O índice TTC é verificado em outro ponto. O PDFium frequentemente pede uma tabela sfnt por vez, como cmap ou glyf, e o componente responde a essas consultas percorrendo o diretório de tabelas dos bytes que você devolveu. Em uma coleção, ele parte do diretório selecionado pelo TTCIndex; um índice além do número de fontes no cabeçalho ttcf, ou um índice não zero em um arquivo de fonte única, faz essas consultas de tabela não devolverem nada. O percurso do diretório reconhece TrueType (0x00010000 e true), OpenType com contornos CFF (OTTO) e coleções (ttcf). Arquivos WOFF e WOFF2 precisam ser descomprimidos para sfnt simples antes de o provider os devolver

O TPdfSystemFontPolicy.Default liga as duas flags, com teto de 64 MB por fonte e 32 entradas de cache. Isso serve para um provider que vai sendo rolado algumas famílias por vez, em que tudo o que você ainda não mapeou continua renderizando como sempre renderizava. Um build de auditoria deve desligar as duas. As lacunas então aparecem como falhas contadas e substituições recusadas, e um acerto de fallback não pode mais esconder uma família que o conjunto de fontes esqueceu

Qual thread chama o ResolveFont?

O ResolveFont roda na thread que estiver carregando ou renderizando a página que precisa da fonte, que não é necessariamente a thread principal. O componente protege seu próprio cache e seus contadores com uma critical section, mas não segura esse lock enquanto o seu método roda. Se a sua aplicação renderiza em threads de fundo, qualquer estado que o provider mude após a construção precisa de proteção própria

Exceções são a segunda coisa a manter dentro do método. O componente captura qualquer coisa que escape do ResolveFont na fronteira com a biblioteca nativa e trata como uma requisição recusada, então a requisição segue para o fallback ou para a falha. Confiar nisso transforma um bug no seu código de mapeamento em uma fonte servida silenciosamente por outra pessoa. O wrapper abaixo registra cada falha sob um lock e mantém as exceções locais, o que também lhe dá a lista de nomes de face a acrescentar à tabela:

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;            // registre aqui; não deixe chegar ao 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;

Segure o gravador por uma variável de interface além da variável de objeto. O componente mantém sua própria referência de interface, e o ClearSystemFontProvider a descarta; se essa era a última referência, o objeto vai junto, e uma variável de classe simples passa a apontar para memória liberada. Para descobrir quais fontes um documento referencia antes de qualquer renderização, a listagem por documento em análise de propriedades de fontes de PDF mostra fontes incorporadas e não incorporadas lado a lado

Dimensionando o cache de fontes

Requisições de mapeamento se repetem o tempo todo durante a renderização, então as respostas aceitas vão para um cache. A chave do cache cobre o nome da face (sem diferenciar maiúsculas), peso, flag de itálico, charset e família de pitch, e quando MaxCacheEntries é atingido a entrada usada menos recentemente é expulsa. Um valor 0 desliga o cache, e toda requisição chega ao seu provider e é validada de novo. Um valor negativo, ou um MaxFontBytes de zero ou menos, faz o ConfigureSystemFontProvider levantar "Invalid system font provider policy"

Contagens de entrada dizem pouco sobre memória quando uma única coleção CJK pode passar de 20 MB. Para um orçamento em bytes, o ConfigureSystemFontCacheGovernor anexa um TPdfCacheGovernor da unit FPdfCache, criado com uma contagem máxima de bytes e compartilhado com os outros caches do componente. Ele também precisa ser definido antes de a biblioteca carregar. Cada entrada em cache é cobrada pelo comprimento total dos seus dados de fonte, então uma coleção de 20 MB respondendo a requisições de quatro charsets diferentes conta quatro vezes contra o orçamento mesmo que o seu provider devolva o mesmo array toda vez. Quando o governor recusa uma reserva, a fonte continua sendo servida, só não vai para o cache. Mantenha o objeto governor vivo até o UnloadLibrary rodar, já que as entradas em cache mantêm reservas contra ele

Comprovando o mapeamento em produção

O GetSystemFontProviderStatistics devolve um record TPdfSystemFontStatistics. Configured e Installed dizem se um provider está definido e se já foi entregue ao PDFium. MapRequests conta toda requisição de mapeamento, e CacheHits, ProviderHits e DefaultFallbackHits mostram como elas foram respondidas. FailedRequests conta as que ninguém respondeu e RejectedProviderResponses as respostas que a policy recusou. Os campos restantes acompanham leituras em nível de tabela (FontDataRequests), handles de fonte vivos, fontes em cache, bytes em cache e expulsões

GetSystemFontProviderStatistics divide as requisições de mapeamento de fontes do PDFium em hits de cache, provider e fallback em uma execução de conformidade Delphi que levanta erro quando DefaultFallbackHits ou FailedRequests aparecem
O record de estatísticas transforma a substituição de fontes em algo que uma execução de conformidade pode afirmar; qualquer fallback ou solicitação que falha significa que o documento precisava de uma fonte que o conjunto não traz

Uma execução de conformidade lê os contadores depois do lote e então descarrega. O UnloadLibrary desanexa o provider do PDFium, libera o mapper da plataforma e esvazia o cache antes de desligar o PDFium, e se recusa a rodar enquanto houver documentos abertos. O ClearSystemFontProvider vem por último; ele levanta erro se o PDFium ainda estiver carregado, e reinicia os contadores, então leia-os primeiro:

var
  Recorder: TRecordingFontProvider;
  RecorderRef: IPdfSystemFontProvider;   // mantém o objeto vivo
  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 são seus; o lote precisa
  // fechar todo documento que abrir antes de o UnloadLibrary rodar
  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;               // desanexa o provider e então desliga o PDFium
  ClearSystemFontProvider;     // permitido somente com o PDFium descarregado

  if (Stats.FailedRequests > 0) or (Stats.RejectedProviderResponses > 0) then
    raise Exception.Create('Font set incomplete:' + sLineBreak +
      Recorder.MissedFaces);
end;

Com o fallback desligado, o DefaultFallbackHits fica em zero e toda lacuna cai em FailedRequests, frequentemente ao lado de RejectedProviderResponses quando o provider respondeu mas a policy recusou o nome ou o tamanho. Em um build de produção com fallback ligado, a mesma lacuna se move para o DefaultFallbackHits, e esse é o contador para graficar: uma alta depois de um cliente novo começar a enviar documentos significa que uma família que o seu conjunto de fontes não cobre agora está sendo renderizada com o que quer que o host ofereça. As regras de threading para o restante do componente seguem a disciplina de lock de renderização descrita à parte

A mesma instância de biblioteca cuida do provisionamento de fontes, da renderização e da extração de texto em Delphi, C++Builder e Lazarus, e a página do PDFium Component para Delphi cobre edições e implantação da biblioteca nativa