How the renderer reads it
A high-level walk from open to pixels — the four pipeline stages and the engine crate that owns each one.
Turning an IDML package into pixels is a four-stage pipeline: open, parse, resolve, build.
In short: An IDML package describes a document's structure and intent, not pixels. Producing a rendered page means running that intent through a pipeline of distinct steps — open the container, parse each part, resolve styles and text flow, then build and rasterize — with each step owned by a different crate in the engine. This page walks the whole path at altitude so the rest of the reference has a shape to hang on. The deeper mechanics live in the renderer and parser internals.
An IDML package describes a document's structure and intent, not pixels. Turning that intent into a rendered page is a pipeline of distinct steps, each owned by a different crate in the engine. This page walks the path at altitude so the rest of the reference has a shape to hang on. The deeper mechanics live in the renderer and parser internals.
Open
First the package is treated as a container. The archive is decompressed, the
mimetype entry is checked, and designmap.xml is read to learn which parts
exist and where. This is the job of paged-parse — ZIP plus XML into an
abstract syntax tree of containers, spreads, stories, styles, and graphics.
Parse
Each part named by the manifest is parsed into typed structures: spreads with
their frames and shapes, stories with their paragraphs and runs, the style sheet,
the color palette. Still paged-parse. At this stage everything is faithful to
the file — nothing has been resolved or laid out yet.
Resolve
Now paged-scene assembles the parsed parts into a coherent document via
Document::open. Two kinds of resolution happen here.
The style cascade: a run's effective attributes are found by walking from the run's direct properties, down through any applied character style, down through the applied paragraph style — each layer filling in only what the layer above left unset.
And story threading: a story can flow through several frames. The resolver
finds the chain head (the frame no other frame points at) and follows
NextTextFrame links until the chain ends, so the text knows which frames it
fills and in what order.
Build
With the document resolved, paged-text shapes and lines the text —
glyph shaping, Knuth-Plass line breaking, hyphenation, tab stops. paged-compose
turns the laid-out result and the page geometry into a display list: an ordered
list of fills, strokes, images, and glyph runs. paged-renderer sits on top,
driving paged-parse → paged-scene → paged-text → paged-compose and
rasterizing the display list into pixels.
Honest gaps
Reading a construct is not the same as rendering it. Some things are parsed and
held faithfully but do not yet change the rendered output. Text variables are a
clear case: the resolved ResultText is captured exactly as the document recorded
it, but live per-page recomputation is a future task.
Where a page in this reference describes a construct we read but do not fully render, it says so and links forward to the status detail. The pipeline above is the spine; the gaps are noted in place rather than hidden.
Frequently asked questions
What are the stages of the rendering pipeline? Four. Open treats the package as a container and reads the manifest; parse turns each named part into typed structures; resolve assembles them into a coherent document, applying the style cascade and story threading; build shapes and lines the text, composes a display list, and rasterizes it into pixels.
Which engine crate handles each stage?
paged-parse handles open and parse. paged-scene handles resolve via
Document::open. paged-text shapes and lines the text and paged-compose builds
the display list, with paged-renderer driving the whole chain and rasterizing the
result.
If the renderer parses something, does that mean it renders it?
Not always. Some constructs are parsed and held faithfully but do not yet change
the rendered output. Text variables are the clear example: the resolved
ResultText is captured exactly as the document recorded it, while live per-page
recomputation is still a future task. Pages flag these gaps in place rather than
hiding them.
Read one by hand
Open the smallest valid IDML package and read its parts — a one-page, one-line document, focused on the story that holds the text.
Package anatomy
An IDML document is a ZIP archive of XML parts — a self-identifying container, a design map that names everything, shared resource parts, and content parts, wired together by id references.