技術記事

PDFiumでDelphiのPDFフォント置換を制御する

Windowsデスクで作られた納品書は、フォント辞書でArialを名指し、フォントプログラムを1つも運んでいませんが、そのデスクのどのビューアでも問題なく見えます。同じファイルをDebianコンテナの中でラスタライズすると、すべてのグリフが別のサンセリフで描かれます。文字の開始位置は正しいままです。グリフ位置はPDFに保存された/Widths配列から来るからです。しかし字形は変わり、代替フォントのアウトラインがその場所の幅より狭いところでは間隔が不均一に見え、代替フォントが持っていない文字は穴になります。レンダラーのせいではありません。ドキュメントがフォントの選択を、レンダリングする側に委ねたのです。そしてその選択は、アプリケーションに同梱するフォントバイトを供給すれば、自分のコードの中で行えます

ISO 32000-1はこれを許しています。§9.6.2.2の標準14フォントは常に名前だけで参照でき、それ以外のシンプルフォントも、辞書とフォントディスクリプタ(§9.8)がメトリクスとフラグを記述している限り、非埋め込みのままで構いません。PDF/Aはこれを丸ごと禁じています(ISO 19005-1 §6.3.4がすべてのフォントプログラムの埋め込みを要求)。名前だけのフォントが、書き出したマシンの外ではどれほど信頼できないか、この一件事が物語っています

非埋め込み Arial フォントを名指す Delphi PDF は、既定ホストマッパー下では 3 台のマシンで異なる描画になる一方、PDFium が IPdfSystemFontProvider からバンドルフォントバイトを受け取れば同一に描画
PDFium は、ドキュメントが埋め込んでいないフォントを名指しするたびにフォントバイトを要求します。プロバイダーは、ホストのマッパーのマシンごとの推測を、自分で出荷するバイトに置き換えます

サーバーにフォントをインストールするだけではだめなのか?

フォントをインストールすれば済むこともあります。それでも、よくある3つの状況では破綻します。フォントのライセンスが、デスクトップ用途は許しても、ドキュメントを自動でレンダリングするサーバーへのインストールを許さないことがあります。コンテナイメージは再構築が頻繁で、手でコピーしたフォントは次のデプロイで消えます。規制されたワークフローは、バージョン管理下の成果物からレンダリングスタックを再現できることを求めますが、マシン全体のフォントフォルダはその条件を満たしません

中間の段階もあります。TPdfLibraryConfiguration.UserFontPathsは、ライブラリのロード前にConfigurePdfLibrary経由で渡すと、PDFiumのネイティブマッパーに対して、どのフォルダをフォントファイルの走査対象にするかを伝えます。このリストはプラットフォームの既定値に追記するのではなく置き換えるもので、WindowsではGDIフォント列挙もオフにします。そのため、インストール済みフォントをドキュメントがまだ必要とするなら、システムフォントフォルダをリストに入れてください。どのファイルが要求に勝つかは、相変わらずマッパーが自分のマッチング規則で決めます。"Arial、ボールド、Cyrillic文字セット"にどのバイトが応えたのか正確に知る必要があるなら、その決定は読めるコードの中に置かれるべきで、それこそシステムフォントプロバイダーの役目です

PDFiumのロード前にIPdfSystemFontProviderをインストールする

PDFium Componentは、フォントマッピングを1つのメソッドを持つ1つのインターフェースで公開します。IPdfSystemFontProvider.ResolveFontは、FaceName、Weight、Italic、Charset、PitchFamilyを運ぶTPdfSystemFontRequestを受け取り、フェイス名、TrueType、OpenType、TrueType Collectionの完全なバイト列、文字セット、TTCIndexを保持するTPdfSystemFontDataレコードで答えます。Falseを返せば要求を辞退します

ConfigureSystemFontProviderは、ライブラリのロード前に実行しなければなりません。PDFiumはフォントマッパーを初期化時に1回だけ受け取るため、Loadedがすでにtrueなら、コンポーネントはEPdfError("Configure the system font provider before loading PDFium")を上げます。多くの呼び出しは機能プローブも含めてライブラリを必要時にロードするので、設定は起動処理の最上部に置いてください。下のプロバイダーはルックアップテーブルを組み立て、コンストラクタで全フォントファイルを読みます。その後のResolveFontは読むだけです

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

type
  TBundledFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
  private
    FKeys: TStringList;           // コンストラクタで1回ソート、以後は読み取り専用
    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);
  // エイリアス:実際に提供するファミリーを報告し、ポリシーから見えるようにする
  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以上はボールドとして提供
  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;                // .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);
  // ここからドキュメントを開く。PDFiumを必要とする最初の呼び出しがロードする
end;

