Fast Web View: how a PDF opens before it finishes downloading

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

At a glance

A linearized PDF is reorganised so the first page and a small navigation index sit at the very front of the file. A viewer can therefore draw page one while the rest of the document is still arriving, and jump straight to page 147 without reading pages 2 through 146 first.

This is the feature most readers know by its friendly name: Fast Web View.

Why this matters

Picture a 200-page report on a phone with one bar of signal. Without linearization, the viewer often needs the very end of the file before it can draw anything, because the central index that says where every object lives traditionally sits at the back. So you watch a spinner while two hundred pages download, just to read the first one.

With linearization, the file is arranged so the answer to “what is on page one” is the first thing off the wire. The reader paints page one in a second, and fetches the rest only as you scroll or jump. On a fast connection you may never notice. On a slow or metered one, it is the difference between a usable document and an abandoned tab.

The short version

• A linearized file is front-loaded: page one and a hint table are placed first, before the rest of the body.
• The hint table is a map of ranges. It tells the viewer which byte ranges belong to each page and to the shared objects, so the viewer can ask the server for just those slices — then the cross-reference table resolves each object number to its exact offset.
• This relies on byte-range requests — the viewer fetching slices of the file on demand, not the whole thing.
• The bytes are identical content to a normal PDF. Linearization changes the order and the index, not the pages themselves.
• It is one explicit, switchable step in NextPDF — produced by a real three-pass rebuild, not a flag that hopes for the best.

How NextPDF approaches it

You cannot front-load a page until you know exactly how big everything is, because the hint table records byte offsets and an offset is only correct once every object’s length is final. That circularity — offsets depend on sizes, sizes depend on layout — is why a linearizer runs in passes rather than one sweep.

NextPDF resolves it with a deterministic three-pass rebuild. The first pass measures, the second decides placement, the third writes the real bytes with the now-known offsets baked in.

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.

The output carries a linearization parameter dictionary as its first object and one or more hint tables that index the pages, exactly as the standard prescribes (SpecSpec: ISO 32000-2, Annex FISO 32000-2 Annex F). Those hint tables work alongside a traditional cross-reference table — they record the byte ranges and locations a viewer needs to fetch, while the cross-reference table is the index that maps each object number to its exact byte offset. NextPDF’s linearizer emits the classic table form and evicts any cross-reference stream along the way, so once a slice arrives the reader resolves an object by its offset straight from that table (SpecSpec: ISO 32000-2, §7.5.4ISO 32000-2 §7.5.4).

A useful mental model: a normal PDF is a book whose table of contents is glued to the back cover. A linearized PDF moves that contents page to the front and adds a per-page page-number index, so you can open to any page directly. The chapters are unchanged. Only the navigation moved.

Practical example

Linearization is an explicit, switchable step. You ask for it; the engine performs the rebuild and emits a Fast-Web-View file.

<?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);

The page content is exactly what you authored. The difference is in the file order of the bytes you receive, and in the hint table that now sits near the top.

You verify the result the way a stranger would — with an external checker:

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

qpdf --check-linearization does not just look for a flag. It re-derives the offsets the file claims and confirms they are true: that the first-page objects really are where the linearization dictionary says, that the hint table points at the right bytes, and that the structure conforms to Annex F. A file that lies about its own layout fails this check even if it looks linearized at a glance.

Common misconception

The frequent assumption is that linearization compresses the file or makes the download faster overall. It does neither. A linearized file is often a few bytes larger, because it carries the extra hint tables. The total transfer time for the whole document is essentially unchanged.

What changes is when the first useful pixel appears. Linearization optimises time-to-first-page, not total bytes. It is a latency feature, not a compression feature. Streaming page one early and downloading the file quickly are different goals, and linearization serves the first.

A second misconception is that any web server will stream a linearized file. The viewer needs to fetch byte ranges, which means the server must honour HTTP range requests. Most do, but a server that always returns the entire file turns Fast Web View back into a slow, whole-file wait — the file is ready to stream, but the transport is not.

Human-factors note:Human-factors note

Linearization is an explicit, switchable step, and that is deliberate. It costs an extra serialisation pass to produce, and it helps most for large documents served over slow links and opened in a browser. For a small invoice generated and emailed as an attachment, it adds work for no benefit. Making it a switch rather than an always-on default lets you spend that cost exactly where a reader feels it — the big public report on a phone — and skip it where they never would.

Limits and boundaries

NextPDF has full core support for producing linearized files: a production three-pass linearizer that emits the parameter dictionary and hint tables and passes an external Annex F check.

Fast Web View (linearization) output — edition availability

Edition	Availability
Core	○ Full support. NextPDF produces linearized (Fast Web View) output through a production three-pass MEASURE → PLACE → FILL rebuild, conforming to ISO 32000-2 Annex F.
Pro	○Not in this edition
Enterprise	○Not in this edition

Two boundaries are worth naming. First, linearization is a property of one revision. The moment you append an incremental update — a signature, a form fill, an edit — the appended bytes go at the end and the file is no longer strictly linearized until it is rebuilt. That is a normal trade-off, not a defect; see incremental updates for why appending is the right behaviour for signed documents.

Second, the engine controls the file. It does not control the network. Fast Web View only delivers its promise when the serving connection honours byte-range requests; the bytes can be perfectly linearized and still arrive as one slow lump if the server insists on sending the whole file.

Related docs

• The anatomy of a PDF file — the header, body, cross-reference table, and trailer that linearization rearranges. Read this first to see what is being reordered.
• Memory and streaming — write-side streaming, a different axis: how NextPDF keeps memory flat while producing bytes, versus how a reader streams them in.
• Incremental updates and why they matter — why a later edit appends to the end, and what that means for a linearized file’s front-loaded layout.
• Streams and filters — what lives inside the body objects the hint table points at, and how they are compressed.

Glossary

• Linearization — the rebuild that front-loads the first page and a navigation index so a viewer can render and navigate before the whole file arrives. The standard’s name for the result.
• Fast Web View — the consumer-facing name for a linearized PDF; the two terms describe the same file.
• Hint table — the structure inside a linearized file that records the byte ranges and locations of each page and the shared objects, so a viewer knows which slices to request; the cross-reference table is what then maps an object number to its exact byte offset.
• Linearization parameter dictionary — the first object in a linearized file; it declares the key offsets (first-page length, hint-table location, main cross-reference position) that make on-demand fetching possible.
• Byte-range request — an HTTP request for a slice of a file rather than the whole thing; the transport mechanism Fast Web View depends on.
• Time-to-first-page — how long until a reader sees page one. The latency linearization optimises, distinct from total download time.