Alur Rendering

Antara OpenDocumentAsync dan PNG yang sampai ke browser ada dua tahap yang berbeda: resolusi penampil (mesin mana yang memuat dokumen, diputuskan sekali per pembukaan) dan pemrosesan halaman (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 terlebih dahulu. Apa pun yang Anda daftarkan dengan DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) mengungguli semua 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 ada 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 menimbulkan:

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

Setelah resolusi, konfigurasi diselesaikan: objek konfigurasi eksplisit Anda jika Anda menyertakannya, 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 menampilkan 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 dikonversi menjadi PDF dalam memori, mesin sumber dilepaskan, dan penampil PDF mengambil alih. PDF yang dihasilkan menyertakan teks asli, sehingga pencarian full‑text 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 membutuhkan proyeksi PDF yang membawa teks — dengan biaya konversi di 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 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 ke 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 error PNG (teks merah pada putih) alih‑alih halaman error 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 merender ulang. BaseConfig.ImageResolution (25–300 DPI, 0 = default format) adalah pengatur utama kualitas/memori; default setiap format didokumentasikan pada halaman konfigurasinya.

DocOptions.ImageResolution usang dan tidak mengontrol kualitas render. Jika Anda membawa aplikasi dari perpustakaan sebelumnya, pindahkan nilai itu ke konfigurasi format — kompiler akan menandai setiap situs pemanggilan.

Rendering pada satu node vs. banyak

Semua di atas menggambarkan rendering pada satu node secara permintaan untuk sesi yang membuka dokumen. Sebuah penyebaran di mana satu node merender dan memublikasikan seluruh set artefak, dan node lain melayani halaman tersebut dari penyimpanan bersama, menggunakan jalur baca yang berbeda — lihat Penyebaran Terdistribusi.

Di mana menyesuaikan apa