原生 headless 文件比較
HPDFHeadlessCompare 透過 HPDFCompareHeadlessDocuments 比較兩份已載入的原生文件；Linux callback ABI 則以 hpdf_document_compare_json_v1 搭配 type:compare 公開同一套實作
| Pascal 模式 | JSON 模式 | 比較內容 |
|---|---|---|
| hcmPageCount | pagecount | 頁面樹葉節點數 |
| hcmPageText | pagetext | 頁數與擷取的 Unicode 文字 |
| hcmObjectCount | objectcount | 頁數與實際使用中的 cross-reference 物件數 |
| hcmRenderedImage | renderedimage | 頁數、rendered 尺寸與原生 Cairo 像素 |
| hcmStructural | structural | 頁數與正規化後的 catalog、information 與不可達物件圖 |
| hcmFull | full | 頁數與物件數、正規化物件圖、Unicode 文字與 rendered 像素 |
結構等價性
結構比較會解開間接參照、排序 dictionary 條目、正規化 PDF 名稱與 literal 或十六進位字串表示，並在以 SHA-256 雜湊內容之前先解碼一般 stream filter
物件編號、序列化順序與一般 stream 壓縮不影響結構等價性；最終影像編碼保留其 filter 與解碼策略，不可達物件則以 multiset 方式比較
加密 dictionary 與 cross-reference 或 object-stream 儲存容器不列入語意結構；已驗證的 AES R5/R6 內容會在解密後比較，並強制執行擷取權限
結構差異會回報文件層級路徑 $Document；實體物件數仍是獨立模式，等價內容採用不同儲存布局時數字可能不同
Rendered 比較
每一頁都以原生 Cairo 裝置在選定的 DPI 下實際 render；解碼後的影像像素會合成到白底上，再以 RGB 或亮度比較
報告包含尺寸、變更像素數、最大通道差、平均絕對誤差、變更像素比例與相似度；相似度為 1 - meanAbsoluteError / 255
像素的最大通道差超過 ColorTolerance 即視為變更；只有尺寸相符、且相似度與變更像素比例都達到設定門檻，該頁才算通過
render 需要與原生頁面 render 相同的支援字型、影像編解碼器與圖形語意；不支援的頁面會讓比較失敗，而不是產出完全相同的報告
有界執行
比較選項會限制走訪、深度、物件、解碼 stream、文字準備、結果儲存與 rendered 像素；取消機制涵蓋走訪、文字擷取與 render
Pascal 比較期間，兩個文件實例都必須保持存活且由呼叫端獨佔；成功、失敗與取消時都會保留原始內容與資源選項
Linux ABI 接受上述六個小寫模式名稱，以及與 Pascal 上限一致的嚴格 options 成員，另有 dpi、colorTolerance、minimumSimilarity、maxChangedPixelRatio 與 colorSpace:rgb 或 luminance
ABI 結果在同步 callback 發布之前就已完整準備並設好界限；同 handle 呼叫與相反順序的並行呼叫沿用既有的穩定鎖定順序
報告欄位 · 語意契約比較 · 原生 Linux C ABI