Monkeybread Software - DynaPDF Manual

DynaPDF Manual - Page 306

Function Reference

Page 306 of 839

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, ...);

pdfEndTemplate(pdf);

// A soft mask can only be activated with an extended graphics state.

TPDFExtGState gs;

pdfInitExtGState(&gs);

// Create the soft mask from the group and set it in the graphics state

// object. You can change more settings of the graphics state if

// necessary...

gs.SoftMask = pdfCreateSoftMask(pdf, grp, smtLuminosity, 0);

// Create the extended graphics state now

SI32 extGState = pdfCreateExtGState(pdf, &gs);

// And activate it...

pdfSetExtGState(pdf, extGState);

// The soft mask is now active, draw something on the page

pdfInsertImage(pdf, ...);

// The only way to deactivate a soft mask is to set a second extended

// graphics state that disables the soft mask.

gs.SoftMask

= NULL;

gs.SoftMaskNone = true;

SI32 restoreSoftMask = pdfCreateExtGState(pdf, &gs);

pdfSetExtGState(pdf, restoreSoftMask);

Return values:

If the function succeeds the return value is a pointer to the soft mask object. This pointer is required

to create an extended graphics state so that the mask can be activated. If the function fails the return

value is NULL.