[cairo-commit] cairo/src cairo-path-data-private.h, 1.5, 1.6 cairo-path-data.c, 1.6, 1.7 cairo.c, 1.100, 1.101 cairo.h, 1.125, 1.126

Carl Worth commit at pdx.freedesktop.org
Mon Jun 13 16:29:28 PDT 2005


Committed by: cworth

Update of /cvs/cairo/cairo/src
In directory gabe:/tmp/cvs-serv8599/src

Modified Files:
	cairo-path-data-private.h cairo-path-data.c cairo.c cairo.h 
Log Message:

        Originally 2005-06-02  Carl Worth  <cworth at cworth.org>:

        * src/cairo.h: Add a status field to cairo_path_t.

        * src/cairo.c:
        (cairo_copy_path), (cairo_copy_path_flat): Add documentation for
        the new approach for handling errors in these functions---always
        returning a valid pointer with at least a status.
        (cairo_append_path): Propagate path status errors to the
        context. Add note to documentation on initializing path->status.

        * src/cairo-path-data-private.h: Add missing cairo_private
        qualifier to a couple functions.

        * src/cairo-path-data.c: (_cairo_path_data_create_real): Track new
        status field in cairo_path_t.
        (cairo_path_destroy): Don't destroy cairo_path_nil. Add
        documentation.
        (_cairo_path_data_create):
        (_cairo_path_data_create_flat):
        (_cairo_path_data_append_to_context): Add documentation.
        (_cairo_path_data_create_in_error): New function to create a
        placeholder cairo_path_t just to propagate a cairo_status_t error.


Index: cairo-path-data-private.h
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-path-data-private.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- cairo-path-data-private.h	11 May 2005 03:45:55 -0000	1.5
+++ cairo-path-data-private.h	13 Jun 2005 23:29:26 -0000	1.6
@@ -38,17 +38,18 @@
 
 #include "cairoint.h"
 
-extern cairo_path_t _cairo_path_nil;
-
-cairo_path_t *
+cairo_private cairo_path_t *
 _cairo_path_data_create (cairo_path_fixed_t *path,
 			 cairo_gstate_t     *gstate);
 
-cairo_path_t *
+cairo_private cairo_path_t *
 _cairo_path_data_create_flat (cairo_path_fixed_t *path,
 			      cairo_gstate_t     *gstate);
 
-cairo_status_t
+cairo_private cairo_path_t *
+_cairo_path_data_create_in_error (cairo_status_t status);
+
+cairo_private cairo_status_t
 _cairo_path_data_append_to_context (cairo_path_t *path,
 				    cairo_t	 *cr);
 

Index: cairo-path-data.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-path-data.c,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- cairo-path-data.c	3 Jun 2005 23:45:47 -0000	1.6
+++ cairo-path-data.c	13 Jun 2005 23:29:26 -0000	1.7
@@ -37,8 +37,8 @@
 #include "cairo-path-fixed-private.h"
 #include "cairo-gstate-private.h"
 
