Teknik Makale

PDFium Library Config: Brotli Skia yerine AGG getirebilir

BrotliEnabled'i ya da IsolatePerDocument'i açmak, FPDF_LIBRARY_CONFIG'u PDFium'un m_RendererType'ı harfiyen okuduğu bir sürüme taşır; dolayısıyla "default" için AGG yazan bir sarmalayıcı, hiçbir hata vermeden bir Skia derlemesini AGG renderer'a çevirir. Delphi için PDFium Component'te TPdfLibraryConfiguration, varsayılan renderer'ı DLL'nin kendi varsayılanında tutar ve DLL'nin yerine getiremediği bir Skia ya da Fontations isteği, süreci öldürmek yerine yakalanabilir bir EPdfError yükseltir

İki tuzak zıt yönlerde başarısız olur. İlki, gönderip test ettiğiniz derlemeden biraz farklı kenar yumuşatma ve metin kenarlarına sahip, iyi görünen ama başka bir rasterleştiriciyle render edilmiş sayfalar üretir. İkincisi kendini yüksek sesle duyurur: yerel başlatmanın içinden ana süreci aşağı çekerek. İkisi de aynı yerden gelir: sürümlü bir C yapısı; alanları, sürüm sayısı onları saydığını söyleyene kadar önemli olmayan ve sıfır değerlerinin "unset" değil gerçek seçim olduğu bir yapı

FPDF_LIBRARY_CONFIG, PDFium'un hangi renderer'ı kullanacağına nasıl karar verir?

FPDF_InitLibraryWithConfig, m_RendererType'a yalnızca yapının Version alanı 4 ve üzerindeyken bakar ve o sürümden itibaren değeri yazıldığı gibi kullanır. Sürüm 4'ün altında PDFium alanı yok sayar ve derleme varsayılanını seçer; PDF_USE_SKIA ile derlenmiş derlemelerde Skia, gerisinde AGG

Sonraki her alan aynı örüntüyü izler. Yapı birer yetenekle büyüdü ve her yetenek yeni bir sürüm numarasıyla birlikte geldi. PDFium Component, yerel yapıyı LoadLibrary'de sizin TPdfLibraryConfiguration'ınızdan kurar ve sürümü yalnızca set ettiğiniz seçeneklerin gerektirdiği kadar yükseltir

Yapı sürümüEklediği alanKim set eder
2m_pIsolate, m_v8EmbedderSlotHer zaman yazılır; V8Isolate, V8EmbedderSlot
3m_pPlatformV8Platform nil değilken
4m_RendererTypeRenderer, prpDefault dışındayken
5m_FontLibraryTypeFontBackend, pfbpDefault dışındayken
6m_BrotliEnabledBrotliEnabled = True
7m_IsolatePerDocumentIsolatePerDocument = True

Tuzak son iki satırda. Sürümler kümülatiftir: sürüm 6 bir yapı aynı zamanda sürüm 4 ve sürüm 5 bir yapıdır; dolayısıyla PDFium, yalnızca Brotli istemiş olsanız bile m_RendererType ile m_FontLibraryType'ı okur. O anda o iki alanda ne duruyorsa renderer ile font backend olur; onları seçmek isteseniz de istemeseniz de

PDFium Component FPDF_LIBRARY_CONFIG sürüm merdiveni, sürüm 2'den sürüm 7'ye hangi TPdfLibraryConfiguration seçeneğinin m_RendererType, m_FontLibraryType, m_BrotliEnabled ve m_IsolatePerDocument eklediğini ve kümülatif sürümlerin neden sıfırlanmış bir renderer alanını her derlemede unset değer değil kasıtlı bir AGG seçimi yaptığını gösterir
Her seçenek yapı sürümünü yükseltir ve önceki her alan canlı kalır; dolayısıyla m_RendererType'taki sıfır, PDFium'a açık bir AGG isteği olarak ulaşır

Brotli'yi açmak renderer'ı neden AGG'ye çevirebilir?

Bariz eşleme, prpDefault için FPDF_RENDERERTYPE_AGG'yi m_RendererType'a yazar; böylece yapıyı sürüm 6'ya ya da 7'ye taşıyan her yapılandırma, bir Skia derlemesinde AGG'yi zorunlu kılar. Bileşenle gelen pdfium.dll ve pdfium.v8.dll çalışma zamanları Skia derlemeleridir; dolayısıyla o eşleme egzotik bir dağıtımı değil, varsayılan dağıtımı vurur

