기술 문서

PDFium 라이브러리 설정: Brotli가 Skia를 AGG로 바꾸는 이유

BrotliEnabled나 IsolatePerDocument를 켜면 FPDF_LIBRARY_CONFIG가 PDFium이 m_RendererType을 문자 그대로 읽는 버전으로 올라가므로, "default"라는 뜻으로 AGG를 써 넣는 래퍼는 오류 하나 없이 Skia 빌드를 AGG 렌더러로 조용히 바꿔 버립니다. Delphi용 PDFium Component에서 TPdfLibraryConfiguration은 기본 렌더러를 DLL 자신의 기본값으로 유지하고, DLL이 존중할 수 없는 Skia나 Fontations 요청은 프로세스를 죽이는 대신 잡을 수 있는 EPdfError로 돌려줍니다

두 함정은 정반대 방식으로 실패합니다. 첫 번째는 다른 래스터라이저가 그려 준, 그럴듯해 보이는 페이지를 만듭니다. 출시하고 검증한 빌드와 미세하게 다른 안티앨리어싱과 텍스트 가장자리를 가진 채로요. 두 번째는 네이티브 초기화 내부에서 호스트 프로세스를 끌어내리며 큰 소리로 자신을 알립니다. 둘 다 같은 곳에서 옵니다: 버전 번호가 그렇다고 말할 때만 필드가 유효해지는 버전 관리된 C 구조체이며, 그 0 값은 "unset"이 아니라 실제 선택이라는 것입니다

FPDF_LIBRARY_CONFIG는 PDFium이 어떤 렌더러를 쓸지 어떻게 정할까?

FPDF_InitLibraryWithConfig는 구조체의 Version 필드가 4 이상일 때만 m_RendererType을 참조하고, 그 버전부터는 쓰인 값 그대로 사용합니다. 버전 4 미만에서는 PDFium이 이 필드를 무시하고 빌드 기본값을 택하며, PDF_USE_SKIA로 컴파일된 빌드에서는 Skia, 그 외에서는 AGG입니다

이후의 각 필드는 같은 패턴을 따릅니다. 구조체는 한 번에 기능 하나씩 자랐고, 각 기능은 새 버전 번호와 함께 도착했습니다. PDFium Component는 LoadLibrary에서 여러분의 TPdfLibraryConfiguration으로 네이티브 구조체를 만들며, 설정한 옵션이 요구하는 만큼만 버전을 올립니다

구조체 버전추가되는 필드설정 주체
2m_pIsolate, m_v8EmbedderSlot항상 기록; V8Isolate, V8EmbedderSlot
3m_pPlatformV8Platform이 nil이 아닐 때
4m_RendererTypeRenderer가 prpDefault 이외일 때
5m_FontLibraryTypeFontBackend가 pfbpDefault 이외일 때
6m_BrotliEnabledBrotliEnabled = True
7m_IsolatePerDocumentIsolatePerDocument = True

함정은 마지막 두 행에 있습니다. 버전은 누적입니다. version 6 구조체는 version 4이자 version 5 구조체이기도 하므로, Brotli만 요청했어도 PDFium은 m_RendererType과 m_FontLibraryType을 읽습니다. 그 순간 두 필드에 앉아 있는 무엇이든 여러분이 고를 뜻이 있었든 없든 렌더러와 폰트 백엔드가 됩니다

PDFium Component FPDF_LIBRARY_CONFIG 버전 사다리(version 2부터 version 7까지): 어떤 TPdfLibraryConfiguration 옵션이 m_RendererType, m_FontLibraryType, m_BrotliEnabled, m_IsolatePerDocument를 추가하는지, 그리고 누적 버전이 어떻게 0으로 초기화된 렌더러 필드를 어떤 빌드에서든 설정 없는 값이 아니라 의도된 AGG 선택으로 만드는지 보여줌
각 옵션은 구조체 버전을 올리고 이전의 모든 필드는 계속 살아 있으므로, m_RendererType의 0은 PDFium에 명시적인 AGG 요청으로 도착합니다

Brotli를 켜면 왜 렌더러가 AGG로 바뀌는가?

