Artículo técnico

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

Una hoja de embalaje producida 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. Rasterizada dentro de un contenedor Debian, el mismo fichero dibuja cada glifo con un sans serif distinto. El texto sigue empezando donde debe, porque las posiciones de glifo vienen del array /Widths guardado en el PDF, pero las formas de las letras cambian, el espaciado se ve desigual allá donde los contornos del sustituto son más estrechos que las anchuras en las que se sientan, y un carácter que falta al sustituto deja un hueco. El renderizador no tiene la culpa. El documento entregó la elección de fuente a quien lo renderice, y esa elección se puede hacer en su propio código aportando bytes de fuente que distribuye con la aplicación

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

Un PDF de Delphi que nombra una fuente Arial sin incrustar se renderiza distinto en tres máquinas bajo el mapeador de host predeterminado pero igual una vez PDFium recibe los bytes de fuente empaquetados de un IPdfSystemFontProvider
PDFium pide bytes de fuente cada vez que un documento nombra una fuente que no incrusta; el proveedor sustituye la adivinanza por máquina del mapper del anfitrión por bytes que usted mismo distribuye

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

A veces esa es la respuesta, y cuando lo es, adóptela. Pero falla en tres situaciones habituales. La licencia puede prohibir instalar una fuente en un servidor para renderizado automatizado. Las imágenes de contenedor se reconstruyen con frecuencia y una fuente instalada a mano desaparece con el siguiente despliegue. Y los flujos de trabajo regulados necesitan que la pila de renderizado sea reproducible a partir de artefactos bajo control de versiones, cosa que una instalación de fuente a nivel de máquina no es

También hay un paso intermedio. TPdfLibraryConfiguration.UserFontPaths, pasada a través de ConfigurePdfLibrary antes de que la biblioteca cargue, dice al mapper nativo de PDFium qué carpetas escanear en busca de ficheros de fuente. La lista sustituye a los valores por defecto de la plataforma en lugar de añadirse a ellos, y en Windows además apaga la enumeración de fuentes GDI, así que incluya la carpeta de fuentes del sistema si los documentos aún necesitan fuentes instaladas. El mapper sigue decidiendo qué fichero gana para una solicitud dada, según sus propias reglas de coincidencia. Cuando necesite saber exactamente qué bytes responden a "Arial, bold, charset cirílico", esa decisión tiene que vivir en código que pueda leer, y eso es lo que le da un proveedor de fuentes del sistema

Instalar un IPdfSystemFontProvider antes de que PDFium cargue

PDFium Component expone la correspondencia 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 registro 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 ejecutarse antes de que la biblioteca esté cargada. PDFium toma su mapper de fuentes una sola vez, durante la inicialización, así que el componente lanza EPdfError ("Configure the system font provider before loading PDFium") si Loaded ya es true. Muchas llamadas cargan la biblioteca bajo demanda, incluidas las probes de funcionalidad, así que ponga la configuración al principio mismo del arranque. El proveedor de abajo construye una tabla de búsqueda y lee cada fichero de fuente en su constructor; después, 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, luego de solo lectura
    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: informar la familia realmente servida, para que la política la vea
  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 negrita
  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 abrir documentos; la primera llamada que necesita PDFium la carga
end;

Las claves de la tabla de este ejemplo son deliberadamente ingenuas. Los documentos reales escriben la misma familia de varias formas, así que registre Request.FaceName desde un lote representativo antes de congelar la tabla; el wrapper de grabación de más abajo produce exactamente esa lista. El umbral de grosor 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 en un lado o en el otro

Qué deciden realmente los indicadores de política

Cada solicitud sigue el mismo orden. El componente comprueba 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á activado; si no, la solicitud se cuenta como fallida y PDFium sigue sin su fuente

La validación en sí es breve. 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 desactivado, un nombre de cara informado que difiere del solicitado (comparado sin distinción de mayúsculas) también se rechaza. Esa comprobación lee el nombre que usted informa y nada más. Un proveedor que sirve bytes de Liberation Sans informando "Arial" pasa sin problema, que es por lo que el ejemplo informa la familia real para su alias Helvetica: con el flag desactivado, una solicitud Helvetica respondida con "Arial" se rechaza y aterriza en RejectedProviderResponses

Las puertas de validación de PDFium Component comprueban datos vacíos, tamaño MaxFontBytes, índice TTC y sustitución de fuente antes de que los bytes lleguen a PDFium, con AllowDefaultFallback decidiendo entre la reserva del host y una petición fallida
La validación corre dentro del componente antes de que cualquier byte del proveedor llegue a PDFium; con el retroceso desactivado, una fuente no mapeada falla con estruendo en lugar de renderizarse con un sustituto

