Monkeybread Software - DynaPDF Manual

DynaPDF Manual - Page 318

Function Reference

Page 318 of 860

}TSoftMaskType;

The function creates a soft mask from a transparency group, see BeginTransparencyGroup() for

further information. A soft mask represents an alpha channel that can be applied on vector graphics,

texts, and images.

The creation of a soft mask begins with the creation of a transparency group. The rendered result of

the transparency group represents finally the soft mask or alpha channel.

The color space of the transparency group should be device gray or a gray ICC based color space. It

is also possible to define the group in RGB or CMYK but this is not really meaningful since the

result must always be converted to gray.

Soft mask types

The parameter Type specifies the type of the soft mask. If the type is smtAlpha the mask is computed

from the group's alpha channel, disregarding any color in the group. This type of soft mask works

like a clipping path. Any pixel that is drawn in the group makes the mask transparent, uncovered

areas remain invisible. There are not many cases for which this kind of masking can be useful. It is

mostly used for images if the source image format did not support an alpha channel or if the mask

was stored in a separate image file.

If the type is smtLuminosity the group is composited with a fully opaque backdrop as specified by

the parameter BackColor (the background color must be specified in the group's color space). The

mask is finally computed from the luminosity of the resulting color at each point in the group. This

enables the definition of the mask with arbitrary vector graphics, text, shadings, and images. The

underlying transparency group must be isolated since a non-isolated group would be initialized

with the current backdrop and this conflicts with the properties of the soft mask.

This is the most common type of a soft maks since it works like a real alpha channel with the

advantage that it can be created with vector graphics and especially shadings.

Possible rendering issues

A soft mask is designed to mask one object at time. Although it is possible to draw arbitrary objects

when a soft mask is active, the result is maybe not what is intended because the effect on

overlapping objects is as if the mask would be applied twice. If multiple objects must be drawn then

these objects are usually placed into a transparency group since a transparency group is rendered as

a hole and hence avoids issues with overlapping objects.

How to activate a soft mask?

Once the soft mask was created it can be activated and deactivated with an extended graphics state:

Example:

// Create the transpareny group

SI32 grp = pdfBeginTransparancyGroup(pdf, ...);