kitepdf-core/io.github.yuroyami.kitepdf.core.render/KiteCanvas/applySoftMask

applySoftMask

open fun applySoftMask(kind: SoftMask.Kind, maskBBox: KiteRectangle, maskCtm: KiteMatrix, render: () -> Unit, renderMask: (KiteCanvas) -> Unit)

Apply a soft mask to the content rendered inside render (ISO 32000-1 §11.6.5). The default implementation just calls render. Backends without offscreen compositing fall back to painting through the mask.

Concrete implementations: open a saveLayer for the content, render() it, then over-paint via renderMask using DstIn blend mode so the mask's alpha determines the visible region.

The shipped backends implement both SMask kinds: Alpha uses the mask group's own alpha, and Luminosity composites the group over an opaque black backdrop and converts luminance to alpha (Skia's LUMA filter, a Compose colour-matrix filter, a per-pixel pass on AWT) per §11.6.5.2.

open fun applySoftMask(kind: SoftMask.Kind, maskBBox: KiteRectangle, maskCtm: KiteMatrix, transfer: KiteMaskTransfer?, render: () -> Unit, renderMask: (KiteCanvas) -> Unit)

Applies a soft mask whose values pass through transfer before they gate the content (ISO 32000-1, 11.6.5.2, Table 144, /TR). A null transfer is the identity. The transfer applies to every mask value, also where the group paints nothing.

The default implementation ignores transfer and calls the applySoftMask above, so a canvas written before the transfer function still masks. The renderer calls this overload only for a mask with a transfer function. A wrapper that delegates with by must override both overloads: Kotlin sends an overload that the wrapper does not override straight to the wrapped canvas.