[cairo-commit] cairo/src Makefile.am, 1.39, 1.40 cairo-path-data-private.h, NONE, 1.1 cairo.c, 1.55, 1.56 cairo.h, 1.79, 1.80 cairo_path_data.c, NONE, 1.1

[Carl Worth]

Committed by: cworth

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

Modified Files:
	Makefile.am cairo.c cairo.h 
Added Files:
	cairo-path-data-private.h cairo_path_data.c 
Log Message:

        * doc/public/cairo-sections.txt:
        * doc/public/tmpl/cairo-surface.sgml:
        * doc/public/tmpl/cairo.sgml: Added some documentation, so we get
        some churn here.

        * src/cairo.c:
        * src/cairo.h: New functions: cairo_copy_path_data,
        cairo_copy_path_data_flat, and cairo_append_path_data.

        * src/Makefile.am:
        * src/cairo-path-data-private.h:
        * src/cairo_path_data.c: Add new implementation for
        cairo_copy_path_data and cairo_append_path_data.

        * test/Makefile.am:
        * test/path_data.c: New test for new path_data functions.


Index: Makefile.am
===================================================================
RCS file: /cvs/cairo/cairo/src/Makefile.am,v
retrieving revision 1.39
retrieving revision 1.40
diff -u -d -r1.39 -r1.40
--- Makefile.am	4 Feb 2005 16:04:36 -0000	1.39
+++ Makefile.am	11 Mar 2005 22:29:15 -0000	1.40
@@ -91,6 +91,8 @@
 	cairo_matrix.c		\
 	cairo_path.c		\
 	cairo_path_bounds.c	\
+	cairo_path_data.c	\
+	cairo-path-data-private.h \
 	cairo_path_fill.c	\
 	cairo_path_stroke.c	\
 	cairo_pen.c		\

--- NEW FILE: cairo-path-data-private.h ---
(This appears to be a binary file; contents omitted.)

Index: cairo.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.c,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -d -r1.55 -r1.56
--- cairo.c	9 Mar 2005 20:35:36 -0000	1.55
+++ cairo.c	11 Mar 2005 22:29:15 -0000	1.56
@@ -34,8 +34,8 @@
  *	Carl D. Worth <cworth at cworth.org>
  */
 
-
 #include "cairoint.h"
+#include "cairo-path-data-private.h"
 
 #define CAIRO_TOLERANCE_MINIMUM	0.0002 /* We're limited by 16 bits of sub-pixel precision */
 
@@ -56,6 +56,8 @@
     case CAIRO_STATUS_INVALID_MATRIX:
     case CAIRO_STATUS_NO_TARGET_SURFACE:
     case CAIRO_STATUS_NULL_POINTER:
+    case CAIRO_STATUS_INVALID_STRING:
+    case CAIRO_STATUS_INVALID_PATH_DATA:
 	break;
     default:
 	return 0;
@@ -1705,6 +1707,88 @@
 }
 DEPRECATE (cairo_current_path_flat, cairo_get_path_flat);
 
