Teknik Makale

PDFium ile Delphi'de PDF Yazı Tipi İkamesi Kontrolü

Windows tezgahında üretilmiş bir sevkiyat fişi, font sözlüğünde Arial adlandırır, font programı taşımaz ve o tezgahtaki her görüntüleyicide düzgün görünür. Aynı dosya bir Debian konteyneri içinde rasterize edildiğinde her glyph'i başka bir sans seriftan çizer. Metin yine olması gereken yerde başlar; çünkü glyph konumları PDF'in içinde saklı /Widths dizisinden gelir ama harf biçimleri değişir, ikamenin hatları oturdukları genişliklerden dar olan her yerde aralıklar düzensiz görünür ve ikamenin eksik bıraktığı bir karakter bir delik bırakır. Suçlu render edici değildir. Belge, font seçimini onu render edene bırakmıştır; ve o seçim, uygulamayla birlikte gönderdiğiniz font baytlarını vererek kendi kodunuzda yapılabilir

ISO 32000-1 buna izin verir. §9.6.2.2'deki standart 14 font her zaman yalnızca adla referans verilebilir ve öteki her basit font, sözlüğü ile font tanımlayıcısı (§9.8) metrikleri ve bayrakları tarif ettiği sürece gömülmeden bırakılabilir. PDF/A buna tümüyle izin vermez (ISO 19005-1 §6.3.4 her font programının gömülmesini ister); bu, yalnızca adla anılan fontların, dosyayı yazan makineden çıktıktan sonra ne kadar güvenilmez olduğuna dair çok şey söyler

Gömülü olmayan bir Arial yazı tipini adlandıran bir Delphi PDF'si, varsayılan ana makine eşleyicisi altında üç makinede farklı işlenir; PDFium bir IPdfSystemFontProvider'dan paketli yazı tipi baytları aldığında ise özdeş işlenir
PDFium, bir belge gömmediği bir yazı tipini her adlandırdığında yazı tipi baytları ister; sağlayıcı, ana makine eşleyicisinin makine başına tahminini sizin gönderdiğiniz baytlarla değiştirir

Yazı tiplerini neden doğrudan sunucuya kurmuyoruz?

Bazen fontları kurmak yeterlidir. Üç yaygın durumda bozulur. Bir font lisansı, masaüstü kullanımına izin verip belgeleri otomatik render eden bir sunucuya kurulmasına izin vermeyebilir. Konteyner görüntüleri sık sık yeniden kurulur ve elle kopyalanmış bir font bir sonraki dağıtımla kaybolur. Düzenlenmiş iş akışları, render yığınının sürüm kontrolü altındaki eserlerden yeniden üretilebilir olmasını ister; makine genelindeki bir font klasörü ise öyle değildir

Bir de orta yol var. Kütüphane yüklenmeden önce ConfigurePdfLibrary üzerinden geçen TPdfLibraryConfiguration.UserFontPaths, PDFium'un yerel eşleyicisine hangi klasörlerin font dosyası için taranacağını söyler. Liste, platform varsayılanlarına ekleme yapmak yerine onların yerini alır ve Windows'ta GDI font numaralandırmasını da kapatır; o yüzden belgeler hâlâ kurulu fontlara ihtiyaç duyuyorsa sistem font klasörünü de listeye alın. Eşleyici, bir istek için hangi dosyanın kazanacağına yine kendi eşleme kurallarıyla karar verir. Hangi baytların "Arial, bold, Cyrillic charset" isteğini yanıtladığını tam olarak bilmeniz gerektiğinde, o kararın okuyabildiğiniz bir kodda yaşaması gerekir; sistem font sağlayıcısının verdiği tam olarak budur

PDFium yüklenmeden önce bir IPdfSystemFontProvider kurmak

PDFium Component font eşlemeyi tek arayüzün tek metodu üzerinden açar. IPdfSystemFontProvider.ResolveFont, FaceName, Weight, Italic, Charset ve PitchFamily taşıyan bir TPdfSystemFontRequest alır; yüz adını, eksiksiz TrueType, OpenType ya da TrueType Collection baytlarını, bir karakter kümesini ve TTCIndex'i tutan bir TPdfSystemFontData kaydıyla yanıtlar. False döndürmek isteği reddeder