Eşleme zararsız görünür. Sürüm 2 ya da 3'te alan hiç okunmaz; dolayısıyla prpDefault gerçekten "DLL ne yaparsa" demektir. BrotliEnabled (sürüm 6) ya da IsolatePerDocument (sürüm 7) işin içine girdiği an, aynı kod "tercih yok"u açık bir AGG isteğine çevirir. Hiçbir şey başarısız olmaz. PDFium normal başlar, her sayfayı render eder ve hiçbir hata kodu döndürmez; çünkü onun bakış açısından çağıran AGG istedi ve AGG aldı

Bir piksel karması, takası ekran görüntülerinin göremediği yerde görünür kılar. Aynı örnek belgenin ilk sayfasını üç yapılandırma altında render etmek şunları verir:

  • Varsayılan yapılandırma: karma 502D77C3711B4ACF
  • prpDefault FPDF_RENDERERTYPE_AGG yazılarak BrotliEnabled = True: karma F75B5EB4728ADE87
  • Açık prpAgg: karma F75B5EB4728ADE87, Brotli koşusuyla özdeş

PDFium Component bunu, bir TPdfRendererPreference'ı m_RendererType'a yazılan değere çözen kamuya açık PdfNativeRendererType fonksiyonuyla çözer. prpAgg ile prpSkia bire bir eşlenir. prpDefault, yüklenen DLL FPDF_RenderPageSkia'yı dışa aktarıyorken Skia'ya, aksi hâlde AGG'ye eşlenir. O export, Skia varsayılanının kendisiyle aynı PDF_USE_SKIA koşulu altında derlenir; bu da onu DLL'nin dışından gözlemleyebileceğiniz tek derleme özelliği yapar. O çözümle Brotli yapılandırması, varsayılanınkiyle aynı karmayı üretir

PDFium Component piksel karma karşılaştırması: varsayılan Skia render karması 502D77C3711B4ACF, AGG yazılmış prpDefault'lı bir BrotliEnabled yapılandırmasının F75B5EB4728ADE87 karmasıyla açık prpAgg koşusuna eşleşmesi ve PdfNativeRendererType'ın prpDefault'u FPDF_RenderPageSkia export'u üzerinden özgün Skia karmasına geri çözmesi
Bir piksel karması, ekran görüntülerinin gizlediğini yakalar: varsayılan AGG yazılmışken Brotli'yi açmak her sayfayı AGG ile render eder; çözülmüş varsayılan ise dokunulmamış yapılandırmayla eşleşir

Font backend'in aynı sorunu yoktur. m_FontLibraryType sürüm 5'ten itibaren okunur ve sıfır değeri olan FPDF_FONTBACKENDTYPE_FREETYPE, alan hiç okunmadığındaki PDFium varsayılanıdır. Dolayısıyla pfbpDefault için FreeType yazmak, yerel varsayılanı tam olarak yeniden üretir. Sıfır değerleri her zaman yanlış değildir; sadece hiçbir zaman otomatik olarak doğru da değildir

Doğal olarak yazacağınız başlatma kodu, yazdığı şeyi yapar:

uses
  PDFium;

procedure ConfigurePdfiumAtStartup;
var
  Config: TPdfLibraryConfiguration;
begin
  // Yerel kütüphaneyi yükleyen her şeyden önce koşmalı
  Config := TPdfLibraryConfiguration.Default;
  Config.BrotliEnabled := True;   // FPDF_LIBRARY_CONFIG'u sürüm 6'ya taşır
  // Renderer prpDefault kalır: FPDF_RenderPageSkia'yı dışa aktaran derlemelerde
  // Skia'ya, yalnızca-AGG derlemelerde AGG'ye çözülür
  // UserFontPaths platform font klasörlerinin yerini alır; belgeler sistem
  // fontlarını hâlâ bulabilsin diye Windows font klasörünü de listeler
  SetLength(Config.UserFontPaths, 2);
  Config.UserFontPaths[0] := 'C:\ProgramData\MyApp\Fonts';
  Config.UserFontPaths[1] := 'C:\Windows\Fonts';
  ConfigurePdfLibrary(Config);
end;

UserFontPaths bir ekleme değil, yerine geçen listedir. En az bir klasör tuttuğu an PDFium yalnızca o klasörleri tarar ve platform varsayılanlarını düşürür: Linux'ta /usr/share/fonts ve dostları, macOS'ta üç Library/Fonts klasörü. Windows'ta değişiklik bir yol değişiminden büyüktür; çünkü PDFium, kurulu fontları GDI üzerinden saymayı bırakır ve font dosyalarını listelenen klasörlerden okumaya düşer. Bu yüzden yalnızca uygulama klasörünüzü sayan bir liste, Arial ya da Times New Roman'a bel bağlayan her belgeyi ikameye terk eder; örnek, Windows font klasörünü de ekler (gerçek kodda sürücüyü sabitlemek yerine GetWindowsDirectory ile çözün)

