Fast Web View: como um PDF abre antes de terminar de baixar

SpecSpec: ISO 32000-2, Annex FISO 32000-2 Annex F

Visão geral

Um PDF linearizado é reorganizado de modo que a primeira página e um pequeno índice de navegação fiquem bem à frente do arquivo. Um visualizador pode, portanto, desenhar a página um enquanto o resto do documento ainda está chegando, e saltar direto para a página 147 sem ler antes as páginas 2 a 146.

Este é o recurso que a maioria dos leitores conhece pelo seu nome amigável: Fast Web View.

Por que isso importa

Imagine um relatório de 200 páginas em um celular com uma barra de sinal. Sem linearização, o visualizador muitas vezes precisa do final do arquivo antes de conseguir desenhar qualquer coisa, porque o índice mestre que diz onde cada objeto vive tradicionalmente fica no fim. Então você fica olhando para um spinner enquanto duzentas páginas baixam, só para ler a primeira.

Com a linearização, o arquivo é arrumado de modo que a resposta para “o que há na página um” seja a primeira coisa a sair do fio. O leitor pinta a página um em um segundo e busca o resto apenas conforme você rola ou salta. Em uma conexão rápida, você pode nunca notar. Em uma lenta ou tarifada, é a diferença entre um documento utilizável e uma aba abandonada.

A versão resumida

• Um arquivo linearizado é front-loaded: a página um e uma hint table são colocadas primeiro, antes do resto do corpo.
• A hint table é um mapa de faixas. Ela diz ao visualizador quais faixas de bytes pertencem a cada página e aos objetos compartilhados, de modo que o visualizador possa pedir ao servidor apenas essas fatias — e então a tabela de referências cruzadas resolve cada número de objeto até seu offset exato.
• Isso depende de requisições por faixa de bytes — o visualizador buscando fatias do arquivo sob demanda, não o arquivo inteiro.
• Os bytes têm conteúdo idêntico ao de um PDF normal. A linearização muda a ordem e o índice, não as páginas em si.
• É um passo explícito e comutável no NextPDF — produzido por uma reconstrução real de três passes, não uma flag que torce pelo melhor.

Como o NextPDF aborda isso

Você não pode front-loadar uma página até saber exatamente o tamanho de tudo, porque a hint table registra offsets de byte e um offset só está correto depois que o comprimento de cada objeto é final. Essa circularidade — offsets dependem de tamanhos, tamanhos dependem do layout — é o motivo pelo qual um linearizador roda em passes em vez de uma única varredura.

O NextPDF resolve isso com uma reconstrução determinística de três passes. O primeiro passe mede, o segundo decide o posicionamento, o terceiro escreve os bytes reais com os offsets agora conhecidos já gravados.

1. MEASURESerializa cada objeto uma vez para descobrir seu comprimento exato em bytes. Os offsets são circulares — dependem dos tamanhos — então os tamanhos são fixados primeiro.
2. PLACEDecide a ordem: a primeira página e suas dependências à frente, depois o resto. Reserva espaço para o dicionário de parâmetros de linearização e para a hint table.
3. FILLEscreve os bytes finais. Cada campo reservado é preenchido com valores computados após MEASURE e PLACE — o comprimento da primeira página, a localização da hint table, o offset principal de referências cruzadas — derivados dos tamanhos medidos e do posicionamento escolhido.

A reconstrução de linearização em três passes. MEASURE dimensiona cada objeto para que os comprimentos sejam finais; PLACE decide a ordem front-loaded e reserva a região da hint table; FILL escreve os bytes reais com os offsets agora conhecidos, de modo que a primeira página e a hint table fiquem à frente e os dados de referências cruzadas resolvam na primeira busca.

A saída carrega um dicionário de parâmetros de linearização como seu primeiro objeto e uma ou mais hint tables que indexam as páginas, exatamente como a norma prescreve (SpecSpec: ISO 32000-2, Annex FISO 32000-2 Annex F). Essas hint tables funcionam ao lado de uma tabela de referências cruzadas tradicional — elas registram as faixas de bytes e localizações que um visualizador precisa buscar, enquanto a tabela de referências cruzadas é o índice que mapeia cada número de objeto até seu offset exato em bytes. O linearizador do NextPDF emite a forma clássica de tabela e remove qualquer cross-reference stream ao longo do caminho, de modo que, assim que uma fatia chega, o leitor resolve um objeto pelo seu offset diretamente a partir dessa tabela (SpecSpec: ISO 32000-2, §7.5.4ISO 32000-2 §7.5.4).

Um modelo mental útil: um PDF normal é um livro cujo sumário está colado na contracapa de trás. Um PDF linearizado move essa página de sumário para a frente e adiciona um índice de números de página por página, de modo que você pode abrir diretamente em qualquer página. Os capítulos permanecem inalterados. Só a navegação se moveu.

Exemplo prático

A linearização é um passo explícito e comutável. Você a solicita; o motor executa a reconstrução e emite um arquivo Fast-Web-View.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Contracts\OutputDestination;

$document = Document::createStandalone();
$document->setTitle('Annual Report');

for ($page = 1; $page <= 200; $page++) {
    $document->addPage();
    $document->setFont('helvetica', '', 12);
    $document->cell(0, 12, "Page {$page}", newLine: true);
}

// Linearization is requested explicitly — an operability choice, not a default.
// enableLinearization() takes no arguments; it is the on-switch. The engine
// runs the MEASURE -> PLACE -> FILL rebuild and emits a Fast-Web-View file
// with the first page and hint table at the front.
$document->enableLinearization();