このサンプルのテーブルキーは意図的に素朴です。実際のドキュメントは同じファミリーを何通りにも綴るので、テーブルを固める前に代表的なバッチからRequest.FaceNameをログに取ってください。下の方にある記録ラッパーが、まさにそのリストを作ります。ウェイトの閾値も選択です。FPdfExtensionsユニットではFXFONT_FW_NORMALが400、FXFONT_FW_BOLDが700で、600のセミボールド要求はどちらかに着地しなければなりません

ポリシーフラグが実際に決めていること

すべての要求は同じ順序を通ります。コンポーネントはまず自分のキャッシュを確認し、次にあなたのプロバイダーを呼び、それから答えを検証します。受け入れられた答えはキャッシュされ、PDFiumへ渡されます。辞退されたり拒否されたりした答えは、FPDF_GetDefaultSystemFontInfoが返すプラットフォームマッパーへ行きますが、それはAllowDefaultFallbackがオンのときだけです。オフなら要求は失敗として数えられ、PDFiumはあなたのフォントなしで処理を進めます

検証そのものは短いです。空のFontDataは拒否され、MaxFontBytesより長いものも拒否されます。答えの中の空のFaceNameは要求された名前で埋められます。AllowFaceSubstitutionがオフのとき、報告されたフェイス名が要求と異なる(大文字小文字を無視して比較)場合も拒否されます。このチェックが読むのは、あなたが報告した名前だけで、それ以外は何も読みません。Liberation Sansのバイトを"Arial"と報告して提供するプロバイダーは素通りします。だからこそサンプルは、Helveticaのエイリアスに対して実際のファミリーを報告しているのです。フラグがオフなら、"Arial"で答えられたHelvetica要求は拒否され、RejectedProviderResponsesへ落ちます

PDFium Component の検証ゲートが、バイトが PDFium に届く前に空データ、MaxFontBytes サイズ、フェイス代替を確認。AllowDefaultFallback がホストフォールバックと失敗要求を決める
検証はコンポーネントの内側、プロバイダーのバイトが 1 つも PDFium に届く前に走ります。フォールバックがオフのとき、対応付けられない要求は FailedRequests に 1 回だけ数えられ、PDFium はテキストを内蔵の代替フォントで描きます

TTCインデックスは別の場所でチェックされます。PDFiumはしばしばsfntテーブルを1つずつ要求します(cmapやglyfなど)。コンポーネントは、あなたが返したバイトのテーブルディレクトリを辿ってこうした問いに答えます。コレクションの場合はTTCIndexが選んだディレクトリから始めます。ttcfヘッダーのフォント数を超えるインデックスや、単一フォントファイルへのゼロでないインデックスは、それらのテーブル問い合わせを空返しにします。ディレクトリ走査はTrueType(0x00010000とtrue)、CFFアウトラインのOpenType(OTTO)、コレクション(ttcf)を認識します。WOFFとWOFF2のファイルは、プロバイダーが返す前に素のsfntへ展開されていなければなりません

TPdfSystemFontPolicy.Defaultは両方のフラグをオンにし、フォントあたり64 MBの上限と32キャッシュエントリを設定します。これは、ファミリーを少数ずつ展開していくプロバイダーに向いています。まだマップしていないものは従来どおり描画され続けます。監査ビルドでは両方のフラグをオフに切り替えるべきです。欠けは数えられた失敗と拒否された代替として表面化し、フォールバックのヒットが、フォントセットが忘れたファミリーを隠すことはもうありません

どのスレッドがResolveFontを呼ぶのか?

ResolveFontは、フォントを必要とするページをロードあるいはレンダリングしているスレッドで実行されます。それは必ずしもメインスレッドではありません。コンポーネントは自分のキャッシュとカウンタをクリティカルセクションで守りますが、あなたのメソッドが走っている間はそのロックを保持しません。アプリケーションがバックグラウンドスレッドでレンダリングするなら、プロバイダーが構築後に変更する状態には、自分自身のガードが必要です

メソッドの内側に留めるべき2つ目のものは例外です。コンポーネントはネイティブライブラリとの境界で、ResolveFontから漏れたものをすべて捕捉し、辞退された要求として扱います。要求はフォールバックか失敗へ続きます。それに頼ると、マッピングコードのバグが、こっそり誰か別のフォントで済まされる状態に変わります。下のラッパーはすべてのミスをロック下で記録し、例外を局所に留めます。おまけに、テーブルへ追加すべきフェイス名のリストも手に入ります

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;            // ここで記録する。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;