-cairo_path_t
-_cairo_path_nil = { NULL, 0 };
+static cairo_path_t
+cairo_path_nil = { CAIRO_STATUS_NO_MEMORY, NULL, 0 };
 
 /* Closure for path interpretation. */
 typedef struct cairo_path_data_count {
@@ -347,7 +347,7 @@
 
     path = malloc (sizeof (cairo_path_t));
     if (path == NULL)
-	return &_cairo_path_nil;
+	return &cairo_path_nil;
 
     path->num_data = _cairo_path_data_count (path, path_fixed,
 					     gstate->tolerance, flatten);
@@ -355,9 +355,11 @@
     path->data = malloc (path->num_data * sizeof (cairo_path_data_t));
     if (path->data == NULL) {
 	free (path);
-	return &_cairo_path_nil;
+	return &cairo_path_nil;
     }
 
+    path->status = CAIRO_STATUS_SUCCESS;
+
     _cairo_path_data_populate (path, path_fixed,
 			       gstate, flatten);
 
@@ -366,22 +368,22 @@
 
 /**
  * cairo_path_destroy:
- * @path: a #cairo_path_t pointer returned from either cairo_copy_path
- * or cairo_copy_path_flat.
+ * @path: a path to destroy which was previously returned by either
+ * cairo_copy_path or cairo_copy_path_flat.
  * 
- * Frees @path and all memory associated with it. Upon returning from
- * this function @path will be pointing to an invalid location which
- * should not be used.
+ * Immediately releases all memory associated with @path. After a call
+ * to cairo_path_destroy() the @path pointer is no longer valid and
+ * should not be used further.
  *
- * The cairo_path_destroy function should only be called with a
- * pointer to a #cairo_path_t returned by a cairo function. Any
- * manually created cairo_path_t object should be freed manually as
- * well.
+ * NOTE: cairo_path_destroy function should only be called with a
+ * pointer to a #cairo_path_t returned by a cairo function. Any path
+ * that is created manually (ie. outside of cairo) should be destroyed
+ * manually as well.
  **/
 void
 cairo_path_destroy (cairo_path_t *path)
 {
-    if (path == NULL)
+    if (path == NULL || path == &cairo_path_nil)
 	return;
 
     free (path->data);
@@ -389,6 +391,20 @@
     free (path);
 }
 
+/**
+ * _cairo_path_data_create:
+ * @path: a fixed-point, device-space path to be converted and copied
+ * @gstate: the current graphics state
+ * 
+ * Creates a user-space #cairo_path_t copy of the given device-space
+ * @path. The @gstate parameter provides the inverse CTM for the
+ * conversion.
+ * 
+ * Return value: the new copy of the path. If there is insufficient
+ * memory a pointer to a special static cairo_path_nil will be
+ * returned instead with status==CAIRO_STATUS_NO_MEMORY and
+ * data==NULL.
+ **/
 cairo_path_t *
 _cairo_path_data_create (cairo_path_fixed_t *path,
 			 cairo_gstate_t     *gstate)
@@ -396,6 +412,21 @@
     return _cairo_path_data_create_real (path, gstate, FALSE);
 }
 
+/**
+ * _cairo_path_data_create_flat:
+ * @path: a fixed-point, device-space path to be flattened, converted and copied
+ * @gstate: the current graphics state
+ * 
+ * Creates a flattened, user-space #cairo_path_t copy of the given
+ * device-space @path. The @gstate parameter provide the inverse CTM
+ * for the conversion, as well as the tolerance value to control the
+ * accuracy of the flattening.
+ * 
+ * Return value: the flattened copy of the path. If there is insufficient
+ * memory a pointer to a special static cairo_path_nil will be
+ * returned instead with status==CAIRO_STATUS_NO_MEMORY and
+ * data==NULL.
+ **/
 cairo_path_t *
 _cairo_path_data_create_flat (cairo_path_fixed_t *path,
 			      cairo_gstate_t     *gstate)
@@ -403,6 +434,45 @@
     return _cairo_path_data_create_real (path, gstate, TRUE);
 }
 
+/**
+ * _cairo_path_data_create_in_error:
+ * @status: an error status
+ * 
+ * Create an empty #cairo_path_t object to hold an error status. This
+ * is useful for propagating status values from an existing object to
+ * a new #cairo_path_t.
+ * 
+ * Return value: a #cairo_path_t object with status of @status, NULL
+ * data, and 0 num_data. If there is insufficient memory a pointer to
+ * a special static cairo_path_nil will be returned instead with
+ * status==CAIRO_STATUS_NO_MEMORY rather than @status.
+ **/
+cairo_path_t *
+_cairo_path_data_create_in_error (cairo_status_t status)
+{
+    cairo_path_t *path;
+
+    path = malloc (sizeof (cairo_path_t));
+    if (path == NULL)
+	return &cairo_path_nil;
+
+    path->status = status;
+    path->data = NULL;
+    path->num_data = 0;
+
+    return path;
+}
+
+/**
+ * _cairo_path_data_append_to_context:
+ * @path: the path data to be appended
+ * @cr: a cairo context
+ * 
+ * Append @path to the current path within @cr.
+ * 
+ * Return value: CAIRO_STATUS_INVALID_PATH_DATA if the data in @path
+ * is invalid, and CAIRO_STATUS_SUCCESS otherwise.
+ **/
 cairo_status_t
 _cairo_path_data_append_to_context (cairo_path_t *path,
 				    cairo_t	 *cr)

