기술 문서

PDFium으로 Delphi에서 PDF 폰트 대체 제어하기

Windows 책상에서 만든 packing slip은 폰트 딕셔너리에 Arial을 이름 짓고 폰트 프로그램은 실지 않으며, 그 책상의 모든 뷰어에서 멀쩡해 보입니다. 같은 파일을 Debian 컨테이너 안에서 래스터화하면 모든 글리프가 다른 산세리프에서 그려집니다. 텍스트는 여전히 제 자리에서 시작합니다. 글리프 위치는 PDF 안에 저장된 /Widths 배열에서 오기 때문입니다. 하지만 글자 모양은 바뀌고, 대체 폰트의 윤곽이 자리한 폭보다 좁은 곳에서는 자간이 들쭉날쭉해 보이며, 대체 폰트가 가진 글자가 빠진 곳에는 구멍이 남습니다. 렌더러가 잘못한 게 아닙니다. 문서가 폰트 선택을 렌더링하는 쪽에 넘겼고, 그 선택은 애플리케이션이 함께 배포하는 폰트 바이트를 공급함으로써 여러분 코드 안에서 내려질 수 있습니다

ISO 32000-1은 이를 허용합니다. §9.6.2.2의 표준 14 폰트는 언제나 이름만으로 참조될 수 있고, 다른 단순 폰트도 딕셔너리와 폰트 디스크립터(§9.8)가 메트릭스와 플래그를 기술해 주면 임베드하지 않고 남겨둘 수 있습니다. PDF/A는 아예 금지합니다(ISO 19005-1 §6.3.4가 모든 폰트 프로그램의 임베드를 요구하는데, 이름뿐인 폰트가 파일을 작성한 기계를 떠난 뒤 얼마나 믿기 어려운지를 잘 보여주는 대목입니다)

기본 호스트 매퍼 아래에서는 임베드되지 않은 Arial을 이름 지은 Delphi PDF가 세 기계마다 다르게 렌더링되지만, IPdfSystemFontProvider가 번들 폰트 바이트를 PDFium에 넘겨주면 동일하게 렌더링됨
PDFium은 문서가 임베드하지 않은 폰트를 이름 지을 때마다 폰트 바이트를 청구합니다. 프로바이더는 호스트 매퍼의 기계별 추측을 여러분이 직접 배포하는 바이트로 바꿉니다

왜 그냥 서버에 폰트를 설치하지 않을까?

폰트 설치로 충분한 때도 있습니다. 그러나 흔한 세 상황에서는 통하지 않습니다. 폰트 라이선스가 데스크톱 사용은 허용해도 문서를 자동으로 렌더링하는 서버에의 설치는 허용하지 않을 수 있습니다. 컨테이너 이미지는 자주 다시 만들어지고, 손으로 복사해 넣은 폰트는 다음 배포와 함께 사라집니다. 규제된 워크플로는 버전 관리되는 아티팩트부터 렌더링 스택이 재현 가능하기를 원하지, 기계 전역 폰트 폴더는 그런 아티팩트가 아닙니다

중간 단계도 있습니다. 라이브러리가 로드되기 전에 ConfigurePdfLibrary로 넘기는 TPdfLibraryConfiguration.UserFontPaths는 PDFium의 네이티브 매퍼에게 폰트 파일을 검색할 폴더를 알려줍니다. 이 목록은 플랫폼 기본값을 대체할 뿐 덧붙이지 않으므로, 문서가 여전히 설치된 폰트를 필요로 한다면 시스템 폰트 폴더도 목록에 넣어야 합니다. Windows에서는 GDI 폰트 열거도 함께 꺼지므로 마찬가지입니다. 매퍼는 여전히 자기 매칭 규칙으로 요청마다 어느 파일이 이기는지 정합니다. "Arial, bold, Cyrillic charset"에 정확히 어떤 바이트가 대답하는지 알아야 한다면 그 결정은 읽을 수 있는 코드 안에 있어야 하고, 시스템 폰트 프로바이더가 바로 그것을 줍니다

PDFium이 로드되기 전에 IPdfSystemFontProvider 설치하기

PDFium Component는 폰트 매핑을 메서드 하나짜리 인터페이스 하나로 노출합니다. IPdfSystemFontProvider.ResolveFont는 FaceName, Weight, Italic, Charset, PitchFamily를 실은 TPdfSystemFontRequest를 받고, 페이스 이름과 완전한 TrueType, OpenType, TrueType Collection 바이트, charset, TTCIndex를 담은 TPdfSystemFontData 레코드로 답합니다. False를 돌려주면 요청을 거절하는 것입니다

