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.

1 files changed, 12 insertions, 2 deletions

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>";