Pipeline Rendering

Antara OpenDocumentAsync dan PNG yang sampai ke browser ada dua tahap yang berbeda: viewer resolution (mesin mana yang memuat dokumen, diputuskan sekali per pembukaan) dan page processing (apa yang terjadi pada setiap gambar halaman pada setiap permintaan). Mengetahui keduanya menjelaskan mengapa sebuah format dirender seperti itu — dan apa yang sebenarnya diubah oleh DefaultRender.

Tahap 1 — Menyelesaikan penampil format

Pabrik memetakan ekstensi file ke penampil melalui katalog format, dengan tiga tingkat prioritas:

1. Penampil khusus pertama. Apa pun yang Anda daftarkan dengan DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) mengalahkan semua penampil bawaan.
2. Penampil keluarga bawaan. Katalog memetakan setiap ekstensi yang dapat dilihat ke keluarga penampil — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — masing‑masing dengan adaptor mesin mereka sendiri. Jika plugin berlisensi menyumbangkan penampil untuk ekstensi yang sama, penampil plugin menggantikan yang bawaan. AddDoconut() memvalidasi hak plugin yang terdaftar saat startup; fallback pabrik ke penampil bawaan adalah aturan runtime defensif.
3. Format hanya plugin. Beberapa ekstensi tidak memiliki penampil bawaan sama sekali — DICOM (.dcm) hanya tersedia melalui plugin DICOM. Membuka satu tanpa kemampuan yang diperlukan akan melempar:

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

Sebuah ekstensi yang tidak memiliki penampil akan memunculkan:

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

Setelah resolusi, konfigurasi ditetapkan: objek konfigurasi eksplisit Anda jika Anda memberikannya, jika tidak konfigurasi default format dari katalog. DocOptions.Password disalin ke dalam konfigurasi untuk dokumen yang dilindungi.

Tahap 1b — Mode pengalihan (DefaultRender = false)

Sebagian besar konfigurasi per-format mengekspos flag DefaultRender. Flag ini memilih antara dua jalur yang secara fundamental berbeda:

• DefaultRender = true — dokumen dirender secara native, langsung ke gambar halaman.
• DefaultRender = false — dokumen pertama kali diubah menjadi PDF dalam memori, mesin sumber dilepaskan, dan penampil PDF mengambil alih. PDF yang dihasilkan menyertakan teks asli, sehingga pencarian teks penuh mendapatkan sorotan native yang akurat piksel; pipeline memaksa AllowSearch dan AllowCopy aktif untuk PDF yang dialihkan karena konversi tidak terlihat oleh pengguna.

XPS dan default katalog untuk MHT menggunakan jalur pengalihan. Proyeksi PDF dapat menyediakan pencarian native untuk format seperti HTML dan Microsoft Project. Jika PDF yang dihasilkan berisi gambar tanpa lapisan teks, penampil standar tidak dapat mencari piksel tersebut.

Gunakan mode pengalihan ketika Anda memerlukan proyeksi PDF yang berisi teks — dengan biaya konversi awal saat dokumen dibuka.

Tahap 2 — Pipeline gambar-halaman

Halaman yang dirender diproses per permintaan melalui urutan tetap:

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

• Watermark — diterapkan berdasarkan status lisensi (lisensi hilang, sementara atau berlangganan yang kedaluwarsa, domain tidak valid, versi salah) dan dari DocOptions.Watermark untuk teks khusus Anda. Aplikasi yang berlisensi dengan benar — atau lisensi Temporary yang aktif — tanpa watermark khusus melewati langkah ini.
• Rotate/flip — keadaan per halaman yang diatur pengguna di widget (90°/180°/270°, flip horizontal/vertikal) disimpan dalam sesi dan diterapkan pada setiap render berikutnya dari halaman tersebut.
• Scale — thumbnail dan tingkat zoom dihasilkan dengan menskalakan halaman yang dirender ke ukuran target yang diminta; 0 berarti menyajikan pada ukuran asli.
• Annotation burn — anotasi yang disimpan digambar pada bitmap sehingga ekspor dan gambar halaman menampilkannya.
• Encoding — hasilnya dikodekan ke PNG menggunakan aliran memori yang dipool dan ditulis langsung ke respons HTTP.

Kesalahan di dalam middleware dikembalikan sebagai gambar kesalahan PNG (teks merah pada putih) alih‑alih halaman kesalahan HTTP, sehingga widget dapat menampilkannya di area halaman.

Caching halaman

BaseConfig.CachePages (default true) menyimpan gambar halaman yang dirender dalam memori selama masa sesi dokumen, sehingga mengunjungi kembali sebuah halaman tidak memaksa render ulang. BaseConfig.ImageResolution (25–300 DPI, 0 = default format) adalah pengatur utama kualitas/memori; default setiap format didokumentasikan pada halaman konfigurasinya.

Di mana menyesuaikan apa