setOverprint method

@override void setOverprint({ required bool fill, required bool stroke, required int mode, })

Sets the overprint state for subsequent painting (gs /OP, /op, /OPM; PDF §8.6.7). fill is nonstroking overprint (/op), stroke is stroking overprint (/OP), and mode is the overprint mode (/OPM, 0 or 1).

Overprint is a subtractive (CMYK/spot colorant) operation: an overprinting colorant that is not written leaves the underlying colorant untouched instead of knocking it out. The interpreter resolves that in a CMYK/spot colorant buffer (PdfOverprintCompositor, issue #502) before the draw reaches a device: a resolved draw arrives with its composite already in the colour and this flag cleared, so devices paint it plainly.

The flag therefore only arrives set where the buffer declined - over an image, a gradient, a transparency group, or a colour space with no colorant reading. Painting devices approximate that residue with a darken (per-channel min) composite, which is a no-op over white, so it only affects ink laid over ink. mode is the parsed /OPM; the RGB approximation cannot act on its zero-component distinction, which is a colorant-space question the buffer has already answered. Non-compositing devices can ignore all three.

Implementation

@override
void setOverprint(
    {required bool fill, required bool stroke, required int mode}) {
  // [mode] (OPM 0/1) only distinguishes which DeviceCMYK components are
  // written, which is a colorant-space question: it is acted on by
  // PdfOverprintCompositor upstream and cannot be acted on here, so it is
  // intentionally not stored. Empirically (issue #502) no fixed RGB blend
  // that keys off OPM beats darken-always in this device: gating OPM-0 to a
  // knockout fixes the "over CMYK" patches but reintroduces the fail-marker
  // on the "over spot" patches (a separation colorant must survive the
  // knockout), and vice-versa. See
  // doc/dev-log/2026-07-23-overprint-rgb-ceiling.md.
  _fillOverprint = fill;
  _strokeOverprint = stroke;
}