Artículo técnico

Controlar la sustitución de fuentes PDF en Delphi con PDFium

Un packing slip producido en un escritorio Windows nombra Arial en su diccionario de fuentes, no lleva ningún programa de fuente, y se ve bien en cada visor de ese escritorio. Rasterizado dentro de un contenedor Debian, el mismo archivo dibuja cada glifo con un sans serif distinto. El texto sigue empezando donde debe, porque las posiciones de glifo vienen del arreglo /Widths guardado en el PDF, pero las formas de las letras cambian, el espaciado se ve desigual donde los contornos del sustituto son más angostos que los anchos en los que se sientan, y un carácter que el sustituto no tiene deja un hueco. El renderizador no tiene la culpa. El documento le entregó la elección de fuente a quien lo renderice, y esa elección se puede tomar en su propio código suministrando bytes de fuente que usted distribuye con la aplicación

ISO 32000-1 lo permite. Las 14 fuentes estándar de §9.6.2.2 siempre pueden referenciarse por su solo nombre, y cualquier otra fuente simple puede dejarse sin incrustar mientras su diccionario y su font descriptor (§9.8) describan métricas y flags. PDF/A lo prohíbe de plano (ISO 19005-1 §6.3.4 exige que cada programa de fuente vaya incrustado), lo que dice mucho sobre qué tan confiables son las fuentes de solo nombre una vez que el archivo deja la máquina que lo escribió

Un PDF de Delphi que nombra una fuente Arial sin incrustar se renderiza de forma distinta en tres máquinas bajo el mapeador de host predeterminado pero idéntico una vez que PDFium recibe los bytes de fuente incluidos de un IPdfSystemFontProvider
PDFium pide bytes de fuente cada vez que un documento nombra una fuente que no incrusta; el proveedor reemplaza la adivinanza por máquina del mapper del anfitrión con bytes que usted mismo envía

¿Por qué no simplemente instalar las fuentes en el servidor?

A veces instalar las fuentes es suficiente. Se rompe en tres situaciones comunes. Una licencia de fuente puede permitir el uso de escritorio pero no la instalación en un servidor que renderiza documentos automáticamente. Las imágenes de contenedor se reconstruyen a menudo, y una fuente copiada a mano desaparece con el siguiente despliegue. Los flujos de trabajo regulados quieren la pila de renderizado reproducible a partir de artefactos bajo control de versiones, y una carpeta de fuentes a nivel de máquina no lo es

También hay un paso intermedio. TPdfLibraryConfiguration.UserFontPaths, pasado a través de ConfigurePdfLibrary antes de que la biblioteca cargue, le dice al mapper nativo de PDFium qué carpetas escanear en busca de archivos de fuente. La lista reemplaza los valores por defecto de la plataforma en lugar de agregarlos, y en Windows además apaga la enumeración de fuentes GDI, así que incluya la carpeta de fuentes del sistema si los documentos todavía necesitan fuentes instaladas. El mapper sigue decidiendo qué archivo gana para una solicitud dada, según sus propias reglas de match. Cuando necesita saber exactamente qué bytes responden a “Arial, bold, charset cirílico”, esa decisión tiene que vivir en código que usted pueda leer, y eso es lo que le da un system font provider

Instalar un IPdfSystemFontProvider antes de que PDFium cargue

PDFium Component expone el mapeo de fuentes a través de una interfaz con un método. IPdfSystemFontProvider.ResolveFont recibe un TPdfSystemFontRequest que lleva FaceName, Weight, Italic, Charset y PitchFamily, y responde con un record TPdfSystemFontData que contiene el nombre de cara, los bytes completos TrueType, OpenType o TrueType Collection, un charset y un TTCIndex. Devolver False declina la solicitud

ConfigureSystemFontProvider tiene que correr antes de que la biblioteca cargue. PDFium toma su font mapper una sola vez, durante la inicialización, así que el componente levanta EPdfError (“Configure the system font provider before loading PDFium”) si Loaded ya es true. Muchas llamadas cargan la biblioteca bajo demanda, incluidos los probes de features, así que ponga la configuración en lo más alto del startup. El proveedor de abajo construye una tabla de búsqueda y lee cada archivo de fuente en su constructor; después de eso, ResolveFont solo lee:

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

type
  TBundledFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
  private
    FKeys: TStringList;           // ordenada una vez en el constructor, de solo lectura después
    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: reporte la familia realmente servida, para que la política pueda verla
  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 adelante se sirve 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 de cara dentro de una colección .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 ahora abra documentos; la primera llamada que necesite PDFium la carga
