[Cairo] Rectangle-based clipping for surfaces

[Carl Worth]

On Oct 14, Soorya Kuloor wrote:
 > I have latest version of patch that adds the
 > cairo_surface_clip_rectangle() call with the new virtualization changes.
 > Do you want it? However, I do not have the restore call.

Sure. But I won't commit it without restore. That's why I've been
sitting on the previous version of the patch --- I've been waiting
until I found time to implement the rest, or someone else did.

Also, Keith and I were talking about this API and identified a
problem. cairo_surface_clip_restore expands the clip region to the
entire surface. cairo_surface_clip_rectangle also expands the clip
region to include the given rectangle. Therefore, there must be some
other way to restrict the clip region.

The original proposal made the first call to
cairo_surface_clip_rectangle "special" in that it restricts the clip
region exactly to the given rectangle. This special case seems quite
messy.

The idea we came up with is to add a new call:

	cairo_status_t
	cairo_surface_clip_begin (cairo_surface_t *surface);

That restricts the clip region to the empty region. That way, all
calls to cairo_surface_clip_rectangle are consistent.

I feel that's a nice improvement.

The only thing left that I dislike is that in the path-based clipping
API, cairo_clip always reduces the size of the clip region. However,
in the rectangle-based API, cairo_surface_clip_rectangle always
expands the size of its region. Maybe we could find a better name for
cairo_surface_clip_rectangle that more clearly indicates the operation
we want?

-Carl