기술 문서

Delphi에서 CJK·이모지 텍스트의 자동 폰트 폴백

Arial로 짜인 송장 템플릿이 "Invoice for"까지 출력하고 그 뒤를 비워 둔다. 텍스트 호출은 1을 반환했고 파일은 검증을 통과했지만, 텍스트 추출 결과는 딱 열 글자 모자라다. 北京示例科技有限公司의 한자가 전부 사라진 것이다. Arial에는 그 글자들이 없다. PDF Library for Delphi의 자동 폰트 폴백은 기본으로 켜려 있어 이런 문자를 설치된 서체에서 끌어 오고, AddFontFallback으로 탐색 순서를 직접 정하며, 어떤 서체도 그리지 못하는 문자는 JSON 리포트를 갖춘 누락 글리프 정책이 처리한다

조용히 사라진다는 점이 비용을 키운다. 거래처 이름이 있어야 할 자리가 빈 채인 PDF는 구조 검사를 모두 통과하고 모든 뷰어에서 열리며, 보통은 테스트 스위트가 아니라 고객이 먼저 발견한다

지원되지 않는 텍스트는 왜 오류를 내는 대신 사라지는가?

PDF에는 폰트가 문자를 거부한다는 개념 자체가 없으므로, 누락 글리프는 파일 수준에서는 오류가 아니다. 단순 폰트는 인코딩을 통해 1바이트 코드를 글리프 이름으로 사상하고, 복합 폰트는 CMap을 거쳐 코드를 CID로, 다시 글리프 인덱스로 사상한다. 서체에 없는 것을 요청하면 글리프 인덱스 0, 곧 .notdef에 떨어지는데, ISO 32000-1 §9.7.6.3은 이를 정의되지 않은 문자의 표준 결과로 다룬다. 대부분의 서체는 .notdef를 아예 그리지 않는다. 빈 상자를 그리는 서체도 있다

어느 쪽이든 콘텐츠 스트림은 잘 구성되어 있고 페이지는 렌더링된다. 규격은 어디에도 텍스트 연산자를 쓰기 전에 커버리지를 확인하라고 요구하지 않으므로, 확인을 건너뛰는 생성기는 콘텐츠를 조용히 잃은 규격 준수 파일을 만들어 낸다. 폴백과 보고가 한 세트인 이유가 이것이다. 해결할 수 있는 것을 해결하는 것이 일의 절반이고, 나머지를 알려 주는 것이 나머지 절반이다. 그리고 이름이나 금액이 들어가는 문서라면 후자가 더 중요하다고 우리는 본다

PDF Library for Delphi에서 폴백 체인 켜기

폴백은 선택된 폰트가 문자열 안의 문자를 실제로 빠뜨릴 때만 개입하므로, Latin 전용 텍스트는 평소 경로를 유지하고 추가 비용도 없다. 새 TPDFlib 인스턴스는 자동 폴백이 이미 켜져 있으므로 드로잉 코드에 추가 호출이 전혀 필요 없다:

var
  Lib: TPDFlib;
begin
  Lib := TPDFlib.Create;
  try
    // 자동 폴백은 기본으로 켜져 있다: 이모지, 가나, 한글,
    // 한자와 기호는 내장 후보 표에서 찾는다
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);

    Lib.AddTrueTypeFont('Arial', 2);   // 2 = 서브셋으로 임베드
    Lib.SetTextSize(11);
    Lib.DrawText(72, 720, 'Invoice for 北京示例科技有限公司');
    Lib.DrawText(72, 700, 'Delivery status: on time ✅');

    Lib.SaveToFile('invoice.pdf');
  finally
    Lib.Free;
  end;
end;

자동 폴백이 켜져 있으면 라이브러리는 해석되지 않은 문자 각각의 문자 체계에 따라 후보를 고른다. 이 표는 고정되어 있고 Windows 지향이다. 이모지와 픽토그래프는 Segoe UI Emoji, Segoe UI Symbol, Arial Unicode MS 순으로 시도하고, 가나는 Yu Gothic을 먼저 시도하며, 한글은 Malgun Gothic을 먼저 시도한다. 통합 한자 블록은 Microsoft YaHei, Microsoft JhengHei, Yu Gothic, Malgun Gothic, SimSun 순으로 시도하고, 수학·기술 기호는 Segoe UI Symbol과 Cambria Math로 간다. 나머지는 Nirmala UI와 Segoe UI로 시작하는 넓은 목록으로 넘어간다