ConfigureSystemFontProvider kütüphane yüklenmeden koşmalıdır. PDFium font eşleyicisini başlatma sırasında bir kez alır; bileşen, Loaded hâlihazırda true ise EPdfError fırlatır ("Configure the system font provider before loading PDFium"). Özellik sondaları dâhil birçok çağrı kütüphaneyi talep üzerine yükler; o yüzden yapılandırmayı başlangıcın en tepesine koyun. Aşağıdaki sağlayıcı bir arama tablosu kurar ve tüm font dosyalarını kurucuda okur; sonra ResolveFont yalnızca okur:

uses
  System.SysUtils, System.Classes, System.IOUtils, PDFium;

type
  TBundledFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
  private
    FKeys: TStringList;           // kurucuda bir kez sıralanır, sonra salt-okunur
    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);
  // Bir takma ad: gerçekte sunulan aileyi bildir, böylece ilke onu görebilir
  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 ve üzeri kalın olarak sunulur
  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;                // bir .ttc koleksiyonu içindeki yüz numarası
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);
  // Belgeleri ancak şimdi açın; PDFium gerektiren ilk çağrı onu yükler
end;

Bu örnekdeki tablo anahtarları bilerek naiftir. Gerçek belgeler aynı aileyi birkaç biçimde yazar; o yüzden tabloyu dondurmadan önce temsilî bir yığından Request.FaceName'i günlüğe yazın; biraz aşağıdaki kayıt sarmalayıcısı tam olarak o listeyi üretir. Ağırlık eşiği de bir tercihtir: FPdfExtensions ünitesinde FXFONT_FW_NORMAL 400, FXFONT_FW_BOLD 700'dür ve 600'lük bir semibold isteği iki taraftan birine düşmek zorundadır

İlke bayrakları gerçekte neye karar verir?

Her istek aynı sırada yürür. Bileşen önce önbelleğine bakar, sonra sağlayıcınızı çağırır, sonra yanıtı doğrular. Kabul edilen yanıt önbelleğe girer ve PDFium'a verilir. Reddedilen ya da ayıklanan yanıt, FPDF_GetDefaultSystemFontInfo'nun döndürdüğü platform eşleyicine gider; ama yalnızca AllowDefaultFallback açıksa. Değilse istek başarısız sayılır ve PDFium sizin fontunuz olmadan yola devam eder

Doğrulamanın kendisi kısadır. Boş FontData reddedilir; MaxFontBytes'tan uzun olan her şey de. Yanıttaki boş bir FaceName, istenen adla doldurulur. AllowFaceSubstitution kapalıyken, istenenden farklı (büyük-küçük harf yoksayarak karşılaştırılan) bir yüz adı bildiren yanıt da reddedilir. O denetim yalnızca bildirdiğiniz adı okur, başka hiçbir şeyi değil. Liberation Sans baytlarını "Arial" bildirerek sunan bir sağlayıcı bu denetimi rahat geçer; örnekdeki Helvetica takma adının gerçek aileyi bildirmesinin nedeni budur: bayrak kapalıyken "Arial" ile yanıtlanan bir Helvetica isteği reddedilir ve RejectedProviderResponses'a düşer

PDFium Component doğrulama kapıları, baytlar PDFium'a ulaşmadan önce boş veriyi, MaxFontBytes boyutunu ve yüz değişimini kontrol eder; AllowDefaultFallback, ana makine yedeği ile başarısız bir istek arasında karar verir
Doğrulama, sağlayıcı baytları PDFium'a ulaşmadan bileşenin içinde çalışır; yedek kapalıyken eşlenemeyen bir yazı tipi, bir yedekle işlemek yerine yüksek sesle başarısız olur ve FailedRequests içinde bir kez sayılır