レコーダーは、オブジェクト変数に加えてインターフェース変数経由でも保持してください。コンポーネントは自分のインターフェース参照を持ち、ClearSystemFontProviderがそれを手放します。それが最後の参照だった場合、オブジェクトも一緒に消え、素のクラス変数は解放済みメモリを指します。レンダリングが始まる前にドキュメントがどのフォントを参照しているか調べるには、PDFフォントプロパティの分析にある文書単位の一覧が、埋め込みフォントと非埋め込みフォントを並べて示してくれます

フォントキャッシュのサイズ設定

マッピング要求はレンダリング中に絶えず繰り返されるため、受け入れられた答えはキャッシュされます。キャッシュキーはフェイス名(大文字小文字を無視)、ウェイト、イタリックフラグ、文字セット、ピッチファミリーを網羅し、MaxCacheEntriesに達すると最も使われていないエントリが追い出されます。0はキャッシュの停止で、すべての要求がプロバイダーへ届き、再度検証されます。負の値や、ゼロ以下のMaxFontBytesは、ConfigureSystemFontProviderに"Invalid system font provider policy"を上げさせます

1つのCJKコレクションが20 MBを超えられるとなると、エントリ数だけではメモリの見当がつきません。バイト予算のためには、ConfigureSystemFontCacheGovernorがFPdfCacheユニットのTPdfCacheGovernorを取り付けます。最大バイト数を指定して作成し、コンポーネントの他のキャッシュと共有します。これもライブラリのロード前に設定しなければなりません。キャッシュされた各エントリはフォントデータの全長で課金されるため、4つの異なる文字セットの要求に答える20 MBのコレクションは、プロバイダーが毎回同じ配列を返していても、予算に対して4回数えられます。ガバナーが予約を拒否しても、フォントは提供されます。ただしキャッシュされないだけです。ガバナーオブジェクトはUnloadLibraryが走るまで生存させてください。キャッシュされたエントリはガバナーに対する予約を保持しているからです

本番環境でマッピングを証明する

GetSystemFontProviderStatisticsはTPdfSystemFontStatisticsレコードを返します。ConfiguredとInstalledは、プロバイダーが設定されているか、PDFiumに引き渡されたかを示します。MapRequestsはすべてのマッピング要求を数え、CacheHits、ProviderHits、DefaultFallbackHitsがその答え方を示します。FailedRequestsは誰も答えなかったものを、RejectedProviderResponsesはポリシーが拒否した答えを数えます。残りのフィールドは、テーブルレベルの読み出し(FontDataRequests)、生存中のフォントハンドル、キャッシュ済みフォント、キャッシュ済みバイト、追い出しを追跡します

GetSystemFontProviderStatistics が PDFium フォントマッピング要求をキャッシュ、プロバイダー、フォールバックのヒットへ分割。DefaultFallbackHits や FailedRequests が現れると例外を発生させる Delphi 適合実行
統計レコードがフォント代替を、適合実行がアサートできるものへ変えます。フォールバックや失敗した要求は、ドキュメントがそのセットにないフォントを必要としたことを意味します

適合実行は、バッチの後にカウンタを読み、それからアンロードします。UnloadLibraryは、PDFiumをシャットダウンする前に、プロバイダーをPDFiumから切り離し、プラットフォームマッパーを解放し、キャッシュを空にします。そしてドキュメントがまだ開いている間は実行を拒否します。ClearSystemFontProviderは最後に来ます。PDFiumがまだロードされていれば上げられ、カウンタをリセットするので、先に読んでください

var
  Recorder: TRecordingFontProvider;
  RecorderRef: IPdfSystemFontProvider;   // オブジェクトを生存させ続ける
  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、RenderCorpusは自分のもの。バッチは
  // UnloadLibraryの実行前に開いたドキュメントをすべて閉じること
  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;               // プロバイダーを切り離してからPDFiumをシャットダウンする
  ClearSystemFontProvider;     // PDFiumのアンロード後にのみ許可される

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

フォールバックがオフのとき、DefaultFallbackHitsはゼロのままですべての欠けがFailedRequestsに落ちます。プロバイダーは答えたけれどポリシーが名前やサイズを拒否した場合には、RejectedProviderResponsesも並んでよく起こります。フォールバックがオンの本番ビルドでは、同じ欠けはDefaultFallbackHitsへ移り、グラフ化すべきはこのカウンタです。新しい顧客がドキュメントを送り始めた後にこの数が増えたら、フォントセットがカバーしていないファミリーが、ホストの提供するもので描画され始めた合図です。コンポーネントの残りの部分のスレッド規則は、別途説明しているレンダーロック規律に従います

同じライブラリインスタンスが、Delphi、C++Builder、Lazarusにわたってフォント供給、レンダリング、テキスト抽出を担います。PDFium Component for Delphiページが、エディションとネイティブライブラリの配置を扱います