Watermark
model.PdfPage has two watermark methods, AddWatermarkText and
AddWatermarkImage. Both wrap the page’s existing content in q/Q and append a
form XObject after it, so the watermark always lands on top of the page with a clean
graphics state and the original content is never rewritten.
The two are less independent than they look. AddWatermarkText renders the text into
a PNG with FreeType, wraps it in an image XObject, and calls AddWatermarkImage.
Every watermark is an image watermark underneath.
Which approach
| Approach | What you get | Cost |
|---|---|---|
page.AddWatermarkText(text, opts) | One rasterized text stamp per page, centered, with an angle. | Not real text: not selectable, not searchable, resolution-dependent. |
page.AddWatermarkImage(ximg, opts) | An image stamp per page, centered or stretched to the page width. | You build the XObjectImage yourself. |
Draw it with the creator | Anything: real text, tiling, precise placement, per-page variation. | You have to feed every page through the creator with AddPage. |
Reach for AddWatermarkText when you want “CONFIDENTIAL” across a document and don’t
care that it’s a bitmap. Use the creator when the watermark needs to be real text, be
repeated across the page, or sit somewhere other than the center.
Alpha behaves differently in the two option structs
WatermarkTextOptions fills in defaults for a zero value: Alpha becomes 0.5,
FontSize becomes 20, a nil FontColor becomes black. WatermarkImageOptions does
not. An Alpha of 0 is written straight through as an opacity of 0, so
model.WatermarkImageOptions{} produces a fully transparent, invisible watermark
with no error and no warning. Always set Alpha when adding an image watermark.
Writing the result
Neither method writes anything. After watermarking the pages, either convert the
reader with pdfReader.ToWriter(nil) and call WriteToFile, or hand each page to a
creator with AddPage and let the creator write. The writer route preserves more of
the original document structure and is what the image examples use.
Where to look
| Guide | Covers |
|---|---|
| Add a text watermark | WatermarkTextOptions field by field, and the consequences of the text being rasterized. |
| Add an image watermark | Building the image XObject, and how FitToWidth and PreserveAspectRatio interact. |
| Remove an image watermark | Removing a watermark by XObject name, and what an empty name removes. |