TTC indeksi başka bir noktada denetlenir. PDFium çoğu kez tek seferde tek sfnt tablosu ister; cmap ya da glyf gibi. Bileşen o tabloları, geri döndürdüğünüz baytların tablo dizinini yürüerek yanıtlar. Bir koleksiyon için TTCIndex'in seçtiği dizinden başlar; ttcf başlığındaki font sayısını aşan bir indeks ya da tek fontlu bir dosyada sıfırdan farklı bir indeks, o tablo sorgularının boş dönmesine yol açar. Dizin yürüyüşü TrueType'ı (0x00010000 ve true), CFF hatlı OpenType'ı (OTTO) ve koleksiyonları (ttcf) tanır. WOFF ve WOFF2 dosyalarının sağlayıcı onları döndürmeden düz sfnt'ye açılması gerekir

TPdfSystemFontPolicy.Default her iki bayrağı açar; font başına 64 MB tavan ve 32 önbellek girdisiyle. Bu, birkaç aileyi bir anda yayan bir sağlayıcıya uyar: henüz eşlemediğiniz her şey, eskiden nasıl render ediliyorsa öyle render olmayı sürdürür. Bir denetim derlemesi her iki bayrağı da kapatmalıdır. Böylece boşluklar sayılan başarısızlıklar ve reddedilen ikameler olarak görünür ve bir yedek isabeti, font kümesinin unuttuğu bir aileyi artık gizleyemez

ResolveFont hangi iş parçacığında çağrılır?

ResolveFont, fontu gerektiren sayfayı yükleyen ya da render eden hangi iş parçacığıysa orada koşar; bu, ana iş parçacığı olmak zorunda değildir. Bileşen kendi önbelleğini ve sayaçlarını bir kritik bölümle korur, ama sizin metodunuz koşarken o kilidi tutmaz. Uygulamanız arka plan iş parçacıklarında render ediyorsa, sağlayıcının kuruluştan sonra değiştirdiği her durum kendi korumasına ihtiyaç duyar

İstisnalar metodun içinde tutulacak ikinci şeydir. Bileşen, ResolveFont'tan yerel kütüphaneyle olan sınırda kaçan her şeyi yakalar ve reddedilmiş bir istek gibi işler; istek yedeğe ya da başarısızlığa yoluna devam eder. Buna güvenmek, eşleme kodunuzdaki bir hatayı başkasının sessizce sunduğu bir fonte çevirir. Aşağıdaki sarmalayıcı her boşluğu bir kilit altında kaydeder ve istisnaları yerinde tutar; üstelik tabloya eklenecek yüz adlarının listesini de size verir:

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;            // burada günlüğe yaz; PDFiuma ulaşmasına izin verme
  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;

Kaydediciyi nesne değişkeninin yanı sıra bir arayüz değişkeniyle de tutun. Bileşen kendi arayüz referansını tutar ve ClearSystemFontProvider onu düşürür; o son referanssa nesne onunla birlikte gider ve düz bir sınıf değişkeni artık serbest bırakılmış belleğe işaret eder. Herhangi bir render başlamadan önce bir belgenin hangi fontlara referans verdiğini bulmak için, PDF font özelliklerini analiz etme yazısındaki belge başına listeleme, gömülü ve gömülü olmayan fontları yan yana gösterir

Yazı tipi önbelleğini boyutlandırmak

Eşleme istekleri render sırasında sürekli tekrarlanır; o yüzden kabul edilen yanıtlar önbelleğe girer. Önbellek anahtarı yüz adını (büyük-küçük harf yoksayarak), ağırlığı, italik bayrağını, karakter kümesini ve aralık ailesini kapsar ve MaxCacheEntries'e ulaşıldığında en uzun süredir kullanılmayan girdi tahliye edilir. 0 değeri önbelleği kapatır; her istek sağlayıcınıza ulaşır ve yeniden doğrulanır. Negatif bir değer ya da sıfır ve altındaki bir MaxFontBytes, ConfigureSystemFontProvider'ın "Invalid system font provider policy" fırlatmasına yol açar

