Flattens the form's fields, and optionally every annotation, into the page content: each one's normal appearance becomes part of its page, and the widgets, the annotations and the interactive form are removed.
public bool Flatten(PdfFlattenOptions options)
Whether annotations other than widgets are flattened too, and for which intent.
true when anything changed: an annotation was removed or the form was.
ISO 32000-2 §12.5.5. Each annotation's normal appearance (for its appearance state, AS) is referenced from the page's
resources as the form XObject it is, and drawn after the page's own content, in Annots order, with the matrix A of
Algorithm "Appearance streams" (the form's own Matrix is applied by Do, making AA). The page's content is
kept byte for byte inside q … Q (balanced against any unmatched q or Q it has), so the appearances
start from the default graphics state (RewriteContent(ContentEditor)). An annotation with
optional content (OC, §8.11.3.3) is drawn inside an /OC marked-content sequence, so it stays optional; one with
an opacity (CA, ca) or blend mode (BM) is composited as §12.5.5 says, as a transparency group with those
values.
Annotations with the Hidden flag, and with the NoView flag (View) or without the Print flag
(Print), are removed without being drawn, as are those without an appearance. The
appearances are flattened as they are: a form whose NeedAppearances is set may need its appearances regenerated first
(GenerateAppearances()). A signed form records a FlattenInvalidatesSignatures warning,
since removing the signature fields changes what the signatures cover.
A page's Annots then lists only the annotations it keeps, and goes when it keeps none, unless a page tree node above
the page has an Annots of its own (§7.7.3.3, Table 31: not inheritable, but read as viewers read it when the page has
none): the page then keeps an empty one, so the node's annotations do not show on it instead.
In a tagged document, the structure tree keeps no reference to a removed annotation (§14.7.5.3, §14.7.5.4): its object
references (OBJR) leave their elements' K, and its StructParent entry leaves the parent tree. A drawn
annotation's appearance keeps its structure: it is drawn inside a marked-content sequence tagged with the element's type whose
MCID (one the page's content and tree do not use) takes the place of the element's first object reference to it
(§14.7.5.2). The catalog's permissions (Perms, §12.8.6) lose the DocMDP entry naming a removed signature field's
signature, and go when nothing else is left in them.
Removed annotations and the form's fields stay objects of the document until a save with RemoveUnreachableObjects drops them. NoZoom and NoRotate cannot be kept in page content: the appearance is placed as at 100% zoom on an unrotated page. A mutation: no read may run concurrently with it.