cairo-push-group (cr)

cr -- a cairo-t context

Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to the cairo-pop-group or cairo-pop-group-to-source functions. These calls provide the result of any drawing to the group as a pattern, either as an explicit object, or set as the source pattern.

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 the cairo-push-group and cairo-pop-group functions. Each call pushes and pops the new target group onto and from a stack.

The cairo-push-group function calls the cairo-save function so that any changes to the graphics state will not be visible outside the group, the pop group functions call the cairo-restore function.

By default the intermediate group will have a :color-alpha value of the cairo-content-t enumeration. Other content types can be chosen for the group by using the cairo-push-group-with-content function 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:

(cairo-push-group cr)
(cairo-set-source cr fill-pattern)
(cairo-fill-preserve cr)
(cairo-set-source cr stroke-pattern)
(cairo-stroke cr)
(cairo-pop-group-to-source cr)
(cairo-paint-with-alpha cr alpha)