BrotliEnabled'in PDF 2.0 /BrotliDecode akışlarını çözülebilir kılmasının, DLL kendisi PDF_ENABLE_BROTLI ile derlenmişse geçerli olduğunu unutmayın. Bayrak bir istektir ve Brotli desteği olmayan bir derlemede etkisi yoktur. TPdfLibraryConfiguration.Hardened, AllowMachineTime'un False olması dışında Default ile aynıdır; bu, belge JavaScript'ine gerçek saati okutmayı engeller ve güvenilmeyen dosyaların sunucu tarafı işlenmesi için makul bir başlangıç noktasıdır

DLL'nin içermediği bir backend istediğinizde ne olur?

PDFium, derlemede eksik bir renderer ya da font backend için hata döndürmez: FPDF_InitLibraryWithConfig yerel bir CHECK'i düşürür; bu, Windows'ta bir breakpoint exception olarak görünür ve çağrının etrafında yapılandırılmış bir exception handler yoksa süreci sonlandırır. Header da aynı şeyi söyler; desteklenmeyen bir değerin "anında çökmeyle benzer biçimde başarısız olacağı" uyarısıyla

İki somut durum: FPDF_RENDERERTYPE_SKIA alan yalnızca-AGG bir derleme ve FPDF_FONTBACKENDTYPE_FONTATIONS alan Fontations'sız bir derleme. Paketlenmiş Skia runtime ikinci gruptadır: Skia ile render eder ama fontlar için FreeType kullanır. Ona karşı prpSkia ile pfbpFontations'ı birlikte istemek, Delphi tarafında External exception 80000003 üretti. Debugger ya da bir exception handler tesadüfen onu yakalasa bile durum hâlâ kurtarılamaz:

  • PDFium yarım başlatılmış olarak kalır
  • Süreç geneli yapılandırma çoktan mühürlenmiştir; dolayısıyla ConfigurePdfLibrary, düzeltilmiş bir yapılandırmayı reddeder
  • Aynı süreçte başka bir yapılandırmayla yeniden denemek artık mümkün değildir

Bu, Brotli takasının tersidir. Orada alan, kimsenin seçmediği bir değer tuttu ve PDFium onu sessizce kabul etti. Burada alan, çağıranın bilinçli seçtiği bir değer tutuyor ve PDFium hakkında hiçbir tartışmaya izin vermiyor. İkisi de bir sarmalayıcının yerel çağrıdan önce çözmesi gereken sorunlardır; çünkü çağrıdan sonra yakalanacak hiçbir şey kalmaz

PDFium Component Skia ile Fontations'ı nasıl ön-denetler?

LoadLibrary, yapılandırmayı DLL export'larını bağladıktan sonra ve FPDF_InitLibraryWithConfig'i çağırmadan önce doğrular ve desteklenmeyen bir renderer ya da font backend'i, suçlu ayarı ile alternatiflerini adıyla söyleyen bir EPdfError'a çevirir. DLL boşaltılır ve yapılandırmanın mührü açılır; böylece çağıran başka ayarlar seçip yeniden yükleyebilir

Kararın kendisi, yapılandırmayı ve derlemeyi tanımlayan iki Boolean'ı alan, kombinasyon güvenliyken boş string döndüren saf fonksiyon PdfLibraryConfigurationSupportError'da yaşar. Yerel duruma dokunmadığı için kendi testlerinizden herhangi bir yetenek kombinasyonuyla çağırabilirsiniz. LoadLibrary içinde o iki Boolean farklı türden kanıtlardan gelir ve farklı güven düzeylerini hak eder:

  • Skia, FPDF_RenderPageSkia export'unun varlığından saptanır; PdfNativeRendererType'ın kullandığı sinyalin aynısı. Export ile Skia renderer tek koşul altında derlenir; dolayısıyla kontrol kesindir
  • Fontations'ın kendi export'u yoktur. Bıraktığı tek iz, ikiliye kattığı Rust font crate'leridir; dolayısıyla PDFium Component, yüklenen kütüphane dosyasında skrifa ve read-fonts (ayrıca read_fonts) crate adlarını arar. Tarama yalnızca pfbpFontations istendiğinde koşar ve okunamayan bir dosya "Fontations yok" sayılır