El índice TTC se comprueba en otro punto. PDFium a menudo pide una tabla sfnt cada 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 empieza por el directorio seleccionado por TTCIndex; un índice pasado del número de fuentes de la cabecera ttcf, o un índice distinto de cero sobre un fichero 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 ficheros WOFF y WOFF2 tienen que descomprimirse a sfnt plano antes de que el proveedor los devuelva

TPdfSystemFontPolicy.Default activa los dos flags, con un techo de 64 MB por fuente y 32 entradas de caché. Eso conviene a un proveedor que se despliega pocas familias cada vez, donde todo lo que aún no ha mapeado sigue renderizando como lo hacía. Una build de auditoría debería apagar los dos flags. Los huecos aparecen entonces como fallos contados y sustituciones rechazadas, y un acierto de respaldo ya no puede esconder una familia que el conjunto de fuentes olvidó

¿Qué hilo llama a ResolveFont?

ResolveFont se ejecuta en el hilo que esté cargando o renderizando la página que necesita la fuente, que no tiene por qué ser el hilo principal. El componente protege su propia caché y sus contadores con una sección crítica, pero no mantiene ese bloqueo mientras su método se ejecuta. Si su aplicación renderiza en hilos secundarios, 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 se escape de ResolveFont en el límite con la biblioteca nativa y lo trata como una solicitud declinada, así que la solicitud sigue hacia el respaldo o el fallo. Contar con eso convierte un bug en su código de correspondencia en una fuente servida silenciosamente por otro. El wrapper de abajo registra cada fallo bajo un bloqueo y mantiene las excepciones locales, lo que también le da la lista de nombres de cara que añadir 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ístrelo aquí; no deje que llegue 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;

Sujete el recorder también 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 a memoria liberada. Para saber qué fuentes referencia un documento antes de que ocurra ningún renderizado, el listado por documento de analizar las propiedades de fuente de un PDF muestra las fuentes incrustadas y no incrustadas lado a lado

Dimensionar la caché de fuentes

Las solicitudes de correspondencia 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 distinción de mayúsculas), el grosor, el flag de cursiva, el charset y la familia de paso, y cuando se alcanza MaxCacheEntries se expulsa 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 lance "Invalid system font provider policy"

Los recuentos de entradas dicen poco sobre la 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 recuento máximo de bytes y compartido con las demás cachés del componente. También hay que fijarlo antes de que la biblioteca cargue. Cada entrada en caché se carga con 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 aunque su proveedor devuelva el mismo array cada vez. Cuando el governor rechaza una reserva la fuente se sirve igualmente, solo que sin caché. Mantenga vivo el objeto governor hasta que UnloadLibrary se haya ejecutado, ya que las entradas en caché mantienen reservas contra él

Demostrar la correspondencia en producción

GetSystemFontProviderStatistics devuelve un registro TPdfSystemFontStatistics. Configured e Installed dicen si hay un proveedor fijado y si se ha entregado a PDFium. MapRequests cuenta cada solicitud de correspondencia, y CacheHits, ProviderHits y DefaultFallbackHits muestran cómo se respondieron. FailedRequests cuenta las que no respondió nadie, y RejectedProviderResponses las respuestas que la política rechazó. Los campos restantes siguen las lecturas a nivel de tabla (FontDataRequests), los manejadores de fuente vivos, las fuentes en caché, los bytes en caché y las expulsiones

GetSystemFontProviderStatistics divide las peticiones de mapeo de fuentes PDFium en aciertos de caché, proveedor y reserva en una ejecución de conformidad 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 ejecución de conformidad puede afirmar; cualquier retroceso o petición fallida significa que el documento necesitaba una fuente que el conjunto no trae

Una ejecución 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 ejecutarse mientras queden documentos abiertos. ClearSystemFontProvider va el último; lanza una excepción si PDFium sigue cargado, y reinicia 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 abra antes de que UnloadLibrary se ejecute
  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 y después apaga PDFium
  ClearSystemFontProvider;     // permitido solo cuando PDFium está descargado

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

Con el respaldo desactivado, DefaultFallbackHits se queda en cero y cada hueco aterriza en FailedRequests, a menudo junto a RejectedProviderResponses cuando el proveedor respondió pero la política rechazó el nombre o el tamaño. En una build de producción con respaldo activado, 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 empiece a enviar documentos significa que una familia que su conjunto de fuentes no cubre se está renderizando con lo que el anfitrión ofrezca. Las reglas de hilos del resto del componente siguen la disciplina de bloqueo de renderizado descrita aparte

La misma instancia de biblioteca se encarga del aprovisionamiento de fuentes, del renderizado y de la extracción de texto en Delphi, C++Builder y Lazarus, y la página de PDFium Component para Delphi cubre ediciones y despliegue de la biblioteca nativa