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, 28 insertions, 1 deletions

diff --git a/src/cairo.h b/src/cairo.h
index c0a122fdd..8f609d488 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;
 
 /**