Native annotation decorations

HPDFRenderHeadlessPagePNG generates missing-appearance relief borders and line captions through its normal bounded annotation Form renderer

A supplied normal appearance takes precedence over generated decorations

Rectangular relief borders

Square, Link, FreeText and Stamp border frames support BS styles B and I using opposing shaded bands, with the light direction reversed for inset

For each border color component c, the light band uses 1 − (1 − c) × 0.35 and the dark band uses c × 0.5

Band width is clamped to half the shorter frame dimension; rectangle differences, zero width, empty colors and separate CA/ca opacity remain effective

Unknown named BS styles use the standard solid default; an incorrectly typed style remains a malformed dictionary entry

Line caption layout

Cap enables a caption from Contents or XHTML RC with DS styling; CP selects Inline or Top placement and CO supplies offsets along the original endpoint direction and its left normal

Inline captions leave a measured gap in the line; Top captions and captions wider than the line use above-line placement

Reversed endpoints retain upright text, while arrow endings and leader lines retain their independent geometry

The plain default is a deterministic 12-point Helvetica resource name with the annotation color, resolved through the existing document and page font resources

Unicode, rich-text styling and explicit paragraph breaks use the existing read-only text appearance builder; empty text leaves the ordinary line intact

Clipping, lifetime and limits

Caption placement uses the measured temporary Form dimensions and retains its BBox and annotation rectangle clips

The field builder's inner padding clip is removed only from this generated caption layout; ordinary PDF W and W* operators are unchanged

Generated text resources share immutable font program storage within one annotation, with independent stream positions and cleanup after all temporary resource views are released

Decoded bytes, working memory, tokens, operations, output size and cancellation remain bounded, including long multilingual captions and recovery after a failed render

Acceptance and remaining work

The non-GUI runners in Tests/Linux/HeadlessAnnotationDecorations.en-us.md compare ordinary page-content geometry companions at two scales in view and print usage, retaining separate MuPDF and Poppler observations

Fixtures cover opacity, transparency, optional visibility, encrypted documents, short and long Unicode, caption boundaries, source-graph preservation and cancellation recovery

Original Type1C, CIDFontType0C and bare Type1 default fonts, OpenType CFF appearances and OpenType CFF2 default-instance appearances are supported through their documented font paths; raw-font complex shaping and standalone raw CFF2 remain outside those paths

The bounded FreeText DA profile applies text transforms and initial stroke state to generated text and decorations; text clipping uses glyph outlines rather than the expanded stroke silhouette, and the four finite two-run Tr4 through Tr7 controls passed native comparisons and independent MuPDF 1.28.5 and Poppler readers

Fractional filled-glyph composition has its own released bounds and allocation rules; finite DA controls do not establish arbitrary transformed raster envelopes or exact mathematical coverage at every boundary pixel

See annotation fallback for the broader supported geometry and format scope

See native cloudy annotation borders for continuous contour construction, Unicode content bounds and the normal acceptance entry points