src/cairo-surface.c src/cairoint.h: Add _cairo_surface_begin/end to save and restore the clip state of a surface. Copy and store clip regions set on a surface so that we can save and restore them.

Add a CAIRO_STATUS_BAD_NESTING error for interleaved use of two cairo_t's on the same surface. Also, add a skeleton doc comment for cairo_status_t.
src/cairo.c src/cairo-gstate.c src/cairoint.h: Use _cairo_surface_begin/end to replace _cairo_gstate_restore_external_state.
Use _cairo_surface_begin/end to save the state of a surface when we start drawing at it and restore it at the end. Check that the save level of the surface is what we expect on drawing operations and fail with CAIRO_STATUS_BAD_NESTING otherwise.
src/cairo-pattern.c src/cairoint.h (_cairo_pattern_acquire_surface_for_surface) (_cairo_pattern_release_surface): Surround use of pattern->surface with _cairo_surface->begin/end so we don't clip surfaces used as sources.
test/clip-nesting.c test/Makefile.am: Test of destinatin clipping with the nested creation of cairo_t's for the same context.
test/source-clip.c test/Makefile.am: Test that clipping on a source as a destination doesn't affect use of it as a source.
XFAIL test for copying from a surface as a source to itself as a destination with a clip.

16 files changed, 649 insertions, 77 deletions

diff --git a/ChangeLog b/ChangeLog
index 5b77aa0c..794ebe15 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,38 @@
+2005-04-28  Owen Taylor  <otaylor@redhat.com>
+
+	* src/cairo-surface.c src/cairoint.h: Add _cairo_surface_begin/end
+	to save and restore the clip state of a surface. Copy and store
+	clip regions set on a surface so that we can save and restore them.
+
+	* src/cairo.[ch]: Add a CAIRO_STATUS_BAD_NESTING error
+	for interleaved use of two cairo_t's on the same surface. Also,
+	add a skeleton doc comment for cairo_status_t.
+
+	* src/cairo.c src/cairo-gstate.c src/cairoint.h: Use
+	_cairo_surface_begin/end to replace
+	_cairo_gstate_restore_external_state.
+
+	* src/cairo-gstate.c: Use _cairo_surface_begin/end to save the 
+	state of a surface when we start drawing at it and restore it
+	at the end. Check that the save level of the surface is what
+	we expect on drawing operations and fail with CAIRO_STATUS_BAD_NESTING
+	otherwise.
+
+	* src/cairo-pattern.c src/cairoint.h (_cairo_pattern_acquire_surface_for_surface) 
+	(_cairo_pattern_release_surface): Surround use of pattern->surface
+	with _cairo_surface->begin/end so we don't clip surfaces used as 
+	sources.
+
+	* test/clip-nesting.c test/Makefile.am: Test of destinatin
+	clipping with the nested creation of cairo_t's for the same
+	context.
+
+	* test/source-clip.c test/Makefile.am: Test that clipping on
+	a source as a destination doesn't affect use of it as a source.
+
+	* test/self-copy.c: XFAIL test for copying from a surface as
+	a source to itself as a destination with a clip.
+
 2005-05-02  Keith Packard  <keithp@keithp.com>
 
 	reviewed by: cworth
diff --git a/doc/public/tmpl/cairo.sgml b/doc/public/tmpl/cairo.sgml
index 342c1eda..a6179624 100644
--- a/doc/public/tmpl/cairo.sgml
+++ b/doc/public/tmpl/cairo.sgml
@@ -1042,6 +1042,7 @@ Drawing contexts.
 @CAIRO_STATUS_WRITE_ERROR: 
 @CAIRO_STATUS_SURFACE_FINISHED: 
 @CAIRO_STATUS_SURFACE_TYPE_MISMATCH: 
+@CAIRO_STATUS_BAD_NESTING: 
 
 <!-- ##### FUNCTION cairo_status ##### -->
 <para>
diff --git a/src/cairo-gstate-private.h b/src/cairo-gstate-private.h
index fcf8a23f..eeb35b83 100644
--- a/src/cairo-gstate-private.h
+++ b/src/cairo-gstate-private.h
@@ -61,6 +61,7 @@ struct _cairo_gstate {
     cairo_scaled_font_t *scaled_font;	/* Specific to the current CTM */
 
     cairo_surface_t *surface;
+    int surface_level;		/* Used to detect bad nested use */
 
     cairo_pattern_t *source;
 
diff --git a/src/cairo-gstate.c b/src/cairo-gstate.c
index f4bfb5d8..017b41d2 100644
--- a/src/cairo-gstate.c
+++ b/src/cairo-gstate.c
@@ -103,6 +103,7 @@ _cairo_gstate_init (cairo_gstate_t *gstate)
 			     CAIRO_GSTATE_DEFAULT_FONT_SIZE);
     
     gstate->surface = NULL;
+    gstate->surface_level = 0;
 
     gstate->clip.region = NULL;
     gstate->clip.surface = NULL;
@@ -160,8 +161,16 @@ _cairo_gstate_init_copy (cairo_gstate_t *gstate, cairo_gstate_t *other)
     if (status)
 	goto CLEANUP_FONT;
 
+    status = _cairo_surface_begin (gstate->surface);
+    if (status)
+	goto CLEANUP_PEN;
+    gstate->surface_level = gstate->surface->level;
+
     return status;
 
+  CLEANUP_PEN:
+    _cairo_pen_fini (&gstate->pen_regular);
+
   CLEANUP_FONT:
     cairo_scaled_font_destroy (gstate->scaled_font);
     gstate->scaled_font = NULL;