ConfigureSystemFontProvider는 라이브러리가 로드되기 전에 돌아야 합니다. PDFium은 초기화 시점에 단 한 번 폰트 매퍼를 받으므로, Loaded가 이미 참이면 컴포넌트는 EPdfError("Configure the system font provider before loading PDFium")를 raise합니다. 기능 탐침을 포함해 많은 호출이 필요할 때 라이브러리를 로드하므로, 설정은 시작 시점의 맨 위에 두십시오. 아래 프로바이더는 생성자에서 룩업 테이블을 만들고 모든 폰트 파일을 읽으며, 그 뒤의 ResolveFont는 읽기만 합니다:

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

type
  TBundledFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
  private
    FKeys: TStringList;           // 생성자에서 한 번 정렬, 이후 읽기 전용
    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 이상은 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;                // .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 별칭에 실제 패밀리를 보고하는 것입니다. 플래그가 꺼져 있으면 Helvetica 요청에 "Arial"로 답한 것은 거부되어 RejectedProviderResponses에 쌓입니다

PDFium Component 검증 게이트는 바이트가 PDFium에 닿기 전에 빈 데이터, MaxFontBytes 크기, 페이스 대체를 검사하고, AllowDefaultFallback이 호스트 폴백과 실패한 요청 사이를 결정함
검증은 프로바이더 바이트가 PDFium에 닿기 전에 컴포넌트 내부에서 돌아갑니다. 폴백이 꺼져 있으면 매핑 못한 요청이 FailedRequests에 한 번 집계되고 PDFium은 자체 내장 대체 폰트로 텍스트를 그립니다

TTC 인덱스는 다른 지점에서 검사됩니다. PDFium은 종종 cmap이나 glyf 같은 sfnt 테이블을 한 번에 하나씩 청구하는데, 컴포넌트는 돌려준 바이트의 테이블 디렉터리를 걸어 그 질의에 답합니다. 컬렉션이라면 TTCIndex가 가리키는 디렉터리에서 시작합니다. ttcf 헤더의 폰트 수를 넘는 인덱스, 단일 폰트 파일에 대한 0이 아닌 인덱스는 그 테이블 질의들이 아무것도 돌려주지 못하게 만듭니다. 디렉터리 순회는 TrueType(0x00010000과 true), CFF 윤곽의 OpenType(OTTO), 컬렉션(ttcf)을 인식합니다. WOFF와 WOFF2 파일은 프로바이더가 돌려주기 전에 평범한 sfnt로 풀어야 합니다

TPdfSystemFontPolicy.Default는 폰트당 64 MB 상한과 캐시 항목 32개로 두 플래그를 모두 켭니다. 패밀리를 조금씩 나눠 출시하는 프로바이더에는 알맞은 설정이고, 아직 매핑하지 못한 것은 전부 종전처럼 렌더링됩니다. 감사용 빌드는 두 플래그를 모두 꺼야 합니다. 빈틈이 집계된 실패와 거부된 대체로 드러나고, 폴백 적중이 폰트 세트가 빠뜨린 패밀리를 더 이상 감추지 못합니다

어느 스레드가 ResolveFont를 부를까?

ResolveFont는 그 폰트가 필요한 페이지를 로드하거나 렌더링 중인 스레드에서 돌며, 반드시 메인 스레드인 것은 아닙니다. 컴포넌트는 자기 캐시와 카운터를 크리티컬 섹션으로 보호하지만 여러분의 메서드가 도는 동안 그 락을 쥐고 있지 않습니다. 애플리케이션이 배경 스레드에서 렌더링한다면, 생성 이후 프로바이더가 바꾸는 상태에는 자체 보호가 필요합니다

예외는 메서드 안에 가둬야 할 두 번째 대상입니다. 컴포넌트는 네이티브 라이브러리 경계에서 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 폰트 속성 분석 문서의 문서별 목록이 임베드된 폰트와 그렇지 않은 폰트를 나란히 보여줍니다

폰트 캐시 크기 잡기