+/**
+ * cairo_copy_path_data:
+ * @cr: a cairo context
+ * 
+ * Creates a copy of the current path and returns it to the user as an
+ * array of #cairo_path_data_t. See #cairo_path_data_t for hints on
+ * how to iterate over the returned data structure.
+ * 
+ * Return value: the copy of the current path. The caller is
+ * responsible for the returned memory and should free() it when
+ * finished.
+ **/
+cairo_path_data_t *
+cairo_copy_path_data (cairo_t *cr)
+{
+    CAIRO_CHECK_SANITY (cr);
+    if (cr->status)
+	return &_cairo_path_data_nil;
+
+    return _cairo_path_data_create (cr->gstate);
+}
+
+/**
+ * cairo_copy_path_data_flat:
+ * @cr: a cairo context
+ * 
+ * Gets a flattened copy of the current path and returns it to the
+ * user an an array of #cairo_path_data_t. See #cairo_path_data_t for hints on
+ * how to iterate over the returned data structure.
+ *
+ * This function is like cairo_copy_path_data() except that any curves
+ * in the path will be approximated with piecewise-linear
+ * approximations, (accurate to within the current tolerance
+ * value). That is, the result is guaranteed to not have any elements
+ * of type CAIRO_PATH_CURVE_TO which will instead be replaced by a
+ * series of CAIRO_PATH_LINE_TO elements.
+ * 
+ * Return value: the copy of the current path. The caller is
+ * responsible for the returned memory and should free() it when
+ * finished.
+ **/
+cairo_path_data_t *
+cairo_copy_path_data_flat (cairo_t *cr)
+{
+    CAIRO_CHECK_SANITY (cr);
+    if (cr->status)
+	return &_cairo_path_data_nil;
+
+    return _cairo_path_data_create_flat (cr->gstate);
+}
+
+/**
+ * cairo_append_path_data:
+ * @cr: a cairo context
+ * @path_data: path data to be appended
+ * 
+ * Append the @path_data onto the current path. See #cairo_path_data_t
+ * for details on how the path data array must be initialized.
+ **/
+void
+cairo_append_path_data (cairo_t		  *cr,
+			cairo_path_data_t *path_data)
+{
+    CAIRO_CHECK_SANITY (cr);
+    if (cr->status)
+	return;
+
+    if (!path_data) {
+	cr->status = CAIRO_STATUS_NULL_POINTER;
+	return;
+    }
+
+    if (path_data == &_cairo_path_data_nil) {
+	cr->status = CAIRO_STATUS_NO_MEMORY;
+	return;
+    }
+
+    cr->status = _cairo_path_data_append_to_context (path_data, cr);
+
+    CAIRO_CHECK_SANITY (cr);
+}
+
 cairo_status_t
 cairo_status (cairo_t *cr)
 {
@@ -1735,6 +1819,8 @@
 	return "NULL pointer";
     case CAIRO_STATUS_INVALID_STRING:
 	return "input string not valid UTF-8";
+    case CAIRO_STATUS_INVALID_PATH_DATA:
+	return "input path data not valid";
     }
 
     return "<unknown error status>";

Index: cairo.h
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.h,v
retrieving revision 1.79
retrieving revision 1.80
diff -u -d -r1.79 -r1.80
--- cairo.h	10 Mar 2005 16:59:11 -0000	1.79
+++ cairo.h	11 Mar 2005 22:29:15 -0000	1.80
@@ -55,7 +55,7 @@
  *
  * #cairo_bool_t is used for boolean values. Returns of type
  * #cairo_bool_t will always be either 0 or 1, but testing against
- * these values explicitely is not encouraged; just use the
+ * these values explicitly is not encouraged; just use the
  * value as a boolean condition.
  *
  * <informalexample><programlisting>
@@ -106,7 +106,8 @@
     CAIRO_STATUS_INVALID_MATRIX,
     CAIRO_STATUS_NO_TARGET_SURFACE,
     CAIRO_STATUS_NULL_POINTER,
-    CAIRO_STATUS_INVALID_STRING
+    CAIRO_STATUS_INVALID_STRING,
+    CAIRO_STATUS_INVALID_PATH_DATA
 } cairo_status_t;
 
 /* Functions for manipulating state objects */
@@ -145,7 +146,7 @@
  * cairo_format_t
  * @CAIRO_FORMAT_ARGB32: each pixel is a 32-bit quantity, with
  *   alpha in the upper 8 bits, then red, then green, then blue.
- *   The 32-bit quanties are stored native-endian. Pre-multiplied
+ *   The 32-bit quantities are stored native-endian. Pre-multiplied
  *   alpha is used. (That is, 50% transparent red is 0x80800000,
  *   not 0x80ff0000.)
  * @CAIRO_FORMAT_RGB24: each pixel is a 32-bit quantity, with
@@ -664,7 +665,7 @@
 void
 cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix);
 
-/* XXX: Need to decide the memory mangement semantics of this
+/* XXX: Need to decide the memory management semantics of this
    function. Should it reference the surface again? */
 cairo_surface_t *
 cairo_get_target_surface (cairo_t *cr);
@@ -682,7 +683,7 @@
 
 typedef void (cairo_close_path_func_t) (void *closure);
 
-extern void
+void
 cairo_get_path (cairo_t			*cr,
 		cairo_move_to_func_t	*move_to,
 		cairo_line_to_func_t	*line_to,
@@ -690,13 +691,98 @@
 		cairo_close_path_func_t	*close_path,
 		void			*closure);
 
-extern void
+void
 cairo_get_path_flat (cairo_t                 *cr,
 		     cairo_move_to_func_t    *move_to,
 		     cairo_line_to_func_t    *line_to,
 		     cairo_close_path_func_t *close_path,
 		     void                    *closure);
 