@@ -181,9 +190,11 @@ _cairo_gstate_fini (cairo_gstate_t *gstate)
     if (gstate->scaled_font)
 	cairo_scaled_font_destroy (gstate->scaled_font);
 
-    if (gstate->surface)
+    if (gstate->surface) {
+	_cairo_surface_end (gstate->surface);
 	cairo_surface_destroy (gstate->surface);
-    gstate->surface = NULL;
+	gstate->surface = NULL;
+    }
 
     if (gstate->clip.surface)
 	cairo_surface_destroy (gstate->clip.surface);
@@ -329,20 +340,36 @@ _cairo_gstate_end_group (cairo_gstate_t *gstate)
 cairo_status_t
 _cairo_gstate_set_target_surface (cairo_gstate_t *gstate, cairo_surface_t *surface)
 {
+    cairo_status_t status;
+    
+    if (gstate->surface == surface)
+	return CAIRO_STATUS_SUCCESS;
+    
+    if (surface) {
+	status = _cairo_surface_begin_reset_clip (surface);
+	if (!CAIRO_OK (status))
+	    return status;
+    }
+
     _cairo_gstate_unset_font (gstate);
 
-    if (gstate->surface)
+    if (gstate->surface) {
+	_cairo_surface_end (gstate->surface);
 	cairo_surface_destroy (gstate->surface);
+    }
 
     gstate->surface = surface;
 
     /* Sometimes the user wants to return to having no target surface,
      * (just like after cairo_create). This can be useful for forcing
      * the old surface to be destroyed. */
-    if (surface == NULL)
+    if (surface == NULL) {
+	gstate->surface_level = 0;
 	return CAIRO_STATUS_SUCCESS;
+    }
 
     cairo_surface_reference (gstate->surface);
+    gstate->surface_level = surface->level;
 
     _cairo_gstate_identity_matrix (gstate);
 
@@ -721,6 +748,9 @@ _cairo_gstate_paint (cairo_gstate_t *gstate)
     cairo_status_t status;
     cairo_box_t box;
     cairo_traps_t traps;
+
+    if (gstate->surface->level != gstate->surface_level)
+	return CAIRO_STATUS_BAD_NESTING;
     
     status = _cairo_surface_get_clip_extents (gstate->surface, &rectangle);
     if (!CAIRO_OK (status))
@@ -872,6 +902,9 @@ _cairo_gstate_mask (cairo_gstate_t  *gstate,
     cairo_status_t status;
     int mask_x, mask_y;
 
+    if (gstate->surface->level != gstate->surface_level)
+	return CAIRO_STATUS_BAD_NESTING;
+    
     _get_mask_extents (gstate, mask, &extents);
     
     if (gstate->clip.surface) {
@@ -937,6 +970,9 @@ _cairo_gstate_stroke (cairo_gstate_t *gstate, cairo_path_fixed_t *path)
     cairo_status_t status;
     cairo_traps_t traps;
 
+    if (gstate->surface->level != gstate->surface_level)
+	return CAIRO_STATUS_BAD_NESTING;
+    
     if (gstate->line_width <= 0.0)
 	return CAIRO_STATUS_SUCCESS;
 
@@ -1405,6 +1441,9 @@ _cairo_gstate_fill (cairo_gstate_t *gstate, cairo_path_fixed_t *path)
     cairo_status_t status;
     cairo_traps_t traps;
 
+    if (gstate->surface->level != gstate->surface_level)
+	return CAIRO_STATUS_BAD_NESTING;
+    
     _cairo_traps_init (&traps);
 
     status = _cairo_path_fixed_fill_to_traps (path, gstate, &traps);
@@ -1537,6 +1576,9 @@ BAIL:
 cairo_status_t
 _cairo_gstate_reset_clip (cairo_gstate_t *gstate)
 {
+    if (gstate->surface->level != gstate->surface_level)
+	return CAIRO_STATUS_BAD_NESTING;
+    
     /* destroy any existing clip-region artifacts */
     if (gstate->clip.surface)
 	cairo_surface_destroy (gstate->clip.surface);
@@ -1554,25 +1596,6 @@ _cairo_gstate_reset_clip (cairo_gstate_t *gstate)
     return CAIRO_STATUS_SUCCESS;
 }
 
-/* Reset surface clip region to the one in the gstate */
-cairo_status_t
-_cairo_gstate_restore_external_state (cairo_gstate_t *gstate)
-{
-    cairo_status_t status;
-
-    status = CAIRO_STATUS_SUCCESS;
-    
-    if (gstate->surface) 
-	status = _cairo_surface_set_clip_region (gstate->surface, 
-						 gstate->clip.region);
-
-    /* If not supported we're already using surface clipping */
-    if (status == CAIRO_INT_STATUS_UNSUPPORTED)
-	status = CAIRO_STATUS_SUCCESS;
-
-    return status;
-}
-
 cairo_status_t
 _cairo_gstate_clip (cairo_gstate_t *gstate, cairo_path_fixed_t *path)
 {
@@ -1582,6 +1605,9 @@ _cairo_gstate_clip (cairo_gstate_t *gstate, cairo_path_fixed_t *path)
     cairo_box_t extents;
     pixman_region16_t *region;
 
+    if (gstate->surface->level != gstate->surface_level)
+	return CAIRO_STATUS_BAD_NESTING;
+    
     /* Fill the clip region as traps. */
 
     _cairo_traps_init (&traps);
@@ -2130,6 +2156,9 @@ _cairo_gstate_show_glyphs (cairo_gstate_t *gstate,
     cairo_box_t bbox;
     cairo_rectangle_t extents;
 
+    if (gstate->surface->level != gstate->surface_level)
+	return CAIRO_STATUS_BAD_NESTING;
+    
     status = _cairo_gstate_ensure_font (gstate);
     if (status)
 	return status;
diff --git a/src/cairo-pattern.c b/src/cairo-pattern.c
index 8fd8f0d9..70dd93d5 100644
--- a/src/cairo-pattern.c
+++ b/src/cairo-pattern.c
@@ -972,6 +972,7 @@ _cairo_pattern_acquire_surface_for_gradient (cairo_gradient_pattern_t *pattern,
     attr->extend = repeat ? CAIRO_EXTEND_REPEAT : CAIRO_EXTEND_NONE;
     attr->filter = CAIRO_FILTER_NEAREST;
     attr->acquired = FALSE;
+    attr->clip_saved = FALSE;
     
     return status;
 }
@@ -999,6 +1000,7 @@ _cairo_pattern_acquire_surface_for_solid (cairo_solid_pattern_t	     *pattern,
     attribs->extend = CAIRO_EXTEND_REPEAT;
     attribs->filter = CAIRO_FILTER_NEAREST;
     attribs->acquired = FALSE;
+    attribs->clip_saved = FALSE;
     
     return CAIRO_STATUS_SUCCESS;
 }
@@ -1042,21 +1044,36 @@ _cairo_pattern_acquire_surface_for_surface (cairo_surface_pattern_t   *pattern,
     int tx, ty;
 
     attr->acquired = FALSE;
+    attr->clip_saved = FALSE;
 	    
     if (_cairo_surface_is_image (dst))
     {
 	cairo_image_surface_t *image;
 	
+	status = _cairo_surface_begin_reset_clip (pattern->surface);
+	if (!CAIRO_OK (status))
+	    return status;
+
 	status = _cairo_surface_acquire_source_image (pattern->surface,
 						      &image,
 						      &attr->extra);
-	if (CAIRO_OK (status))
-	    *out = &image->base;
-	
+	if (!CAIRO_OK (status))
+	    return status;
+
+	_cairo_surface_end (pattern->surface);
+
+	*out = &image->base;
 	attr->acquired = TRUE;
     }
     else
+    {
+	status = _cairo_surface_begin_reset_clip (pattern->surface);
+	if (!CAIRO_OK (status))
+	    return status;
+
 	status = _cairo_surface_clone_similar (dst, pattern->surface, out);
+	_cairo_surface_end (pattern->surface);
+    }
     
     attr->extend = pattern->base.extend;
     attr->filter = pattern->base.filter;
@@ -1104,14 +1121,16 @@ _cairo_pattern_acquire_surface (cairo_pattern_t		   *pattern,
 				cairo_surface_t		   **surface_out,
 				cairo_surface_attributes_t *attributes)
 {
+    cairo_status_t status;
+    
     switch (pattern->type) {
     case CAIRO_PATTERN_SOLID: {
 	cairo_solid_pattern_t *src = (cairo_solid_pattern_t *) pattern;
 	
-	return _cairo_pattern_acquire_surface_for_solid (src, dst,
-							 x, y, width, height,
-							 surface_out,
-							 attributes);
+	status = _cairo_pattern_acquire_surface_for_solid (src, dst,
+							   x, y, width, height,
+							   surface_out,
+							   attributes);
 	} break;
     case CAIRO_PATTERN_LINEAR:
     case CAIRO_PATTERN_RADIAL: {
@@ -1130,30 +1149,43 @@ _cairo_pattern_acquire_surface (cairo_pattern_t		   *pattern,
 
 	    _cairo_pattern_init_solid (&solid, color);
 
-	    return _cairo_pattern_acquire_surface_for_solid (&solid, dst,
-							     x, y,
-							     width, height,
-							     surface_out,
-							     attributes);
+	    status = _cairo_pattern_acquire_surface_for_solid (&solid, dst,
+							       x, y,
+							       width, height,
+							       surface_out,
+							       attributes);
 	}
 	else
-	    return _cairo_pattern_acquire_surface_for_gradient (src, dst,
-								x, y,
-								width, height,
-								surface_out,
-								attributes);
+	    status = _cairo_pattern_acquire_surface_for_gradient (src, dst,
+								  x, y,
+								  width, height,
+								  surface_out,
+								  attributes);
     } break;
     case CAIRO_PATTERN_SURFACE: {
 	cairo_surface_pattern_t *src = (cairo_surface_pattern_t *) pattern;
 	
-	return _cairo_pattern_acquire_surface_for_surface (src, dst,
-							   x, y, width, height,
-							   surface_out,
-							   attributes);
+	status = _cairo_pattern_acquire_surface_for_surface (src, dst,
+							     x, y, width, height,
+							     surface_out,
+							     attributes);
     } break;
+    default:
+	status = CAIRO_INT_STATUS_UNSUPPORTED;
+    }
+
+    
+    if (CAIRO_OK (status) && (*surface_out)->clip_region) {
+	status = _cairo_surface_begin_reset_clip (*surface_out);
+	if (!CAIRO_OK (status)) {
+	    _cairo_pattern_release_surface (dst, *surface_out, attributes);
+	    return status;
+	}
+	
+	attributes->clip_saved = TRUE;
     }
 
-    return CAIRO_INT_STATUS_UNSUPPORTED;
+    return status;
 }
 
 /**
@@ -1169,11 +1201,15 @@ _cairo_pattern_release_surface (cairo_surface_t		   *dst,
 				cairo_surface_t		   *surface,
 				cairo_surface_attributes_t *attributes)
 {
+    if (attributes->clip_saved)
+	_cairo_surface_end (surface);
+    
     if (attributes->acquired)
+    {
 	_cairo_surface_release_source_image (dst,
 					     (cairo_image_surface_t *) surface,
 					     attributes->extra);
-    else
+    } else
 	cairo_surface_destroy (surface);
 }
 
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 9a22b129..6518d04b 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -39,6 +39,17 @@
 
 #include "cairoint.h"
 
+struct _cairo_surface_save {
+    cairo_surface_save_t *next;
+    pixman_region16_t *clip_region;
+};
+
+static cairo_status_t
+_cairo_surface_set_clip_region_internal (cairo_surface_t   *surface,
+					 pixman_region16_t *region,
+					 cairo_bool_t       copy_region,
+					 cairo_bool_t       free_existing);   
+
 void
 _cairo_surface_init (cairo_surface_t			*surface,
 		     const cairo_surface_backend_t	*backend)
@@ -57,11 +68,110 @@ _cairo_surface_init (cairo_surface_t			*surface,
     surface->device_x_offset = 0;
     surface->device_y_offset = 0;
 
-    surface->is_clipped = 0;
-    surface->clip_extents.x = 0;
-    surface->clip_extents.y = 0;
-    surface->clip_extents.width  = 0;
-    surface->clip_extents.height = 0;
+    surface->clip_region = NULL;
+
+    surface->saves = NULL;
+    surface->level = 0;
+}
+
+static cairo_status_t
+_cairo_surface_begin_internal (cairo_surface_t *surface,
+			       cairo_bool_t     reset_clip)
+{
+    cairo_surface_save_t *save;
+
+    if (surface->finished)
+	return CAIRO_STATUS_SURFACE_FINISHED;
+
+    save = malloc (sizeof (cairo_surface_save_t));
+    if (!save)
+	return CAIRO_STATUS_NO_MEMORY;
+
+    if (surface->clip_region) {
+	if (reset_clip)
+	{
+	    cairo_status_t status;
+	    
+	    save->clip_region = surface->clip_region;
+	    status = _cairo_surface_set_clip_region_internal (surface, NULL, FALSE, FALSE);
+	    if (!CAIRO_OK (status)) {
+		free (save);
+		return status;
+	    }
+	}
+	else
+	{
+	    save->clip_region = pixman_region_create ();
+	    pixman_region_copy (save->clip_region, surface->clip_region);
+	}
+    } else {
+	save->clip_region = NULL;
+    }
+
+    save->next = surface->saves;
+    surface->saves = save;
+    surface->level++;
+
+    return CAIRO_STATUS_SUCCESS;
+}
+
+/**
+ * _cairo_surface_begin:
+ * @surface: a #cairo_surface_t
+ * 
+ * Must be called before beginning to use the surface. State
+ * of the surface like the clip region will be saved then restored
+ * on the matching call _cairo_surface_end().
+ */
+cairo_private cairo_status_t
+_cairo_surface_begin (cairo_surface_t *surface)
+{
+  return _cairo_surface_begin_internal (surface, FALSE);
+}
+
+/**
+ * _cairo_surface_begin_reset_clip:
+ * @surface: a #cairo_surface_t
+ * 
+ * Must be called before beginning to use the surface. State
+ * of the surface like the clip region will be saved then restored
+ * on the matching call _cairo_surface_end().
+ *
+ * After the state is saved, the clip region is cleared.  This
+ * combination of operations is a little artificial; the caller could
+ * simply call _cairo_surface_set_clip_region (surface, NULL); after
+ * _cairo_surface_save(). Combining the two saves a copy of the clip
+ * region, and also simplifies error handling for the caller.
+ **/
+cairo_private cairo_status_t
+_cairo_surface_begin_reset_clip (cairo_surface_t *surface)
+{
+    return _cairo_surface_begin_internal (surface, TRUE);
+}
+
+/**
+ * _cairo_surface_end:
+ * @surface: a #cairo_surface_t
+ * 
+ * Restores any state saved by _cairo_surface_begin()
+ **/
+cairo_private cairo_status_t
+_cairo_surface_end (cairo_surface_t *surface)
+{
+    cairo_surface_save_t *save;
+    pixman_region16_t *clip_region;
+
+    if (!surface->saves)
+	return CAIRO_STATUS_BAD_NESTING;
+
+    save = surface->saves;
+    surface->saves = save->next;
+    surface->level--;
+
+    clip_region = save->clip_region;
+    free (save);
+
+    return _cairo_surface_set_clip_region_internal (surface, clip_region, FALSE, TRUE);
 }
 
 cairo_surface_t *
@@ -176,6 +286,14 @@ cairo_surface_finish (cairo_surface_t *surface)
     if (surface->finished)
 	return CAIRO_STATUS_SURFACE_FINISHED;
 
+    if (surface->saves)
+	return CAIRO_STATUS_BAD_NESTING;
+    
+    if (surface->clip_region) {
+	pixman_region_destroy (surface->clip_region);
+	surface->clip_region = NULL;
+    }
+
     if (surface->backend->finish) {
 	status = surface->backend->finish (surface);
 	if (status)
@@ -855,43 +973,60 @@ _cairo_surface_show_page (cairo_surface_t *surface)
     return surface->backend->show_page (surface);
 }
 
-cairo_status_t
-_cairo_surface_set_clip_region (cairo_surface_t   *surface,
-				pixman_region16_t *region)
+static cairo_status_t
+_cairo_surface_set_clip_region_internal (cairo_surface_t   *surface,
+					 pixman_region16_t *region,
+					 cairo_bool_t       copy_region,
+					 cairo_bool_t       free_existing)
 {
-    pixman_box16_t *box;
-
     if (surface->finished)
 	return CAIRO_STATUS_SURFACE_FINISHED;
 
+    if (region == surface->clip_region)
+	return CAIRO_STATUS_SUCCESS;
+    
     if (surface->backend->set_clip_region == NULL)
 	return CAIRO_INT_STATUS_UNSUPPORTED;
 
-    if (region) {
-	box = pixman_region_extents (region);
-
-	surface->clip_extents.x = box->x1;
-	surface->clip_extents.y = box->y1;
-	surface->clip_extents.width  = box->x2 - box->x1;
-	surface->clip_extents.height = box->y2 - box->y1;
-
-	surface->is_clipped = 1;
-    } else {
-	surface->is_clipped = 0;
+    if (surface->clip_region) {
+	if (free_existing)
+	    pixman_region_destroy (surface->clip_region);
+	surface->clip_region = NULL;
     }
 
+    if (region) {
+	if (copy_region) {
+	    surface->clip_region = pixman_region_create ();
+	    pixman_region_copy (surface->clip_region, region);
+	} else
+	    surface->clip_region = region;
+    }
+    
     return surface->backend->set_clip_region (surface, region);
 }
 
 cairo_status_t
+_cairo_surface_set_clip_region (cairo_surface_t   *surface,
+				pixman_region16_t *region)
+{
+    return _cairo_surface_set_clip_region_internal (surface, region, TRUE, TRUE);
+}
+
+cairo_status_t
 _cairo_surface_get_clip_extents (cairo_surface_t   *surface,
 				 cairo_rectangle_t *rectangle)
 {
     if (surface->finished)
 	return CAIRO_STATUS_SURFACE_FINISHED;
 
-    if (surface->is_clipped) {
-	*rectangle = surface->clip_extents;
+    if (surface->clip_region) {
+	pixman_box16_t *box = pixman_region_extents (surface->clip_region);
+
+	rectangle->x = box->x1;
+	rectangle->y = box->y1;
+	rectangle->width  = box->x2 - box->x1;
+	rectangle->height = box->y2 - box->y1;
+	
 	return CAIRO_STATUS_SUCCESS;
     }
 
diff --git a/src/cairo.c b/src/cairo.c
index 4f17fbea..301f3246 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -226,8 +226,6 @@ cairo_restore (cairo_t *cr)
     if (cr->status)
 	return;
    
-    cr->status = _cairo_gstate_restore_external_state (cr->gstate);
-    
     CAIRO_CHECK_SANITY (cr);
 }
 slim_hidden_def(cairo_restore);
@@ -301,6 +299,16 @@ cairo_pop_group (cairo_t *cr)
  * will be referenced by the #cairo_t, so you can immediately
  * call cairo_surface_destroy() on it if you don't need to
  * keep a reference to it around.
+ *
+ * Note that there are restrictions on using the same surface in
+ * multiple contexts at the same time. If, after setting @surface as
+ * the target surface of @cr_a, you set it as the target surface of
+ * @cr_b, you must finish using @cr_b and unset the target surface
+ * before resuming using @cr_a. Unsetting the target surface happens
+ * automatically when the last reference to the context is released
+ * with cairo_destroy(), or you can call cairo_set_target_surface
+ * (@cr_b, %NULL) explicitly.  See also the %CAIRO_STATUS_BAD_NESTING
+ * status.
  **/
 void
 cairo_set_target_surface (cairo_t *cr, cairo_surface_t *surface)
@@ -2628,6 +2636,8 @@ cairo_status_string (cairo_t *cr)
 	return "the target surface has been finished";
     case CAIRO_STATUS_SURFACE_TYPE_MISMATCH:
 	return "the surface type is not appropriate for the operation";
+    case CAIRO_STATUS_BAD_NESTING:
+	return "drawing operations interleaved for two contexts for the same surface";
     }
 
     return "<unknown error status>";
diff --git a/src/cairo.h b/src/cairo.h
index c0a122fd..8f609d48 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -124,6 +124,32 @@ typedef struct _cairo_user_data_key {
     int unused;
 } cairo_user_data_key_t;
 
+/**
+ * cairo_status_t
+ * @CAIRO_STATUS_SUCCESS: no error has occurred
+ * @CAIRO_STATUS_NO_MEMORY: 
+ * @CAIRO_STATUS_INVALID_RESTORE:
+ * @CAIRO_STATUS_INVALID_POP_GROUP:
+ * @CAIRO_STATUS_INVALID_MATRIX:
+ * @CAIRO_STATUS_NO_TARGET_SURFACE:
+ * @CAIRO_STATUS_NULL_POINTER:
+ * @CAIRO_STATUS_INVALID_STRING:
+ * @CAIRO_STATUS_INVALID_PATH_DATA:
+ * @CAIRO_STATUS_READ_ERROR:
+ * @CAIRO_STATUS_WRITE_ERROR:
+ * @CAIRO_STATUS_SURFACE_FINISHED:
+ * @CAIRO_STATUS_SURFACE_TYPE_MISMATCH:
+ * @CAIRO_STATUS_BAD_NESTING: the same surface was used as the
+ *  target surface for two different cairo contexts at once,
+ *  and more drawing was done on the first context before the
+ *  surface was unset as the target for the second context.
+ *  See the documentation for cairo_set_target_surface()
+ *
+ * #cairo_status_t is used to indicate errors that can occur when
+ * using Cairo. In some cases it is returned directly by functions.
+ * but when using #cairo_t, the last error, if any, is stored in
+ * the context and can be retrieved with cairo_status().
+ **/
 typedef enum cairo_status {
     CAIRO_STATUS_SUCCESS = 0,
     CAIRO_STATUS_NO_MEMORY,
@@ -138,7 +164,8 @@ typedef enum cairo_status {
     CAIRO_STATUS_READ_ERROR,
     CAIRO_STATUS_WRITE_ERROR,
     CAIRO_STATUS_SURFACE_FINISHED,
-    CAIRO_STATUS_SURFACE_TYPE_MISMATCH
+    CAIRO_STATUS_SURFACE_TYPE_MISMATCH,
+    CAIRO_STATUS_BAD_NESTING
 } cairo_status_t;
 
 /**
diff --git a/src/cairoint.h b/src/cairoint.h
index 1a6ff337..6c0461e9 100644
--- a/src/cairoint.h
+++ b/src/cairoint.h
@@ -690,6 +690,8 @@ typedef struct _cairo_format_masks {
     unsigned long blue_mask;
 } cairo_format_masks_t;
 
+typedef struct _cairo_surface_save cairo_surface_save_t;
+
 struct _cairo_surface {
     const cairo_surface_backend_t *backend;
 
@@ -704,8 +706,10 @@ struct _cairo_surface {
     double device_x_offset;
     double device_y_offset;
 
-    int is_clipped;
-    cairo_rectangle_t clip_extents;
+    cairo_surface_save_t *saves; /* Stack of saved states from cairo_surface_begin/end() */
+    int level;			 /* Number saved states */
+  
+    pixman_region16_t *clip_region;
 };
 
 struct _cairo_image_surface {
@@ -827,6 +831,7 @@ typedef struct _cairo_surface_attributes {
     int		   x_offset;
     int		   y_offset;
     cairo_bool_t   acquired;
+    cairo_bool_t   clip_saved;
     void	   *extra;
 } cairo_surface_attributes_t;
 
@@ -1100,9 +1105,6 @@ cairo_private cairo_status_t
 _cairo_gstate_reset_clip (cairo_gstate_t *gstate);
 
 cairo_private cairo_status_t
-_cairo_gstate_restore_external_state (cairo_gstate_t *gstate);
-
-cairo_private cairo_status_t
 _cairo_gstate_show_surface (cairo_gstate_t	*gstate,
 			    cairo_surface_t	*surface,
 			    double		 x,
@@ -1394,6 +1396,15 @@ _cairo_surface_init (cairo_surface_t			*surface,
 		     const cairo_surface_backend_t	*backend);
 
 cairo_private cairo_status_t
+_cairo_surface_begin (cairo_surface_t *surface);
+
+cairo_private cairo_status_t
+_cairo_surface_begin_reset_clip (cairo_surface_t *surface);
+
+cairo_private cairo_status_t
+_cairo_surface_end (cairo_surface_t *surface);
+
+cairo_private cairo_status_t
 _cairo_surface_fill_rectangle (cairo_surface_t	   *surface,
 			       cairo_operator_t	    operator,
 			       const cairo_color_t *color,
diff --git a/test/Makefile.am b/test/Makefile.am
index 531f9b37..b1a90290 100644
--- a/test/Makefile.am
+++ b/test/Makefile.am
@@ -1,6 +1,7 @@
 # All test cases go here
 TESTS = 		\
 clip-twice		\
+clip-nesting		\
 coverage		\
 create-for-png		\
 fill-and-stroke		\
@@ -17,7 +18,9 @@ path-data		\
 pdf-surface		\
 pixman-rotate		\
 select-font-no-show-text\
+self-copy		\
 set-source		\
+source-clip		\
 surface-finish-twice	\
 surface-pattern		\
 text-cache-crash	\
@@ -32,6 +35,7 @@ rel-path
 # I really don't like having to repeat this list. Anyone know a good
 # way to avoid it? Can I use a wildcard here?
 EXTRA_DIST =			\
+clip-nesting-ref.png		\
 create-for-png-ref.png		\
 fill-and-stroke-ref.png		\
 fill-rule-ref.png		\
@@ -43,11 +47,14 @@ mask-ref.png			\
 move-to-show-surface-ref.png	\
 coverage-ref.png		\
 clip-twice-ref.png		\
+mask-ref.png			\
 paint-ref.png			\
 path-data-ref.png		\
 pixman-rotate-ref.png		\
 romedalen.png			\
+self-copy-ref.png		\
 set-source-ref.png		\
+source-clip-ref.png		\
 surface-pattern-ref.png		\
 transforms-ref.png		\
 translate-show-surface-ref.png	\
@@ -70,6 +77,7 @@ rel-path-ref.png
 XFAIL_TESTS =		\
 coverage		\
 pixman-rotate		\
+self-copy		\
 text-rotate
 
 check_PROGRAMS = $(TESTS)
@@ -99,6 +107,7 @@ LDADDS = libcairotest.la $(top_builddir)/src/libcairo.la
 # ARGH! I have to repeat the list of tests a third time. Maybe it's
 # time to break down and auto-generate the Makefile.am or something
 # from autogen.sh. My, but this is painful...
+clip_nesting_LDADD = $(LDADDS)
 clip_twice_LDADD = $(LDADDS)
 coverage_LDADD = $(LDADDS)
 create_for_png_LDADD = $(LDADDS)
@@ -116,7 +125,9 @@ path_data_LDADD = $(LDADDS)
 pdf_surface_LDADD = $(LDADDS)
 pixman_rotate_LDADD = $(LDADDS)
 select_font_no_show_text_LDADD = $(LDADDS)
+self_copy_LDADD = $(LDADDS)
 set_source_LDADD = $(LDADDS)
+source_clip_LDADD = $(LDADDS)
 surface_finish_twice_LDADD = $(LDADDS)
 surface_pattern_LDADD = $(LDADDS)
 text_cache_crash_LDADD = $(LDADDS)
diff --git a/test/clip-nesting-ref.png b/test/clip-nesting-ref.png
new file mode 100644
index 00000000..6b7e1cd5
--- /dev/null
+++ b/test/clip-nesting-ref.png
diff --git a/test/clip-nesting.c b/test/clip-nesting.c
new file mode 100644
index 00000000..03760b01
--- /dev/null
+++ b/test/clip-nesting.c
@@ -0,0 +1,101 @@
+/*
+ * Copyright © 2005 Red Hat, Inc.
+ *
+ * Permission to use, copy, modify, distribute, and sell this software
+ * and its documentation for any purpose is hereby granted without
+ * fee, provided that the above copyright notice appear in all copies
+ * and that both that copyright notice and this permission notice
+ * appear in supporting documentation, and that the name of
+ * Red Hat, Inc. not be used in advertising or publicity pertaining to
+ * distribution of the software without specific, written prior
+ * permission. Red Hat, Inc. makes no representations about the
+ * suitability of this software for any purpose.  It is provided "as
+ * is" without express or implied warranty.
+ *
+ * RED HAT, INC. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
+ * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS, IN NO EVENT SHALL RED HAT, INC. BE LIABLE FOR ANY SPECIAL,
+ * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+ * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+ * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ * Author: Owen Taylor <otaylor@redhat.com>
+ */
+
+#include <math.h>
+#include "cairo-test.h"
+#include <stdio.h>
+
+#define SIZE 100
+#define BORDER 10
+#define LINE_WIDTH 20
+
+cairo_test_t test = {
+    "clip-nesting",
+    "Test clipping with multiple contexts for the same surface",
+    SIZE, SIZE
+};
+
+static cairo_test_status_t
+draw (cairo_t *cr, int width, int height)
+{
+    cairo_surface_t *target_surface;
+    cairo_t *cr2, *cr3;
+
+    target_surface = cairo_get_target_surface (cr);
+
+    cr2 = cairo_create ();
+    cairo_set_target_surface (cr2, target_surface);
+
+    /* Draw a diagonal line and clip to it */
+    
+    cairo_move_to (cr2, BORDER,                     BORDER);
+    cairo_line_to (cr2, BORDER + LINE_WIDTH,        BORDER);
+    cairo_line_to (cr2, SIZE - BORDER,              SIZE - BORDER);
+    cairo_line_to (cr2, SIZE - BORDER - LINE_WIDTH, SIZE - BORDER);
+
+    cairo_clip (cr2);
+    cairo_set_source_rgb (cr2, 0, 0, 1); /* Blue */
+    cairo_paint (cr2);
+
+    /* Clipping affects this cairo_t */
+
+    cairo_set_source_rgb (cr2, 1, 1, 1); /* White */
+    cairo_rectangle (cr2,
+		     SIZE / 2 - LINE_WIDTH / 2, BORDER,
+		     LINE_WIDTH,                SIZE - 2 * BORDER);
+    cairo_fill (cr2);
+
+    /* But doesn't affect another cairo_t that we create temporarily for
+     * the same surface
+     */
+    cr3 = cairo_create ();
+    
+    cairo_set_target_surface (cr3, target_surface);
+    cairo_set_source_rgb (cr3, 1, 1, 1); /* White */
+    cairo_rectangle (cr3,
+		     SIZE - BORDER - LINE_WIDTH, BORDER,
+		     LINE_WIDTH,                 SIZE - 2 * BORDER);
+    cairo_fill (cr3);
+
+    cairo_destroy (cr3);
+    cairo_destroy (cr2);
+
+    /* And doesn't affect anything after this cairo_t is destroyed */
+
+    cairo_set_source_rgb (cr, 1, 1, 1); /* White */
+    cairo_rectangle (cr,
+		     BORDER,     BORDER,
+		     LINE_WIDTH, SIZE - 2 * BORDER);
+    cairo_fill (cr);
+    
+    return CAIRO_TEST_SUCCESS;
+
+}
+
+int
+main (void)
+{
+    return cairo_test (&test, draw);
+}
diff --git a/test/self-copy-ref.png b/test/self-copy-ref.png
new file mode 100644
index 00000000..92a20db6
--- /dev/null
+++ b/test/self-copy-ref.png
diff --git a/test/self-copy.c b/test/self-copy.c
new file mode 100644
index 00000000..abb13271
--- /dev/null
+++ b/test/self-copy.c
@@ -0,0 +1,90 @@
+/*
+ * Copyright © 2005 Red Hat, Inc.
+ *
+ * Permission to use, copy, modify, distribute, and sell this software
+ * and its documentation for any purpose is hereby granted without
+ * fee, provided that the above copyright notice appear in all copies
+ * and that both that copyright notice and this permission notice
+ * appear in supporting documentation, and that the name of
+ * Red Hat, Inc. not be used in advertising or publicity pertaining to
+ * distribution of the software without specific, written prior
+ * permission. Red Hat, Inc. makes no representations about the
+ * suitability of this software for any purpose.  It is provided "as
+ * is" without express or implied warranty.
+ *
+ * RED HAT, INC. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
+ * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS, IN NO EVENT SHALL RED HAT, INC. BE LIABLE FOR ANY SPECIAL,
+ * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+ * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+ * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ * Author: Owen Taylor <otaylor@redhat.com>
+ */
+
+#include <math.h>
+#include "cairo-test.h"
+#include <stdio.h>
+
+#define SIZE 40
+
+cairo_test_t test = {
+    "self-copy",
+    "Test copying from a surface to itself with a clip",
+    SIZE, SIZE
+};
+
+static cairo_test_status_t
+draw (cairo_t *cr, int width, int height)
+{
+    cairo_pattern_t *pattern;
+    cairo_matrix_t matrix;
+    
+    /* Paint a diagonal division as a test image */
+    cairo_set_source_rgb (cr, 1, 1, 1);	/* White */
+    cairo_paint (cr);
+
+    cairo_move_to (cr, SIZE,    0);
+    cairo_line_to (cr, SIZE, SIZE);
+    cairo_line_to (cr, 0,    SIZE);
+
+    cairo_set_source_rgb (cr, 0, 0, 0);
+    cairo_fill (cr);
+
+    /* Create a pattern with the target surface as the source,
+     * offset by SIZE/2
+     */
+    pattern = cairo_pattern_create_for_surface (cairo_get_target_surface (cr));
+    
+    cairo_matrix_init_translate (&matrix, - SIZE / 2, - SIZE / 2);
+    cairo_pattern_set_matrix (pattern, &matrix);
+    
+    cairo_set_source (cr, pattern);
+    cairo_pattern_destroy (pattern);
+
+    /* Copy two rectangles from the upper-left quarter of the image to
+     * the lower right.  It will work if we use cairo_fill(), but the
+     * cairo_clip() cairo_paint() combination fails because the clip
+     * on the surface as a destination affects it as the source as
+     * well.
+     */
+    cairo_rectangle (cr,
+		     2 * SIZE / 4, 2 * SIZE / 4,
+		     SIZE / 4,     SIZE / 4);
+    cairo_rectangle (cr,
+		     3 * SIZE / 4, 3 * SIZE / 4,
+		     SIZE / 4,     SIZE / 4);
+    cairo_clip (cr);
+    cairo_paint (cr);
+
+    return CAIRO_TEST_SUCCESS;
+
+}
+
+int
+main (void)
+{
+    return cairo_test_expect_failure (&test, draw,
+				      "copying from a surface to itself doesn't handle clipping properly");
+}
diff --git a/test/source-clip-ref.png b/test/source-clip-ref.png
new file mode 100644
index 00000000..8df2bff9
--- /dev/null
+++ b/test/source-clip-ref.png
diff --git a/test/source-clip.c b/test/source-clip.c
new file mode 100644
index 00000000..ec4c68f6
--- /dev/null
+++ b/test/source-clip.c
@@ -0,0 +1,85 @@
+/*
+ * Copyright © 2005 Red Hat, Inc.
+ *
+ * Permission to use, copy, modify, distribute, and sell this software
+ * and its documentation for any purpose is hereby granted without
+ * fee, provided that the above copyright notice appear in all copies
+ * and that both that copyright notice and this permission notice
+ * appear in supporting documentation, and that the name of
+ * Red Hat, Inc. not be used in advertising or publicity pertaining to
+ * distribution of the software without specific, written prior
+ * permission. Red Hat, Inc. makes no representations about the
+ * suitability of this software for any purpose.  It is provided "as
+ * is" without express or implied warranty.
+ *
+ * RED HAT, INC. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
+ * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS, IN NO EVENT SHALL RED HAT, INC. BE LIABLE FOR ANY SPECIAL,
+ * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+ * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+ * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ * Author: Owen Taylor <otaylor@redhat.com>
+ */
+
+#include <math.h>
+#include "cairo-test.h"
+#include <stdio.h>
+
+#define SIZE 50
+
+cairo_test_t test = {
+    "source-clip",
+    "Test using a surface with an active clip as a source",
+    SIZE, SIZE
+};
+
+static cairo_test_status_t
+draw (cairo_t *cr, int width, int height)
+{
+    cairo_pattern_t *pattern;
+    cairo_surface_t *source_surface;
+    cairo_t *cr2;
+
+    source_surface = cairo_surface_create_similar (cairo_get_target_surface (cr),
+						   CAIRO_FORMAT_ARGB32,
+						   SIZE, SIZE);
+
+    cr2 = cairo_create ();
+    cairo_set_target_surface (cr2, source_surface);
+
+    /* Fill the source surface with solid black */
+    cairo_set_source_rgb (cr2, 0, 0, 0);
+    cairo_paint (cr2);
+
+    /* Now leave a clip in place */
+    cairo_rectangle (cr2,
+		     SIZE / 4, SIZE / 4,
+		     SIZE / 2, SIZE / 2);
+    cairo_clip (cr2);
+
+    /* Fill the destination surface with solid white */
+    cairo_set_source_rgb (cr, 1, 1, 1);
+    cairo_paint (cr);
+
+    /* Now draw the source surface onto the destination surface */
+    pattern = cairo_pattern_create_for_surface (source_surface);
+    cairo_set_source (cr, pattern);
+    cairo_paint (cr);
+
+    /* As the clip shouldn't matter, the result should be solid black */
+    
+    cairo_destroy (cr2);
+    cairo_pattern_destroy (pattern);
+    cairo_surface_destroy (source_surface);
+
+    return CAIRO_TEST_SUCCESS;
+
+}
+
+int
+main (void)
+{
+    return cairo_test (&test, draw);
+}