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가 모든 폰트 프로그램의 임베드를 요구하는데, 이름뿐인 폰트가 파일을 작성한 기계를 떠난 뒤 얼마나 믿기 어려운지를 잘 보여주는 대목입니다)
왜 그냥 서버에 폰트를 설치하지 않을까?
폰트 설치로 충분한 때도 있습니다. 그러나 흔한 세 상황에서는 통하지 않습니다. 폰트 라이선스가 데스크톱 사용은 허용해도 문서를 자동으로 렌더링하는 서버에의 설치는 허용하지 않을 수 있습니다. 컨테이너 이미지는 자주 다시 만들어지고, 손으로 복사해 넣은 폰트는 다음 배포와 함께 사라집니다. 규제된 워크플로는 버전 관리되는 아티팩트부터 렌더링 스택이 재현 가능하기를 원하지, 기계 전역 폰트 폴더는 그런 아티팩트가 아닙니다
중간 단계도 있습니다. 라이브러리가 로드되기 전에 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에 쌓입니다
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), 살아 있는 폰트 핸들, 캐시된 폰트, 캐시된 바이트, 축출을 추적합니다
적합성 실행은 배치 뒤에 카운터를 읽고 언로드합니다. 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 페이지에 에디션과 네이티브 라이브러리 배포가 정리되어 있습니다