PDF Soft Mask
A PDF Soft Mask (SMask) is a greyscale image or luminosity group used as an alpha channel to control the transparency of a painted object. Unlike hard clipping masks, soft masks allow smooth gradients of opacity — used in drop shadows, feathered edges, and photographic transparency effects in PDF graphics.
A PDF Soft Mask (SMask) is a greyscale image or luminosity group used as an alpha-channel proxy to control the transparency of painted graphical content. Unlike a hard clipping path — which either fully shows or fully hides content based on a binary boundary — a soft mask assigns a continuous opacity value (0–255 grey level) to every pixel in the painted area. Where the mask is white, the paint is fully opaque; where it is black, the paint is fully transparent; grey values produce proportional partial transparency.
Soft masks were introduced with the <a href="https://pdftheguide.com/news/pdf-version-history" target="_blank" rel="noopener">PDF 1.4 transparency model</a> and are one of the most powerful compositing tools available in the PDF graphics architecture. They enable photographic blending effects — drop shadows with realistic fall-off, feathered image edges, gradient fade-outs, and vignettes — that would be impossible with clipping paths alone.
Types of soft masks
The PDF specification defines two types of soft masks, set via the <code>/S</code> (subtype) key in the soft mask dictionary:
**Alpha soft mask** (<code>/S /Alpha</code>): Uses the alpha (opacity) channel of the mask group as the mask value. Each pixel's alpha value (0 = transparent, 1 = opaque) directly controls the opacity of the corresponding pixel in the masked object. This is used for pre-multiplied alpha-channel compositing, as in RGBA raster images.
**Luminosity soft mask** (<code>/S /Luminosity</code>): Uses the luminosity (brightness) of the mask group as the mask value. A bright (high luminosity) pixel produces higher opacity; a dark (low luminosity) pixel produces lower opacity. Luminosity soft masks are used for the "glow" and "shadow" effects created in Photoshop and Illustrator — a white-to-black gradient mask produces a fade from opaque to transparent.
Luminosity soft masks are more commonly used in practice because they interact naturally with the existing greyscale image pipeline and are easier to generate from design tool outputs.
How soft masks are specified in the graphics state
Soft masks are part of the PDF graphics state. They are set using the <code>gs</code> (set graphics state parameters) operator with a graphics state parameter dictionary that includes an <code>/SMask</code> key. The value is either the name <code>/None</code> (clearing the mask) or a soft mask dictionary.
The soft mask dictionary specifies: - <code>/Type /Mask</code>: Identifies it as a mask dictionary. - <code>/S</code>: The subtype (Alpha or Luminosity). - <code>/G</code>: The mask's form <a href="https://pdftheguide.com/glossary/pdf-xobject" target="_blank" rel="noopener">XObject</a> — the group that will be rendered to produce the mask. - <code>/BC</code> (optional): Background colour used outside the mask group's bounding box. - <code>/TR</code> (optional): A <a href="https://pdftheguide.com/glossary/pdf-transfer-function" target="_blank" rel="noopener">transfer function</a> applied to the mask values before use.
The mask group is itself a transparency group XObject — a self-contained mini-canvas that paints its content and then provides the result as the mask for the parent context.
Soft masks in design tool output
When you apply a drop shadow, outer glow, feathered mask, or gradient fade in Adobe Photoshop, Illustrator, or InDesign and export to PDF, the tool generates soft mask dictionaries in the output. The design software handles the complexity of translating its visual effect model into the PDF transparency architecture automatically.
In PDF output from Illustrator: - A Gaussian blur effect becomes a luminosity soft mask with a blurred greyscale group - A layer mask in Photoshop (embedded in an Illustrator linked file) exports as an alpha soft mask - Gradient transparency on a vector object (opacity applied via a gradient) exports as a form XObject with a gradient-painted luminosity soft mask
Understanding this mapping is useful when diagnosing print reproduction problems: if a soft-masked object prints with incorrect opacity on a PostScript printer, the issue is usually in the transparency flattener's handling of the mask group.
Soft masks and PDF/A
<a href="https://pdftheguide.com/glossary/pdf-a" target="_blank" rel="noopener">PDF/A-1</a> prohibits transparency entirely — which means soft masks are not permitted in PDF/A-1 documents. When converting a PDF with soft masks to PDF/A-1, the transparency must be flattened: the compositing effect is pre-rendered and the result replaced with a raster image approximation. This can degrade visual quality, particularly for smooth gradients.
PDF/A-2 and PDF/A-3 permit transparency, including soft masks, as part of their PDF 1.7-based feature set. This is one of the key practical advantages of PDF/A-2 over PDF/A-1 for design-heavy documents — the visual fidelity of gradient fades, drop shadows, and blended effects is preserved in the archival copy.
Frequently asked questions
What is the difference between a soft mask and a clipping path in PDF?
A clipping path is a binary mask: every pixel is either inside the clip region (fully visible) or outside it (fully invisible). A soft mask is a continuous-tone mask: every pixel can have any opacity value from 0 (fully transparent) to 1 (fully opaque). Soft masks enable smooth transparency gradients, feathered edges, and drop shadows; clipping paths only produce hard-edged cuts. In PDF, clipping paths are set with the W and W* operators; soft masks are set via the graphics state parameters operator (gs).
Can I use soft masks in PDF/A documents?
Not in PDF/A-1 — transparency (including soft masks) is prohibited. In PDF/A-2 and PDF/A-3, soft masks are permitted as part of the full PDF 1.7 transparency model. If you need to archive documents containing soft-masked elements and target PDF/A-1, transparency must be flattened during the conversion — the composited result is rendered to a raster image. This may degrade visual quality for smooth gradients. Use PDF/A-2b instead to preserve transparency effects without flattening.
Why does a soft-masked object look different when printed vs on screen?
PostScript printers do not natively support the PDF transparency model. When a PostScript RIP encounters a PDF transparency group with soft masks, it must run a transparency flattener to convert the transparency into opaque raster or vector content. Different flatteners produce slightly different results — particularly for overlapping transparency groups. For print production, ensure your PDF workflow sends directly to a PDF-capable RIP (not PostScript), and use PDF/X-4 format which natively supports live transparency without pre-flattening.
How are soft masks related to transfer functions?
A soft mask dictionary can include a /TR entry (transfer function) that remaps mask values before they are applied as opacity weights. This allows a linear grey gradient used as a mask to be curved — producing non-linear fade effects. The transfer function is applied to each mask sample value in the 0–1 range, transforming the opacity curve. This is analogous to the "curves" adjustment in Photoshop applied to a layer mask.