[cairo-commit] cairo/src cairo-ft-font.c, 1.109,
1.110 cairo-path-data.c, 1.11, 1.12 cairo-pattern.c, 1.63,
1.64 cairo.c, 1.131, 1.132 cairo.h, 1.149, 1.150
Billy Biggs
commit at pdx.freedesktop.org
Tue Aug 23 19:52:11 PDT 2005
Committed by: vektor
Update of /cvs/cairo/cairo/src
In directory gabe:/tmp/cvs-serv21181/src
Modified Files:
cairo-ft-font.c cairo-path-data.c cairo-pattern.c cairo.c
cairo.h
Log Message:
* doc/public/tmpl/cairo-matrix.sgml: Update the long description
of cairo_matrix_t to match the current sources.
* doc/public/tmpl/cairo-paths.sgml: Add cairo_path_data_t.
* src/cairo-ft-font.c:
* src/cairo-path-data.c:
* src/cairo-pattern.c:
* src/cairo.c:
* src/cairo.h: Some documentation updates and improvements.
Index: cairo-ft-font.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-ft-font.c,v
retrieving revision 1.109
retrieving revision 1.110
diff -u -d -r1.109 -r1.110
--- cairo-ft-font.c 23 Aug 2005 21:12:01 -0000 1.109
+++ cairo-ft-font.c 24 Aug 2005 02:52:09 -0000 1.110
@@ -2606,10 +2606,9 @@
* @scaled_font: A #cairo_scaled_font_t from the FreeType font backend. Such an
* object can be created by calling cairo_scaled_font_create() on a
* FreeType backend font face (see cairo_ft_font_face_create_for_pattern(),
- * cairo_ft_font_face_create_for_face()).
+ * cairo_ft_font_face_create_for_ft_face()).
*
- * Releases a face obtained with cairo_ft_font_lock_face(). See the
- * documentation for that function for full details.
+ * Releases a face obtained with cairo_ft_scaled_font_lock_face().
**/
void
cairo_ft_scaled_font_unlock_face (cairo_scaled_font_t *abstract_font)
Index: cairo-path-data.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-path-data.c,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -d -r1.11 -r1.12
--- cairo-path-data.c 13 Aug 2005 08:17:06 -0000 1.11
+++ cairo-path-data.c 24 Aug 2005 02:52:09 -0000 1.12
@@ -367,8 +367,8 @@
/**
* cairo_path_destroy:
- * @path: a path to destroy which was previously returned by either
- * cairo_copy_path or cairo_copy_path_flat.
+ * @path: a path previously returned by either cairo_copy_path() or
+ * cairo_copy_path_flat().
*
* Immediately releases all memory associated with @path. After a call
* to cairo_path_destroy() the @path pointer is no longer valid and
Index: cairo-pattern.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-pattern.c,v
retrieving revision 1.63
retrieving revision 1.64
diff -u -d -r1.63 -r1.64
--- cairo-pattern.c 23 Aug 2005 21:53:08 -0000 1.63
+++ cairo-pattern.c 24 Aug 2005 02:52:09 -0000 1.64
@@ -618,7 +618,7 @@
*
* Note: If the pattern is not a gradient pattern, (eg. a linear or
* radial pattern), then the pattern will be put into an error status
- * with a status of CAIRO_STATUS_PATTERN_MISMATCH.
+ * with a status of %CAIRO_STATUS_PATTERN_TYPE_MISMATCH.
**/
void
cairo_pattern_add_color_stop_rgb (cairo_pattern_t *pattern,
@@ -669,7 +669,7 @@
*
* Note: If the pattern is not a gradient pattern, (eg. a linear or
* radial pattern), then the pattern will be put into an error status
- * with a status of CAIRO_STATUS_PATTERN_MISMATCH.
+ * with a status of %CAIRO_STATUS_PATTERN_TYPE_MISMATCH.
*/
void
cairo_pattern_add_color_stop_rgba (cairo_pattern_t *pattern,
Index: cairo.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.c,v
retrieving revision 1.131
retrieving revision 1.132
diff -u -d -r1.131 -r1.132
--- cairo.c 23 Aug 2005 21:04:28 -0000 1.131
+++ cairo.c 24 Aug 2005 02:52:09 -0000 1.132
@@ -163,8 +163,8 @@
* Creates a new #cairo_t with all graphics state parameters set to
* default values and with @target as a target surface. The target
* surface should be constructed with a backend-specific function such
- * as cairo_image_surface_create (or any other
- * cairo_<backend>_surface_create variant).
+ * as cairo_image_surface_create() (or any other
+ * <literal>cairo_<backend>_surface_create</literal> variant).
*
* This function references @target, so you can immediately
* call cairo_surface_destroy() on it if you don't need to
@@ -453,7 +453,7 @@
*
* Other than the initial translation pattern matrix, as described
* above, all other pattern attributes, (such as its extend mode), are
- * set to the default values as in cairo_pattern_create_for_surface.
+ * set to the default values as in cairo_pattern_create_for_surface().
* The resulting pattern can be queried with cairo_get_source() so
* that these attributes can be modified if desired, (eg. to create a
* repeating pattern with cairo_pattern_set_extend()).
@@ -491,8 +491,8 @@
*
* Note: The pattern's transformation matrix will be locked to the
* user space in effect at the time of cairo_set_source(). This means
- * that further modifications of the CTM will not affect the source
- * pattern. See cairo_pattern_set_matrix().
+ * that further modifications of the current transformation matrix
+ * will not affect the source pattern. See cairo_pattern_set_matrix().
*
* XXX: I'd also like to direct the reader's attention to some
* (not-yet-written) section on cairo's imaging model. How would I do
@@ -2202,14 +2202,15 @@
*
* Gets the target surface for the cairo context as passed to
* cairo_create().
- *
- * Return value: the target surface. This object is owned by cairo. To
- * keep a reference to it, you must call cairo_surface_reference().
*
* This function will always return a valid pointer, but the result
* can be a "nil" surface if @cr is already in an error state,
- * (ie. cairo_status(cr) != CAIRO_STATUS_SUCCESS). A nil surface is
- * indicated by cairo_surface_status(surface) != CAIRO_STATUS_SUCCESS.
+ * (ie. cairo_status() <literal>!=</literal> %CAIRO_STATUS_SUCCESS).
+ * A nil surface is indicated by cairo_surface_status()
+ * <literal>!=</literal> %CAIRO_STATUS_SUCCESS.
+ *
+ * Return value: the target surface. This object is owned by cairo. To
+ * keep a reference to it, you must call cairo_surface_reference().
**/
cairo_surface_t *
cairo_get_target (cairo_t *cr)
@@ -2233,15 +2234,22 @@
* 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:
+ * will have no data (<literal>data==NULL</literal> and
+ * <literal>num_data==0</literal>), if either of the following
+ * conditions hold:
*
- * 1) If there is insufficient memory to copy the path.
+ * <orderedlist>
+ * <listitem>If there is insufficient memory to copy the path.</listitem>
+ * <listitem>If @cr is already in an error state.</listitem>
+ * </orderedlist>
*
- * 2) If @cr is already in an error state.
+ * In either case, <literal>path->status</literal> will be set to
+ * %CAIRO_STATUS_NO_MEMORY (regardless of what the error status in
+ * @cr might have been).
*
- * In either case, path->status will be set to CAIRO_STATUS_NO_MEMORY,
- * (regardless of what the error status in @cr might have been).
+ * Return value: the copy of the current path. The caller owns the
+ * returned object and should call cairo_path_destroy() when finished
+ * with it.
**/
cairo_path_t *
cairo_copy_path (cairo_t *cr)
@@ -2264,23 +2272,26 @@
* 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.
+ * of type %CAIRO_PATH_CURVE_TO which will instead be replaced by a
+ * series of %CAIRO_PATH_LINE_TO elements.
+ *
+ * This function will always return a valid pointer, but the result
+ * will have no data (<literal>data==NULL</literal> and
+ * <literal>num_data==0</literal>), if either of the following
+ * conditions hold:
+ *
+ * <orderedlist>
+ * <listitem>If there is insufficient memory to copy the path. In this
+ * case <literal>path->status</literal> will be set to
+ * %CAIRO_STATUS_NO_MEMORY.</listitem>
+ * <listitem>If @cr is already in an error state. In this case
+ * <literal>path->status</literal> will contain the same status that
+ * would be returned by cairo_status().</listitem>
+ * </orderedlist>
*
* 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)
@@ -2300,8 +2311,8 @@
* 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.
+ * initialized, and note that <literal>path->status</literal> must be
+ * initialized to %CAIRO_STATUS_SUCCESS.
**/
void
cairo_append_path (cairo_t *cr,
@@ -2333,12 +2344,28 @@
_cairo_set_error (cr, cr->status);
}
+/**
+ * cairo_status:
+ * @cr: a cairo context
+ *
+ * Checks whether an error has previously occurred for this context.
+ *
+ * Returns the current status of this context, see #cairo_status_t
+ **/
cairo_status_t
cairo_status (cairo_t *cr)
{
return cr->status;
}
+/**
+ * cairo_status_to_string:
+ * @status: a cairo status
+ *
+ * Provides a human-readable description of a #cairo_status_t.
+ *
+ * Returns a string representation of the status
+ */
const char *
cairo_status_to_string (cairo_status_t status)
{
Index: cairo.h
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.h,v
retrieving revision 1.149
retrieving revision 1.150
diff -u -d -r1.149 -r1.150
--- cairo.h 23 Aug 2005 20:57:00 -0000 1.149
+++ cairo.h 24 Aug 2005 02:52:09 -0000 1.150
@@ -106,11 +106,11 @@
* @y0: Y translation component of the affine transformation
*
* A #cairo_matrix_t holds an affine transformation, such as a scale,
- * rotation, or shear, or a combination of those. The transformation is given
- * by:
+ * rotation, shear, or a combination of those. The transformation on
+ * a point (x, y) is given by:
* <programlisting>
- * x_new = xx * x + xy * y + x0;
- * y_new = yx * x + yy * y + y0;
+ * x_new = xx * x + xy * y + x0;
+ * y_new = yx * x + yy * y + y0;
* </programlisting>
**/
typedef struct _cairo_matrix {
@@ -973,15 +973,22 @@
cairo_surface_t *
cairo_get_target (cairo_t *cr);
+typedef enum _cairo_path_data_type {
+ CAIRO_PATH_MOVE_TO,
+ CAIRO_PATH_LINE_TO,
+ CAIRO_PATH_CURVE_TO,
+ CAIRO_PATH_CLOSE_PATH
+} cairo_path_data_type_t;
+
/**
* cairo_path_data_t:
*
- * A data structure for holding path data---appears within
+ * #cairo_path_data_t is used to represent the path data inside a
* #cairo_path_t.
*
* 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.
+ * #cairo_path_data_t, which is a union of headers and points.
*
* 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
@@ -990,10 +997,12 @@
* 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
+ * <programlisting>
+ * %CAIRO_PATH_MOVE_TO: 1 point
+ * %CAIRO_PATH_LINE_TO: 1 point
+ * %CAIRO_PATH_CURVE_TO: 3 points
+ * %CAIRO_PATH_CLOSE_PATH: 0 points
+ * </programlisting>
*
* The semantics and ordering of the coordinate values are consistent
* with cairo_move_to(), cairo_line_to(), cairo_curve_to(), and
@@ -1003,42 +1012,35 @@
*
* <informalexample><programlisting>
* int i;
- * cairo_path_t *path;
+ * cairo_path_t *path;
* cairo_path_data_t *data;
- *
- * path = cairo_copy_path (cr);
- *
+ *
+ * path = cairo_copy_path (cr);
+ *
* for (i=0; i < path->num_data; i += path->data[i].header.length) {
- * data = &path->data[i];
- * switch (data->header.type) {
- * case CAIRO_PATH_MOVE_TO:
- * do_move_to_things (data[1].point.x, data[1].point.y);
- * break;
- * case CAIRO_PATH_LINE_TO:
- * do_line_to_things (data[1].point.x, data[1].point.y);
- * break;
- * case CAIRO_PATH_CURVE_TO:
- * do_curve_to_things (data[1].point.x, data[1].point.y,
- * data[2].point.x, data[2].point.y,
- * data[3].point.x, data[3].point.y);
- * break;
- * case CAIRO_PATH_CLOSE_PATH:
- * do_close_path_things ();
- * break;
- * }
- * }
- *
- * cairo_path_destroy (path);
+ * data = &path->data[i];
+ * switch (data->header.type) {
+ * case CAIRO_PATH_MOVE_TO:
+ * do_move_to_things (data[1].point.x, data[1].point.y);
+ * break;
+ * case CAIRO_PATH_LINE_TO:
+ * do_line_to_things (data[1].point.x, data[1].point.y);
+ * break;
+ * case CAIRO_PATH_CURVE_TO:
+ * do_curve_to_things (data[1].point.x, data[1].point.y,
+ * data[2].point.x, data[2].point.y,
+ * data[3].point.x, data[3].point.y);
+ * break;
+ * case CAIRO_PATH_CLOSE_PATH:
+ * do_close_path_things ();
+ * break;
+ * }
+ * }
+ * cairo_path_destroy (path);
* </programlisting></informalexample>
- */
-typedef enum _cairo_path_data_type {
- CAIRO_PATH_MOVE_TO,
- CAIRO_PATH_LINE_TO,
- CAIRO_PATH_CURVE_TO,
- CAIRO_PATH_CLOSE_PATH
-} cairo_path_data_type_t;
-
-typedef union {
+ **/
+typedef union _cairo_path_data_t cairo_path_data_t;
+union _cairo_path_data_t {
struct {
cairo_path_data_type_t type;
int length;
@@ -1046,7 +1048,7 @@
struct {
double x, y;
} point;
-} cairo_path_data_t;
+};
/**
* cairo_path_t:
@@ -1064,7 +1066,7 @@
*
* The num_data member gives the number of elements in the data
* array. This number is larger than the number of independent path
- * portions (MOVE_TO, LINE_TO, CURVE_TO, CLOSE_PATH), since the data
+ * portions (defined in #cairo_path_data_type_t), since the data
* includes both headers and coordinates for each portion.
**/
typedef struct cairo_path {
More information about the cairo-commit
mailing list