$bytes = $document->output(dest: OutputDestination::String);

O conteúdo da página é exatamente o que você escreveu. A diferença está na ordem de arquivo dos bytes que você recebe, e na hint table que agora fica perto do topo.

Você verifica o resultado do jeito que um estranho faria — com um verificador externo:

$ qpdf --check-linearization report.pdf
report.pdf: no linearization errors

qpdf --check-linearization não procura apenas por uma flag. Ele re-deriva os offsets que o arquivo afirma e confirma que são verdadeiros: que os objetos da primeira página realmente estão onde o dicionário de linearização diz, que a hint table aponta para os bytes certos, e que a estrutura está em conformidade com o Annex F. Um arquivo que mente sobre seu próprio layout falha nessa verificação, mesmo que pareça linearizado à primeira vista.

Equívoco comum

A suposição frequente é que a linearização comprime o arquivo ou torna o download mais rápido como um todo. Ela não faz nenhuma das duas coisas. Um arquivo linearizado costuma ser alguns bytes maior, porque carrega as hint tables extras. O tempo total de transferência do documento inteiro é essencialmente o mesmo.

O que muda é quando o primeiro pixel útil aparece. A linearização otimiza o time-to-first-page, não o total de bytes. É um recurso de latência, não um recurso de compressão. Transmitir a página um cedo e baixar o arquivo rápido são metas diferentes, e a linearização serve à primeira.

Um segundo equívoco é que qualquer servidor web transmitirá um arquivo linearizado. O visualizador precisa buscar faixas de bytes, o que significa que o servidor deve honrar requisições HTTP de faixa. A maioria honra, mas um servidor que sempre devolve o arquivo inteiro transforma o Fast Web View de volta em uma espera lenta pelo arquivo inteiro — o arquivo está pronto para ser transmitido, mas o transporte não está.

Human-factors note:Human-factors note

A linearização é um passo explícito e comutável, e isso é deliberado. Ela custa um passe extra de serialização para ser produzida, e ajuda mais em documentos grandes servidos por links lentos e abertos em um navegador. Para uma pequena fatura gerada e enviada por e-mail como anexo, ela adiciona trabalho sem benefício. Torná-la um interruptor em vez de um padrão sempre-ligado permite que você gaste esse custo exatamente onde um leitor sente — o grande relatório público em um celular — e o pule onde ele nunca sentiria.

Limites e fronteiras

O NextPDF tem suporte core completo para produzir arquivos linearizados: um linearizador de produção de três passes que emite o dicionário de parâmetros e as hint tables e passa em uma verificação externa de Annex F.

Fast Web View (linearization) output — edition availability

Edition	Availability
Core	○ Suporte completo. O NextPDF produz saída linearizada (Fast Web View) por meio de uma reconstrução de produção de três passes MEASURE → PLACE → FILL, conforme a ISO 32000-2 Annex F.
Pro	○Not in this edition
Enterprise	○Not in this edition

Duas fronteiras vale nomear. Primeira, a linearização é uma propriedade de uma revisão. No momento em que você anexa uma atualização incremental — uma assinatura, um preenchimento de formulário, uma edição — os bytes anexados vão para o fim e o arquivo deixa de ser estritamente linearizado até ser reconstruído. Esse é um compromisso normal, não um defeito; veja atualizações incrementais para entender por que anexar é o comportamento certo para documentos assinados.

Segunda, o motor controla o arquivo. Ele não controla a rede. O Fast Web View só cumpre sua promessa quando a conexão de serviço honra requisições por faixa de bytes; os bytes podem estar perfeitamente linearizados e ainda assim chegar como um único bloco lento se o servidor insistir em enviar o arquivo inteiro.

Documentos relacionados

• A anatomia de um arquivo PDF — o cabeçalho, o corpo, a tabela de referências cruzadas e o trailer que a linearização rearranja. Leia isto primeiro para ver o que está sendo reordenado.
• Memória e streaming — streaming do lado da escrita, um eixo diferente: como o NextPDF mantém a memória plana enquanto produz bytes, em contraste com como um leitor os recebe em fluxo.
• Atualizações incrementais e por que importam — por que uma edição posterior anexa ao fim, e o que isso significa para o layout front-loaded de um arquivo linearizado.
• Streams e filtros — o que vive dentro dos objetos do corpo para os quais a hint table aponta, e como eles são comprimidos.

Glossário

• Linearização — a reconstrução que coloca à frente a primeira página e um índice de navegação para que um visualizador possa renderizar e navegar antes de o arquivo inteiro chegar. O nome da norma para o resultado.
• Fast Web View — o nome voltado ao consumidor para um PDF linearizado; os dois termos descrevem o mesmo arquivo.
• Hint table — a estrutura dentro de um arquivo linearizado que registra as faixas e localizações de bytes de cada página e dos objetos compartilhados, de modo que um visualizador saiba quais fatias requisitar; a tabela de referências cruzadas é o que então mapeia um número de objeto até seu offset exato em bytes.
• Dicionário de parâmetros de linearização — o primeiro objeto em um arquivo linearizado; ele declara os offsets-chave (comprimento da primeira página, localização da hint table, posição principal de referências cruzadas) que tornam possível a busca sob demanda.
• Requisição por faixa de bytes — uma requisição HTTP por uma fatia de um arquivo em vez do arquivo inteiro; o mecanismo de transporte do qual o Fast Web View depende.
• Time-to-first-page — quanto tempo até um leitor ver a página um. A latência que a linearização otimiza, distinta do tempo total de download.