자연스러운 매핑은 prpDefault에 FPDF_RENDERERTYPE_AGG를 m_RendererType에 쓰는 것이고, 그러면 구조체를 버전 6이나 7로 밀어 올리는 모든 구성이 Skia 빌드에서 AGG를 강제합니다. 컴포넌트와 함께 배포되는 pdfium.dll과 pdfium.v8.dll 런타임은 Skia 빌드이므로, 그 매핑은 이색 배포가 아니라 기본 배포를 직격합니다

매핑은 무해해 보입니다. 버전 2나 3에서는 필드를 아예 읽지 않으므로 prpDefault는 실제로 "DLL이 하는 대로"를 뜻합니다. 그러나 BrotliEnabled(버전 6)나 IsolatePerDocument(버전 7)가 그림에 들어오는 순간, 같은 코드가 "선호 없음"을 명시적 AGG 요청으로 바꿉니다. 아무것도 실패하지 않습니다. PDFium은 정상적으로 초기화하고 모든 페이지를 렌더링하며 오류 코드를 돌려주지 않습니다. PDFium 입장에서는 호출자가 AGG를 요청했고 AGG를 받았을 뿐이기 때문입니다

픽셀 해시는 스크린샷이 보여 주지 못하는 자리에서 교체를 드러냅니다. 같은 샘플 문서의 첫 페이지를 세 구성으로 렌더링하면:

  • 기본 구성: 해시 502D77C3711B4ACF
  • BrotliEnabled = True이고 prpDefault를 FPDF_RENDERERTYPE_AGG로 기록: 해시 F75B5EB4728ADE87
  • 명시적 prpAgg: 해시 F75B5EB4728ADE87, Brotli 실행과 동일

PDFium Component는 공개 함수 PdfNativeRendererType으로 이를 해석합니다. 이 함수는 TPdfRendererPreference를 m_RendererType에 기록할 값으로 변환합니다. prpAgg와 prpSkia는 일대일로 매핑됩니다. prpDefault는 로드된 DLL이 FPDF_RenderPageSkia를 익스포트하면 Skia로, 아니면 AGG로 매핑됩니다. 그 익스포트는 Skia 기본값 자체와 같은 PDF_USE_SKIA 조건 아래 컴파일되므로, DLL 바깥에서 관측할 수 있는 유일한 빌드 속성입니다. 이 해석으로 Brotli 구성은 기본 구성과 같은 해시를 만들어 냅니다

PDFium Component 픽셀 해시 비교: 기본 Skia 렌더 해시 502D77C3711B4ACF, AGG로 기록된 prpDefault를 쓰는 BrotliEnabled 구성이 해시 F75B5EB4728ADE87의 명시적 prpAgg 실행과 일치하는 모습, 그리고 PdfNativeRendererType이 FPDF_RenderPageSkia 익스포트를 통해 prpDefault를 원래의 Skia 해시로 되돌리는 과정
픽셀 해시는 스크린샷이 가리는 것을 잡아 냅니다. 기본값을 AGG로 기록하면 Brotli를 켜는 순간 모든 페이지가 AGG로 렌더링되지만, 해석된 기본값은 만지지 않은 구성과 일치합니다

폰트 백엔드에는 같은 문제가 없습니다. m_FontLibraryType은 버전 5부터 읽히고, 그 0 값인 FPDF_FONTBACKENDTYPE_FREETYPE는 필드를 아예 읽지 않을 때의 PDFium 기본값이기도 합니다. 따라서 pfbpDefault에 FreeType을 쓰면 네이티브 기본값을 정확히 재현합니다. 0 값이 언제나 틀린 게 아니라, 언제나 자동으로 옳은 것도 절대 아니라는 뜻입니다

자연스럽게 쓰게 될 시작 코드는 하는 말 그대로 동작합니다:

uses
  PDFium;

procedure ConfigurePdfiumAtStartup;
var
  Config: TPdfLibraryConfiguration;
