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 alan | Kim set eder |
|---|---|---|
| 2 | m_pIsolate, m_v8EmbedderSlot | Her zaman yazılır; V8Isolate, V8EmbedderSlot |
| 3 | m_pPlatform | V8Platform nil değilken |
| 4 | m_RendererType | Renderer, prpDefault dışındayken |
| 5 | m_FontLibraryType | FontBackend, pfbpDefault dışındayken |
| 6 | m_BrotliEnabled | BrotliEnabled = True |
| 7 | m_IsolatePerDocument | IsolatePerDocument = 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
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 prpDefaultFPDF_RENDERERTYPE_AGGyazılarakBrotliEnabled= True: karmaF75B5EB4728ADE87- Açık
prpAgg: karmaF75B5EB4728ADE87, 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
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_RenderPageSkiaexport'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
skrifaveread-fonts(ayrıcaread_fonts) crate adlarını arar. Tarama yalnızcapfbpFontationsistendiğ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
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
- 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 - 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.PageRenderile kullanın - Yalnızca-AGG bir DLL'de
prpSkiaiçin ya da Fontations içermeyen bir DLL'depfbpFontationsiçin çökme değilEPdfErrorbekleyin - Bir yetenek reddinden sonra
PdfLibraryConfigurationSealedFalse'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
TComponentad çakışmalarından kaçınmak içinPDFium.LoadLibraryvePDFium.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