Rendering Pipeline

Between OpenDocumentAsync and the PNG that reaches the browser there are two distinct stages: viewer resolution (which engine loads the document, decided once per open) and page processing (what happens to each page image on every request). Knowing both explains why a format renders the way it does — and what DefaultRender really switches.

Stage 1 — Resolving the format viewer

The factory maps the file extension to a viewer through the format catalog, with three levels of precedence:

1. Custom viewers first. Anything you registered with DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) wins over every built-in.
2. Built-in family viewers. The catalog maps each viewable extension to a viewer family — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — each with its own engine adapter. If a licensed plugin contributes a viewer for the same extension, the plugin viewer replaces the built-in one. AddDoconut() validates registered plugin entitlements at startup; the factory's fallback to the built-in viewer is a defensive runtime rule.
3. Plugin-only formats. Some extensions have no built-in viewer at all — DICOM (.dcm) exists only through the DICOM plugin. Opening one without the required capability throws:

LicenseException: This document type requires the 'Dicom' plugin license.

An extension no viewer claims raises:

FormatNotSupportedException: Document format '<extension>' is not supported.

After resolution, the config is settled: your explicit config object if you passed one, otherwise the format's default config from the catalog. DocOptions.Password is copied into the config for protected documents.

Stage 1b — Redirect mode (DefaultRender = false)

Most per-format configs expose a DefaultRender flag. It selects between two fundamentally different paths:

• DefaultRender = true — the document renders natively, straight to page images.
• DefaultRender = false — the document is first converted to a PDF in memory, the source engine is released, and a PDF viewer takes over. The generated PDF embeds real text, so full-text search gets pixel-accurate native highlights; the pipeline forces AllowSearch and AllowCopy on for the redirected PDF since the conversion is invisible to the user.

XPS and the catalog default for MHT use the redirect path. A PDF projection can provide native search for formats such as HTML and Microsoft Project. If the resulting PDF contains images without a text layer, the standard viewer cannot search those pixels.

Use redirect mode when you need a text-bearing PDF projection — at the cost of an upfront conversion when the document opens.

Stage 2 — The page-image pipeline

Rendered pages are processed per request through a fixed sequence:

raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response

• Watermark — applied from the license state (missing license, expired temporary or subscription, invalid domain, wrong version) and from DocOptions.Watermark for your own custom text. A properly licensed app — or an active Temporary license — with no custom watermark skips this step.
• Rotate/flip — per-page state the user sets in the widget (90°/180°/270°, horizontal/vertical flips) is stored in the session and applied on every subsequent render of that page.
• Scale — thumbnails and zoom levels are produced by scaling the rendered page to the requested target size; 0 means serve at original size.
• Annotation burn — saved annotations are drawn onto the bitmap so exports and page images show them.
• Encoding — the result is encoded to PNG using pooled memory streams and written directly to the HTTP response.

Errors inside the middleware are returned as PNG error images (red text on white) rather than HTTP error pages, so the widget can display them in the page area.

Page caching

BaseConfig.CachePages (default true) keeps rendered page images in memory for the lifetime of the document session, so revisiting a page does not re-render it. BaseConfig.ImageResolution (25–300 DPI, 0 = format default) is the main quality/memory dial; each format's default is documented on its config page.

Where to tune what