InsertFormObjectFromXObject method

InsertFormObjectFromXObject is the second half of the v1.25.0 Form XObject reuse API. It takes a TPdfXObject handle (built by CreateXObjectFromPage) and inserts ONE FPDF_PAGEOBJECT that references that XObject into THIS document's CURRENT page. Each call inserts a new page object, so the same XObject can be stamped multiple times across multiple pages of the destination — every stamp shares the underlying page-content cache, which keeps file size down even when the watermark / template is busy.

The returned FPDF_PAGEOBJECT handle lets the caller call FPDFPageObj_SetMatrix or the TPdfMatrix helpers to position / scale / rotate the stamp anywhere on the page. Without an explicit transform the inserted page sits at the bottom-left corner at 1:1 scale, which is almost never what you want; always set a matrix before calling UpdatePage.

Returns nil on failure (XObject is nil, this TPdf not Active, no current page). After insertion the page object is owned by the page, not by the XObject — freeing the XObject does not invalidate the inserted page object.

• The destination page is identified by THIS TPdf's PageNumber. Set PageNumber first, then call InsertFormObjectFromXObject.
• Call UpdatePage after positioning the stamp so PDFium re-renders the page content stream.
• Stamping the same XObject onto N pages produces N FPDF_PAGEOBJECT references in N page content streams, all pointing at the single XObject definition — far cheaper than copying the underlying content N times.
• The XObject's lifetime can be shorter than the destination page object's lifetime; once inserted, the page owns its reference.