AddFontFallback으로 등록한 서체는 그 내장 표보다 먼저, 그리고 추가한 순서대로 시도된다. SetAutomaticFontFallback(0)은 내장 표만 끈다. 명시적 체인은 계속 동작하므로, 출력이 승인된 서체만 쓰길 원할 때 고르는 설정이다. AddFontFallback은 이미 목록에 있는 이름을 무시하고 그 1 기반 위치를 반환하며, ClearFontFallbacks, RemoveFontFallback, GetFontFallbackCount로 문서 사이에서 체인을 다시 구성할 수 있다

한자 통합의 함정: 공유 문자는 누가 이기는가?

중국어, 일본어, 한국어는 Unicode의 한자 표의문자 대부분을 공유하지만, 로케일마다 기대하는 자형은 많이 다르다. 直이나 骨의 코드 포인트는 도쿄 주소와 베이징 주소에서 같다. 그러나 현지 독자가 기대하는 모양은 같지 않다. 폴백 체인은 "설치된 어느 서체가 이 코드 포인트의 글리프를 갖고 있는가"에만 답하고, CJK 서체라면 모두 갖고 있으므로 체인에서 먼저 나오는 서체가 공유 문자를 전부 가져간다

자동 표는 한자에 Microsoft YaHei를 먼저 놓는다. 간체 중국어에는 맞고 일본어에는 틀리다. 그 송장의 일본 주소는 한 줄 안에서 가나는 Yu Gothic이 그리고(가나는 일본어 서체를 먼저 찾는다) 한자는 중국식 자형의 YaHei가 그리는 결과가 나온다. 빠진 글자는 없고 리포트도 비어 있지만, 일본어 독자는 뭔가 어긋났음을 바로 알아본다

권장 방식은 한자에 대해 자동 순서에 기대지 않고 문서의 로케일에서 명시적 체인을 만드는 것이다. 로케일은 보통 이미 알고 있다. 고객 레코드나 템플릿 언어에서:

procedure ConfigureFallback(Lib: TPDFlib; const Locale: string);
begin
  Lib.ClearFontFallbacks;
  if Locale = 'ja' then
  begin
    Lib.AddFontFallback('Yu Gothic');
    Lib.AddFontFallback('Meiryo');
  end
  else if (Locale = 'zh-TW') or (Locale = 'zh-HK') then
    Lib.AddFontFallback('Microsoft JhengHei')
  else if Locale = 'ko' then
    Lib.AddFontFallback('Malgun Gothic')
  else
    Lib.AddFontFallback('Microsoft YaHei');
  // 이모지, 기호, 위에서 커버되지 않은 문자 체계는 여전히
  // 내장 후보를 거친다. 막으려면 여기서 0을 넘긴다
  Lib.SetAutomaticFontFallback(1);
end;

문서마다 첫 DrawText 전에 한 번 호출한다. 명시적 목록 안의 순서도 똑같이 중요하다. 문자를 커버하는 첫 번째 서체가 이기므로 Arial Unicode MS 같은 범용 Unicode 서체는 어차피 넣을 거라면 끝에 둔다. 앞에 두면 거의 모든 것을 그 서체가 그려 버리고, 신중하게 골라 둔 문자 체계별 서체는 영영 호출되지 않는다

폴백은 클러스터 전체 단위로 동작한다

PDF Library for Delphi는 그래프 클러스터 단위로 폴백을 결정하므로 하나의 클러스터는 항상 하나의 서체가 그린다. 데바나가리 음절, 피부톤 변형자가 붙은 이모지, 결합 악센트가 붙은 기본 문자는 각각 화면에서 한 단위이고, 그 안의 셰이핑 결정은 특정 한 폰트의 표에서 나온다. 클러스터의 절반은 Arial이, 나머지 절반은 폴백 서체가 그리면 기술적으로는 존재하지만 눈에 띄게 깨진 글리프가 페이지에 놓인다. 빈 칸보다 못한 결과다

선택된 폰트가 먼저 문자열을 셰이핑한다. 글리프 0으로 돌아온 클러스터만 다른 서체를 찾고, 같은 서체로 해석되는 인접 클러스터는 하나의 런으로 묶여 함께 그려진다. 열 글자짜리 중국어 이름이 열 번의 폰트 전환이 아니라 YaHei 런 하나가 되는 이유다. 오른쪽에서 왼쪽 순서도 유지된다. 아랍어나 히브리어 텍스트 안의 폴백 런은 쌍방향 알고리즘이 놓아 둔 자리에 앉는다. 같은 셰이핑 장치가 일본어·중국어 세로쓰기도 떠받친다