begin
  // 네이티브 라이브러리를 로드하는 무엇보다도 먼저 실행해야 한다
  Config := TPdfLibraryConfiguration.Default;
  Config.BrotliEnabled := True;   // FPDF_LIBRARY_CONFIG를 버전 6으로 올린다
  // Renderer는 prpDefault 유지: FPDF_RenderPageSkia를 익스포트하는 빌드에서는 Skia로,
  // AGG 전용 빌드에서는 AGG로 해석된다
  // UserFontPaths는 플랫폼 폰트 폴더를 대체하므로, 문서가 시스템 폰트를
  // 여전히 찾아야 한다면 Windows 폰트 폴더도 목록에 넣는다
  SetLength(Config.UserFontPaths, 2);
  Config.UserFontPaths[0] := 'C:\ProgramData\MyApp\Fonts';
  Config.UserFontPaths[1] := 'C:\Windows\Fonts';
  ConfigurePdfLibrary(Config);
end;

UserFontPaths는 추가 목록이 아니라 대체 목록입니다. 폴더를 하나라도 담는 순간 PDFium은 그 폴더들만 스캔하고 플랫폼 기본값을 내려놓습니다. Linux의 /usr/share/fonts와 그 친구들, macOS의 세 Library/Fonts 폴더가 그렇습니다. Windows에서는 경로 교체보다 변화가 큽니다. PDFium이 GDI를 통한 설치된 폰트 열거를 멈추고 나열된 폴더에서 폰트 파일을 읽는 것으로 폴백하기 때문입니다. 애플리케이션 폴더만 적은 목록은 Arial이나 Times New Roman에 의존하는 모든 문서를 치환(substitution)에 맡겨 버립니다. 예제가 Windows 폰트 폴더를 추가하는 이유입니다(실제 코드에서는 드라이브를 하드코딩하는 대신 GetWindowsDirectory로 resolve하세요)

BrotliEnabled는 DLL 자신이 PDF_ENABLE_BROTLI로 빌드되었을 때만 PDF 2.0 /BrotliDecode 스트림을 디코딩 가능하게 만든다는 점을 기억하세요. 플래그는 요청이며 Brotli 지원이 없는 빌드에서는 효과가 없습니다. TPdfLibraryConfiguration.Hardened는 AllowMachineTime이 False라는 점만 Default와 다릅니다. 문서 JavaScript가 실제 시계를 읽는 것을 막으며, 신뢰할 수 없는 파일의 서버 측 처리에는 합리적인 출발점입니다

DLL이 담고 있지 않은 백엔드를 요청하면 무엇이 일어날까?

PDFium은 빌드에 없는 렌더러나 폰트 백엔드에 대해 오류를 돌려주지 않습니다. FPDF_InitLibraryWithConfig는 네이티브 CHECK를 실패시키는데, Windows에서는 breakpoint 예외로 표면화되고 호출 주위에 구조화 예외 핸들러가 없으면 프로세스를 끝냅니다. 헤더도 그렇게 경고합니다. 지원되지 않는 값은 "마찬가지로 즉각적인 크래시로 실패할 것"이라고요

구체적인 두 사례는 FPDF_RENDERERTYPE_SKIA를 받는 AGG 전용 빌드와, Fontations 없는 빌드가 받는 FPDF_FONTBACKENDTYPE_FONTATIONS입니다. 번들된 Skia 런타임은 두 번째 그룹입니다. Skia로 렌더링하지만 폰트에는 FreeType을 씁니다. 그것에 대해 prpSkia와 pfbpFontations를 함께 요청하면 Delphi 쪽에서 External exception 80000003이 나왔습니다. 디버거나 예외 핸들러가 우연히 그것을 잡더라도 상황은 여전히 복구 불가입니다:

  • PDFium은 절반만 초기화된 채로 남습니다
  • 프로세스 전역 구성은 이미 봉인되어 ConfigurePdfLibrary가 바로잡은 구성을 거부합니다
  • 같은 프로세스에서 다른 구성으로 재시도하는 것은 더 이상 불가능합니다

