Fast Web View: come un PDF si apre prima di finire il download

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

In sintesi

Un PDF linearizzato è riorganizzato in modo che la prima pagina e un piccolo indice di navigazione si trovino proprio all’inizio del file. Un lettore può quindi disegnare la prima pagina mentre il resto del documento sta ancora arrivando, e saltare direttamente alla pagina 147 senza leggere prima le pagine da 2 a 146.

Questa è la funzionalità che la maggior parte dei lettori conosce con il suo nome amichevole: Fast Web View.

Perché è importante

Si immagini un report di 200 pagine su un telefono con una tacca di segnale. Senza linearizzazione, il lettore ha spesso bisogno della parte finale del file prima di poter disegnare qualcosa, perché l’indice principale che indica dove risiede ogni oggetto si trova tradizionalmente in fondo. Così si guarda una rotellina di caricamento mentre duecento pagine vengono scaricate, solo per leggere la prima.

Con la linearizzazione, il file è disposto in modo che la risposta a «cosa c’è nella prima pagina» sia la prima cosa a uscire dal cavo. Il lettore dipinge la prima pagina in un secondo, e recupera il resto solo quando si scorre o si salta. Su una connessione veloce si potrebbe non notarlo mai. Su una lenta o a consumo, è la differenza tra un documento utilizzabile e una scheda abbandonata.

In breve

• Un file linearizzato è caricato in testa: la prima pagina e una hint table sono collocate per prime, prima del resto del corpo.
• La hint table è una mappa di intervalli. Indica al lettore quali intervalli di byte appartengono a ciascuna pagina e agli oggetti condivisi, così che il lettore possa chiedere al server solo quelle porzioni — poi la cross-reference table risolve ogni numero di oggetto al suo offset esatto.
• Questo si basa sulle richieste byte-range — il lettore che recupera porzioni del file su richiesta, non l’intera cosa.
• I byte sono contenuto identico a un PDF normale. La linearizzazione cambia l’ordine e l’indice, non le pagine stesse.
• È un passaggio esplicito e attivabile in NextPDF — prodotto da una vera ricostruzione in tre passaggi, non un flag che spera per il meglio.

Come NextPDF lo affronta

Non si può mettere in testa una pagina finché non si sa esattamente quanto è grande ogni cosa, perché la hint table registra gli offset dei byte e un offset è corretto solo quando la lunghezza di ogni oggetto è definitiva. Quella circolarità — gli offset dipendono dalle dimensioni, le dimensioni dipendono dal layout — è il motivo per cui un linearizzatore viene eseguito in passaggi anziché in una sola passata.

NextPDF la risolve con una ricostruzione deterministica in tre passaggi. Il primo passaggio misura, il secondo decide la collocazione, il terzo scrive i byte reali con gli offset ormai noti incorporati.

1. MEASURESerialise every object once to learn its exact byte length. Offsets are circular — they depend on sizes — so sizes are pinned first.
2. PLACEDecide the order: first page and its dependencies up front, then the rest. Reserve space for the linearization parameter dictionary and the hint table.
3. FILLWrite the final bytes. Each reserved field is filled with values computed after MEASURE and PLACE — the first-page length, the hint-table location, the main cross-reference offset — derived from the measured sizes and the chosen placement.

The three-pass linearization rebuild. MEASURE sizes every object so lengths are final; PLACE decides the front-loaded order and reserves the hint-table region; FILL writes the real bytes with the now-known offsets, so the first page and the hint table land at the front and the cross-reference data resolves on first fetch.

L’output porta un linearization parameter dictionary come suo primo oggetto e una o più hint table che indicizzano le pagine, esattamente come lo standard prescrive (SpecSpec: ISO 32000-2, Annex FISO 32000-2 Annex F). Quelle hint table funzionano accanto a una tradizionale cross-reference table — registrano gli intervalli di byte e le posizioni che un lettore deve recuperare, mentre la cross-reference table è l’indice che mappa ogni numero di oggetto al suo offset di byte esatto. Il linearizzatore di NextPDF emette la forma classica a tabella ed espelle lungo il percorso ogni cross-reference stream, così che, una volta arrivata una porzione, il lettore risolva un oggetto tramite il suo offset direttamente da quella tabella (SpecSpec: ISO 32000-2, §7.5.4ISO 32000-2 §7.5.4).

Un modello mentale utile: un PDF normale è un libro il cui indice è incollato alla quarta di copertina. Un PDF linearizzato sposta quella pagina di indice in testa e aggiunge un indice di numeri di pagina per ciascuna pagina, così da poter aprire direttamente a qualsiasi pagina. I capitoli sono invariati. Si è spostata solo la navigazione.

Esempio pratico

La linearizzazione è un passaggio esplicito e attivabile. Lo si richiede; il motore esegue la ricostruzione ed emette un file 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);

Il contenuto della pagina è esattamente quello che si è creato. La differenza sta nell’ordine nel file dei byte che si ricevono, e nella hint table che ora si trova vicino all’inizio.

Si verifica il risultato come farebbe un estraneo — con un controllore esterno:

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