+/**
+ * cairo_path_data_t:
+ *
+ * A data structure for holding path data. This data structure is used
+ * as the return value for cairo_copy_path_data() and
+ * cairo_copy_path_data_flat() as well the input value for
+ * cairo_append_path_data().
+ *
+ * The data structure is designed to try to balance the demands of
+ * efficiency and ease-of-use. A path is represented as an array of
+ * cairo_path_data_t which is a union of headers and points. The array
+ * must be terminated by a header element of type CAIRO_PATH_END_PATH.
+ *
+ * Each portion of the path is represented by one or more elements in
+ * the array, (one header followed by 0 or more points). The length
+ * value of the header is the number of array elements for the current
+ * portion including the header, (ie. length == 1 + # of points), and
+ * where the number of points for each element type must be as
+ * follows:
+ *
+ *	CAIRO_PATH_MOVE_TO:	1 point
+ *	CAIRO_PATH_LINE_TO:	1 point
+ *	CAIRO_PATH_CURVE_TO:	3 points
+ *	CAIRO_PATH_CLOSE_PATH:	0 points
+ *
+ * The semantics and ordering of the coordinate values are consistent
+ * with cairo_move_to(), cairo_line_to(), cairo_curve_to(), and
+ * cairo_close_path().
+ *
+ * Here is sample code for iterating through a cairo_path_data_t
+ * array:
+ *
+ * <informalexample><programlisting>
+ *	cairo_path_data_t *path, *p;
+ *
+ *	path = cairo_copy_path_data (cr);
+ *
+ *	for (p = path; p->header.type != CAIRO_PATH_END; p += p->header.length) {
+ *	    switch (p->header.type) {
+ *	    case CAIRO_PATH_MOVE_TO:
+ *		do_move_to_things (p[1].point.x, p[1].point.y);
+ *		break;
+ *	    case CAIRO_PATH_LINE_TO:
+ *		do_line_to_things (p[1].point.x, p[1].point.y);
+ *		break;
+ *	    case CAIRO_PATH_CURVE_TO:
+ *		do_curve_to_things (p[1].point.x, p[1].point.y,
+ *				    p[2].point.x, p[2].point.y,
+ *				    p[3].point.x, p[3].point.y);
+ *		break;
+ *	    case CAIRO_PATH_CLOSE_PATH:
+ *		do_close_path_things ();
+ *		break;
+ *	    }
+ *	}
+ *
+ *	free (path);
+ * </programlisting></informalexample>
+ */
+typedef union {
+    struct {
+	enum {
+	    CAIRO_PATH_MOVE_TO,
+	    CAIRO_PATH_LINE_TO,
+	    CAIRO_PATH_CURVE_TO,
+	    CAIRO_PATH_CLOSE_PATH,
+	    CAIRO_PATH_END
+	} type;
+	int length;
+    } header;
+    struct {
+	double x, y;
+    } point;
+} cairo_path_data_t;
+
+cairo_path_data_t *
+cairo_copy_path_data (cairo_t *cr);
+
+cairo_path_data_t *
+cairo_copy_path_data_flat (cairo_t *cr);
+
+void
+cairo_append_path_data (cairo_t		  *cr,
+			cairo_path_data_t *path_data);
+
 /* Error status queries */
 
 cairo_status_t
@@ -921,7 +1007,7 @@
 #define cairo_current_rgb_color      cairo_current_rgb_color_DEPRECATED_BY_cairo_get_rgb_color
 #define cairo_current_alpha	     cairo_current_alpha_DEPRECATED_BY_cairo_get_alpha
 #define cairo_current_tolerance	     cairo_current_tolerance_DEPRECATED_BY_cairo_get_tolerance
-#define cairo_current_point	     cairo_current_point_DEPRECTATED_BY_cairo_get_current_point
+#define cairo_current_point	     cairo_current_point_DEPRECATED_BY_cairo_get_current_point
 #define cairo_current_fill_rule	     cairo_current_fill_rule_DEPRECATED_BY_cairo_get_fill_rule
 #define cairo_current_line_width     cairo_current_line_width_DEPRECATED_BY_cairo_get_line_width
 #define cairo_current_line_cap       cairo_current_line_cap_DEPRECATED_BY_cairo_get_line_cap

--- NEW FILE: cairo_path_data.c ---
(This appears to be a binary file; contents omitted.)