Fontations kontrolü bir sezgiseldir ve tek yönde yanılabilir: o string'lerin hepsinden arındırılmış bir Fontations derlemesi, işe yarayabilirdi ama reddedilirdi. O taviz bilinerek yapıldı. Yanlış bir reddin bedeli, yakalayabileceğiniz bir exception ve FreeType'a bir fallback'tir. Yanlış bir kabulün bedeli sürecin kendisidir

Mührü açmak, kontrol kadar önemlidir. LoadLibrary yapılandırmayı yüklemenin en başında mühürler; reset olmadan bir yetenek reddi, ConfigurePdfLibrary'nin her denemeye EPdfError "PDFium library configuration is already sealed" ile karşılık vermesi demek olurdu. Ret yolu önce UnloadLibrary çağırır; onun FPDF_DestroyLibrary çağrısı o noktada güvenlidir, çünkü PDFium henüz başlatılmamıştır ve hemen döner. Eksik bir DLL ya da mimari uyuşmazlığı gibi öteki yükleme başarısızlıkları mührü korur; dolayısıyla bir yeniden deneme döngüsü ikisini ayırt etmek zorundadır:

uses
  SysUtils, PDFium;

function StartPdfiumPreferringSkia: TPdfRendererPreference;
var
  Config: TPdfLibraryConfiguration;
begin
  Config := TPdfLibraryConfiguration.Default;
  Config.Renderer := prpSkia;
  ConfigurePdfLibrary(Config);
  try
    PDFium.LoadLibrary;   // unit nitelemeli: Windows.LoadLibrary aynı ada sahiptir
    Result := prpSkia;
  except
    on E: EPdfError do
    begin
      // Yetenek reddi DLL'yi boşaltır ve yapılandırmanın mührünü açar.
      // Hiç yükleyemeyen bir DLL mühürlü kalır: yeniden denemek işe yaramaz
      if PdfLibraryConfigurationSealed then
        raise;
      Config.Renderer := prpAgg;
      ConfigurePdfLibrary(Config);
      PDFium.LoadLibrary;
      Result := prpAgg;
    end;
  end;
end;

Açık PDFium.LoadLibrary'ye dikkat. Aynı zamanda Windows ya da Winapi.Windows kullanan bir unit'te nitelemsiz bir LoadLibrary, uses yan tümcesinde en sonda görünen unit'e çözülür; o Win32 fonksiyonu olduğunda parametresiz çağrı, PDFium hakkında hiçbir şey söylemeyen bir argüman sayısı hatasıyla derlenemez

PDFium Component LoadLibrary ön-denetim akışı: ConfigurePdfLibrary yapılandırmayı mühürler; yetenek kontrolü FPDF_RenderPageSkia export'unu ve skrifa string kanıtını test eder; desteklenmeyen bir istek yakalanabilir bir EPdfError yükseltir ve yeniden deneme için mührü açar; hiç yüklenmeyen bir DLL ise PdfLibraryConfigurationSealed'i true tutar
Doğrulama, export'lar bağlandıktan sonra ve başlatmadan önce koşar; dolayısıyla eksik bir backend, süreci öldüren yerel bir CHECK yerine yakalayabileceğiniz bir EPdfError olarak başarısız olur

Daha da erken gerçekleşen doğrulama

ConfigurePdfLibrary, bazı kombinasyonları hiçbir DLL işin içine girmeden reddeder; hepsi EPdfError ile. pfbpFreeType dâhil açık bir FontBackend, Renderer = prpSkia gerektirir; çünkü PDFium font backend'ine yalnızca Skia renderer için bakar. IsolatePerDocument, V8Isolate'in nil olmasını gerektirir; PDFium belge başına kendi isolate'ini kurar ve siz ona bir tane de elden verirseniz yerel bir CHECK'i düşürür. UserFontPaths'teki boş dizgiler reddedilir. Ve ilk yükleme denemesinden sonraki her çağrı, "PDFium library configuration is already sealed" ile başarısız olur

Son kuralın pratik bir sonucu vardır: önce DLL'yi yoklayıp sonra yapılandıramazsınız. GetSkiaRenderCapabilities, V8FeaturesAvailable, bir belge açmak ve çoğu öteki giriş noktası içeride LoadLibrary çağırır; bu da yapılandırmayı anında mühürler. Sonradan UnloadLibrary çağırmak da onu yeniden açmaz. Önce yapılandırın, sonra yükleyin, sonra sorular sorun; tanısal bir rutinin izlemesi gereken düzen tam olarak budur:

uses
  SysUtils, PDFium, FPdfView;

function DescribePdfiumState: string;
var
  Config: TPdfLibraryConfiguration;
  Renderer: string;