qpdf --check-linearization non si limita a cercare un flag. Ricalcola gli offset che il file dichiara e conferma che siano veri: che gli oggetti della prima pagina siano davvero dove il linearization dictionary dice, che la hint table punti ai byte giusti, e che la struttura sia conforme ad Annex F. Un file che mente sul proprio layout fallisce questo controllo anche se a colpo d’occhio sembra linearizzato.

Equivoco comune

Si dà spesso per scontato che la linearizzazione comprima il file o renda il download complessivamente più veloce. Non fa né l’una né l’altra cosa. Un file linearizzato è spesso di pochi byte più grande, perché porta le hint table aggiuntive. Il tempo di trasferimento totale dell’intero documento è essenzialmente invariato.

Ciò che cambia è quando appare il primo pixel utile. La linearizzazione ottimizza il time-to-first-page, non il totale dei byte. È una funzionalità di latenza, non di compressione. Trasmettere in streaming la prima pagina presto e scaricare il file in fretta sono obiettivi diversi, e la linearizzazione serve il primo.

Un secondo equivoco è che qualsiasi server web trasmetterà in streaming un file linearizzato. Il lettore deve recuperare intervalli di byte, il che significa che il server deve onorare le richieste HTTP di intervallo. La maggior parte lo fa, ma un server che restituisce sempre l’intero file riporta Fast Web View a un’attesa lenta dell’intero file — il file è pronto per lo streaming, ma il trasporto no.

Human-factors note:Human-factors note

La linearizzazione è un passaggio esplicito e attivabile, e questo è deliberato. Costa un passaggio di serializzazione aggiuntivo per essere prodotta, e aiuta soprattutto per documenti grandi serviti su connessioni lente e aperti in un browser. Per una piccola fattura generata e inviata via email come allegato, aggiunge lavoro senza alcun beneficio. Renderla un interruttore anziché un valore predefinito sempre attivo permette di spendere quel costo esattamente dove un lettore lo avverte — il grande report pubblico su un telefono — e di saltarlo dove non lo avvertirebbe mai.

Limiti e confini

NextPDF ha pieno supporto core per produrre file linearizzati: un linearizzatore di produzione in tre passaggi che emette il parameter dictionary e le hint table e supera un controllo Annex F esterno.

Fast Web View (linearization) output — edition availability

Edition	Availability
Core	○ Pieno supporto. NextPDF produce output linearizzato (Fast Web View) attraverso una ricostruzione di produzione in tre passaggi MEASURE → PLACE → FILL, conforme a ISO 32000-2 Annex F.
Pro	○Not in this edition
Enterprise	○Not in this edition

Vale la pena nominare due confini. Primo, la linearizzazione è una proprietà di una revisione. Nel momento in cui si accoda un aggiornamento incrementale — una firma, la compilazione di un modulo, una modifica — i byte accodati vanno alla fine e il file non è più strettamente linearizzato finché non viene ricostruito. Questo è un normale compromesso, non un difetto; si veda aggiornamenti incrementali per capire perché l’accodamento sia il comportamento corretto per i documenti firmati.

Secondo, il motore controlla il file. Non controlla la rete. Fast Web View mantiene la sua promessa solo quando la connessione di servizio onora le richieste byte-range; i byte possono essere perfettamente linearizzati e arrivare comunque come un unico blocco lento se il server insiste a inviare l’intero file.

Documenti correlati

• L’anatomia di un file PDF — l’header, il corpo, la cross-reference table e il trailer che la linearizzazione riordina. Si legga prima questo per vedere cosa viene riordinato.
• Memoria e streaming — lo streaming lato scrittura, un asse diverso: come NextPDF mantiene piatta la memoria mentre produce i byte, rispetto a come un lettore li trasmette in streaming.
• Aggiornamenti incrementali e perché sono importanti — perché una modifica successiva si accoda alla fine, e cosa significa per il layout caricato in testa di un file linearizzato.
• Stream e filtri — cosa vive dentro gli oggetti del corpo a cui punta la hint table, e come sono compressi.

Glossario

• Linearizzazione — la ricostruzione che mette in testa la prima pagina e un indice di navigazione così che un lettore possa renderizzare e navigare prima che l’intero file arrivi. Il nome dello standard per il risultato.
• Fast Web View — il nome rivolto al consumatore per un PDF linearizzato; i due termini descrivono lo stesso file.
• Hint table — la struttura dentro un file linearizzato che registra gli intervalli e le posizioni di byte di ciascuna pagina e degli oggetti condivisi, così che un lettore sappia quali porzioni richiedere; la cross-reference table è ciò che poi mappa un numero di oggetto al suo offset di byte esatto.
• Linearization parameter dictionary — il primo oggetto in un file linearizzato; dichiara gli offset chiave (lunghezza della prima pagina, posizione della hint table, posizione della cross-reference principale) che rendono possibile il recupero su richiesta.
• Richiesta byte-range — una richiesta HTTP per una porzione di un file anziché l’intera cosa; il meccanismo di trasporto da cui dipende Fast Web View.
• Time-to-first-page — quanto tempo passa prima che un lettore veda la prima pagina. La latenza che la linearizzazione ottimizza, distinta dal tempo di download totale.