Dowód dostawy wyprodukowany na biurku z Windows nazywa Arial w swoim słowniku fontu, nie niesie programu fontu i wygląda dobrze w każdej przeglądarce na tym biurku. Zrasteryzowany w kontenerze Debiana ten sam plik rysuje każdy glif innym bezszeryfowym fontem. Tekst wciąż zaczyna się tam, gdzie powinien, bo pozycje glifów pochodzą z tablicy /Widths zapisanej w PDF-ie, ale kształty liter się zmieniają, odstępy wyglądają nierówno wszędzie tam, gdzie kontury zastępnika są węższe niż szerokości, w których siedzą, a znak, którego zastępnik nie ma, zostawia dziurę. Renderer nie zawinił. Dokument oddał wybór fontu temu, kto go renderuje, i ten wybór może zapaść w twoim własnym kodzie przez dostarczenie bajtów fontu, które wysyłasz razem z aplikacją
ISO 32000-1 na to pozwala. Standardowe 14 fontów z §9.6.2.2 zawsze można wskazać samą nazwą, a każdy inny prosty font może pozostać nieosadzony, o ile jego słownik i deskryptor fontu (§9.8) opisują metryki i flagi. PDF/A zabrania tego wprost (ISO 19005-1 §6.3.4 wymaga osadzenia każdego programu fontu), co wiele mówi o tym, jak wiarygodne są fonty wskazywane samą nazwą, gdy plik opuści maszynę, która go zapisała
Dlaczego po prostu nie zainstalować fontów na serwerze?
Czasem zainstalowanie fontów wystarczy. Zawodzi to w trzech typowych sytuacjach. Licencja fontu może pozwalać na użycie desktopowe, ale nie na instalację na serwerze, który renderuje dokumenty automatycznie. Obrazy kontenerów są często przebudowywane, a font wgrany ręcznie znika z następnym wdrożeniem. Regulowane procesy chcą stosu renderowania odtwarzalnego z artefaktów pod kontrolą wersji, a ogólnosystemowy folder fontów do nich nie należy
Jest też krok pośredni. TPdfLibraryConfiguration.UserFontPaths, przekazywane przez ConfigurePdfLibrary przed załadowaniem biblioteki, mówi natywnemu mapperowi PDFium, które foldery skanować w poszukiwaniu plików fontów. Lista zastępuje domyślne ścieżki platformy, zamiast je uzupełniać, a na Windows wyłącza też enumerację fontów GDI, więc dołącz systemowy folder fontów, jeśli dokumenty nadal potrzebują zainstalowanych fontów. Mapper wciąż decyduje, który plik wygrywa dla danego żądania, według własnych reguł dopasowania. Gdy musisz wiedzieć dokładnie, które bajty odpowiadają na "Arial, bold, Cyrillic charset", ta decyzja musi żyć w kodzie, który możesz przeczytać, i to właśnie daje dostawca fontów systemowych
Instalowanie IPdfSystemFontProvider przed załadowaniem PDFium
PDFium Component wystawia mapowanie fontów przez jeden interfejs z jedną metodą. IPdfSystemFontProvider.ResolveFont dostaje TPdfSystemFontRequest niosący FaceName, Weight, Italic, Charset i PitchFamily, a odpowiada rekordem TPdfSystemFontData z nazwą kroju, kompletnymi bajtami TrueType, OpenType lub TrueType Collection, zestawem znaków i TTCIndex. Zwrócenie False odrzuca żądanie
ConfigureSystemFontProvider musi się wykonać przed załadowaniem biblioteki. PDFium bierze swój mapper fontów raz, podczas inicjalizacji, więc komponent rzuca EPdfError ("Configure the system font provider before loading PDFium"), jeśli Loaded jest już prawdą. Wiele wywołań ładuje bibliotekę na żądanie, włącznie z sondami funkcji, więc umieść konfigurację na samym początku startu. Dostawca poniżej buduje tabelę wyszukiwania i czyta każdy plik fontu w konstruktorze; potem ResolveFont tylko czyta:
uses
System.SysUtils, System.Classes, System.IOUtils, PDFium;
type
TBundledFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
private
FKeys: TStringList; // sortowane raz w konstruktorze, potem tylko do odczytu
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);
// Alias: zgłaszaj faktycznie podawaną rodzinę, żeby zasada ją widziała
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 i więcej podawane jako bold
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; // numer kroju wewnątrz kolekcji .ttc
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);
// Dopiero teraz otwieraj dokumenty; pierwsze wywołanie potrzebujące PDFium je ładuje
end;
Klucze tabeli w tym przykładzie są celowo naiwne. Prawdziwe dokumenty piszą tę samą rodzinę na kilka sposobów, więc zaloguj Request.FaceName z reprezentatywnej partii, zanim zamrozisz tabelę; nagrywający wrapper niżej produkuje dokładnie taką listę. Próg wagi też jest wyborem: FXFONT_FW_NORMAL to 400, a FXFONT_FW_BOLD to 700 w module FPdfExtensions, a żądanie semibold o wadze 600 musi wylądować po jednej albo po drugiej stronie
Co dokładnie decydują flagi zasady
Każde żądanie idzie tą samą ścieżką. Komponent najpierw sprawdza swój cache, potem woła twojego dostawcę, potem waliduje odpowiedź. Zaakceptowana odpowiedź trafia do cache i do PDFium. Odrzucona lub odmowna odpowiedź idzie do mappera platformy zwracanego przez FPDF_GetDefaultSystemFontInfo, ale tylko gdy AllowDefaultFallback jest włączone; w przeciwnym razie żądanie liczy się jako nieudane i PDFium idzie dalej bez twojego fontu
Sama walidacja jest krótka. Puste FontData jest odrzucane, podobnie jak cokolwiek dłuższego niż MaxFontBytes. Pusty FaceName w odpowiedzi jest uzupełniany żądaną nazwą. Przy wyłączonym AllowFaceSubstitution zgłoszona nazwa kroju różna od żądanej (porównywana bez względu na wielkość liter) jest również odrzucana. Ta kontrola czyta nazwę, którą zgłaszasz, i nic więcej. Dostawca, który podaje bajty Liberation Sans, zgłaszając "Arial", przechodzi bez problemu, i dlatego przykład zgłasza prawdziwą rodzinę dla swojego aliasu Helvetica: przy wyłączonej fladze żądanie Helvetica obsłużone jako "Arial" jest odrzucane i ląduje w RejectedProviderResponses
Indeks TTC jest sprawdzany w innym miejscu. PDFium często prosi o jedną tabelę sfnt naraz, na przykład cmap albo glyf, a komponent odpowiada na te zapytania, przechodząc po katalogu tabel zwróconych bajtów. Dla kolekcji startuje od katalogu wybranego przez TTCIndex; indeks poza liczbą fontów w nagłówku ttcf albo niezerowy indeks na pliku z pojedynczym fontem sprawia, że te zapytania o tabele nie zwracają nic. Przejście po katalogu rozpoznaje TrueType (0x00010000 i true), OpenType z konturami CFF (OTTO) i kolekcje (ttcf). Pliki WOFF i WOFF2 trzeba zdekompresować do zwykłego sfnt, zanim dostawca je zwróci
TPdfSystemFontPolicy.Default włącza obie flagi, z pułapem 64 MB na font i 32 wpisami cache. To pasuje do dostawcy wdrażanego po kilka rodzin naraz, gdzie wszystko, czego jeszcze nie zmapowałeś, renderuje się tak jak dotąd. Build audytowy powinien wyłączyć obie flagi. Luki pokazują się wtedy jako policzone niepowodzenia i odrzucone podstawienia, a trafienie w fallback nie może już ukryć rodziny, o której zestaw fontów zapomniał
Który wątek woła ResolveFont?
ResolveFont biegnie na tym wątku, który akurat ładuje lub renderuje stronę potrzebującą fontu, a to niekoniecznie wątek główny. Komponent chroni własny cache i liczniki sekcją krytyczną, ale nie trzyma tej blokady, gdy wykonuje się twoja metoda. Jeśli aplikacja renderuje na wątkach w tle, każdy stan, który dostawca zmienia po konstrukcji, potrzebuje własnej ochrony
Wyjątki to druga rzecz, którą trzeba trzymać wewnątrz metody. Komponent łapie wszystko, co ucieknie z ResolveFont, na granicy z biblioteką natywną i traktuje to jako odrzucone żądanie, więc żądanie idzie dalej do fallbacku albo niepowodzenia. Poleganie na tym zamienia błąd w twoim kodzie mapowania w font po cichu podany przez kogoś innego. Wrapper poniżej zapisuje każde pudło pod blokadą i trzyma wyjątki lokalnie, co daje ci też listę nazw krojów do dodania do tabeli:
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; // zaloguj tutaj; nie pozwól temu dotrzeć do PDFium
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;
Trzymaj rekorder zarówno przez zmienną interfejsową, jak i przez zmienną obiektową. Komponent trzyma własną referencję interfejsu, a ClearSystemFontProvider ją zwalnia; jeśli była to ostatnia referencja, obiekt znika razem z nią, a zwykła zmienna klasowa wskazuje teraz zwolnioną pamięć. Do znalezienia, które fonty dokument wskazuje, zanim dojdzie do jakiegokolwiek renderowania, listowanie per dokument w analizie właściwości fontów PDF pokazuje fonty osadzone i nieosadzone obok siebie
Dobieranie rozmiaru cache fontów
Żądania mapowania powtarzają się bez przerwy podczas renderowania, więc zaakceptowane odpowiedzi trafiają do cache. Klucz cache obejmuje nazwę kroju (bez względu na wielkość liter), wagę, flagę kursywy, zestaw znaków i rodzinę pitch, a po osiągnięciu MaxCacheEntries wyrzucany jest wpis najdawniej używany. Wartość 0 wyłącza cache, więc każde żądanie dociera do twojego dostawcy i jest walidowane ponownie. Wartość ujemna albo MaxFontBytes równe zero lub mniej sprawia, że ConfigureSystemFontProvider rzuca "Invalid system font provider policy"
Liczba wpisów mało mówi o pamięci, gdy pojedyncza kolekcja CJK może przekroczyć 20 MB. Dla budżetu bajtowego ConfigureSystemFontCacheGovernor podpina TPdfCacheGovernor z modułu FPdfCache, utworzony z maksymalną liczbą bajtów i współdzielony z pozostałymi cache komponentu. Jego też trzeba ustawić przed załadowaniem biblioteki. Każdy wpis w cache jest obciążany pełną długością swoich danych fontu, więc kolekcja 20 MB odpowiadająca na żądania dla czterech różnych zestawów znaków liczy się cztery razy do budżetu, nawet jeśli dostawca za każdym razem zwraca tę samą tablicę. Gdy governor odmawia rezerwacji, font nadal jest podawany, tylko nie trafia do cache. Trzymaj obiekt governora przy życiu, dopóki nie wykona się UnloadLibrary, bo wpisy w cache trzymają wobec niego rezerwacje
Dowodzenie poprawności mapowania na produkcji
GetSystemFontProviderStatistics zwraca rekord TPdfSystemFontStatistics. Configured i Installed mówią, czy dostawca jest ustawiony i czy został przekazany do PDFium. MapRequests liczy każde żądanie mapowania, a CacheHits, ProviderHits i DefaultFallbackHits pokazują, jak zostały obsłużone. FailedRequests liczy te, na które nic nie odpowiedziało, a RejectedProviderResponses odpowiedzi odrzucone przez zasadę. Pozostałe pola śledzą odczyty na poziomie tabel (FontDataRequests), żywe uchwyty fontów, fonty w cache, bajty w cache i wyrzucenia
Przebieg zgodności czyta liczniki po partii, a potem wyładowuje bibliotekę. UnloadLibrary odłącza dostawcę od PDFium, zwalnia mapper platformy i opróżnia cache, zanim zamknie PDFium, i odmawia działania, dopóki dokumenty są jeszcze otwarte. ClearSystemFontProvider idzie na końcu; rzuca wyjątek, jeśli PDFium jest wciąż załadowane, i zeruje liczniki, więc najpierw je odczytaj:
var
Recorder: TRecordingFontProvider;
RecorderRef: IPdfSystemFontProvider; // trzyma obiekt przy życiu
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 i RenderCorpus są twoje; partia musi
// zamknąć każdy otwarty dokument, zanim wykona się UnloadLibrary
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; // odłącza dostawcę, potem zamyka PDFium
ClearSystemFontProvider; // dozwolone dopiero po wyładowaniu PDFium
if (Stats.FailedRequests > 0) or (Stats.RejectedProviderResponses > 0) then
raise Exception.Create('Font set incomplete:' + sLineBreak +
Recorder.MissedFaces);
end;
Przy wyłączonym fallbacku DefaultFallbackHits zostaje na zerze, a każda luka ląduje w FailedRequests, często obok RejectedProviderResponses, gdy dostawca odpowiedział, ale zasada odrzuciła nazwę albo rozmiar. W buildzie produkcyjnym z włączonym fallbackiem ta sama luka przenosi się do DefaultFallbackHits i to ten licznik warto wykreślać: wzrost po tym, jak nowy klient zaczyna przysyłać dokumenty, oznacza, że rodzina, której twój zestaw fontów nie pokrywa, jest teraz renderowana tym, co akurat oferuje host. Reguły wątkowania dla reszty komponentu opisuje osobno dyscyplina blokady renderowania
Ta sama instancja biblioteki obsługuje dostarczanie fontów, renderowanie i ekstrakcję tekstu w Delphi, C++Builder i Lazarus, a strona PDFium Component dla Delphi opisuje edycje i wdrażanie biblioteki natywnej