이것은 Brotli 교체와 정반대의 실패입니다. 그쪽은 필드가 아무도 고르지 않은 값을 담고 있었고 PDFium이 조용히 받아들였습니다. 이쪽은 필드가 호출자가 의도적으로 고른 값을 담고 있고 PDFium은 그것에 관한 논의를 전혀 받아들이지 않습니다. 둘 다 래퍼가 네이티브 호출 전에 풀어야 할 문제입니다. 호출 뒤에는 잡을 것이 아무것도 남지 않으니까요

PDFium Component는 Skia와 Fontations를 어떻게 사전 검사하나

LoadLibrary는 DLL 익스포트를 바인딩한 뒤 FPDF_InitLibraryWithConfig를 호출하기 전에 구성을 검증하고, 지원되지 않는 렌더러나 폰트 백엔드를 문제의 설정과 대안을 이름으로 지목하는 메시지를 단 EPdfError로 바꿉니다. DLL은 언로드되고 구성은 봉인 해제되므로 호출자는 다른 설정을 고르고 다시 로드할 수 있습니다

결정 자체는 순수 함수 PdfLibraryConfigurationSupportError에 삽니다. 설정과 빌드를 기술하는 boolean 둘을 받아 조합이 안전하면 빈 문자열을 돌려줍니다. 네이티브 상태를 만지지 않으므로, 자기 테스트에서 어떤 기능 조합으로든 호출할 수 있습니다. LoadLibrary 안에서 두 boolean은 다른 종류의 증거에서 나오며, 서로 다른 신뢰 수준을 받을 자격이 있습니다:

  • Skia는 FPDF_RenderPageSkia 익스포트의 존재로 탐지합니다. PdfNativeRendererType이 쓰는 같은 신호입니다. 익스포트와 Skia 렌더러는 하나의 조건 아래 컴파일되므로 검사는 정확합니다
  • Fontations에는 자기 익스포트가 없습니다. 남기는 흔적은 바이너리에 끌어들인 Rust 폰트 크레이트뿐이므로, PDFium Component는 로드된 라이브러리 파일에서 크레이트 이름 skrifa와 read-fonts(read_fonts도)를 스캔합니다. 스캔은 pfbpFontations가 요청될 때만 돌며, 읽을 수 없는 파일은 "Fontations 없음"으로 칩니다

Fontations 검사는 휴리스틱이며 한 방향으로는 틀릴 수 있습니다. 그 문자열들을 전부 털어낸 Fontations 빌드는 실제로는 동작했을지라도 거부됩니다. 그 절충은 의도된 것입니다. 잘못된 거부는 잡을 수 있는 예외와 FreeType 폴백이라는 비용이 들고, 잘못된 수용은 프로세스라는 비용이 듭니다

봉인 해제는 검사만큼 중요합니다. LoadLibrary는 로드의 아주 시작에서 설정을 봉인하므로, 리셋이 없다면 기능 거절 뒤에 ConfigurePdfLibrary는 모든 재시도에 EPdfError "PDFium library configuration is already sealed"로 답할 것입니다. 거절 경로는 먼저 UnloadLibrary를 호출합니다. 그 FPDF_DestroyLibrary 호출은 그 시점에서 안전합니다. PDFium이 아직 초기화되지 않아 즉시 돌아오기 때문입니다. DLL 누락이나 아키텍처 불일치 같은 다른 로드 실패는 봉인을 유지하므로, 재시도 루프는 둘을 구별해야 합니다:

uses
  SysUtils, PDFium;

function StartPdfiumPreferringSkia: TPdfRendererPreference;
var
  Config: TPdfLibraryConfiguration;
begin
  Config := TPdfLibraryConfiguration.Default;
  Config.Renderer := prpSkia;
  ConfigurePdfLibrary(Config);
  try
    PDFium.LoadLibrary;   // 유닛 한정: Windows.LoadLibrary가 같은 이름
    Result := prpSkia;
  except
    on E: EPdfError do
    begin
      // 기능 거절은 DLL을 언로드하고 설정의 봉인을 해제함.
      // 아예 로드에 실패한 DLL은 sealed 유지: 재시도는 도움이 안 됨
      if PdfLibraryConfigurationSealed then
        raise;
      Config.Renderer := prpAgg;
      ConfigurePdfLibrary(Config);
      PDFium.LoadLibrary;
      Result := prpAgg;
    end;
  end;
