Soft Mask

Soft mask is represented by a transparency group XObject to be used as source of position dependent mask values and the backdrop color space for the group compositing information. It also contains some other entries that control the conversion from the group results to mask values. Soft masks are used to modify the shape of an object or group and produce effects such as a gradual transition between an object and its background. For more information on soft mask, see PDF specification 1.7.

In GcPdf, soft mask can be created using the Create method of the SoftMask class which accepts the target document and the bounds where mask is to be applied as parameters. Then, you need to retrieve the graphics of the soft mask by using the Graphics property of FormXObject of the SoftMask class. You can design the mask by drawing on these graphics and once the mask is created, apply the mask to PDF document graphics by assigning it to SoftMask property of the PdfDocumentGraphics class.

Note:

• Only the alpha channel from the mask is used. Solid areas do not mask at all however, transparent areas mask completely. Semi-transparent areas mask in inverse proportion to the alpha value.

• Some PDF viewers do not handle changing the soft masks correctly unless the mask is reset prior to assigning a new one. This can be done by setting the SoftMask property of Graphics object to 'none'.

To create soft mask using GcPdf:

1. Initialize GcPdfDocument class to create the target PDF document.

2. Invoke the Create method of the SoftMask class to create the SoftMask class object.

3. Get the transparency group FormXobject to be used as the source of alpha for this mask, using the FormXObject property of the SoftMask class.

4. To generate the content for the FormXObject, access its graphics using the Graphics property of the FormXObject class which returns an instance of the GcPdfGraphics class.

5. Use the different drawing methods of the returned GcPdfGraphics object to design the soft mask.

6. Apply the soft mask to the target PDF document by assigning the created soft mask to the SoftMask property of the target PDF document graphics object.

   public int CreatePDF(Stream stream)
   {
       var doc = new GcPdfDocument();
       var page = doc.NewPage();
       var g = page.Graphics;
   
       var rMask = new RectangleF(0, 0, 72 * 5, 72 * 2);
       var rDoc = new RectangleF(36, 36, rMask.Width, rMask.Height);
   
       var softMask = SoftMask.Create(doc, rDoc);
       var smGraphics = softMask.FormXObject.Graphics;
       smGraphics.FillEllipse(rMask, Color.FromArgb(128, Color.Black));
       smGraphics.DrawString("SOLID TEXT",
       new TextFormat() { Font = StandardFonts.HelveticaBold, FontSize = 52, ForeColor = Color.Black },
       new RectangleF(rMask.X, rMask.Y, rMask.Width, rMask.Height),
       TextAlignment.Center, ParagraphAlignment.Center, false);
       var rt = rMask;
       rt.Inflate(-8, -8);
       // Color on the mask does not matter, only alpha channel is important:
       smGraphics.DrawEllipse(rt, Color.Red);
       g.SoftMask = softMask;
       g.DrawImage(Image.FromFile(Path.Combine("Resources", "Images", "reds.jpg")),
           rDoc, null, ImageAlign.StretchImage);
       // Done:
       doc.Save(stream);
       return doc.Pages.Count;
   }

For more information about implementation of soft mask feature using GcPdf, see GcPdf sample browser.