Girdi sayıları, tek bir CJK koleksiyonu 20 MB'ı aşabildiğinde bellek hakkında az şey söyler. Bayt bütçesi için ConfigureSystemFontCacheGovernor, FPdfCache ünitesinden bir TPdfCacheGovernor takar; en yüksek bayt sayısıyla kurulan ve bileşenin öteki önbellekleriyle paylaşılan bir nesne. O da kütüphane yüklenmeden ayarlanmalıdır. Her önbellek girdisi font verisinin tam uzunluğuyla faturalanır; dört farklı karakter kümesi için istekleri yanıtlayan bir 20 MB'lık koleksiyon, sağlayıcınız her seferinde aynı diziyi döndürse bile bütçeye dört kez yansır. Vali bir rezervasyonu reddettiğinde font yine sunulur, yalnızca önbelleğe alınmaz. Vali nesnesini UnloadLibrary koşana kadar canlı tutun; çünkü önbellek girdileri ona karşı rezervasyon tutar

Eşlemeyi üretimde kanıtlamak

GetSystemFontProviderStatistics bir TPdfSystemFontStatistics kaydı döndürür. Configured ile Installed, bir sağlayıcının kurulup kurulmadığını ve PDFium'a verilip verilmediğini söyler. MapRequests her eşleme isteğini sayar; CacheHits, ProviderHits ve DefaultFallbackHits bunların nasıl yanıtlandığını gösterir. FailedRequests hiç kimsenin yanıtlamadıklarını, RejectedProviderResponses ise ilkenin reddettiği yanıtları sayar. Kalan alanlar tablo düzeyi okumaları (FontDataRequests), canlı font tanıtıcılarını, önbellekteki fontları, önbellekteki baytları ve tahliyeleri izler

GetSystemFontProviderStatistics, PDFium yazı tipi eşleme isteklerini bir Delphi uyumluluk çalıştırmasında önbellek, sağlayıcı ve yedek isabetlerine ayırır; DefaultFallbackHits veya FailedRequests göründüğünde istisna yükseltir
İstatistik kaydı, yazı tipi değiştirmesini bir uygunluk çalıştırmasının iddia edebileceği bir şeye çevirir; herhangi bir yedekleme ya da başarısız istek, belgenin kümenin göndermediği bir yazı tipine gereksinim duyduğu demektir

Bir uygunluk çalıştırması sayaçları toplu işten sonra okur, sonra kaldırır. UnloadLibrary, PDFium'u kapatmadan önce sağlayıcıyı PDFium'dan ayırır, platform eşleyicisini serbest bırakır ve önbelleği boşaltır; belgeler hâlâ açıkken koşmayı reddeder. ClearSystemFontProvider en sona kalır; PDFium hâlâ yüklüyse fırlatır ve sayaçları sıfırlar, o yüzden önce onları okuyun:

var
  Recorder: TRecordingFontProvider;
  RecorderRef: IPdfSystemFontProvider;   // nesneyi canlı tutar
  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 ve RenderCorpus sizin; toplu iş, UnloadLibrary
  // koşmadan önce açtığı her belgeyi kapatmalı
  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;               // sağlayıcıyı ayırır, sonra PDFiumu kapatır
  ClearSystemFontProvider;     // yalnızca PDFium kaldırıldıktan sonra serbest

  if (Stats.FailedRequests > 0) or (Stats.RejectedProviderResponses > 0) then
    raise Exception.Create('Font set incomplete:' + sLineBreak +
      Recorder.MissedFaces);
end;

Yedek kapalıyken DefaultFallbackHits sıfırda kalır ve her boşluk FailedRequests'e düşer; sağlayıcı yanıt verdi ama ilke adı ya da boyutu reddettinde çoğu kez yanı başında RejectedProviderResponses olur. Yedek açık bir üretim derlemesinde aynı boşluk DefaultFallbackHits'e taşınır ve grafiklenecek olan o sayaçtır: yeni bir müşteri belge göndermeye başladıktan sonraki yükseliş, font kümenizin kapsamadığı bir ailenin artık ana makinenin ne sunuyorsa onunla render edildiği anlamına gelir. Bileşenin geri kalanı için iş parçacığı kuralları, ayrıca anlatılan render kilidi disiplinini izler

Aynı kütüphane örneği font sağlamayı, render etmeyi ve metin çıkarmayı Delphi, C++Builder ve Lazarus'ta üstlenir; sürümler ve yerel kütüphanenin dağıtımı Delphi için PDFium Component sayfasında anlatılır