Optional-content viewer state

Native rasterisation can explicitly apply viewer-style optional-content recommendations from ISO 32000-1:2008 sections 8.11.4.4 and 8.11.4.5

Default options leave ViewerState=nil and retain stand-alone final-form D behaviour in both annotation usages, without applying AS automatically

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 initialises D, applies matching View applications, then manual overrides; Print or Export applications temporarily replace current recommendations for that operation and do not modify the state object or PDF dictionaries

Every active recommendation across matching applications and categories must be ON for a group to receive ON; absent usage information provides no recommendation and preserves that group's current state

Supported categories are View, Print, Export, Zoom, Language and User; CreatorInfo and PageElement remain informational

Zoom uses an inclusive min and exclusive max, with at least one bound required and defaults of zero and infinity; Language prefers exact case-insensitive tags within the application's OCGs, otherwise matching primary-language groups marked Preferred ON

User compares the explicitly supplied Individual, Title or Organization against a string or array of names using exact Unicode text; PDFDocEncoding, UTF-16 and PDF 2.0 UTF-8 text strings retain their decoded meaning

An application with omitted OCGs defaults to an empty group set; PrintState omitted from an existing Print usage dictionary provides no recommendation

AS does not limit categories to the identically named event, so a Print application may apply Zoom or Language recommendations using the same explicit context

OCMD policies, recursive VE expressions, nested marked content, Form XObjects, images and annotation appearances consume the resulting group states through the existing bounded visibility path

Manual changes persist across context changes until cleared or reverted; document reload, mutation, close or destruction expires the state permanently, requiring fresh access and a new object

Keep the borrowed state alive and unchanged during each render; read-only reuse is permitted whilst the underlying adapter's callback concurrency contract remains in force

Render work, group lookup, language candidate scans, manual-selection lookup, bounded hexadecimal and UTF-8 text decoding and temporary state storage participate in operation, token, decoded-byte, working-byte and cancellation limits

SetGroupState is a caller-driven state-container operation with a 100000-selection capacity; render limits independently bound consumption, and applications should impose suitable limits on external selection requests

Viewer event is independent of annotation Usage; neither option grants print permission, executes SetOCGState actions, activates rich media or creates a user interface

Acceptance uses independent declared states and exact RGB rectangle masks, lifetime and mutation tests, reentrant and serialized-callback concurrent rendering, and separate MuPDF and Poppler observations

Reader default-context observations do not substitute for explicit native Zoom, Language, User or manual-state equations; plain geometry companions independently validate raster coordinates

Linux versioned JSON operations

{
  "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}
    ]
  }
}

Omitting optionalContent retains static D behaviour; an object activates automatic state with a default View event, zoom 1 and empty language and user context strings

The event accepts view, print or export and remains independent of the annotation usage; no operating-system language, user identity or display zoom is inferred

Context strings admit at most 4096 UTF-16 code units each; zoom must be finite, positive and at most 1000000000

Selections require a positive object number, a generation number from zero through 65535 and an explicit Boolean enabled value; the operation admits at most 1024 selections within its working-memory limit, and repeated references use the last supplied state

Every operation creates and frees its own borrowed native state, so send the desired manual selections again with a later request; the PDF dictionaries and subsequent renders without this object retain their prior configuration

Malformed JSON options return invalid-argument status, admitted-budget failures return budget-exceeded status, and malformed document metadata or stale group references retain the existing render parse-error status before PNG publication

Capabilities report optionalContent.automaticState, the three events, explicit context members, manual selection support and operation-scoped lifetime

Generate actual plain and AES R5/R6 Language/User sources with Tests/Linux/Build-LinuxABIOptionalAutomaticFixtures.py OUTPUT, then run Tests/Linux/Run-LinuxABIOptionalAutomaticAcceptance.sh LIBRARY FIXTURES NEW_OUTPUT against each native ABI build

The callback acceptance checks independent pixel formulas, strict JSON types, encryption, budgets, cancellation, sticky output/result failures, same-handle recovery and absence of retained viewer state; it requires pypdf, cryptography, NumPy and Pillow and suppresses desktop viewer launch

See THPDFHeadlessOptionalContentState, THPDFOptionalContentContext and IHPDFHeadlessRenderLifetime