This group functionality can be convenient for performing
intermediate compositing. One common use of a group is to render
objects as opaque within the group, (so that they occlude each
other), and then blend the result with translucence onto the
destination.
Groups can be nested arbitrarily deep by making balanced calls to
cairoPushGroup
/cairoPopGroup
. Each call pushes/pops the new
target group onto/from a stack.
The cairoPushGroup
function calls cairoSave
so that any
changes to the graphics state will not be visible outside the
group, (the pop_group functions call cairoRestore
).
By default the intermediate group will have a content type of
CAIRO_CONTENT_COLOR_ALPHA
. Other content types can be chosen for
the group by using cairoPushGroupWithContent
instead.
As an example, here is how one might fill and stroke a path with
translucence, but without any portion of the fill being visible
under the stroke:
cr$pushGroup()
cr$setSource(fill_pattern)
cr$fillPreserve()
cr$setSource(stroke_pattern)
cr$stroke()
cr$popGroupToSource()
cr$paintWithAlpha(alpha)
Since 1.2