[cairo] How to use clipping?

[Carl Worth]

On Tue, 3 Aug 2004 11:58:39 -0400 (EDT), Sebastien Lemieux wrote:
>   I've just started to use Cairo to produce png graphics and everything 
> seems just perfect!  I'd like to use the clipping functions.  Could 
> someone just summarize the use of:
> 
> cairo_init_clip()
> cairo_clip()

Sure.

Within the cairo graphics state, there is a notion of a current clipping
path. Initially, this path is infinitely large, (eg. no clipping is
performed).

Calling cairo_clip computes a new clipping path by intersecting the
current clipping path with the current path, (ie. the path formed with
things like cairo_move_to/line_to/curve_to). After that, the effect of
all subsequent drawing operations will be restricted to the area within
the current clipping path.

It is important to note that cairo_clip does not consume the current
path like cairo_stroke and cairo_fill do. This allows you to retain the
current path for subsequent drawing options, since a cairo_save/restore
cannot be used for this purpose as that would eliminate the effect of
cairo_clip. If the path is no longer needed, the user should call
cairo_new_path after cairo_clip to avoid unexpected behavior.

Calling cairo_clip can only shrink the current clipping region. There
are two ways to expand the clip region:

	1) Call cairo_init_clip which restores the clip path to its
           original infinite size.

	2) Call cairo_restore to restore a graphics state where a larger
           clip path was earlier saved with cairo_save.

NOTE: In the current implementation, things slow down quite a bit after
calling cairo_clip. Keith thinks this should be pretty easy to fix if
someone just goes and implements a more optimized version of the IN
operator for us.

> Will they apply to a cairo_show_surface() call?

Yes, the clipping should apply to all drawing operations. If not, it's a
bug, and you should let us know about it.

I hope that helps,

-Carl