begin
  Config := GetPdfLibraryConfiguration;   // bir kopya, incelemesi güvenli
  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;
  // LoadLibrary'nin FPDF_LIBRARY_CONFIG'i kurarken uyguladığı aynı çözüm
  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;

O satırı başlangıçta bir kez loglamak ucuzdur ve "metin sunucuda farklı görünüyor" diyen bir destek kaydında isteyeceğiniz ilk şeydir. PDFium.Loaded, LoadLibrary ile aynı nedenle nitelenmiştir: bir form ya da bileşen metodunun içinde çıplak bir Loaded, TComponent.Loaded'a bağlanır

Sürümlü bir C yapılandırma yapısının yanlış gittiği iki yol

Her sürümlü yapılandırma yapısı — FPDF_LIBRARY_CONFIG olsun, bir Win32 cbSize record'u olsun ya da bir plugin ABI — iki simetrik yoldan başarısız olur ve bir wrapper ikisine karşı da korunmalıdır. Birincisi sürümü fazla düşük bırakıp bir alanı doldurmak; ikincisi bir alanı, kütüphanenin kasıtlı seçim diye okuduğu bir sıfır değerde bırakıp sürümü yükseltmektir

  1. Alan set edilmiş, sürüm fazla düşük. Sürüm 2 bir yapıya m_BrotliEnabled = 1 yazın ve PDFium ona hiç bakmaz. Çağrı başarılı olur ve Brotli akışları çözülemez kalır. Savunma, sürümü sabitlemek yerine kullanımdaki alanlardan türetmektir; LoadLibrary'nin yaptığı da budur
  2. Sürüm yeterince yüksek, sıfır alan bir şey ifade eder. Sürümü 6'ya çıkarın ve sürüm 6'ya kadarki her alan artık canlıdır. FillChar, m_RendererType'ı FPDF_RENDERERTYPE_AGG'ye sıfırlar; o bir gerçek renderer'dır, "unset" değil. Savunma, seçilen sürümün kapsadığı her alana kasıtlı bir değer yazmak ve "default"u gerçek derlemeye karşı çözmektir; varsaymamak

Çağrılanı çökertebilecek değerler için üçüncü bir kural gelir: onları, çağrıdan önce kullanılabilir en güçlü kanıtla binary'nin yapabildiklerine karşı doğrulayın ve o kanıt bir sezgiselse kodda da dokümantasyonda da dürüst olun. Export edilmiş bir simge kanıttır. String tablosundaki bir crate adı iyi bir tahmindir

Hızlı başvuru: PDFium Component kütüphane yapılandırması

  • ConfigurePdfLibrary'yi, DLL'yi yükleyen her şeyden önce bir kez çağırın; her yetenek sorgusu ya da belge yüklemesi onu mühürler
  • Belirli bir rasterleştiriciye ihtiyacınız yoksa Renderer'ı prpDefault'ta bırakın; her yapı sürümünde derleme varsayılanına çözülür
  • Hangi renderer'ın gerçekten aktif olduğunu loglamak için PdfNativeRendererType'ı GetSkiaRenderCapabilities.PageRender ile kullanın
  • Yalnızca-AGG bir DLL'de prpSkia için ya da Fontations içermeyen bir DLL'de pfbpFontations için çökme değil EPdfError bekleyin
  • Bir yetenek reddinden sonra PdfLibraryConfigurationSealed False'tur ve yeniden yapılandırabilirsiniz; başarısız bir DLL yüklemesinden sonra True kalır
  • Fontations algısını sezgisel sayın ve bir FreeType fallback'i tutun
  • Win32 ile TComponent ad çakışmalarından kaçınmak için PDFium.LoadLibrary ve PDFium.Loaded'ı unit adıyla yazın

DLL, yapılandırma hiç önem kazanmadan başarısız oluyorsa Delphi'de PDFium DLL yükleme başarısızlıklarını teşhis ile başlayın; bileşenin her platformda doğru binary'yi nasıl bulduğu için PDFium yerel kütüphanesini herhangi bir hedefte yükleme yazısına bakın. Renderer oturduktan sonra render cache ve akıcı zoom taktikleri, sayfa render'ını bir görüntüleyicide hızlı tutmayı işler

PDFium Component, PDFium motorunu Delphi ve C++Builder için bu tür yapılandırma kontrolleriyle sarar; böylece yerel başlatma, bir süreç çıkışı yerine işleyebileceğiniz bir Pascal exception olarak başarısız olur. Ürün ayrıntıları ve indirmeler Delphi için PDFium Component ürün sayfasında