end;

Las claves de la tabla en este sample son deliberadamente ingenuas. Los documentos reales deletrean la misma familia de varias maneras, así que haga log de Request.FaceName desde un lote representativo antes de congelar la tabla; el wrapper de grabación más abajo produce exactamente esa lista. El umbral de peso también es una elección: FXFONT_FW_NORMAL es 400 y FXFONT_FW_BOLD es 700 en la unidad FPdfExtensions, y una solicitud semibold de 600 tiene que caer de un lado o del otro

Qué deciden realmente los flags de política

Cada solicitud sigue el mismo orden. El componente revisa primero su caché, luego llama a su proveedor, y después valida la respuesta. Una respuesta aceptada se guarda en caché y se entrega a PDFium. Una respuesta declinada o rechazada va al mapper de plataforma que devuelve FPDF_GetDefaultSystemFontInfo, pero solo cuando AllowDefaultFallback está encendido; de lo contrario la solicitud se cuenta como fallida y PDFium sigue sin su fuente

La validación en sí es corta. Un FontData vacío se rechaza, y también cualquier cosa más larga que MaxFontBytes. Un FaceName vacío en la respuesta se rellena con el nombre solicitado. Con AllowFaceSubstitution apagado, un nombre de cara reportado distinto del solicitado (comparado sin importar mayúsculas) también se rechaza. Esa verificación lee el nombre que usted reporta y nada más. Un proveedor que sirve bytes de Liberation Sans mientras reporta “Arial” pasa sin problemas, razón por la que el sample reporta la familia real para su alias Helvetica: con el flag apagado, una solicitud Helvetica respondida con “Arial” se rechaza y aterriza en RejectedProviderResponses

Las compuertas de validación de PDFium Component verifican datos vacíos, tamaño MaxFontBytes y sustitución de cara antes de que los bytes lleguen a PDFium, con AllowDefaultFallback decidiendo entre el fallback del host y una solicitud fallida
La validación corre dentro del componente antes de que cualquier byte del proveedor llegue a PDFium; con el fallback apagado, una solicitud no mapeada se cuenta una vez en FailedRequests y PDFium dibuja el texto con su propia fuente sustituta incorporada

El índice TTC se verifica en otro punto. PDFium a menudo pide una tabla sfnt a la vez, como cmap o glyf, y el componente responde esas consultas recorriendo el directorio de tablas de los bytes que usted devolvió. Para una colección arranca desde el directorio seleccionado por TTCIndex; un índice pasado del número de fuentes en el encabezado ttcf, o un índice distinto de cero sobre un archivo de fuente única, hace que esas consultas de tabla no devuelvan nada. El recorrido del directorio reconoce TrueType (0x00010000 y true), OpenType con contornos CFF (OTTO) y colecciones (ttcf). Los archivos WOFF y WOFF2 tienen que descomprimirse a sfnt plano antes de que el proveedor los devuelva

TPdfSystemFontPolicy.Default enciende ambos flags, con un techo de 64 MB por fuente y 32 entradas de caché. Eso conviene a un proveedor que incorpora unas pocas familias a la vez, donde todo lo que aún no mapeó sigue renderizando como lo venía haciendo. Un build de auditoría debería apagar ambos flags. Los huecos entonces aparecen como fallos contados y sustituciones rechazadas, y un hit de fallback ya no puede esconder una familia que el set de fuentes olvidó

¿Qué hilo llama a ResolveFont?

ResolveFont corre en el hilo que esté cargando o renderizando la página que necesita la fuente, que no es necesariamente el hilo principal. El componente protege su propia caché y sus contadores con una sección crítica, pero no retiene ese lock mientras su método corre. Si su aplicación renderiza en hilos de fondo, cualquier estado que el proveedor cambie después de la construcción necesita su propia protección

Las excepciones son lo segundo que mantener dentro del método. El componente captura cualquier cosa que escape de ResolveFont en el límite con la biblioteca nativa y lo trata como una solicitud declinada, así que la solicitud continúa hacia el fallback o el fallo. Confiar en eso convierte un bug en su código de mapeo en una fuente servida silenciosamente por otro. El wrapper de abajo graba cada miss bajo un lock y mantiene las excepciones locales, lo que además le da la lista de nombres de cara para agregar a la tabla:

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;            // regístrela aquí; no la deje llegar 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;

