Ligar BrotliEnabled ou IsolatePerDocument eleva o FPDF_LIBRARY_CONFIG a uma versão em que o PDFium lê o m_RendererType literalmente, então um wrapper que escreve AGG para "default" troca silenciosamente uma build Skia para o renderer AGG sem erro nenhum. No PDFium Component para Delphi, o TPdfLibraryConfiguration mantém o renderer padrão no padrão da própria DLL, e um pedido de Skia ou Fontations que a DLL não possa honrar levanta um EPdfError capturável em vez de matar o processo
As duas armadilhas falham de maneiras opostas. A primeira produz páginas que parecem boas, só que renderizadas por um rasterizador diferente, com anti-aliasing e bordas de texto ligeiramente diferentes da build que você entregou e testou. A segunda se anuncia aos berros, derrubando o processo host de dentro da inicialização nativa. Ambas vêm do mesmo lugar: uma estrutura C versionada cujos campos só contam quando o número de versão diz que contam, e cujos valores zero não são "não definido", mas escolhas reais
Como o FPDF_LIBRARY_CONFIG decide qual renderer o PDFium usa?
O FPDF_InitLibraryWithConfig consulta o m_RendererType só quando o campo Version da estrutura é 4 ou maior, e a partir dessa versão usa o valor exatamente como escrito. Abaixo da versão 4 o PDFium ignora o campo e escolhe o padrão da build, que é Skia em builds compiladas com PDF_USE_SKIA e AGG em todo o resto
Cada campo posterior segue o mesmo padrão. A estrutura cresceu uma capacidade por vez, e cada capacidade chegou junto com um novo número de versão. O PDFium Component monta a estrutura nativa no LoadLibrary a partir do seu TPdfLibraryConfiguration e eleva a versão só até onde as opções que você definiu exigem
| Versão da estrutura | Campo que adiciona | Definido por |
|---|---|---|
| 2 | m_pIsolate, m_v8EmbedderSlot | Sempre gravado; V8Isolate, V8EmbedderSlot |
| 3 | m_pPlatform | V8Platform não nil |
| 4 | m_RendererType | Renderer diferente de prpDefault |
| 5 | m_FontLibraryType | FontBackend diferente de pfbpDefault |
| 6 | m_BrotliEnabled | BrotliEnabled = True |
| 7 | m_IsolatePerDocument | IsolatePerDocument = True |
A armadilha está nas duas últimas linhas. Versões são cumulativas: uma estrutura de versão 6 também é uma estrutura de versão 4 e de versão 5, então o PDFium lê o m_RendererType e o m_FontLibraryType mesmo que você só tenha pedido Brotli. O que estiver nesses dois campos naquele momento vira o renderer e o backend de fontes, você quis escolhê-los ou não
Por que ligar o Brotli pode trocar o renderer para AGG?
O mapeamento óbvio escreve FPDF_RENDERERTYPE_AGG no m_RendererType para o prpDefault, e então qualquer configuração que empurre a estrutura para a versão 6 ou 7 force AGG numa build Skia. Os runtimes pdfium.dll e pdfium.v8.dll que vêm com o componente são builds Skia, então esse mapeamento acertaria o deployment padrão, não um exótico
O mapeamento parece inofensivo. Na versão 2 ou 3 o campo nunca é lido, então prpDefault realmente significa "o que a DLL fizer". No momento em que BrotliEnabled (versão 6) ou IsolatePerDocument (versão 7) entra em cena, o mesmo código transforma "sem preferência" num pedido AGG explícito. Nada falha. O PDFium inicializa normalmente, renderiza cada página, e devolve nenhum código de erro, porque do ponto de vista dele o chamador pediu AGG e recebeu AGG
Um hash de pixels torna a troca visível onde screenshots não mostram. Renderizar a primeira página do mesmo documento de amostra sob três configurações dá:
- Configuração padrão: hash
502D77C3711B4ACF BrotliEnabled= True comprpDefaultescrito comoFPDF_RENDERERTYPE_AGG: hashF75B5EB4728ADE87prpAggexplícito: hashF75B5EB4728ADE87, idêntico à execução com Brotli
O PDFium Component resolve isso através da função pública PdfNativeRendererType, que resolve um TPdfRendererPreference para o valor escrito no m_RendererType. prpAgg e prpSkia mapeiam um para um. prpDefault mapeia para Skia quando a DLL carregada exporta FPDF_RenderPageSkia e para AGG caso contrário. Esse export é compilado sob a mesma condição PDF_USE_SKIA que o próprio padrão Skia, o que o torna a única propriedade de build observável de fora da DLL. Com essa resolução, a configuração com Brotli produz o mesmo hash que a padrão
O backend de fontes não tem o mesmo problema. O m_FontLibraryType é lido a partir da versão 5, e o valor zero dele, FPDF_FONTBACKENDTYPE_FREETYPE, também é o padrão do PDFium quando o campo não é lido de forma alguma. Escrever FreeType para pfbpDefault portanto reproduz o padrão nativo exatamente. Valores zero nem sempre são errados, só nunca são automaticamente certos
O código de inicialização que você escreveria naturalmente faz o que diz:
uses
PDFium;
procedure ConfigurePdfiumAtStartup;
var
Config: TPdfLibraryConfiguration;
begin
// Precisa rodar antes de qualquer coisa carregar a biblioteca nativa
Config := TPdfLibraryConfiguration.Default;
Config.BrotliEnabled := True; // eleva FPDF_LIBRARY_CONFIG à versão 6
// Renderer fica prpDefault: resolve para Skia em builds que exportam
// FPDF_RenderPageSkia e para AGG em builds só AGG
// UserFontPaths substitui as pastas de fontes da plataforma, então liste
// a pasta de fontes do Windows também se os documentos ainda devem achar fontes do sistema
SetLength(Config.UserFontPaths, 2);
Config.UserFontPaths[0] := 'C:\ProgramData\MyApp\Fonts';
Config.UserFontPaths[1] := 'C:\Windows\Fonts';
ConfigurePdfLibrary(Config);
end;
UserFontPaths é uma lista de substituição, não uma adição. Assim que ele guarda pelo menos uma pasta, o PDFium varre só essas pastas e descarta os padrões da plataforma: /usr/share/fonts e companhia no Linux, as três pastas Library/Fonts no macOS. No Windows a mudança é maior que uma troca de caminho, porque o PDFium para de enumerar fontes instaladas através da GDI e volta a ler arquivos de fonte das pastas listadas. Uma lista que nomeia só a pasta da sua aplicação deixa, portanto, todo documento que depende de Arial ou Times New Roman à substituição, que é por que o exemplo acrescenta a pasta de fontes do Windows (resolva-a com GetWindowsDirectory em vez de fixar a unidade no código real)
Lembre que o BrotliEnabled só torna streams /BrotliDecode do PDF 2.0 decodificáveis quando a própria DLL foi construída com PDF_ENABLE_BROTLI. A flag é um pedido, e numa build sem suporte a Brotli ela não tem efeito. O TPdfLibraryConfiguration.Hardened é igual ao Default exceto que AllowMachineTime é False, o que impede o JavaScript do documento de ler o relógio real; é um ponto de partida razoável para processamento no servidor de arquivos não confiáveis
O que acontece quando você pede um backend que a DLL não contém?
O PDFium não devolve erro para um renderer ou backend de fontes ausente da build: o FPDF_InitLibraryWithConfig falha num CHECK nativo, que no Windows aparece como uma exceção de breakpoint e, sem um structured exception handler em volta da chamada, termina o processo. O header diz isso, avisando que um valor não suportado "falhará de forma similar com um crash imediato"
Os dois casos concretos são uma build só AGG que recebe FPDF_RENDERERTYPE_SKIA, e uma build sem Fontations que recebe FPDF_FONTBACKENDTYPE_FONTATIONS. O runtime Skia embutido está no segundo grupo: ele renderiza com Skia mas usa FreeType para fontes. Pedir prpSkia junto com pfbpFontations contra ele produziu External exception 80000003 do lado Delphi. Quando o debugger ou um exception handler por acaso pega isso, a situação continua irrecuperável:
- O PDFium fica meio inicializado
- A configuração de todo o processo já está travada, então o
ConfigurePdfLibraryrecusa uma configuração corrigida - Repetir com uma configuração diferente no mesmo processo não é mais possível
Este é o fracasso oposto à troca do Brotli. Ali o campo carregava um valor que ninguém escolheu e o PDFium o aceitou silenciosamente. Aqui o campo carrega um valor que o chamador escolheu deliberadamente e o PDFium não aceita discussão alguma sobre ele. Os dois são problemas que um wrapper precisa resolver antes da chamada nativa, porque depois dela não sobra nada para capturar
Como o PDFium Component pré-checa Skia e Fontations
O LoadLibrary valida a configuração depois de vincular os exports da DLL e antes de chamar FPDF_InitLibraryWithConfig, e transforma um renderer ou backend de fontes não suportado em um EPdfError com uma mensagem que nomeia a configuração ofensora e as alternativas. A DLL é descarregada e a configuração destravada, então o chamador pode escolher outras opções e carregar de novo
A decisão em si vive na função pura PdfLibraryConfigurationSupportError, que recebe a configuração mais dois Booleans descrevendo a build e devolve uma string vazia quando a combinação é segura. Como ela não toca em estado nativo, você pode chamá-la dos seus próprios testes com qualquer combinação de capacidades. Dentro do LoadLibrary os dois Booleans vêm de tipos diferentes de evidência, e merecem níveis diferentes de confiança:
- Skia é detectado pela presença do export
FPDF_RenderPageSkia, o mesmo sinal que oPdfNativeRendererTypeusa. O export e o renderer Skia são compilados sob uma condição, então a checagem é exata - Fontations não tem export próprio. O único rastro que deixa são as font crates Rust que puxa para o binário, então o PDFium Component escaneia o arquivo da biblioteca carregada atrás dos nomes de crate
skrifaeread-fonts(tambémread_fonts). O escaneamento roda só quandopfbpFontationsé pedido, e um arquivo que não pode ser lido conta como "sem Fontations"
A checagem de Fontations é uma heurística, e pode errar num sentido: uma build Fontations despojada de todas essas strings seria rejeitada embora pudesse funcionar. O trade foi feito de propósito. Uma rejeição falsa custa uma exceção que você pode capturar e um fallback para FreeType. Uma aceitação falsa custa o processo
Destravar importa tanto quanto a checagem. O LoadLibrary trava a configuração bem no começo do carregamento, então sem o reset uma rejeição de capacidade deixaria o ConfigurePdfLibrary respondendo toda repetição com o EPdfError "A configuração da biblioteca PDFium já está travada". O caminho de rejeição chama UnloadLibrary primeiro; a chamada FPDF_DestroyLibrary dele é segura nesse ponto porque o PDFium ainda não foi inicializado e retorna imediatamente. Outras falhas de carregamento, como uma DLL ausente ou um mismatch de arquitetura, mantêm a trava, então um loop de repetição tem de distinguir as duas:
uses
SysUtils, PDFium;
function StartPdfiumPreferringSkia: TPdfRendererPreference;
var
Config: TPdfLibraryConfiguration;
begin
Config := TPdfLibraryConfiguration.Default;
Config.Renderer := prpSkia;
ConfigurePdfLibrary(Config);
try
PDFium.LoadLibrary; // qualificado pela unit: Windows.LoadLibrary tem o mesmo nome
Result := prpSkia;
except
on E: EPdfError do
begin
// Uma rejeição de capacidade descarrega a DLL e destrava a configuração.
// Uma DLL que não carregou de forma alguma fica travada: repetir não ajuda
if PdfLibraryConfigurationSealed then
raise;
Config.Renderer := prpAgg;
ConfigurePdfLibrary(Config);
PDFium.LoadLibrary;
Result := prpAgg;
end;
end;
end;
Note o PDFium.LoadLibrary explícito. Numa unit que também usa Windows ou Winapi.Windows, um LoadLibrary sem qualificação resolve para a unit que aparecer por último na uses clause; quando essa é a função Win32, a chamada sem parâmetros não compila com um erro de contagem de argumentos que não diz nada sobre o PDFium
Validação que acontece ainda mais cedo
O ConfigurePdfLibrary rejeita algumas combinações antes de qualquer DLL entrar em cena, todas com EPdfError. Um FontBackend explícito, incluindo pfbpFreeType, exige Renderer = prpSkia, porque o PDFium só consulta o backend de fontes para o renderer Skia. O IsolatePerDocument exige V8Isolate nil, já que o PDFium cria o isolate próprio dele por documento e falha num CHECK nativo se você também entregar um. Strings vazias em UserFontPaths são rejeitadas. E qualquer chamada depois da primeira tentativa de carregamento falha com "A configuração da biblioteca PDFium já está travada"
Essa última regra tem uma consequência prática: você não pode espionar a DLL primeiro e configurá-la depois. O GetSkiaRenderCapabilities, o V8FeaturesAvailable, abrir um documento e a maior parte dos outros pontos de entrada chama o LoadLibrary internamente, o que trava a configuração na hora. Chamar o UnloadLibrary depois também não a reabre. Configure primeiro, depois carregue, depois pergunte, que é exatamente a ordem que uma rotina de diagnóstico deve seguir:
uses
SysUtils, PDFium, FPdfView;
function DescribePdfiumState: string;
var
Config: TPdfLibraryConfiguration;
Renderer: string;
begin
Config := GetPdfLibraryConfiguration; // uma cópia, seguro inspecionar
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;
// A mesma resolução que LoadLibrary aplicou ao montar FPDF_LIBRARY_CONFIG
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;
Registrar essa linha uma vez na inicialização é barato, e é a primeira coisa que você quer num ticket de suporte que diz "o texto parece diferente no servidor". O PDFium.Loaded é qualificado pelo mesmo motivo que o LoadLibrary: dentro de um método de form ou componente, um Loaded nu vincula ao TComponent.Loaded
Duas maneiras de uma struct de configuração C versionada dar errado
Toda estrutura de configuração versionada, seja um FPDF_LIBRARY_CONFIG, um registro Win32 com cbSize, ou uma ABI de plugin, falha de duas maneiras simétricas, e um wrapper precisa se guardar das duas. A primeira é preencher um campo deixando a versão baixa demais; a segunda é elevar a versão deixando um campo num valor zero que a biblioteca lê como escolha deliberada
- Campo definido, versão baixa demais. Grave
m_BrotliEnabled= 1 numa estrutura de versão 2 e o PDFium nunca olha para ele. A chamada tem sucesso e streams Brotli continuam indecodificáveis. A defesa é derivar a versão dos campos efetivamente em uso, que é o que oLoadLibraryfaz, em vez de fixar um - Versão alta o bastante, campo zero significa algo. Eleve a versão para 6 e todo campo até a versão 6 agora está vivo. O
FillCharzera om_RendererTypeparaFPDF_RENDERERTYPE_AGG, que é um renderer real, não "não definido". A defesa é gravar todo campo que a versão escolhida cobre com um valor intencional, e resolver o "padrão" contra a build real em vez de assumi-lo
Uma terceira regra se segue para valores que podem derrubar o chamado: valide-os contra o que o binário consegue fazer antes da chamada, usando a evidência mais forte disponível, e seja honesto no código e na documentação quando essa evidência for uma heurística. Um símbolo exportado é prova. Um nome de crate numa tabela de strings é um bom chute
Referência rápida: configuração da biblioteca do PDFium Component
- Chame o
ConfigurePdfLibraryuma vez, antes de qualquer coisa carregar a DLL; qualquer consulta de capacidade ou carregamento de documento o trava - Deixe o
RendereremprpDefaulta menos que precise de um rasterizador específico; ele resolve para o padrão da build em toda versão da estrutura - Use o
PdfNativeRendererTypecomGetSkiaRenderCapabilities.PageRenderpara registrar qual renderer está de fato ativo - Espere um
EPdfError, não um crash, paraprpSkianuma DLL só AGG oupfbpFontationsnuma DLL sem Fontations - Depois de uma rejeição de capacidade,
PdfLibraryConfigurationSealedé False e você pode reconfigurar; depois de um carregamento de DLL que falhou ele continua True - Trate a detecção de Fontations como heurística e mantenha um fallback FreeType
- Escreva
PDFium.LoadLibraryePDFium.Loadedcom o nome da unit para evitar conflitos de nome com Win32 eTComponent
Se a DLL falha antes de a configuração sequer importar, comece por diagnosticar falhas de carregamento da DLL PDFium em Delphi, e para como o componente encontra o binário certo em cada plataforma veja carregar a biblioteca nativa PDFium em qualquer alvo. Uma vez ajustado o renderer, táticas de cache de render e zoom suave cobre como manter a renderização de páginas rápida num viewer
O PDFium Component embrulha o motor PDFium para Delphi e C++Builder com checagens de configuração como estas, para que a inicialização nativa falhe como uma exceção Pascal que você pode tratar em vez de uma saída do processo. Detalhes de produto e downloads estão na página de produto do PDFium Component para Delphi