Optional content 閱讀器狀態

原生點陣化可以明確套用 ISO 32000-1:2008 8.11.4.4 與 8.11.4.5 中閱讀器風格的 optional content 建議

預設選項保持 ViewerState=nil，在兩種註解用法下都保留獨立的 final-form D 行為，不自動套用 AS

Access := Document.GetRenderAccess(0);
Context := THPDFOptionalContentContext.Default;
Context.Zoom := 2;
Context.Language := 'en-US';
Viewer := THPDFHeadlessOptionalContentState.Create(Access, Context);
try
  Viewer.SetGroupState(10, 0, True);
  Options := THPDFHeadlessRenderOptions.Default;
  Options.ViewerState := Viewer;
  Viewer.Event := hocePrint;
  Options.Usage := hruPrint;
  HPDFRenderHeadlessPagePNGFile(Access, OutputFile, Options);
finally
  Viewer.Free;
end;

View 先初始化 D，再套用相符的 View application，最後是手動覆寫；Print 或 Export application 會在該操作期間暫時替換目前建議，不修改狀態物件或 PDF 字典

要使某組為 ON，相符 application 與類別下每一條作用中建議都必須是 ON；缺失的用法資訊不提供建議，該組保持目前狀態

受支援的類別為 View、Print、Export、Zoom、Language 與 User；CreatorInfo 與 PageElement 僅供參考

Zoom 使用閉區間下限與開區間上限，至少需要一個邊界，預設零與無限大；Language 在 application 的 OCG 內優先精確比對大小寫不敏感的標籤，否則比對標記為 Preferred ON 的主語言群組

User 以精確 Unicode 文字比較明確提供的 Individual、Title 或 Organization 與字串或名稱陣列；PDFDocEncoding、UTF-16 與 PDF 2.0 UTF-8 文字字串保留其解碼後的含義

省略 OCGs 的 application 預設空組集合；既有 Print usage 字典省略 PrintState 時不提供建議

AS 不把類別限定到同名事件，因此 Print application 可以用同一個明確 context 套用 Zoom 或 Language 建議

OCMD 政策、遞迴 VE 運算式、巢狀標記內容、Form XObject、影像與註解外觀透過既有的設有上限可見性路徑消費最終的群組狀態

手動變更在 context 變更之間持續存在，直到被清除或還原；文件重新載入、變更、關閉或銷毀會讓狀態永久過期，需要重新取得存取並新建物件

每次渲染期間請保持借用的狀態存活且不變；只要底層配接器的 callback 並行契約仍然有效，唯讀重用是允許的

渲染工作、群組查找、語言候選掃描、手動選取查找、設有上限的十六進位與 UTF-8 文字解碼以及暫時狀態儲存，都計入操作、token、解碼位元組、工作位元組與取消限制

SetGroupState 是呼叫端驅動的狀態容器操作，容量 100000 個選取項；渲染限制獨立約束消費，應用程式應對外部選取請求施加合適的限制

閱讀器事件獨立於註解 Usage；該選項不授予列印權限、不執行 SetOCGState action、不啟用 rich media，也不建立使用者介面

驗收使用獨立宣告的狀態與精確的 RGB 矩形遮罩、生命週期與變更測試、可重入與序列化 callback 的並行渲染，以及獨立的 MuPDF 與 Poppler 觀察

閱讀器預設 context 的觀察不能替代明確的原生 Zoom、Language、User 或手動狀態等式；plain 幾何伴隨項獨立驗證點陣座標

Linux 版本化 JSON 操作

{
  "schemaVersion": 1,
  "type": "render",
  "dpi": 72,
  "usage": "view",
  "optionalContent": {
    "event": "print",
    "zoom": 2,
    "language": "en-US",
    "individual": "Alice",
    "title": "Engineer",
    "organization": "Example",
    "selections": [
      {"objectNumber": 10, "generationNumber": 0, "enabled": true}
    ]
  }
}

省略 optionalContent 保留靜態 D 行為；提供物件則啟用自動狀態，預設 View 事件、zoom 1 以及空的 language 與 user context 字串

event 接受 view、print 或 export，與註解 usage 相互獨立；不推斷作業系統的語言、使用者身分或顯示縮放

context 字串各最多 4096 個 UTF-16 code unit；zoom 必須是有限正數且不超過 1000000000

selections 要求正的 object number、0 到 65535 的 generation number 與明確 Boolean 的 enabled 值；操作在工作記憶體限額內最多接納 1024 個選取項，重複參照以最後提供的狀態為準

每次操作都會建立並釋放自己的借用原生成員狀態，後續請求請重新傳送所需的手動選取項；不帶該物件的 PDF 字典與後續渲染保留先前設定

畸形 JSON 選項回傳 invalid-argument 狀態，準入預算失敗回傳 budget-exceeded 狀態，畸形文件詮釋資料或過期群組參照在 PNG 發佈前保留既有的渲染解析錯誤狀態

能力回報 optionalContent.automaticState、三種事件、明確 context 成員、手動選取支援與操作級生命週期

用 Tests/Linux/Build-LinuxABIOptionalAutomaticFixtures.py OUTPUT 產生真實的 plain 與 AES R5/R6 Language/User 來源，然後對每個原生 ABI 建置執行 Tests/Linux/Run-LinuxABIOptionalAutomaticAcceptance.sh LIBRARY FIXTURES NEW_OUTPUT

callback 驗收檢查獨立像素公式、嚴格 JSON 型別、加密、預算、取消、黏性輸出／結果失敗、同控制代碼復原以及不保留閱讀器狀態；需要 pypdf、cryptography、NumPy 與 Pillow，並抑制桌面閱讀器啟動

另見 THPDFHeadlessOptionalContentState、THPDFOptionalContentContext 與 IHPDFHeadlessRenderLifetime