DynaPDF Manual - Page 177

Previous Page 176   Index   Next Page 178

Function Reference
Page 177 of 839
SI32 pdfBeginTransparencyGroup(
const PPDF* IPDF,
// Instance pointer
double x1,
// Lower left corner of the bounding box
double y1,
// Lower left corner of the bounding box
double x2,
// Upper right corner of the bounding box
double y2,
// Upper right corner of the bounding box
LBOOL Isolated,
// See description
LBOOL Knockout,
// See description
TExtColorSpace CS, // The group's color space
SI32 CSHandle)
// Required if a non-device space should be used
The function creates a transparency group and opens it so that arbitrary contents can be drawn into
it. A transparency group is a special type of template (see BeginTemplate() for further information)
that enables various effects in the transparent imaging model.
After the contents of the group was drawn the group must be finished with EndTemplate(). Yes, this
is correct. A transparency group is just an extended template.
A transparency group can be used stand alone or as a soft mask. A soft mask consists of a
transparency group that acts as an alpha channel and a corresponding soft mask dictionary that
describes the characteristics of the mask. A soft mask is not directly usable, it must be activated with
an extended graphics state. See CreateSoftMask() for further information.
The creation of a stand alone transparency group is essencially the same as a normal template and
both objects share the same properties. A transparency group can be placed on a page with
PlaceTemplate() or PlaceTemplateEx(), just like ordinary templates.
The difference between a template and a transparency group is that a transparency group is
composited with the backdrop as a hole. This property is very important when a soft mask should
be applied on an arbitrary artwork because a soft mask is designed to mask exactly one object at
The effect for overlapping objects drawn with regular techniques would be as if the soft mask is
applied twice and this is mostly not what is intended.
However, transparency groups can also be used without an active soft mask. Whether this can be
useful depends strongly on the effect that should be achieved. Most effects that can be achieved in
this way can also be achieved with regular drawing techniques and the latter is always preferred.
The Group's Bounding Box
Due to the way how a transparency group is rended it is important to create the group in the correct
size. Creating transparency groups larger than necessary can slow down rendering a lot, especially
if many such groups are used on a page.

Previous topic: BeginTemplate

Next topic: Stand alone transparency groups, Soft masks, Coordinates and bounding box of a soft mask: