Module Cairo.Group

Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to Cairo.Group.pop or Cairo.Group.pop_to_source. 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 Group.push/Group.pop. Each call pushes/pops the new target group onto/from a stack.

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

• parameter content

  The content type of the group. By default the intermediate group will have a content type of COLOR_ALPHA (see Cairo.content).

Terminates the redirection begun by a call to Cairo.Group.push and returns a new pattern containing the results of all drawing operations performed to the group.

The Group.pop function calls Cairo.restore (balancing a call to Cairo.save by the Group.push function), so that any changes to the graphics state will not be visible outside the group.

• returns

  a newly created (surface) pattern containing the results of all drawing operations performed to the group.

Terminates the redirection begun by a call to Group.push and installs the resulting pattern as the source pattern in the given cairo context.

The behavior of this function is equivalent to the sequence of operations:

let group = Cairo.Group.pop cr in
Cairo.set_source cr group;

Gets the current destination surface for the context. This is either the original target surface as passed to create or the target surface for the current group as started by the most recent call to Group.push.