レンダリング パイプライン

OpenDocumentAsync とブラウザに届く PNG の間には、2つの明確な段階があります：viewer resolution（どのエンジンがドキュメントを読み込むか、オープンごとに一度決定されます）とpage processing（各リクエストで各ページ画像に何が行われるか）。両方を理解すれば、フォーマットがそのようにレンダリングされる理由と、DefaultRender が実際に何を切り替えるかが分かります。

ステージ 1 — フォーマットビューアの解決

ファクトリは、フォーマットカタログを通じてファイル拡張子をビューアにマッピングし、3つの優先順位レベルがあります：

1. カスタムビューアが最優先. DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) で登録したものは、すべての組み込みビューアよりも優先されます。
2. 組み込みファミリービューア. カタログは、各閲覧可能な拡張子をビューアファミリー（Word、Excel、PowerPoint、Pdf、Cad、Dgn、Image、Tiff、Psd、Email、Visio、Project、Xps、Epub、Txt、Html、Mht、Dcn）にマッピングし、それぞれが独自のエンジンアダプタを持ちます。同じ拡張子に対してライセンス済みプラグインがビューアを提供した場合、プラグインビューアが組み込みビューアを置き換えます。AddDoconut() は起動時に登録されたプラグインの権利を検証します；ファクトリの組み込みビューアへのフォールバックは防御的なランタイムルールです。
3. プラグイン専用フォーマット. 一部の拡張子には組み込みビューアがまったくありません — DICOM（.dcm）は DICOM プラグインを通じてのみ存在します。必要な機能がない状態で開くと、次の例外がスローされます：

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

ビューアが存在しない拡張子は次の例外を発生させます：

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

解決後、設定が確定します：渡した場合は明示的な設定オブジェクトが使用され、渡さなければカタログから取得したフォーマットのデフォルト設定が使用されます。保護されたドキュメントの場合、DocOptions.Password が設定にコピーされます。

ステージ 1b — リダイレクトモード（DefaultRender = false）

ほとんどのフォーマット別設定は DefaultRender フラグを公開しています。これは、根本的に異なる2つのパスのどちらかを選択します：

• DefaultRender = true — ドキュメントはネイティブにレンダリングされ、直接ページ画像になります。
• DefaultRender = false — ドキュメントはまず メモリ内で PDF に変換 され、元のエンジンは解放され、PDF ビューアが引き継ぎます。生成された PDF には実際のテキストが埋め込まれるため、全文検索はピクセル単位で正確なハイライトが可能です；変換はユーザーに見えないため、パイプラインはリダイレクトされた PDF に対して AllowSearch と AllowCopy を強制的に有効にします。

XPS とカタログのデフォルトである MHT はリダイレクトパスを使用します。PDF プロジェクションは HTML や Microsoft Project などのフォーマットに対してネイティブ検索を提供できます。生成された PDF にテキストレイヤーのない画像が含まれる場合、標準ビューアはそれらのピクセルを検索できません。

ドキュメントを開く際に事前変換が必要になる代償として、テキストを保持した PDF プロジェクションが必要な場合はリダイレクトモードを使用してください。

ステージ 2 — ページ画像パイプライン

レンダリングされたページは、リクエストごとに固定されたシーケンスで処理されます：

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

• Watermark — ライセンス状態（ライセンス未取得、期限切れの一時またはサブスクリプション、無効なドメイン、バージョン不一致）と DocOptions.Watermark によるカスタムテキストから適用されます。適切にライセンスされたアプリ、または有効な一時ライセンスでカスタム透かしが設定されていない場合、このステップはスキップされます。
• Rotate/flip — ユーザーがウィジェットで設定するページごとの状態（90°/180°/270°、水平/垂直フリップ）はセッションに保存され、以降のそのページのレンダリング時に適用されます。
• Scale — サムネイルとズームレベルは、レンダリングされたページを要求されたターゲットサイズにスケーリングして生成されます；0 は元のサイズで提供することを意味します。
• Annotation burn — 保存された注釈がビットマップ上に描画され、エクスポートやページ画像に反映されます。
• Encoding — 結果はプールされたメモリストリームを使用して PNG にエンコードされ、直接 HTTP 応答に書き込まれます。

ミドルウェア内でのエラーは、HTTP エラーページではなく PNG エラー画像（白地に赤文字）として返されるため、ウィジェットはページ領域にそれらを表示できます。

ページキャッシュ

BaseConfig.CachePages（デフォルト true）は、ドキュメントセッションの存続期間中、レンダリングされたページ画像をメモリに保持するため、ページを再訪問しても再レンダリングされません。BaseConfig.ImageResolution（25–300 DPI、0 = フォーマットデフォルト）は品質/メモリの主要な調整項目で、各フォーマットのデフォルトはその設定ページに記載されています。

何を調整すべきか