Module annot_render 

Painting a page’s annotation appearances onto the page.

An annotation’s /AP form is part of the page image rather than an overlay a viewer adds. But it does not all arrive by one route, and the split is the thing to know:

• Pass A is the page render, and it draws the non-widgets: the walk over the annotation list skips every /Widget.
• Pass B is the form-fill draw that follows every bitmap render, unconditionally. That is where widgets are drawn, one at a time through their own one-layer render context.

Both end in the same placement arithmetic and both draw the normal appearance, so one traversal reproduces them — but their visibility tests differ, and merging them would be wrong:

flag	Pass A (non-widgets)	Pass B (widgets)
Invisible (bit 1)	not tested	suppresses
Hidden (bit 2)	suppresses	suppresses
Print (bit 3)	required when printing	not tested
NoView (bit 6)	suppresses on screen	suppresses

is_visible therefore keys on the subtype: a widget goes through Pass B’s rules and everything else through Pass A’s, which is the only place the Invisible bit is read.

Two more decisions change pixels and neither is obvious from the spec:

• The appearance is placed by fitting, not by translating. The form’s /BBox — mapped through the form’s own /Matrix and re-bounded — is fitted into the annotation’s /Rect, so a form whose BBox is a different size from the rect is scaled to it. A degenerate axis takes scale 1, not zero, and the skew terms are forced to zero whatever /Matrix said.
• Order is /Annots order. The only sort is a stable one that lifts pop-ups above everything else, so among non-pop-ups nothing moves. Later annotations paint over earlier ones with no z-ordering of their own; bug_1304714.in stacks three widgets to pin exactly that.

A pop-up is in the list and painted only while it is open, and the one thing that opens it is the pointer entering the parent annotation’s rectangle. So a plain render draws no note cards at all, and a render driven by a script that moves the mouse over an annotated passage draws exactly one.

Functions

overlay

Appends every visible annotation’s appearance to a built page.

overlay_with

The same pass, with an overlay the caller has already filled in.