What is the difference between a text watermark created by Acrobat and one created by the Adobe PDF Library PDDocAddWatermarkFromText API?

The watermark object created by the PDF Library PDDocAddWatermarkFromText() API is a form XObject in the PDF document, with Optional Content with the name “/Watermark.”

When creating a watermark using Adobe Acrobat, Acrobat will create a form XObject, but also includes a DocSettings stream within the ADBE_CompoundType key of the PieceInfo dictionary. To add watermarks in Acrobat, select Tools, Pages, Watermark, and Add Watermark.

If you add a watermark to a PDF document using the Adobe PDF Library, the DocSettings stream will be absent.

Acrobat can remove watermarks found in PDF documents that were created with the Adobe PDF Library, but it cannot update the watermarks created by the Library. To make the watermarks compatible with the Acrobat Watermark Update menu tool, you would need to add the requisite dictionary at the Cos level.