Sostenga el recorder a través de una variable de interfaz además de la variable de objeto. El componente conserva su propia referencia de interfaz, y ClearSystemFontProvider la suelta; si esa era la última referencia, el objeto se va con ella y una variable de clase simple apunta ahora a memoria liberada. Para saber qué fuentes referencia un documento antes de que ocurra cualquier renderizado, el listado por documento de análisis de propiedades de fuente PDF muestra las fuentes incrustadas y no incrustadas lado a lado

Dimensionar la caché de fuentes

Las solicitudes de mapeo se repiten constantemente durante el renderizado, así que las respuestas aceptadas se guardan en caché. La clave de caché cubre el nombre de cara (sin importar mayúsculas), el peso, el flag de cursiva, el charset y la familia de pitch, y cuando se alcanza MaxCacheEntries se desaloja la entrada usada menos recientemente. Un valor de 0 apaga la caché, así que cada solicitud llega a su proveedor y se valida otra vez. Un valor negativo, o un MaxFontBytes de cero o menos, hace que ConfigureSystemFontProvider levante “Invalid system font provider policy”

Los conteos de entradas dicen poco sobre memoria cuando una sola colección CJK puede pasar de 20 MB. Para un presupuesto de bytes, ConfigureSystemFontCacheGovernor adjunta un TPdfCacheGovernor de la unidad FPdfCache, creado con un conteo máximo de bytes y compartido con las otras cachés del componente. También tiene que fijarse antes de que la biblioteca cargue. Cada entrada en caché se le cobra por la longitud completa de sus datos de fuente, así que una colección de 20 MB que responde solicitudes de cuatro charsets distintos cuenta cuatro veces contra el presupuesto incluso si su proveedor devuelve el mismo arreglo cada vez. Cuando el governor rechaza una reserva la fuente se sirve igual, solo que no se guarda en caché. Mantenga el objeto governor vivo hasta que UnloadLibrary haya corrido, ya que las entradas en caché sostienen reservas contra él

Demostrar el mapeo en producción

GetSystemFontProviderStatistics devuelve un record TPdfSystemFontStatistics. Configured e Installed dicen si hay un proveedor fijado y si ya se entregó a PDFium. MapRequests cuenta cada solicitud de mapeo, y CacheHits, ProviderHits y DefaultFallbackHits muestran cómo se respondieron. FailedRequests cuenta las que nadie respondió y RejectedProviderResponses las respuestas que la política rechazó. Los campos restantes siguen lecturas a nivel de tabla (FontDataRequests), handles de fuentes vivos, fuentes en caché, bytes en caché y desalojos

GetSystemFontProviderStatistics divide las solicitudes de mapeo de fuentes de PDFium en aciertos de caché, proveedor y fallback en una corrida de conformidad de Delphi que lanza cuando aparecen DefaultFallbackHits o FailedRequests
El registro de estadísticas convierte la sustitución de fuentes en algo sobre lo que una corrida de conformidad puede asertar; cualquier fallback o solicitud fallida significa que el documento necesitó una fuente que el conjunto no trae

Una corrida de conformidad lee los contadores después del lote y luego descarga. UnloadLibrary desconecta el proveedor de PDFium, libera el mapper de plataforma y vacía la caché antes de apagar PDFium, y se niega a correr mientras haya documentos abiertos. ClearSystemFontProvider va al final; levanta una excepción si PDFium sigue cargado, y resetea los contadores, así que léalos primero:

var
  Recorder: TRecordingFontProvider;
  RecorderRef: IPdfSystemFontProvider;   // mantiene el 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 y RenderCorpus son suyos; el lote debe
  // cerrar cada documento que abre antes de que UnloadLibrary corra
  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;               // desconecta el proveedor, luego apaga PDFium
  ClearSystemFontProvider;     // permitido solo cuando PDFium ya está descargado

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

Con el fallback apagado, DefaultFallbackHits se queda en cero y cada hueco aterriza en FailedRequests, a menudo junto con RejectedProviderResponses cuando el proveedor sí respondió pero la política rechazó el nombre o el tamaño. En un build de producción con fallback encendido, el mismo hueco se mueve a DefaultFallbackHits, y ese contador es el que hay que graficar: una subida después de que un cliente nuevo empieza a enviar documentos significa que una familia que su set de fuentes no cubre ahora se renderiza con lo que el host ofrezca. Las reglas de hilos para el resto del componente siguen la disciplina del lock de renderizado descrita por separado

La misma instancia de biblioteca maneja el aprovisionamiento de fuentes, el renderizado y la extracción de texto a través de Delphi, C++Builder y Lazarus, y la página de PDFium Component para Delphi cubre ediciones y despliegue de la biblioteca nativa