Index: cairo.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.c,v
retrieving revision 1.100
retrieving revision 1.101
diff -u -d -r1.100 -r1.101
--- cairo.c	3 Jun 2005 16:38:39 -0000	1.100
+++ cairo.c	13 Jun 2005 23:29:26 -0000	1.101
@@ -143,7 +143,7 @@
     CAIRO_CHECK_SANITY (cr);
     if (cr->status)
 	return;
-
+    
     cr->ref_count++;
     CAIRO_CHECK_SANITY (cr);
 }
@@ -160,6 +160,7 @@
 cairo_destroy (cairo_t *cr)
 {
     CAIRO_CHECK_SANITY (cr);
+    
     cr->ref_count--;
     if (cr->ref_count)
 	return;
@@ -2069,15 +2070,27 @@
  * Return value: the copy of the current path. The caller owns the
  * returned object and should call cairo_path_destroy() when finished
  * with it.
+ *
+ * This function will always return a valid pointer, but the result
+ * will have no data, (data==NULL and num_data==0), if either of the
+ * following conditions hold:
+ *
+ * 1) If there is insufficient memory to copy the path. In this case
+ *    path->status will be set to CAIRO_STATUS_NO_MEMORY.
+ *
+ * 2) If @cr is already in an error state. In this case path->status
+ *    will contain the same status that would be returned by
+ *    cairo_status(cr).
  **/
 cairo_path_t *
 cairo_copy_path (cairo_t *cr)
 {
     CAIRO_CHECK_SANITY (cr);
-    if (cr->status)
-	return &_cairo_path_nil;
 
-    return _cairo_path_data_create (&cr->path, cr->gstate);
+    if (cr->status)
+	return _cairo_path_data_create_in_error (cr->status);
+    else
+	return _cairo_path_data_create (&cr->path, cr->gstate);
 }
 
 /**
@@ -2098,15 +2111,26 @@
  * Return value: the copy of the current path. The caller owns the
  * returned object and should call cairo_path_destroy() when finished
  * with it.
+ *
+ * This function will always return a valid pointer, but the result
+ * will have no data, (data==NULL and num_data==0), if either of the
+ * following conditions hold:
+ *
+ * 1) If there is insufficient memory to copy the path. In this case
+ *    path->status will be set to CAIRO_STATUS_NO_MEMORY.
+ *
+ * 2) If @cr is already in an error state. In this case path->status
+ *    will contain the same status that would be returned by
+ *    cairo_status(cr).
  **/
 cairo_path_t *
 cairo_copy_path_flat (cairo_t *cr)
 {
     CAIRO_CHECK_SANITY (cr);
     if (cr->status)
-	return &_cairo_path_nil;
-
-    return _cairo_path_data_create_flat (&cr->path, cr->gstate);
+	return _cairo_path_data_create_in_error (cr->status);
+    else
+	return _cairo_path_data_create_flat (&cr->path, cr->gstate);
 }
 
 /**
@@ -2114,8 +2138,12 @@
  * @cr: a cairo context
  * @path: path to be appended
  * 
- * Append the @path onto the current path. See #cairo_path_t
- * for details on how the path data structure must be initialized.
+ * Append the @path onto the current path. The @path may be either the
+ * return value from one of cairo_copy_path() or
+ * cairo_copy_path_flat() or it may be constructed manually.  See
+ * #cairo_path_t for details on how the path data structure should be
+ * initialized, and note that path->status must be initialized to
+ * CAIRO_STATUS_SUCCESS.
  **/
 void
 cairo_append_path (cairo_t	*cr,
@@ -2130,8 +2158,8 @@
 	return;
     }
 
-    if (path == &_cairo_path_nil) {
-	cr->status = CAIRO_STATUS_NO_MEMORY;
+    if (path->status) {
+	cr->status = path->status;
 	return;
     }
 

Index: cairo.h
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.h,v
retrieving revision 1.125
retrieving revision 1.126
diff -u -d -r1.125 -r1.126
--- cairo.h	11 Jun 2005 06:47:25 -0000	1.125
+++ cairo.h	13 Jun 2005 23:29:26 -0000	1.126
@@ -859,6 +859,7 @@
  * includes both headers and coordinates for each portion.
  **/
 typedef struct cairo_path {
+    cairo_status_t status;
     cairo_path_data_t *data;
     int num_data;
 } cairo_path_t;




More information about the cairo-commit mailing list