end;

명시적인 PDFium.LoadLibrary에 주목하세요. Windows나 Winapi.Windows도 쓰는 유닛에서 한정 없는 LoadLibrary는 uses 절에 마지막으로 나오는 유닛으로 해석됩니다. 그것이 Win32 함수라면 인자 없는 호출은 PDFium에 대해 아무것도 말하지 않는 인자 개수 오류로 컴파일에 실패합니다

PDFium Component LoadLibrary 사전 검사 흐름: ConfigurePdfLibrary가 설정을 봉인하고, 기능 검사는 FPDF_RenderPageSkia export와 skrifa 문자열 증거를 시험하며, 지원되지 않는 요청은 잡을 수 있는 EPdfError를 일으키고 재시도를 위해 봉인을 해제하는 반면, 끝내 로드되지 않는 DLL은 PdfLibraryConfigurationSealed를 true로 유지함
검증은 export가 바인딩된 뒤, 초기화 전에 돕니다. 그래서 없는 백엔드는 프로세스를 죽이는 네이티브 CHECK 대신 잡을 수 있는 EPdfError로 실패합니다

더 이른 시점에 일어나는 검증

ConfigurePdfLibrary는 DLL이 관여하기 전에 일부 조합을 거부하며, 전부 EPdfError입니다. pfbpFreeType을 포함한 명시적 FontBackend는 Renderer = prpSkia를 요구합니다. PDFium은 Skia 렌더러에만 폰트 백엔드를 참조하기 때문입니다. IsolatePerDocument는 V8Isolate가 nil이기를 요구합니다. PDFium이 문서별로 자기 isolate를 만들며 여러분이 하나를 더 넘겨 주면 네이티브 CHECK를 실패하기 때문입니다. UserFontPaths의 빈 문자열은 거부됩니다. 그리고 첫 로드 시도 이후의 호출은 "PDFium library configuration is already sealed"로 실패합니다

마지막 규칙에는 실용적 귀결이 있습니다. 먼저 DLL을 들여다보고 나중에 설정할 수는 없습니다. GetSkiaRenderCapabilities, V8FeaturesAvailable, 문서 열기, 그 밖의 대부분 진입점은 내부적으로 LoadLibrary를 호출하며, 그것은 그 자리에서 설정을 봉인합니다. 나중에 UnloadLibrary를 호출해도 다시 열리지 않습니다. 먼저 설정하고, 그다음 로드하고, 그다음 질문하세요. 진단 루틴이 따라야 할 정확히 그 순서입니다:

uses
  SysUtils, PDFium, FPdfView;

function DescribePdfiumState: string;
var
  Config: TPdfLibraryConfiguration;
  Renderer: string;
begin
  Config := GetPdfLibraryConfiguration;   // 사본, 들여다보기 안전
  if not PDFium.Loaded then
  begin
    if PdfLibraryConfigurationSealed then
      Exit('PDFium failed to load; configuration is sealed');
    Exit('PDFium not loaded; configuration can still change');
  end;
  // FPDF_LIBRARY_CONFIG를 만들 때 LoadLibrary가 적용한 것과 같은 해석
  if PdfNativeRendererType(Config.Renderer,
    GetSkiaRenderCapabilities.PageRender) = FPDF_RENDERERTYPE_SKIA then
    Renderer := 'Skia'
  else
    Renderer := 'AGG';
  Result := Format('Renderer=%s Brotli=%s IsolatePerDocument=%s',
    [Renderer, BoolToStr(Config.BrotliEnabled, True),
     BoolToStr(Config.IsolatePerDocument, True)]);
end;

그 줄을 시작 때 한 번 기록하는 것은 값싸고, "서버에서 텍스트가 다르게 보인다"는 지원 티켓에서 가장 먼저 원하는 것입니다. PDFium.Loaded가 한정된 이유는 LoadLibrary와 같습니다. 폼이나 컴포넌트 메서드 안에서 맨 Loaded는 TComponent.Loaded에 바인딩됩니다