PDF Library for Delphi 폴백 체인 다이어그램: CJK 클러스터 런이 기본 Arial 서체에서 빠지면 첫 번째 커버 폴백인 Microsoft YaHei가 그리고, 커버되지 않은 클러스터는 report 또는 abort 정책을 따른다
이 클러스터 런은 기본 서체를 통과해 첫 번째 커버 폴백으로 넘어가고, 실제로 쓰인 서체만 임베드된다. 어떤 서체도 그리지 못하는 클러스터는 누락 글리프 정책을 따른다. report하고 계속하거나 오류 521로 중단한다

누락 글리프가 문서를 멈춰야 할까?

문서가 무엇을 위한 것인지에 달려 있고, PDF Library for Delphi는 SetMissingGlyphPolicy로 선택하게 해 준다. PDF_MISSING_GLYPH_REPORT가 기본값이다. 텍스트 작업은 진행되고, 어떤 서체도 그리지 못하는 문자는 출력에서 빠지며 각각 기록된다. PDF_MISSING_GLYPH_ABORT는 페이지에 무엇이든 쓰기 전에 텍스트 작업 전체를 거부하고, DrawText는 0을 반환하며 오류 코드는 521(PDFLIB_ERROR_MISSING_GLYPH)다

사내 배치 리포트라면 report 정책을 택하고 빠진 부분을 로그로 남긴다. 약간 불완전한 오늘의 리포트가 리포트 없음보다 낫다. 계약서, 송장, 증명서 등 사람이나 회사 이름이 실리는 모든 문서는 abort를 택한다. 거래처 이름에서 글자가 하나 빠지는 결함은 자기 파이프라인 안에서 잡고 싶은 결함이고, abort는 쓰기 전에 일어나므로 절반만 그려진 줄이 페이지에 남지 않는다

var
  Lib: TPDFlib;
  Err: Integer;
  Report: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_ABORT);
    Lib.AddTrueTypeFont('Arial', 2);
    Lib.SetTextSize(11);

    if Lib.DrawText(72, 660, CustomerName) <> 1 then
    begin
      Err := Lib.LastErrorCode;   // 읽는 동시에 0으로 리셋된다
      if Err = PDFLIB_ERROR_MISSING_GLYPH then
      begin
        Report := Lib.GetMissingGlyphReportJSON;
        // {"valid":false,"policy":1,"eventCount":1,"events":[
        //   {"sequence":1,"documentIndex":0,"page":1,"utf16Index":3,
        //    "codePoint":983041,"unicode":"U+F0001",
        //    "fontName":...,"fontType":...,"operation":"DrawText"}]}
        EscalateToOperator(Report);
      end;
    end;
  finally
    Lib.Free;
  end;
end;

지역 변수에 주목하자. LastErrorCode는 읽는 순간 자기 자신을 지운다. 한 곳에서 Lib.LastErrorCode = 0을 검사하고 다른 곳에서 Lib.LastErrorCode를 로그로 남기는 코드는 0을 남긴다. 한 번만 읽고 값을 저장해 두자

리포트 이벤트마다 페이지, 문자열 안의 UTF-16 인덱스, 10진수와 U+XXXX 형태의 코드 포인트, 선택된 폰트와 그 타입, 문제를 맞닥뜜린 API 호출이 담긴다. 덕분에 지원 티켓이 증상 묘사 대신 정확한 문자를 지목한다. valid 플래그는 이벤트가 하나도 기록되지 않았을 때만 true이므로 배치 작업의 값싼 게이트로 쓸 만하다

라이브러리는 최근 256개 이벤트만 유지하고 오래된 것은 버린다. 렌더링 불가능한 텍스트로 가득한 문서가 진단을 메모리 문제로 바꾸지 못한다는 뜻이다. 이벤트는 같은 TPDFlib 인스턴스에서 문서를 넘어 누적된다. 파일당 리포트 하나를 원하면 문서마다 ClearMissingGlyphReport를 호출하거나 documentIndex 필드로 구분하라

문자는 중단하고, 장식은 용인하기

문서 전체에 하나의 정책은 때때로 너무 둔하다. 배송 라벨이 수취인 이름 옆에 장식용 이모지를 달고 있을 수 있고, 라벨을 거부하기보다는 이모지를 포기하는 편이 낫다. OnMissingGlyph 이벤트는 체인의 어떤 서체도 그리지 못한 모든 문자마다 발화하고, 정책을 기본 액션으로 받으며, 코드 포인트별로 이를 재정의할 수 있다:

type
  TGlyphGate = class
    procedure MissingGlyph(Sender: TObject; CodePoint: Cardinal;
      UTF16Index, Page: Integer; const FontName, Operation: WideString;
      var Action: Integer);
  end;

procedure TGlyphGate.MissingGlyph(Sender: TObject; CodePoint: Cardinal;
  UTF16Index, Page: Integer; const FontName, Operation: WideString;
  var Action: Integer);
begin
  // 픽토그래프와 딩뱃은 장식이다: 빠뜨리고 기록한다
  if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
     ((CodePoint >= $2600) and (CodePoint <= $27BF)) then
    Action := PDF_MISSING_GLYPH_REPORT
  else
    Action := PDF_MISSING_GLYPH_ABORT;   // 문자와 숫자가 사라져서는 안 된다
end;

// 연결하기
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;

이벤트는 폴백이 기회를 다 얻은 뒤에 동작하므로 이 머신에서 정말로 해결 불가능한 문자만 눈에 들어온다. 그런 문자는 핸들러가 어떤 액션을 택하든 모두 JSON 리포트에 기록된다

측정, 임베드, 배포

GetTextWidth는 DrawText와 똑같은 클러스터별 폴백 결정을 거친다. 당연하게 들리지만, 직접 만든 폴백 레이어가 정확히 여기서 잘못되곤 한다. 드로잉 호출만 고치고 측정은 기본 폰트에 맡겨 두면, 오른쪽 정렬된 합계와 테이블 칼럼 전부가 페이지에 실제 놓이는 것과 맞지 않는 폭으로 계산된다. 여기서는 그리기 전에 측정한 문자열이 폴백 런을 포함해 측정 당시의 폭을 그대로 차지한다. 손으로 검증해 둔 템플릿 몇 개가 아니라 모든 곳에서 폴백을 켜 둬도 되는 근거다

abort 정책에서의 한 가지 결과: 측정이 해결 불가능한 문자를 만나면 GetTextWidth는 0을 반환하고 오류 521을 설정한다. 폭으로 나누거나 폭으로 셀 크기를 정하는 레이아웃 코드는 그 숫자를 쓰기 전에 이를 검사해야 한다

폴백 서체는 실제로 무언가를 그렸을 때만 임베드된다. 체인 안에서 클러스터를 한 번도 해석하지 않은 서체는 파일에 아무것도 추가하지 않고, 해석한 서체는 그린 글리프의 서브셋으로 임베드된다. Latin 5,000자 사이에 한자 하나가 있는 문서는 메가바이트급 CJK 폰트가 아니라 한자 글리프 하나를 싣는다. 그 서브셋이 어떻게 만들어지는지는 파일 크기 최적화와 폰트 서브셋이 다룬다. 그래서 서비스하는 모든 로케일을 커버하는 긴 체인도 설정 비용이 저렴하고, 각 PDF는 자기가 쓴 것만 값을 지불한다. 다른 곳에서 만들어졌는데 폰트를 임베드하지 않고 참조만 하는 파일은 별개의 수리 대상이며, 기존 PDF에 누락 폰트 임베드하기에서 설명한다

배포 관련 주의사항은 놓치기 쉽다. 폴백은 코드를 실행하는 머신에 설치된 폰트를 대상으로 해석되는데, Office를 통째로 깐 개발 워크스테이션은 골 빠진 서버 이미지나 컨테이너보다 폰트가 훨씬 많다. Yu Gothic이나 Microsoft YaHei가 그 자리에 없으면 체인은 폴백할 곳이 없다. 한자 이름, 한글 이름, 이모지를 하나씩 넣은 문서를 대상 서버에서 하나 돌리고 JSON 리포트를 읽어라. 거기서 events 배열이 비어 있다면 자기 데스크톱의 어떤 테스트보다 많은 것을 알려 준다. 의존하는 폰트를 함께 배포하고, 라이선스가 임베드를 허용하는지도 확인하라

같은 폴백 체인, 누락 글리프 정책, 리포트는 DLL과 ActiveX 에디션에도 노출되어 있으므로 C#, C++ 또는 스크립트 호출자도 같은 호출로 설정한다. 레퍼런스 문서와 다운로드는 PDF Library for Delphi 제품 페이지에 있다