매핑 요청은 렌더링 도중 끊임없이 반복되므로 받아들여진 답은 캐시됩니다. 캐시 키는 페이스 이름(대소문자 무시), 가중치, 이탤릭 플래그, charset, pitch family를 포괄하고, MaxCacheEntries에 이르면 가장 오래 쓰이지 않은 항목이 축출됩니다. 0을 주면 캐싱이 꺼져 모든 요청이 프로바이더에 닿고 다시 검증됩니다. 음수 값이나 0 이하의 MaxFontBytes는 ConfigureSystemFontProvider로 하여금 "Invalid system font provider policy" 예외를 raise하게 만듭니다

CJK 컬렉션 하나가 20 MB를 넘을 수 있으니 항목 수는 메모리에 대해 거의 말해주지 않습니다. 바이트 예산이 필요하면 ConfigureSystemFontCacheGovernor가 FPdfCache 유닛의 TPdfCacheGovernor를 최대 바이트 수와 함께 붙여 컴포넌트의 다른 캐시와 공유하게 합니다. 이것도 라이브러리가 로드되기 전에 설정해야 합니다. 캐시 항목마다 폰트 데이터 전체 길이가 부과되므로, 20 MB 컬렉션이 서로 다른 네 charset의 요청에 답하면 프로바이더가 매번 같은 배열을 돌려줘도 예산에는 네 번 잡힙니다. 거버너가 예약을 거부해도 폰트는 계속 실려 나오며, 캐시에만 안 됩니다. 캐시 항목들이 거버너에 예약을 걸고 있으므로 거버너 객체는 UnloadLibrary가 돌 때까지 살려 두십시오

운영 환경에서 매핑 증명하기

GetSystemFontProviderStatistics는 TPdfSystemFontStatistics 레코드를 돌려줍니다. Configured와 Installed는 프로바이더 설정 여부와 PDFium에 넘겨졌는지를 말해 주고, MapRequests는 모든 매핑 요청을 세며, CacheHits, ProviderHits, DefaultFallbackHits는 어떻게 답했는지를 보여줍니다. FailedRequests는 아무도 답하지 못한 것, RejectedProviderResponses는 정책이 거부한 답을 셉니다. 나머지 필드들은 테이블 수준 읽기(FontDataRequests), 살아 있는 폰트 핸들, 캐시된 폰트, 캐시된 바이트, 축출을 추적합니다

DefaultFallbackHits나 FailedRequests가 나오면 실패 처리하는 Delphi 적합성 실행에서 GetSystemFontProviderStatistics가 PDFium 폰트 매핑 요청을 캐시, 프로바이더, 폴백 적중으로 나누는 모습
통계 레코드는 폰트 대체를 적합성 실행이 단언할 수 있는 대상으로 바꿔 줍니다. 폴백이든 실패한 요청이든 하나 있으면 문서가 폰트 세트에 없는 폰트를 필요로 했다는 뜻입니다

적합성 실행은 배치 뒤에 카운터를 읽고 언로드합니다. UnloadLibrary는 PDFium을 끄기 전에 프로바이더를 분리하고 플랫폼 매퍼를 해제하며 캐시를 비우고, 문서가 아직 열려 있으면 돌기를 거부합니다. ClearSystemFontProvider는 마지막에 옵니다. PDFium이 아직 로드되어 있으면 예외를 raise하고, 카운터를 리셋하므로 먼저 읽어 두십시오:

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는 0에 머물고 모든 빈틈은 FailedRequests로 들어가는데, 프로바이더가 답했지만 정책이 이름이나 크기를 거부한 경우에는 RejectedProviderResponses가 곁에 붙습니다. 폴백이 켜진 운영 빌드에서는 같은 빈틈이 DefaultFallbackHits로 옮겨 가며, 차트를 그릴 카운터는 바로 이것입니다. 새 고객이 문서를 보내기 시작한 뒤 이 수치가 오르면, 폰트 세트가 커버하지 못하는 패밀리가 지금 호스트가 주는 무엇이든 대신 렌더링되고 있다는 뜻입니다. 컴포넌트의 나머지 스레딩 규칙은 별도로 설명한 렌더 락 규율을 따릅니다

같은 라이브러리 인스턴스가 Delphi, C++Builder, Lazarus에서 폰트 프로비저닝, 렌더링, 텍스트 추출을 함께 맡으며, Delphi용 PDFium Component 페이지에 에디션과 네이티브 라이브러리 배포가 정리되어 있습니다