버전화된 C 설정 구조체가 잘못되는 두 가지 방식

버전화된 설정 구조체는 FPDF_LIBRARY_CONFIG든, Win32 cbSize 레코드든, 플러그인 ABI든, 대칭적인 두 가지 방식으로 실패하며 래퍼는 둘 다 막아야 합니다. 첫째는 버전을 너무 낮게 둔 채 필드를 채우는 것이고, 둘째는 라이브러리가 의도된 선택으로 읽는 0 값을 필드에 둔 채 버전을 올리는 것입니다

  1. 필드는 썼는데 버전이 낮다. 버전 2 구조체에 m_BrotliEnabled = 1을 써 넣으면 PDFium은 절대 그것을 보지 않습니다. 호출은 성공하고 Brotli 스트림은 디코딩 불가능으로 남습니다. 방어책은 하나를 하드코딩하는 대신 실제 사용 중인 필드에서 버전을 유도하는 것이며, LoadLibrary가 그렇게 합니다
  2. 버전은 충분한데 0 필드에 의미가 있다. 버전을 6으로 올리면 버전 6까지의 모든 필드가 이제 살아 있습니다. FillChar는 m_RendererType을 FPDF_RENDERERTYPE_AGG로 0으로 만드는데, 이는 "unset"이 아니라 실제 렌더러입니다. 방어책은 선택한 버전이 커버하는 모든 필드에 의도된 값을 쓰고, "default"를 가정하지 않고 실제 빌드에 대해 해석하는 것입니다

호출 대상을 크래시시킬 수 있는 값들에는 세 번째 규칙이 따라 나옵니다: 호출 전에, 사용할 수 있는 가장 강한 증거로 바이너리가 할 수 있는 일에 대해 검증하고, 그 증거가 휴리스틱일 때는 코드와 문서에서 정직하게 말하십시오. 익스포트된 심볼은 증거입니다. 문자열 테이블의 크레이트 이름은 좋은 추측입니다

빠른 참조: PDFium Component 라이브러리 설정

  • 무엇이 DLL을 로드하기 전에 ConfigurePdfLibrary를 한 번 호출하십시오. 어떤 기능 질의나 문서 로드든 봉인합니다
  • 특정 렌더러가 필요하지 않다면 Renderer는 prpDefault로 두십시오. 모든 구조체 버전에서 빌드 기본값으로 해석됩니다
  • 실제로 어떤 렌더러가 활성인지 기록하려면 PdfNativeRendererType과 GetSkiaRenderCapabilities.PageRender를 쓰십시오
  • AGG 전용 DLL의 prpSkia나 Fontations 없는 DLL의 pfbpFontations는 크래시가 아니라 EPdfError를 기대하십시오
  • 기능 거부 후에는 PdfLibraryConfigurationSealed가 False이고 재구성할 수 있습니다. DLL 로드 실패 후에는 True로 남습니다
  • Fontations 탐지는 휴리스틱으로 취급하고 FreeType 폴백을 유지하십시오
  • Win32와 TComponent 이름 충돌을 피하려면 유닛 이름을 붙여 PDFium.LoadLibrary, PDFium.Loaded로 쓰십시오

설정이 문제되기도 전에 DLL이 실패한다면 Delphi에서 PDFium DLL 로드 실패 진단하기부터 시작하고, 컴포넌트가 각 플랫폼에서 올바른 바이너리를 찾는 방법은 어떤 대상에서든 PDFium 네이티브 라이브러리 로드하기를 참조하세요. 렌더러가 정리되면 렌더 캐시와 부드러운 줌 전략이 뷰어에서 페이지 렌더링을 빠르게 유지하는 방법을 다룹니다

PDFium Component는 Delphi와 C++Builder용 PDFium 엔진을 이런 설정 검사와 함께 감싸므로, 네이티브 초기화는 프로세스 종료가 아니라 여러분이 처리할 수 있는 Pascal 예외로 실패합니다. 제품 세부와 다운로드는 Delphi용 PDFium Component 제품 페이지에 있습니다